Claude Code Routines 完全指南：定时、API 与 GitHub 事件三种触发器详解

本文是对官方文档「Automate work with routines」的中文要点摘要,完整内容以原文为准。原文链接:https://code.claude.com/docs/en/routines

什么是 Routines?

Routines 是 Claude Code 的自动化配置单元:一个 prompt + 一个或多个 GitHub 仓库 + 一组 MCP 连接器,打包后在 Anthropic 托管的云端 自动运行,关掉笔记本也能持续执行。

目前处于 Research Preview 阶段,接口与行为可能变化。需要 Pro / Max / Team / Enterprise 订阅并启用 Claude Code on the web。Team / Enterprise 的 Owners(所有者)可在 claude.ai/admin-settings/claude-code 用 Routines 开关为全体成员统一关闭该功能;关闭后现有 Routine 停止运行,成员也无法新建。

三种触发方式

同一个 Routine 可同时绑定多种触发器,例如「每晚定时 + PR 开启时」同时生效。

典型使用场景

• Backlog 维护:每晚定时整理 Issue,自动打标签、分配负责人并推送 Slack 摘要
• 告警分诊:监控系统调用 API 端点传入告警正文,Claude 关联最近提交并自动起草修复 PR
• 代码审查:PR 开启时运行团队自定义 checklist,留 inline 评论,人工只审设计
• 部署验证:CD 流水线部署完成后调用 API,跑冒烟测试并在发布频道推送通知
• 文档同步:每周扫描合并 PR,对引用已变更 API 的文档自动开 PR
• SDK 多语言同步:一个 SDK 合并 PR 后自动将改动移植到另一语言版本

创建 Routine

三个入口:Web UI(claude.ai/code/routines)、Desktop 应用侧边栏 → Routines → New routine → Remote,或 CLI 命令 /schedule。

Desktop 应用中选择 Local 会创建「Desktop Scheduled Task」,在本机运行而非云端,两者互相独立。

关键配置项

• Prompt:Routine 全程自主运行、无审批提示,prompt 必须自包含且明确定义「成功」是什么
• 仓库:每次运行从默认分支克隆;默认只允许推送 claude/ 前缀分支,需手动启用「Allow unrestricted branch pushes」
• 环境(Environment):控制网络访问、环境变量、安装脚本;默认「Trusted」模式仅放行包管理器、云服务商 API 等白名单域名,访问额外域名需手动在环境设置中添加
• 连接器(Connectors):默认包含账号下所有 MCP 连接器,建议仅保留必要的以收窄权限范围

注意:CLI 的 claude mcp add 本地添加的 MCP Server 不会同步到云端,需在 claude.ai/customize/connectors 添加,或通过仓库内的 .mcp.json 文件声明。

Schedule 触发器

• 预置频率:每小时、每日、工作日、每周;自定义 cron 可通过 /schedule update 设置,最小间隔为 1 小时
• 实际启动时间可能比计划时间晚几分钟(固定偏移量)
• 一次性运行(one-off):触发后自动禁用,不计入每日 Routine 配额;支持自然语言描述时间:

/schedule tomorrow at 9am, summarize yesterday's merged PRs
/schedule in 2 weeks, open a cleanup PR that removes the feature flag

API 触发器

通过 Web UI 添加后,复制 URL 并生成 Token(只显示一次,请立即保存至密钥存储)。

curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01ABCD.../fire \
  -H "Authorization: Bearer sk-ant-oat01-xxxxx" \
  -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."}'

text 字段为本次运行附加的上下文(原始字符串,不做结构化解析)。响应返回 claude_code_session_url,可在浏览器实时查看运行进度、继续对话或创建 PR。

该端点使用 experimental-cc-routine-2026-04-01 Beta 头,接口在 Preview 阶段仍可能变化;破坏性变更会随新的带日期 Beta 头版本发布,且最近两个旧版本会继续兼容,留出迁移时间。

GitHub 触发器

需安装 Claude GitHub App(与 /web-setup 的仓库访问权限相互独立,不可替代)。

支持事件:

PR 过滤条件(须全部满足才触发):作者、标题、正文、目标分支、来源分支、标签、是否草稿、是否已合并。

正则过滤匹配整个字段,若要匹配含 hotfix 的标题需写 .*hotfix.*;若只需子串匹配,用 contains 操作符更简洁。

Preview 阶段每个 Routine 和每个账号均有 GitHub 事件的每小时处理上限,超出的事件会被丢弃直到窗口重置。

使用限额

• Routine 运行消耗订阅额度,账号有每日运行次数上限(可在 claude.ai/code/routines 查看剩余量)
• 超限后可开启「Usage Credits」按量计费继续使用(在 Settings → Billing 开启)
• 一次性(one-off)运行不计入每日上限,但仍消耗订阅额度

常见问题排查

/schedule 提示「No commands match」或「Unknown command」,常见原因:

• 使用 Console API Key 或 Bedrock / Vertex / Foundry 登录,而非 claude.ai 账号(移除 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 等环境变量,或 settings.json 中的 apiKeyHelper,它们优先级高于 claude.ai 登录)
• 设置了 DISABLE_TELEMETRY、DO_NOT_TRACK、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_GROWTHBOOK 等禁遥测变量,导致特性开关无法拉取
• CLI 版本低于 v2.1.81,运行 claude update 升级
• 在 Claude Code on the web 会话内执行,应改用 claude.ai/code/routines Web UI

「Routines are disabled by your organization's policy」:Team / Enterprise 组织中的某位 Owner(所有者)在 claude.ai/admin-settings/claude-code 关闭了 Routines 开关,需联系 Owner 开启,本地配置无法绕过。