Claude Code SDK #37：Routines 全解——Schedule × API × GitHub，把 Claude Code 变成自动跑的云端任务 (2026)

如果你已经把 Claude Code 用成了一个「打开终端后才开始干活」的工具，Routines 会让边界往前推一步：任务可以按时间、HTTP 请求或 GitHub 事件自己启动，跑在 Anthropic 托管的云端环境里，电脑合上也不影响执行。官方把 Routines 定义为一组保存好的 Claude Code 配置，包括 prompt、一个或多个仓库，以及一组 connectors；它目前仍是 research preview，行为、限制和 API 表面都可能变化。1

这一期不把它当「定时任务」浅讲。更准确的理解是：Routines 是 Claude Code 的自动化运行层。它把你平时手动发给 Claude 的那段任务说明、仓库上下文、云环境、外部连接和触发条件打包起来，然后在条件命中时启动一场新的 Claude Code 云端 session。1

01｜Routines 存的不是命令，而是一份可重复执行的工作说明

一个 routine 至少要回答四个问题：让 Claude 做什么、在哪些仓库里做、用哪个云环境跑、什么时候触发。官方创建表单也正是围绕 prompt、repositories、environment、connectors、triggers 这些要素展开。1

这里最容易误解的是 prompt。它不是一句「帮我看一下」就够了，因为 routine 运行时没有权限模式选择器，也不会在每一步弹出 approval prompt；它会作为完整的 Claude Code 云端 session 自主运行，可以执行 shell command、使用仓库里提交的 skills，也可以调用你给它的 connectors。1

所以 routine 的 prompt 应该像一份小型 runbook：输入从哪里来，判断标准是什么，允许改哪些文件，最后要产出 PR、评论、报告还是只读摘要。写得越含糊，越容易得到一场「看起来跑完了，但你不知道它到底做对没有」的自动化。

02｜三类触发器：时间、HTTP、GitHub 事件

Routines 支持三类触发方式，而且同一个 routine 可以同时挂多个触发器。比如一个 PR review routine 可以 nightly 跑一次，也可以被部署脚本通过 API 触发，还可以在新 PR 出现时自动启动。1

触发器	适合什么任务	最该注意什么
Schedule	每小时、每天、工作日、每周，或未来某个时间点跑一次；自定义 cron 目前可通过 `/schedule update` 设置，最小间隔是一小时。1	定时任务会有几分钟 stagger，同一个 routine 的偏移保持一致，不适合要求秒级准点的流程。1
API	外部系统向 routine 专属 `/fire` endpoint 发 POST，请求体可带一个自由文本 `text` 字段，适合告警、部署、内部工具触发。1	token 只显示一次，要放进告警或 CI 的 secret store；API 触发目前从 web UI 添加，CLI 不能创建或撤销 token。1
GitHub	对 pull request 和 release 事件启动新 session，可按 author、title、body、base branch、head branch、labels、draft、merged 等字段过滤。1	`/web-setup` 只授予仓库 clone 访问，不会安装 Claude GitHub App，也不会启用 webhook；GitHub trigger 需要安装 GitHub App。1

这个设计的关键点是「触发器只负责开场」。真正决定质量的，还是 routine 保存的 prompt、环境、连接器和仓库权限。把触发器想成入口，把 prompt 想成执行合同，会更接近它的实际使用方式。

03｜云端运行：你的本机配置不会自动跟过去

Routines 跑在 Claude Code on the web 的云环境里，不是在你的终端进程里。Claude Code on the web 本身也是 research preview，任务运行在 Anthropic 托管的云基础设施上，session 关闭浏览器后仍会持续，移动端也能查看进度。2

这会带来一个非常工程化的边界：云 session 从 GitHub 克隆仓库，仓库里提交的配置可以用，本机用户目录里的配置基本不会出现。

配置或资源	云端 routine 能不能用	该怎么处理
仓库里的 `CLAUDE.md`、`.claude/settings.json` hooks、`.mcp.json`、`.claude/rules/`、`.claude/skills/`	可以，原因是它们属于仓库 clone 的一部分。2	想让 routine 稳定复现，就把规则、skills、agents、commands 提交到 repo。
用户级 `~/.claude/CLAUDE.md`、本机 `~/.claude/skills/`、本机 `claude mcp add` 加的 MCP server	不会自动带进云端，因为它们在你的机器上，不在仓库里。2	要么改成仓库级 `.mcp.json`，要么在 claude.ai 侧添加 connector。
setup script 安装的依赖、工具和 Docker image	可以缓存。setup script 第一次跑完后，Anthropic 会 snapshot 文件系统，后续新 session 从缓存启动；缓存保存文件，不保存正在运行的进程。2	把慢安装放 setup script，把每次都要启动的服务放 session 内命令或 SessionStart hook。
环境变量和 setup script 里的 secret	能用，但目前没有专用 secrets store；环境变量和 setup script 存在环境配置里，能编辑环境的人可以看到。2	少放长期高权限 secret。能用 connector 或 GitHub proxy 的地方，不要自己塞 token。

这也是为什么 Routines 和 Remote Control 的边界很清楚：Remote Control 是把本地 session 暴露给手机或浏览器，环境还是你的电脑；Routines 是云端新开 session，适合无人值守和重复任务。Routines 文档也明确说，它们运行在 Anthropic-managed cloud infrastructure，电脑合上也能继续跑。1

04｜一个可落地的 routine 应该长什么样

不要一上来就让 routine「自动修所有线上故障」。先做只读或低写入风险任务，才能看清 prompt、环境和触发器是否稳定。下面是一个适合团队试水的结构：

Name:
  nightly-docs-drift-check

Prompt:
  Read merged pull requests from the last 24 hours.
  Identify API, CLI flag, config, or behavior changes that may require docs updates.
  Do not modify source code.
  If docs are stale, open a PR that updates only docs/ and includes:
  - PR links that caused the change
  - files changed
  - a short reviewer checklist
  If no docs update is needed, leave a summary comment and stop.

Repositories:
  org/product-repo
  org/docs-repo

Environment:
  default cloud environment
  trusted network access

Triggers:
  schedule: weekdays 09:00
  GitHub: pull_request.closed, is merged = true, label contains docs-impact

这类任务有几个优点：输入清楚，输出可 review，修改范围窄，失败成本也低。它还顺手验证了三件事：GitHub 权限是否能 clone 和开 PR，云环境是否能安装依赖，prompt 是否能让 Claude 把「不需要更新」和「需要开 PR」区分开。

05｜API trigger 的正确心智模型：把告警变成上下文，而不是把 JSON 当参数表

API trigger 的请求体只有一个可选 text 字段，它是 freeform text，不会被 routine 当成结构化 JSON 解析。官方示例里，调用方把告警说明放进 text，routine 会把这段内容和保存好的 prompt 一起交给 Claude。1

curl -X POST "https://api.anthropic.com/v1/claude_code/routines/trig_xxx/fire" \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text":"Sentry alert SEN-4521 fired in prod. Stack trace attached."}'

这里的实践建议是：把固定规则写进 routine prompt，把每次变化的现场材料塞进 text。例如「只能改 src/payments/ 和 tests/payments/」「必须先复现失败」「只能开 draft PR」这些规则不要依赖告警系统临时传，应该固化在 routine 里。

06｜GitHub trigger 不等于复用同一场对话

GitHub trigger 每命中一次事件，就会启动一个新的 session。官方文档明确说，GitHub-triggered routines 不支持跨事件复用 session；两个 PR 更新会产生两个独立 session。1

这对 prompt 设计有影响。不要假设 routine 记得上一次评论了什么，也不要把「增量状态」藏在对话历史里。更稳的做法是让它每次从仓库、PR diff、issue 状态和外部系统重新构建上下文，然后把结论写回可审计的位置：PR comment、draft PR、报告文件或工单字段。

GitHub 过滤也要尽量窄。官方支持按 PR 作者、标题、正文、base branch、head branch、labels、draft 状态、merged 状态等字段过滤。1 比如先只跑 label contains docs-impact，比「所有 PR opened 都跑一遍」更容易控成本，也更少打扰团队。

07｜权限边界：它能写，也会以你的身份写

Routine 不是旁观者。文档写得很直白：routine 通过你的 GitHub identity 或 connectors 做事时，看起来就是你在做；commits 和 PR 使用你的 GitHub 用户，Slack、Linear 等 connector 动作使用你连接的账号。1

仓库写入也有默认护栏。每个添加到 routine 的 repository 会在运行时 clone；默认情况下，Claude 只能 push 到 claude/ 前缀的分支，除非你在该 repo 上打开 unrestricted branch pushes。1 这条默认值很重要，建议不要轻易关。

连接器也要收窄。创建 routine 时，当前连接的 connectors 默认会被包含；官方建议移除不需要的 connectors，以限制 routine 运行时可用的工具范围。1 如果一个 routine 只需要读 GitHub PR，就不要把 Slack、Linear、Drive 全都给它。

08｜绿色状态不等于任务成功

Routine run 列表里的绿色状态只表示 session 启动并退出时没有基础设施错误，不代表 prompt 里的任务已经成功。网络被拦、connector 缺工具、任务级失败，都可能只出现在 transcript 里，需要打开 run 查看。1

这个细节决定了你要怎么验收 routine。不要只看「跑完了」。更可靠的验收方式是让 routine 每次输出一段结构化结果，例如：

Outcome: changed | no_change | blocked
Inputs inspected:
  - PR: #1234
  - Files: src/api/client.ts, docs/api.md
Actions taken:
  - Opened draft PR: &lt;url&gt;
Blocked because:
  - missing staging API token
Next human action:
  - add token to environment or mark this run ignored

如果它打开 PR，就让 PR body 带上 run session URL。Claude Code on the web 文档说明，云 session 可以从 CLAUDE_CODE_REMOTE_SESSION_ID 读到自己的 session ID；从 v2.1.179 起，web session 创建的 commit 会带 Claude-Session: trailer，PR body 也会包含 session URL。2 这能让 reviewer 回到原始运行记录里查它为什么这么改。

09｜什么时候不要用 Routines

第一类是不适合云环境的任务。Claude Code on the web 的云 session 有大致资源上限：4 vCPU、16 GB RAM、30 GB disk；大内存构建或重测试任务可能失败，文档建议这类工作改用 Remote Control 跑在自己的硬件上。2

第二类是需要强交互确认的任务。Routine 运行时没有 approval prompts，它适合无人值守，不适合「每改一步都要人判断」的工作。1 如果任务本身需要人来判断产品方向、授权范围或线上风险，先让它产出计划或 draft PR，不要直接合并或直接执行生产操作。

第三类是状态依赖很强的长期任务。GitHub trigger 每次都是新 session，schedule 和 API trigger 也应按「每次独立执行」设计。需要跨次记忆时，把状态写进仓库、issue、PR comment、外部系统或报告文件里，而不是指望下一次 routine 记得上一轮对话。

10｜给 AI 开发者的落地顺序

如果你今天要在团队里试 Routines，我建议按这个顺序来：

先选一个「只读 + 可复核」任务，比如每日 merged PR 摘要、docs drift 检查、依赖升级风险报告。不要第一天就让它自动改核心代码。
把 prompt 写成 runbook：输入范围、允许动作、禁止动作、输出格式、失败条件、reviewer 该看什么，都写清楚。
只给它必要的 repo、connectors 和 network access。默认 claude/ 分支限制先保留，unrestricted branch pushes 只有在非常明确的维护任务里再考虑。
每次运行都要求输出 changed / no_change / blocked 这类状态，让人能一眼知道它到底完成了什么。
稳定后再加第二个触发器。比如先手动 Run now，再加 schedule；schedule 稳了，再接 GitHub label；最后才接 API 告警。

Routines 的价值不在于「让 Claude 定时出现」，而在于把一类重复工作包装成可审、可限制、可触发的云端执行单元。你把边界写清楚，它就能从工具变成团队工作流的一部分；边界写不清楚，它只是一个会准时启动的模糊任务。

Claude Code SDK #37：Routines 全解——Schedule × API × GitHub，把 Claude Code 变成自动跑的云端任务