学习笔记 当前专题

Claude Code Schedule 技能

定时代理与远程代理完整使用指南

一、技能概述

Schedule 是 Claude Code 内置的一项强大技能，允许用户创建、更新、列出和运行按 Cron 调度执行的远程代理（Routines）。这些代理在云端独立运行，无需本地终端保持连接，是实现定时自动化任务的核心工具。

通过 Schedule 技能，开发者可以将重复性工作（如代码审查、报告生成、数据抓取、定时部署）交由远程代理自主完成，大幅提升工作效率。

核心能力：

  • 在远程服务器上创建持久化代理
  • 使用 Cron 表达式精确控制调度频率
  • 查看和管理所有已创建的调度代理
  • 支持一次性执行和周期性执行两种模式

二、什么是远程代理

远程代理（Remote Agent / Routine）是 Claude Code 在 Anthropic 云端基础设施上运行的自包含任务单元。与本地会话不同，远程代理具有以下特征：

远程代理的特点

  • 独立运行： 脱离本地终端环境，在云端沙箱中执行
  • 持久化存储： 代理状态和文件保存在远程存储中，跨多次执行持久存在
  • 定时触发： 通过 Cron 调度器自动唤醒执行
  • 安全隔离： 每个代理运行在独立的沙箱环境中，互不干扰
  • 日志记录： 每次执行的结果和输出自动保存，可供查阅

远程代理非常适合无需人工干预的自动化场景。用户只需定义任务指令和调度规则，代理就会按照预定计划自主执行。

三、Cron 调度机制

Schedule 技能使用标准的 Cron 表达式来定义代理的执行时间规则。Cron 表达式由 5 个字段组成，分别表示分钟、小时、日期、月份、星期。

* * * * * ┬ ┬ ┬ ┬ ┬ │ │ │ │ └─ 星期 (0-7, 0和7都表示周日) │ │ │ └─── 月份 (1-12) │ │ └───── 日期 (1-31) │ └─────── 小时 (0-23) └───────── 分钟 (0-59)

常用 Cron 示例

*/5 * * * * 每 5 分钟执行一次 0 * * * * 每小时整点执行 0 9 * * * 每天上午 9:00 执行 0 0 * * * 每天午夜执行 0 0 * * 1 每周一凌晨执行 0 0 1 * * 每月 1 号凌晨执行 */30 9-18 * * * 每天 9:00-18:00 每 30 分钟执行
提示：Claude Code 使用的 Cron 调度基于 UTC 时间。如果需要特定时区的触发时间，请根据 UTC 偏移量计算相应的 Cron 表达式。

四、创建定时代理

使用 /schedule create 命令创建新的定时代理。创建时需要提供代理的任务描述和 Cron 调度表达式。

基本语法

/schedule create "每 30 分钟检查一次 GitHub PR 状态" --cron "*/30 * * * *"

创建成功后，Claude Code 会返回代理的唯一 ID，可用于后续的管理操作。

创建时的最佳实践

任务指令编写要点

  1. 明确指定代理的目标和输出要求
  2. 包含必要的上下文信息（如仓库路径、API 密钥等）
  3. 设置清晰的成功/失败判定标准
  4. 指定执行结果的输出方式（日志、文件、通知等）
  5. 考虑执行超时和错误处理策略

五、管理定时代理

Schedule 技能提供完整的代理生命周期管理功能，包括查看、更新和删除操作。

列出所有代理

/schedule list

该命令会显示所有已创建的代理列表，包括每个代理的 ID、任务描述、Cron 表达式、上次执行时间和下次执行时间。

更新现有代理

/schedule update <agent-id> --cron "0 9 * * *"

可以更新代理的调度频率或任务指令，无需重新创建。支持修改以下属性：

删除代理

/schedule delete <agent-id>

删除指定代理后，其关联的远程存储数据也会被清理。

提示：代理 ID 是管理代理的唯一标识，建议在创建后及时记录。可以通过 /schedule list 随时查看所有代理的 ID。

六、运行与监控代理

创建定时代理后，代理会在指定时间自动触发。用户也可以通过命令手动触发一次立即执行。

手动触发执行

/schedule run <agent-id>

该命令会立即执行指定代理，不考虑其预定的 Cron 调度。适用于：

查看执行结果

每次执行的结果会自动保存，可以通过以下方式查看：

  • 执行日志：代理执行的完整输出记录
  • 退出状态：成功（0）或失败（非0）状态码
  • 执行时间：每次执行的开始和结束时间戳
  • 错误信息：执行失败时的详细错误描述

七、持久化与会话代理对比

理解持久化代理与会话代理的区别，对于正确使用 Schedule 技能至关重要。

持久化代理（Persistent Agent）

  • 状态持久保存在云端存储中
  • 每次执行之间保留文件系统状态
  • 支持增量更新和累计数据
  • 适合长期运行的数据收集和监控任务
  • Cron 调度触发，无需人工介入

会话代理（Session-Only Agent）

  • 状态仅在单次执行中有效
  • 每次执行从干净环境开始
  • 执行结束后所有数据被清理
  • 适合不需要跨次持久化的独立任务
  • 需要保持终端连接才能运行
选择建议：如果任务需要积累历史数据或维护跨次状态（如日志聚合、增量备份），选择持久化代理。如果任务是幂等的且每次独立（如定时健康检查、一次性报告生成），会话代理更简单安全。

八、典型使用场景

代码仓库自动化

/schedule create "检查仓库 main 分支是否有新的 PR，如果有则自动运行测试并评论结果" --cron "0 */2 * * *"

定时报告生成

/schedule create "汇总最近 24 小时的项目活动：新 issue、合并的 PR、发布版本，生成 Markdown 报告并保存到 reports/ 目录" --cron "0 9 * * *"

数据抓取与监控

/schedule create "访问目标网站检查页面变化，如有更新则下载新内容并记录变更日志" --cron "*/15 * * * *"

定时部署与维护

/schedule create "执行数据库备份脚本，将备份文件上传到 S3 存储桶，保留最近 7 天的备份" --cron "0 3 * * *"

场景共性：

  • 任务可完全自动化，无需人工决策
  • 执行频率固定，有明确的时间规律
  • 失败可重试或降级，不影响核心业务
  • 输出结果便于后续审计和追溯

九、最佳实践

1. 任务指令要精确

远程代理没有人工交互机会，任务指令必须包含所有必要的上下文、决策规则和异常处理逻辑。指令越精确，代理执行越可靠。

2. 合理设置调度间隔

避免过于频繁的调度（如每分钟执行），这不仅消耗 Token 配额，还可能触发 API 限流。根据任务性质选择合理的执行间隔。

3. 实现幂等性

设计任务时确保重复执行不会产生副作用。例如，使用"如果已处理则跳过"的逻辑，而不是无条件重复操作。

4. 添加通知机制

对关键任务，在代理指令中加入通知逻辑（如发送 Slack 消息或邮件），确保在任务失败或异常时能够及时获知。

5. 定期审查代理

定期使用 /schedule list 审查所有代理的运行状态，清理不再需要的代理，更新过时的任务指令。

注意：远程代理执行会产生 Token 消耗，请关注使用配额。Anthropic 的 API 使用政策可能会有更新，建议定期查阅官方文档了解最新限制。

十、核心要点总结