# Claude Code Routines 与 /loop 调度

> Claude Code cloud routines、/schedule、/loop、Cron tools、Desktop scheduled tasks、GitHub/API 触发、网络权限和 5m/1h 缓存策略。

URL: https://docs.passion8.cc/docs/claude-code/routines-scheduling
Language: zh-CN
Publisher: Passion8

Claude Code 的调度能力分两层:

| 方式 | 运行位置 | 适合 |
| --- | --- | --- |
| `/loop` 和 Cron tools | 当前本地 session | 等 CI、轮询部署、短期提醒 |
| Routines 和 `/schedule` | Anthropic 托管云端 | 电脑关机后仍要定时跑、API/GitHub 触发 |
| Desktop scheduled tasks | 本机 Desktop | 需要本地文件和工具,但不想保持 CLI 会话 |
| GitHub Actions | CI 环境 | 仓库事件、标准化审计、团队流程 |




接入 Passion8 时,最稳的是本地 `/loop`。Routines 和 `/schedule` 是 claude.ai cloud 能力,通常要求 subscription 登录和官方云端环境。




## `/loop`

`/loop` 是会话内循环。它每次触发都是一轮普通 prompt,继承当前 session 的上下文、权限、MCP、模型和 Passion8 配置。

```text
/loop 5m check whether the deployment finished
```

```text
/loop check CI and address any review comments
```

| 写法 | 行为 |
| --- | --- |
| `/loop 5m <prompt>` | 固定间隔运行 |
| `/loop <prompt>` | 由 Claude 根据观察结果选择下一次间隔 |
| `/loop` | 使用内置维护 prompt 或 `.claude/loop.md` |
| `/loop 20m /review-pr 1234` | 周期性运行某个允许自动调用的 skill |

支持的间隔单位包括 `s`、`m`、`h`、`d`。底层是 cron,所以秒会向上取整到分钟;不能整除的间隔会被取到接近的 cron cadence。

## `loop.md`

裸 `/loop` 可以用自定义默认 prompt:

| 路径 | 作用域 |
| --- | --- |
| `.claude/loop.md` | 当前项目,优先级更高 |
| `~/.claude/loop.md` | 用户默认 |

示例:

```markdown title=".claude/loop.md"
检查当前 PR。如果 CI 失败,拉取失败日志并修复。若有 review comments,
逐条处理并回复。若一切安静,只输出一行状态。
```

`loop.md` 应该短。官方说明过长内容会被截断,而且每轮都会进入上下文,写得太大等于固定增加成本。

## Cron tools

Claude 也可以直接创建 session-scoped scheduled tasks。常见自然语言:

```text
in 45 minutes, check whether the integration tests passed
```

```text
remind me at 3pm to push the release branch
```

底层工具:

| Tool | 作用 |
| --- | --- |
| `CronCreate` | 创建一次性或重复任务 |
| `CronList` | 列出当前 session 的计划任务 |
| `CronDelete` | 按任务 ID 取消 |

限制:

| 限制 | 说明 |
| --- | --- |
| 依赖当前 session | 关闭终端或新开会话会停止 |
| resume 恢复 | 未过期的 recurring 或未来 one-shot 可以恢复 |
| 7 天过期 | recurring task 创建 7 天后自动删除 |
| 无补偿执行 | 错过多次不会补跑多次 |
| 单 session 上限 | 官方说明最多 50 个 scheduled tasks |

## 缓存策略

| 间隔 | 5 分钟 TTL | 1 小时 TTL |
| --- | --- | --- |
| 1 到 4 分钟 | 大概率持续热 | 持续热 |
| 5 到 10 分钟 | 可能贴边或冷 | 通常热 |
| 15 到 60 分钟 | 多数会冷 | 通常热 |
| 超过 1 小时 | 冷 | 冷 |

关键点:

1. `/loop` 每次触发都是普通新轮次,会刷新当前会话缓存。
2. 如果间隔超过 TTL,下一轮要重读历史。
3. 动态 `/loop` 如果选择长等待,5m TTL 下不应期待一直热。
4. Background session 仍是同一个 session,但停止期间不会刷新 TTL。
5. Routines 是云端独立 session,不共享本地 Passion8 prompt cache。

## Routines

Routine 是一份保存好的 Claude Code 配置:prompt、仓库、环境、connectors 和触发器。它运行在 Anthropic 托管云端,所以电脑关机也能继续。

触发器:

| 触发器 | 用途 |
| --- | --- |
| Schedule | 每小时、每天、每周或未来某个时间运行 |
| API | HTTP POST 到 routine endpoint 触发 |
| GitHub event | PR、release 等事件触发 |

Routine 适合:

| 场景 | 例子 |
| --- | --- |
| Backlog maintenance | 定期整理 issue、打标签、同步 Slack |
| Alert triage | 告警触发后分析日志并开草稿 PR |
| Custom code review | PR 打开时按团队 checklist 评论 |
| Deploy verification | 部署后跑 smoke check 并汇报 |
| Docs drift | 每周扫描代码变更并开文档更新 PR |

## `/schedule`

在 CLI 中,`/schedule` 用对话方式创建或管理 routines:

```text
/schedule daily PR review at 9am
```

```text
/schedule tomorrow at 9am, summarize yesterday's merged PRs
```

常用管理:

| 命令 | 作用 |
| --- | --- |
| `/schedule list` | 查看 routines |
| `/schedule update` | 修改 routine |
| `/schedule run` | 立即触发 |
| `/schedule <description>` | 创建定时 routine |

CLI 创建的主要是 schedule trigger。API 或 GitHub trigger 通常要到 [claude.ai/code/routines](https://claude.ai/code/routines) 配置。

## Routine 权限和网络

Routine 在云端自主运行,不会像本地交互式 session 一样每个工具都等你确认。要把权限收窄:

| 项目 | 控制 |
| --- | --- |
| Repositories | 只选 routine 必须访问的仓库 |
| Branch push | 默认只允许 `claude/` 前缀分支,不要随便开 unrestricted |
| Connectors | 默认可能包含所有已连接 connectors,删掉无关的 |
| Environment variables | 只注入必要 secret |
| Network access | 默认 trusted allowlist,访问内部服务要显式加域名 |
| Setup script | 安装依赖和工具,结果有环境缓存 |

MCP connector 流量走 Anthropic 托管连接,不等于云端 VM 可以访问同一个域名。需要本机数据库、局域网服务或本地文件时,用本地 `/loop` 或 Desktop task。

## API 触发

Routine API trigger 会生成一个专用 URL 和 bearer token。POST 到 `/fire` 会启动一个新 session,返回 session ID 和 URL。请求体可以带一个 `text` 字段,把告警、日志或部署信息传进去。

```bash
curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_xxx/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": "prod deploy failed, check alert SEN-4521"}'
```

这是 research preview 能力,header、限制和响应结构可能变。不要把 token 写进仓库。

## Passion8 下怎么选

| 需求 | 建议 |
| --- | --- |
| 用 Passion8 模型周期检查本地项目 | 本地 `/loop` |
| 超过 5 分钟但少于 1 小时的周期 | 尽量使用 1h TTL 的可用配置,否则接受冷启动 |
| 电脑关机也要跑 | 官方 Routines 或 GitHub Actions |
| 需要本机文件、数据库、局域网 | 本地 `/loop` 或 Desktop scheduled task |
| 需要 API 触发 Claude | 官方 Routine API 或自己封装 CI 调 `claude -p` |
| 想降低 token | prompt 写短,把稳定规则放 CLAUDE.md,不要每轮塞大日志 |

## 排错

| 问题 | 常见原因 |
| --- | --- |
| `/schedule` unknown command | 不是 claude.ai subscription 登录、版本太旧、非必要流量被禁用、或在 web session 内 |
| Routine 不运行 | 组织 Owner 禁用了 Routines、达到每日运行上限、usage credits 不足 |
| 云端访问私有服务 403 | environment network 没加 allowed domain |
| GitHub trigger 没触发 | 未安装 Claude GitHub App,或 filter 不匹配 |
| `/loop` 不自动继续 | session 关闭、任务过期、或按 Esc 停止了等待 |

## 官方参考

- [Scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks.md)
- [Routines](https://code.claude.com/docs/en/routines.md)
- [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md)
- [Commands](https://code.claude.com/docs/en/commands.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)