Claude Code Routines 官方完整指南：定时任务、API 触发、GitHub 事件自动化

Routines 是 Claude Code 最强大的自动化功能：把任何 Claude Code 工作流打包成可复用的配置，运行在 Anthropic 的云端基础设施上。你的笔记本关掉，Routine 照常跑。本文是官方文档的完整中文整理，覆盖创建、三种触发类型、管理运行、权限控制的每个细节。

注意：Routines 目前处于"研究预览"阶段，功能和 API 可能变化。

什么是 Routine？#

一个 Routine = 保存的 Claude Code 配置：

• 一个 Prompt：每次运行时 Claude 执行的指令
• 一个或多个 Repository：Claude 在其中工作的代码库
• 一套 Connectors：Claude 可以使用的 MCP 工具集（Slack、Linear、GitHub 等）

每个 Routine 可以有多种触发方式：

• Schedule（定时）：按固定频率（每小时/每天/每周）或一次性运行
• API（接口）：通过 HTTP POST 按需触发，可传入上下文
• GitHub（代码事件）：响应 PR 创建、发布等 GitHub 事件

一个 Routine 可以同时拥有多个触发器。例如，PR 审查 Routine 可以每晚定时运行、被部署脚本触发、也可以自动响应每个新 PR。

可用计划：Pro、Max、Team、Enterprise（需启用 Claude Code on the web）

管理入口：claude.ai/code/routines 或 CLI 的 /schedule 命令

适合 Routines 的场景#

官方文档给出了 6 个典型使用场景，展示了 Routines 的能力范围：

1. Backlog 维护（Schedule 触发）#

每个工作日晚上运行，通过连接器读取 Issue 追踪器，对自上次运行以来新开的 Issue 自动打标签、分配负责人，并发 Slack 摘要——让团队每天早上看到一个整理好的待办队列。

2. 告警分类（API 触发）#

监控系统的告警阈值触发时，把告警内容发给 Routine 的 API 端点（text 字段传入报警体）。Routine 拉取堆栈跟踪，关联最近的 commit，创建含修复建议的 PR 草稿，并链接回告警。值班工程师直接 Review PR，而不是对着空白终端从头开始。

3. 定制代码审查（GitHub 触发）#

PR 创建时自动触发。Routine 根据团队自定义的审查清单，对安全、性能、风格问题留内联评论，并添加摘要评论——让人工 Reviewer 专注于设计决策，而不是机械检查。

4. 部署验证（API 触发）#

CD 流水线每次部署后调用 Routine 的 API 端点。Routine 对新构建运行冒烟测试、扫描错误日志排查回归，在部署窗口关闭前向发布频道发出"通过/不通过"信号。

5. 文档漂移检测（Schedule 触发）#

每周运行。Routine 扫描自上次以来合并的 PR，标记引用了已变更 API 的文档，并向文档仓库提交更新 PR 供编辑审查。

6. 跨语言 SDK 同步（GitHub 触发）#

监听 SDK 仓库的 PR 合并事件，自动将变更移植到另一语言的 SDK 并开 PR——保持两个库同步，无需人工重复实现。

创建 Routine#

方式一：Web 界面（推荐）#

访问 claude.ai/code/routines，点击 New routine，按以下 7 步配置：

第 1 步：填写名称和 Prompt

Prompt 是最关键的部分。Routine 自主运行，因此 Prompt 必须：

• 自包含（不依赖对话历史）
• 明确说明要做什么
• 明确定义"成功"是什么样子

Prompt 输入框内有模型选择器，每次运行都使用所选模型。

第 2 步：选择 Repository

添加一个或多个 GitHub Repository。每次运行时，Repository 从默认分支克隆。Claude 把变更提交到以 claude/ 为前缀的分支。

第 3 步：选择运行环境（Environment）

Environment 控制云端会话能访问什么：

• Network access：互联网访问级别
• Environment variables：API Keys、Token 等密钥
• Setup script：依赖安装脚本（结果会被缓存，不会每次重新运行）

默认 Environment 使用 Trusted 网络策略，允许访问常见的包注册表、云服务商 API、容器注册表等，但拦截其他域名。如果 Routine 需要访问自己的服务，在运行前编辑 Environment 的网络访问设置。

第 4 步：选择触发器

在 Select a trigger 区域选择触发方式，可以多种组合。详见下节"三种触发器详解"。

第 5 步：检查 Connectors 和权限

• Connectors：所有已连接的 MCP Connector 默认全部包含。移除 Routine 不需要的，以缩小权限范围。Claude 在运行中可以调用所有已包含 Connector 的任意工具（包括写操作），无需额外确认。
• Permissions：如果 Claude 应该能直接推送到现有分支（而不只是 claude/ 前缀的分支），为该 Repository 启用 Allow unrestricted branch pushes。

第 6 步：创建

点击 Create。Routine 出现在列表中，等待下一次触发时运行。要立即运行，在 Routine 详情页点击 Run now。

每次运行都会在你的 Session 列表中创建一个新 Session，可以查看 Claude 做了什么、Review 变更、创建 PR。

方式二：CLI 的 /schedule 命令#

在任意会话中运行 /schedule，通过对话方式创建定时 Routine：

# 自然语言描述
/schedule daily PR review at 9am

# 创建一次性运行
/schedule tomorrow at 9am, summarize yesterday's merged PRs
/schedule in 2 weeks, open a cleanup PR that removes the feature flag

CLI 限制：/schedule 只能创建 Schedule 触发的 Routine。API 和 GitHub 触发器只能在 Web 界面添加。

其他 CLI 管理命令：

/schedule list      # 列出所有 Routines
/schedule update    # 修改某个 Routine
/schedule run       # 立即触发运行

三种触发器详解#

触发器一：Schedule（定时触发）#

在创建/编辑表单的 Select a trigger 里选择预设频率：每小时、每天、工作日、每周。时间按本地时区输入，自动换算，无论云端基础设施在哪里，都会在该本地时钟时间运行。

运行可能因 stagger（错峰） 比计划时间晚几分钟。偏移量对每个 Routine 是固定的。

自定义 Cron 间隔：

在表单里选最接近的预设，然后用 CLI 更新到具体的 Cron 表达式：

/schedule update

最小间隔为 1 小时，更频繁的表达式会被拒绝。

一次性运行：

/schedule in 2 weeks, clean up the feature flag experiment-checkout-v2

Claude 把自然语言时间解析为具体时间戳，确认后保存。运行后自动禁用，Web UI 标记为 Ran。

一次性运行不计入每日 Routine 运行配额，和普通 Session 一样消耗订阅用量。

触发器二：API 触发#

API 触发为 Routine 提供专属的 HTTP 端点。向该端点 POST 即可启动新 Session。

添加 API 触发器（仅 Web 界面）：

1. 打开 Routine 编辑页面
2. 在 Select a trigger 区域点击 Add another trigger → 选 API
3. 记下 URL，点击 Generate token 并立即复制（Token 只展示一次）
4. 把 Token 存入目标系统的密钥存储

触发请求格式：

curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01ABCDEFGHJKLMNOPQRSTUVW/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 告警 SEN-4521 在 prod 触发。以下是堆栈跟踪。"}'

text 字段是可选的，传入运行特定的上下文（告警内容、日志等），以纯文本形式传递给 Routine 的 Prompt。

响应：

{
  "type": "routine_fire",
  "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
  "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}

在浏览器打开 session_url 可以实时查看运行进度。

Token 管理：每个 Routine 有自己的 Token，只能触发该 Routine。轮换或撤销时，在 Routine 编辑页面的 API 触发器部分点击 Regenerate 或 Revoke。

API 说明：/fire 端点在 experimental-cc-routine-2026-04-01 Beta Header 下，不属于 Claude Platform API 主线。Breaking Changes 会发布新的日期版 Header，旧的两个版本会继续支持一段时间。

触发器三：GitHub 事件触发#

GitHub 触发器在匹配的 Repository 事件发生时自动启动新 Session。每个匹配事件启动一个独立 Session，Session 之间不共享上下文。

添加 GitHub 触发器（仅 Web 界面）：

1. 打开 Routine 编辑页面
2. Select a trigger → Add another trigger → GitHub event
3. 如果 Claude GitHub App 未安装，触发器设置会提示你安装
4. 选择 Repository、事件类型、可选过滤器

注意：/web-setup 只授予 Repository 克隆访问，不安装 GitHub App，不启用 Webhook 推送。GitHub 触发器需要单独安装 Claude GitHub App。

支持的事件：

在每个类别内可选特定动作（如 pull_request.opened）或响应该类别的所有动作。

PR 过滤器：

每个过滤器的操作符：等于、包含、以…开头、是其中之一、不是其中之一、匹配正则。

正则注意：matches regex 测试整个字段值。要匹配包含 hotfix 的任何标题，写 .*hotfix.*，而不只是 hotfix。纯子字符串匹配用 contains 操作符更简单。

实用过滤组合：

• Auth 模块专项审查：base branch = main + head branch 包含 auth-provider
• 只审查非草稿 PR：is draft = false
• 标签控制的 Backport：labels 包含 needs-backport

每日 Webhook 频率限制：研究预览期间，GitHub 事件有每 Routine 和每账户的每小时上限，超过后会丢弃事件，直到窗口重置。

管理 Routine 运行#

查看和分析运行结果#

点击运行记录进入完整的 Session 视图：查看 Claude 做了什么、Review 变更、创建 PR、或继续对话。

绿色状态 ≠ 任务成功：绿色只表示 Session 正常启动和退出，不代表 Prompt 里的任务成功完成。必须打开运行记录查看 Claude 实际做了什么。网络请求被拦截、Connector 工具缺失、任务级失败，都会出现在运行记录里而不是状态指示器上。

编辑和控制 Routine#

从 Routine 详情页可以：

• Run now：不等下次触发，立即启动一次运行
• 暂停/恢复：点击 Repeats 部分的开关（保留配置但不运行，直到重新启用）
• 编辑：点击铅笔图标修改名称、Prompt、Repository、Environment、Connector、触发器
• 删除：点击删除图标（过去的运行记录保留在 Session 列表中）

权限和安全#

分支权限#

默认情况下，Claude 只能推送到 claude/ 前缀的分支，防止意外修改受保护的分支。

要移除某个 Repository 的这个限制（允许推送到任意分支），在创建或编辑 Routine 时为该 Repository 启用 Allow unrestricted branch pushes。

Connector 权限范围#

Claude 在运行时可以使用所有已包含 Connector 的任何工具（包括写操作），无需确认。因此：

• 只添加 Routine 实际需要的 Connector
• 创建 Routine 专用的受限 Connector 账户
• 定期审查 Connector 列表

Routine 归属#

Routine 属于个人 claude.ai 账户，不与团队成员共享。Routine 通过你关联的 GitHub 身份或 Connector 账户执行操作——commit、PR、Slack 消息都会显示为你的账户发出的。

网络访问配置#

需要访问自定义域名时：

1. 在 Routine 编辑页面打开环境选择器
2. 悬停在环境名称上，点击设置图标
3. 将 Network access 改为 Custom，在 Allowed domains 里输入域名
4. 勾选 Also include default list 保留默认允许列表

可选访问级别：

• Trusted（默认）：常见包注册表、云服务商 API、容器注册表等
• Custom：默认列表 + 自定义域名
• Full：不限制（慎用）

MCP Connector 的流量通过 Anthropic 的服务器路由，不需要在 Allowed domains 里添加。

用量和限制#

Routines 消耗订阅用量，和交互式 Session 相同。额外限制：

• 每日运行配额：每账户每天的 Routine 运行次数有上限
• 超配用量：启用了 Extra Usage 的 Team/Enterprise 可以在超出配额后继续运行（按计量收费）
• 一次性运行：不计入每日配额，但和普通 Session 一样消耗订阅用量

在 claude.ai/code/routines 或 claude.ai/settings/usage 查看当前用量和剩余配额。

相关功能对比#

来源：Claude Code 官方文档 - Automate work with routines | 整理：ClaudeEagle