定时任务 (Cron)

Cron vs Heartbeat？ 参见 Cron vs Heartbeat 了解何时使用哪种方式。

Cron 是网关内置的调度器。它持久化任务、在正确的时间唤醒代理，并可选择将输出投递回聊天。

如果您想要*"每天早上运行这个"或"20 分钟后提醒代理"*，cron 就是实现机制。

快速入门

Cron 在网关内部运行（不是在模型内部）
任务持久化在 ~/.clawdbot/cron/ 下，重启不会丢失
两种执行风格：
- 主会话：入队系统事件，在下次心跳时运行
- 隔离：在 cron:<jobId> 中运行专用代理轮次，可选投递输出
唤醒是一等公民：任务可以请求"立即唤醒"vs"下次心跳"

基础概念

1) 选择调度方式

一次性提醒 → schedule.kind = "at"（CLI: --at）
重复任务 → schedule.kind = "every" 或 schedule.kind = "cron"
如果 ISO 时间戳省略时区，将被视为 UTC

2) 选择运行位置

sessionTarget: "main" → 在下次心跳期间运行，使用主上下文
sessionTarget: "isolated" → 在 cron:<jobId> 中运行专用代理轮次

3) 选择载荷

主会话 → payload.kind = "systemEvent"
隔离会话 → payload.kind = "agentTurn"

可选：deleteAfterRun: true 成功后删除一次性任务

调度类型

at：一次性时间戳（毫秒时间戳或 ISO 8601）
every：固定间隔（毫秒）
cron：5 字段 cron 表达式，可选 IANA 时区

主会话 vs 隔离执行

主会话任务（系统事件）

入队系统事件并可选唤醒心跳运行器：

wakeMode: "next-heartbeat"（默认）：事件等待下次计划心跳
wakeMode: "now"：事件触发立即心跳运行

隔离任务（专用 cron 会话）

在会话 cron:<jobId> 中运行专用代理轮次：

提示前缀为 [cron:<jobId> <job name>] 以便追踪
每次运行开始一个新会话 ID（无之前对话延续）
摘要发布到主会话（前缀 Cron，可配置）
如果 payload.deliver: true，输出投递到渠道

适用于：嘈杂、频繁的"后台杂务"，不应干扰主聊天历史。

投递（渠道 + 目标）

隔离任务可以投递输出到渠道：

channel: whatsapp / telegram / discord / slack / mattermost / signal / imessage / last
to: 渠道特定的接收者目标

CLI 示例

一次性提醒（UTC ISO，成功后自动删除）

clawdbot cron add \
  --name "发送提醒" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "提醒：提交费用报告。" \
  --wake now \
  --delete-after-run

周期性隔离任务（投递到 WhatsApp）

clawdbot cron add \
  --name "每日状态" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结今日收件箱 + 日历。" \
  --deliver \
  --channel whatsapp \
  --to "+8613800138000"

带模型和思考覆盖的隔离任务

clawdbot cron add \
  --name "深度分析" \
  --cron "0 6 * * 1" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "每周项目进度深度分析。" \
  --model "opus" \
  --thinking high \
  --deliver \
  --channel whatsapp \
  --to "+8613800138000"

手动运行（调试）

clawdbot cron run <jobId> --force

编辑现有任务

clawdbot cron edit <jobId> \
  --message "更新的提示" \
  --model "opus" \
  --thinking low

查看运行历史

clawdbot cron runs --id <jobId> --limit 50

配置

{
  cron: {
    enabled: true,
    store: "~/.clawdbot/cron/jobs.json",
    maxConcurrentRuns: 1
  }
}

禁用 cron：

cron.enabled: false（配置）
CLAWDBOT_SKIP_CRON=1（环境变量）

存储

任务存储：~/.clawdbot/cron/jobs.json
运行历史：~/.clawdbot/cron/runs/<jobId>.jsonl

故障排除

"什么都不运行"

检查 cron 是否启用：cron.enabled 和 CLAWDBOT_SKIP_CRON
检查网关是否持续运行（cron 在网关进程内运行）
对于 cron 调度：确认时区（--tz）vs 主机时区

Telegram 投递到错误位置

对于论坛主题，使用 -100…:topic:<id> 以便明确无歧义

概览 Webhooks