Claude Code Routines：定时云端智能体、子例程与协同例程

这是一篇深度指南。如需五分钟速览，请阅读配套博客文章。

1. 为什么定时智能体很重要

直到不久之前，AI 编程智能体只有在有人盯着时才会工作。你打开终端，交给它一项任务，批准它的操作，再阅读结果。一旦关闭会话，工作就停止了。这种模式适合探索性工作，但大量工程工作既不是探索性的，也不紧急，而是周期性的：分拣夜间积累的 issue 队列、检查文档是否仍与 API 一致、按同一份检查清单评审每个拉取请求、在发布窗口关闭前验证部署。

想让智能体在无人值守的情况下完成这些工作的团队，过去只能自己搭建底层管道。常见做法是在 GitHub Actions 中配置 cron 任务、在机柜里放一台一直开着的闲置机器，或者使用 Trigger.dev、n8n 这类工作流引擎再外挂一个智能体调用。这些方案都行得通，但每一种都要围绕一条本质上很简单的指令，额外增加基础设施、凭据、成本和维护负担，而这条指令不过是：“每晚做这件事，然后告诉我你发现了什么。”

Routines 省去了这些管道。调度、算力、代码仓库检出和审计记录全部内置在 Claude Code 之中。

2. 什么是 routine

Anthropic 将 routine 定义为一份已保存的 Claude Code 配置，它由五个部分组成：

• 提示词。Claude 每次运行都会执行的指令。由于没有人在场回答问题，它必须自成一体，并明确说明“完成”是什么样子。你也在这里选择模型，每次运行都会使用该模型。
• 代码仓库。一个或多个 GitHub 仓库。每次运行开始时都会重新克隆，默认使用默认分支，除非提示词另有说明。
• 云环境。控制网络访问、环境变量，以及一个可选的用于安装依赖的初始化脚本。初始化结果会被缓存，因此不会每次都重新执行。
• 连接器。你 claude.ai 账户上的 MCP 集成，例如 Slack、Linear 或 Google Drive，routine 可以对其进行读取和写入。
• 触发器。定时、API 和 GitHub 事件中的一种或多种。单个 routine 可以同时组合这三种。

每次运行都是一个完整的 Claude Code 云端会话。它可以执行 shell 命令、使用已克隆仓库中提交的技能，并调用你所包含连接器上的全部工具。这里没有权限模式选择器，也没有任何步骤会等待批准。这种自主性正是其价值所在，也正因如此，范围界定才至关重要（参见第 8 节）。

3. 三种触发器类型

3.1 定时

最简单的触发器会按预设频率（每小时、每天、每个工作日或每周）运行 routine，或在未来某个特定时间运行一次。以下细节值得了解：

• 本地时间。你按自己的时区输入时间，由 Claude Code 自动换算，因此无论云端硬件位于何处，设定在 09:00 的运行都会在你当地时间 09:00 执行。一些早期的第三方指南称调度仅支持 UTC，但 Anthropic 的文档说法并非如此。
• 避开整点。恰好安排在整点的运行可能会延迟数分钟才启动。选择 09:07 而不是 09:00，时间会更可预测。
• 自定义 cron。对于预设未覆盖的间隔，例如每两小时一次或每月第一天，先选择最接近的预设，然后在 CLI 中运行 /schedule update 设置 cron 表达式。最小间隔为一小时，更频繁的设置会被拒绝。
• 一次性运行。用自然语言描述时间，例如 /schedule in 2 weeks, open a cleanup PR that removes the feature flag。Claude 会在保存前确认准确的时间戳。触发之后，该 routine 会自动停用并标记为 Ran。一次性运行不计入每日运行上限。

3.2 API

API 触发器为 routine 提供专属的 HTTPS 端点。任何能够发出经过身份验证的 POST 请求的系统都可以启动一次运行：告警工具、部署流水线、内部管理页面等。令牌在网页界面中生成，只显示一次，仅作用于该 routine，并可随时重新生成或撤销。

curl -X POST https://api.anthropic.com/v1/claude_code/routines/<ROUTINE_TRIGGER_ID>/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": "Error rate on checkout-api above 5% for 10 minutes."}'

响应中包含一个会话 ID 和一个会话 URL，打开后即可实时观看运行过程。可选的 text 字段用于携带本次运行的特定上下文。注重安全的团队应当注意：Claude Code 会将这段文本包裹在 <routine-fire-payload> 块中，并将其标记为不可信数据。除非 routine 自身保存的提示词要求使用该载荷，否则 Claude 不会执行其中的指令。如果你的 routine 需要根据告警正文采取行动，提示词应明确说明，例如：“调查 routine-fire-payload 块中描述的告警。”这种设计意味着，令牌泄露后他人虽能启动运行，却无法改写 routine 的指令。

该端点受一个带日期的 beta 请求头约束。Anthropic 表示，破坏性变更将以新的请求头版本发布，而之前的两个版本仍会继续可用，给调用方留出迁移时间。

3.3 GitHub 事件

每当已连接仓库上发生匹配的事件，GitHub 触发器就会启动一个新会话。这要求在该仓库上安装 Claude GitHub App。支持两类事件：

• 拉取请求：打开、关闭、指派、添加标签、同步以及其他更新。
• 发布（release）：创建、发布、编辑或删除。

过滤条件用于缩小哪些事件会被计入。你可以按作者、标题、正文、基础分支、头分支、标签、草稿状态和合并状态过滤，可用的运算符包括 equals（等于）、contains（包含）、starts with（开头为）、is one of（属于其一）、is not one of（不属于其一）和 matches regex（匹配正则）。所有条件都必须满足。有一个易踩的坑：matches regex 会对整个字段进行匹配，因此若要捕获任何包含 “hotfix” 的标题，需要写成 .*hotfix.*，而不是 hotfix。

每个事件都会产生独立的会话，因此向同一个拉取请求推送两次就意味着两次运行。在预览期间，GitHub 事件还受到按 routine 和按账户计算的每小时上限约束。超出上限的事件将被丢弃，直到时间窗口重置。

4. 逐步创建 routine

你可以在三个地方创建 routines：网页端 claude.ai/code/routines、Claude 桌面应用 Code 标签页中的 Routines 区域，或者 CLI。三者写入的是同一个账户，因此在其中一处创建的 routine 会立即出现在另外两处。

4.1 在网页端

1. 打开 claude.ai/code/routines 并选择 New routine。
2. 为它命名并编写提示词，选择模型。
3. 添加 Claude 需要处理的代码仓库。
4. 选择云环境。Default 环境具有 Trusted 网络访问级别，允许访问常见的软件包仓库、云服务商 API 和开发类域名。如果 routine 需要访问你自己的服务，请先调整该环境的允许域名。
5. 选择一个或多个触发器。对于 API 触发器，需要先保存 routine，之后才会生成 URL 和令牌。
6. 检查连接器。默认会包含你已连接的所有连接器，Claude 可以不经询问使用其上的每一个工具，包括写入操作。请移除任务不需要的任何连接器。
7. 选择 Create，然后选择 Run now 进行测试，再依赖正式调度。

4.2 通过 CLI

在任意本地 Claude Code 会话中，/schedule（别名 /routines）可以通过对话创建定时 routine。Claude 会询问执行频率、代码仓库和提示词，然后将其保存到你的账户。

/schedule daily PR review at 9am
/schedule tomorrow at 9am, summarise yesterday's merged PRs
/schedule list
/schedule update
/schedule run
/schedule why did my nightly review do nothing this morning?

最后一个示例尤其有用。Claude 会列出该 routine 最近的运行记录，读取相关日志并解释发生了什么，包括工具错误和权限拒绝。较新的 CLI 版本在安装 GitHub App 后，还可以通过对话添加 GitHub 触发器。不过，API 令牌只能在网页端创建或撤销。

如果 /schedule 无法识别，原因几乎总是身份验证。Routines 需要使用 claude.ai 订阅账户登录。使用 Console API 密钥、ANTHROPIC_API_KEY 环境变量，或 Amazon Bedrock 等云服务商登录方式时，该命令会被隐藏。在 Team 和 Enterprise 套餐中，Owner 还可以为整个组织关闭 routines。

5. 编写经得起无人值守运行的提示词

Routine 的提示词更像一份运行手册（runbook），而不是一条聊天消息。没有人在场澄清歧义，所以模糊的指令只会产生模糊的结果，更糟的是，产生你并不想要却又十分笃定的操作。请比较：

一个好的 routine 提示词应当说明：

• 范围：哪些仓库、哪个时间窗口、哪些条目。
• 允许的操作：Claude 可以修改什么，以及同样重要的，哪些内容绝不能碰。
• 输出：确切的目标位置和格式，例如草稿 PR、某个 Slack 频道或一条工单评论。
• 停止条件：无事可做时该怎么办，以及何时放弃。
• 载荷处理：对于 API 触发器，是否以及如何使用触发时传入的文本。

预计新 routine 在第一周内需要调整两到三次。请阅读运行记录，而不仅仅是状态徽标。Anthropic 明确指出，绿色状态只表示会话已启动并在没有基础设施错误的情况下退出，并不意味着任务成功完成。

6. 子例程：在一次运行内组织工作

Anthropic 并没有推出名为“子例程”（sub-routines）的功能。我们在 Workstation 用这个术语来指代一种设计模式，它能让长时间无人值守的运行可靠得多：routine 的提示词充当编排者，把每个定义明确的步骤委派给提交在仓库中的子智能体或技能。

之所以可行，是因为 Claude Code 的两个构建模块会随你的仓库一起分发：

• 子智能体（subagents）是位于 .claude/agents/ 中带有 YAML front matter 的 Markdown 文件。每个子智能体都有自己的系统提示词、工具白名单和可选模型，并在独立的上下文窗口中运行，只有摘要会返回给调用方。子智能体可以并行运行，默认情况下还能继续向下委派，最多三层。
• 技能（skills）位于 .claude/skills/ 中，用于封装可复用的流程，例如你们的发布说明风格或安全评审检查清单，Claude 会在相关时加载它们。Routines 使用已克隆仓库中提交的技能。

按这种方式构建的夜间维护 routine 大致如下：

# Routine prompt (orchestrator)
1. Use the issue-triager subagent to label and assign issues opened since the last run.
2. Pick the single highest-priority bug labelled "good-first-fix".
3. Use the bug-fixer subagent to implement a fix on a claude/ branch.
4. Use the test-runner subagent to run the test suite; if it fails twice, stop and report.
5. Open ONE draft PR, using the release-notes skill for the description.
6. Post a three-line summary to #eng-nightly.

# .claude/agents/issue-triager.md
---
name: issue-triager
description: Labels and assigns new issues. Never edits code.
tools: Read, Grep, Glob
model: haiku
---
You triage GitHub issues. Apply area labels from CODEOWNERS and
assign the owning team. Return a table of issue, label and owner.

好处非常实际。每个助手只看到它需要的内容，因此在长时间运行中，编排者的上下文始终精简而专注。每一步的工具权限更窄：上面的分拣子智能体根本无法编辑文件。机械性步骤可以交给更便宜的模型处理。而且由于子智能体和技能都纳入版本控制，对 routine 行为的任何修改都会像其他变更一样经过代码评审。

7. 协同例程：相互协作的 routines

同样，“协同例程”（co-routines）是我们的术语，而非 Anthropic 的功能。我们用它来指代多个相互独立、彼此交接工作的 routines，就像生产线把零件从一个工位传到下一个工位。Routines 之间无法直接调用，也不共享内存。取而代之的是，一个 routine 生成持久化的产物，而另一个 routine 的触发器负责监听它。

一条典型的链路：

1. Routine A（定时）在工作日夜间分拣待办事项，并从 claude/fix-… 分支创建草稿 PR。
2. Routine B（GitHub，pull_request.opened）过滤为头分支以 claude/ 开头的事件。它应用团队的评审检查清单并为 PR 添加标签。
3. 由人工评审并合并。这就是审批关卡。
4. Routine C（GitHub，pull_request.closed，merged = true）更新文档，或将变更移植到对应的兄弟 SDK，并创建后续 PR。
5. Routine D（API）在发布后由部署流水线调用。它运行冒烟检查并给出“可发布”或“不可发布”的结论。若结论为不可发布，它会在工单系统中创建一个 issue，由 Routine A 在第二天夜间接手。

交接渠道按结构化程度从高到低排列：

• GitHub 事件：原生支持、可过滤且完全可审计。
• 标签和分支命名约定：无需编写任何胶水代码即可路由工作。
• API 调用：来自 CI、监控或内部工具，载荷被视为不可信的上下文。
• 共享的工单或产物：例如一个 Linear issue 或状态页面，供下一次定时运行读取。

设计协同例程时要谨慎。使用过滤条件，确保 routine 永远不会被自己的产出触发，例如排除它自己创建的作者或分支。在任何编写代码的 routine 与任何负责发布的 routine 之间，保留一道人工合并。请记住，每个阶段都共用同一个账户级的每日运行上限和 GitHub 事件上限。如果你发现自己在大量 routines 之间构建分支逻辑、重试和扇出，说明这种模式已经不够用了，专门的工作流引擎才是更合适的工具。

8. 安全与治理

• Routines 以你的身份行事。Routines 属于单个 claude.ai 账户，不会与团队成员共享。提交和拉取请求带有你的 GitHub 身份，连接器操作使用你关联的账户。请把 routine 当作一个“带着大脑的个人访问令牌”来对待。
• 分支保护。Claude 默认推送到以 claude/ 为前缀的分支。它拒绝推送到受保护分支、他人有未关闭 PR 的分支，以及包含他人提交的分支。
• 最小权限。移除不需要的连接器。除非确需访问特定域名，否则将网络访问保持为 Trusted；被阻止的请求会以 403 和 x-deny-reason: host_not_allowed 失败。在 Pro 和 Max 套餐中，请将 API 密钥存储为环境的 API credentials（API 凭据），而不是普通变量，因为普通变量对使用该环境的任何人都可见。
• 不可信输入。API 载荷和 Run now 文本会被标记为不可信。运行期间获取的内容（例如 issue 正文和网页）仍按常规方式防范提示词注入。编写提示词时，要告诉 Claude 哪些内容可以信任。
• 连接健康状况。如果 GitHub 连接过期，运行最多会被跳过 72 小时，之后 routine 会自动关闭，直到你重新连接。
• 组织级控制。Team 和 Enterprise 的 Owner 可以在管理设置中为所有成员禁用 routines。

9. 套餐、用量与限制

Routines 与交互式会话以相同方式消耗订阅用量，每日上限在此基础上另行适用。你当前的额度显示在 claude.ai/code/routines，并可能在预览期间调整。启用用量额度（usage credits）后，超出上限的运行将按计量超额继续执行；未启用时，额外的运行会被拒绝，直到时间窗口重置。一次性定时运行不计入上限。订阅暂停期间，其 routines 也会暂停。

10. Routines 与其他调度方案的比较

10.1 Claude Code 内部

/loop 任务的作用域限于会话，并在七天后过期。它们非常适合在你工作时盯着某个构建或拉取请求，但不能替代 routine。

10.2 Claude Code 之外

• GitHub Actions 成本低廉，与代码放在一起，并能完全掌控运行器。代价是 YAML、密钥管理和运行器维护。确定性的构建步骤选择 Actions，需要判断力的工作选择 routines。
• 工作流引擎（例如 Trigger.dev）能处理重试、扇出和长时间运行的编排，但编排逻辑需要你用代码编写。当工作流本身就是产品时，请使用它们。
• 集成平台（例如 n8n 和 Zapier）擅长在 SaaS 工具之间传递数据，而 routines 擅长对代码、日志和文档进行推理。两者可以很好地结合：n8n 流程可以调用 routine 的 API 端点。

11. 效果良好的使用场景

• 待办事项梳理：夜间添加标签、指定负责人，并在早上生成摘要。
• 告警分拣：监控系统调用 API 触发器，Claude 将堆栈跟踪与近期提交关联起来，并创建草稿修复。
• 定制化代码评审：对每个待评审的 PR 应用你们自己的检查清单。
• 部署验证：每次发布后运行冒烟检查和日志扫描，最终给出“可发布”或“不可发布”的结论。
• 文档漂移：每周扫描已合并的 PR，并为引用了已变更 API 的文档创建更新 PR。
• 库移植：将一个 SDK 中已合并的变更同步到另一种语言的兄弟 SDK 中。
• 依赖治理：每周审查过时的软件包，并提交一个经过测试的统一升级 PR。

Routines 不太适合频率高于每小时一次的工作、运行中途需要人工决策的任务，以及带有重试机制的复杂多分支工作流。

12. 社区反响

反响褒贬不一，但总体偏正面。InfoQ 引用了一些工程师的观点，他们对通过 webhook 将 AI 直接接入可观测性仪表盘和 CI 工作流充满热情。也有人持怀疑态度，他们指出早期的 Claude 调度功能只能在用户自己的机器上运行，并认为在推出新功能之前，可靠性、正常运行时间和配额限制更值得关注。从我们的经验来看，routines 在安全方面设计得很好，尤其是不可信载荷的处理和分支保护。主要的运维风险在于连接器范围过宽，以及提示词不够具体。

13. Workstation 如何使用它

在 Workstation，我们为客户在 DevOps、财务运营和客户工作流等领域运行智能体自动化。Routines 与我们的方法高度契合：用确定性的基础设施承担底层管道，用 AI 负责判断，并在任何内容进入生产环境之前设置人工审批关卡。如果你希望获得帮助来设计 routine 链路、子智能体库或相关治理机制，欢迎联系我们的团队。

14. 要点总结

• Routine 由已保存的提示词、代码仓库、环境、连接器和触发器组成，在云端自主运行。
• 触发器可以是定时（最小间隔一小时，按本地时间）、API 调用（bearer 令牌，不可信载荷），或 GitHub 拉取请求或发布事件。
• 面向 Pro、Max、Team 和 Enterprise 开放，在正常用量之外另有每日运行上限。该功能仍处于研究预览阶段。
• 使用子例程（子智能体和技能），让单次长时间运行保持专注并遵循最小权限原则。
• 使用协同例程（通过 PR、标签和 API 调用相互交接的 routines）构建多阶段流水线，并在中间保留人工合并关卡。
• 严格限定连接器和网络访问范围，像编写运行手册一样编写提示词，并认真阅读运行记录。

资料来源与延伸阅读

• Anthropic：Introducing routines in Claude Code（2026 年 4 月 14 日）
• Claude Code 文档：Automate work with routines
• Claude Code 文档：Run prompts on a schedule (/loop)
• Claude Code 文档：Subagents
• Claude Platform 文档：Trigger a routine through the API
• InfoQ：Anthropic Introduces Routines for Claude Code Automation
• MindStudio：Claude Code Routines: How to Run Scheduled AI Agents Without a Server
• Tahir 发表于 Medium：What is Claude Code Routines?

Routines 目前处于研究预览阶段，其行为、限制和 API 可能会发生变化。本指南中的信息以截至 2026 年 9 月 25 日 Anthropic 公开发布的文档为准。