Cron Mastery — 定时任务大师

规则 #1：心跳会漂移。Cron 是精确的。

此技能为 OpenClaw 2026.2.15+ 中的时间管理提供了权威指南。它通过严格区分临时检查（心跳）和硬调度（cron）来解决"我错过了提醒"的问题。

核心原则

1. 设置可靠提醒（2026.2.15+ 标准）

规则： 永远不要使用 act:wait 或内部循环进行长延迟（>1 分钟）。使用 cron:add 和一次性 at 调度。

精度与"调度器心跳"

现代一次性提醒模式

主要特性（v2026.2.15+）：

• 有效负载选择： 使用带严格指令的 AgentTurn 进行推送通知（在您手机上 ping 的提醒）。仅将 systemEvent 用于静默日志或后台状态更新。
• 可靠性： nextRunAtMs 损坏和"先添加再更新"死锁问题已解决。
• 自动清理： 一次性任务成功后自动删除（deleteAfterSuccess: true）。

提醒示例

cron:add:
  at: "5m"
  payload:
    type: "AgentTurn"
    strict: true
    agentPrompt: |
      提醒用户他们要求在 5 分钟前被提醒！
  deleteAfterSuccess: true

延迟消息示例

cron:add:
  at: "2026-06-01T09:00:00"
  payload:
    type: "AgentTurn"
    strict: true
    agentPrompt: |
      向用户发送一条消息，祝他们 6 月快乐！
  deleteAfterSuccess: true

2. 定期维护任务

每日报告

cron:add:
  schedule: "0 9   "  # 每天 UTC 时间上午 9 点
  payload:
    type: "systemEvent"
    event: "daily.report"
  id: "daily-report"
  deleteAfterSuccess: false

每周清理

cron:add:
  schedule: "0 2   0"  # 每周日 UTC 时间凌晨 2 点
  payload:
    type: "systemEvent"
    event: "cleanup.temp"
  id: "weekly-cleanup"
  deleteAfterSuccess: false

每月归档

cron:add:
  schedule: "0 3 1  "  # 每月 1 号 UTC 时间凌晨 3 点
  payload:
    type: "systemEvent"
    event: "archive.logs"
  id: "monthly-archive"
  deleteAfterSuccess: false

3. Cron 调度语法

标准的 Unix cron 格式：

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 月份中的日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期中的日期 (0-6) (0=周日到 6=周六，或使用名称)
│ │ │ │ │
│ │ │ │ │
    

快捷方式

• @yearly (或 @annually) - 每年一次，00:00 1月1日
• @monthly - 每月一次，00:00 每月 1 号
• @weekly - 每周一次，00:00 周日
• @daily (或 @midnight) - 每天一次，00:00
• @hourly - 每小时一次，每小时开始时

相对时间

除了 cron 表达式外，还可以使用相对时间：

• 5m - 5 分钟后
• 1h - 1 小时后
• 1d - 1 天后
• 1w - 1 周后

绝对时间

使用 ISO 8601 格式指定绝对时间：

• 2026-06-01T09:00:00 - 2026 年 6 月 1 日上午 9 点 UTC

4. 管理 Cron 任务

列出所有任务

cron:list

获取特定任务

cron:get:
  id: "daily-report"

更新任务

cron:update:
  id: "daily-report"
  schedule: "0 10   *"  # 更新为 UTC 时间上午 10 点

删除任务

cron:delete:
  id: "daily-report"

暂停任务

cron:pause:
  id: "daily-report"

恢复任务

cron:resume:
  id: "daily-report"

5. Heartbeat 的使用场景

在以下情况下使用 heartbeat 而非 cron：

• 非关键轮询 - 检查新邮件、获取最新新闻
• 后台同步 - 定期同步数据（可以接受几分钟偏差）
• 健康检查 - 验证服务是否在运行（可以接受错过几次）

Heartbeat 示例

# 这将自动每 30-60 分钟运行
act:onHeartbeat:
  do:
    - act: "检查新邮件"

6. 最佳实践

提醒任务

• 使用一次性任务并设置 deleteAfterSuccess: true
• 为提醒内容使用带 strict: true 的 AgentTurn
• 考虑时区（所有时间都是 UTC！）

定期任务

• 给任务一个描述性的 id，便于管理
• 设置 deleteAfterSuccess: false
• 在非高峰时间安排维护任务
• 为长时间运行的任务添加上下文日志记录

错误处理

• 监控失败的任务（cron:list 显示最后状态）
• 对于关键任务，考虑使用多个调度
• 添加检查点以避免重复处理

调试

• 使用 cron:history 查看任务运行历史
• 检查网关日志以获取执行详细信息
• 验证 cron 表达式使用 crontab.guru

7. 常见陷阱

❌ 错误做法

# 不要这样做 - 使用 act:wait 进行长时间延迟
act:wait:
  duration: "1h"
then:
  act: "提醒我"
# 不要这样做 - 心跳对于精确提醒太慢
act:onHeartbeat:
  if: "是时候提醒我了"
  then:
    act: "提醒我"

✅ 正确做法

# 这样做 - 对精确提醒使用 cron
cron:add:
  at: "1h"
  payload:
    type: "AgentTurn"
    strict: true
    agentPrompt: "提醒用户他们要求在 1 小时前被提醒！"
  deleteAfterSuccess: true

8. 高级模式

有条件提醒

cron:add:
  at: "1d"
  payload:
    type: "AgentTurn"
    strict: true
    agentPrompt: |
      检查用户是否已完成任务 X。
      如果没有，友好地提醒他们。
      如果有，祝贺他们并删除此提醒。
  deleteAfterSuccess: true

重试机制

cron:add:
  at: "5m"
  payload:
    type: "systemEvent"
    event: "deliver.message"
    data:
      message: "你好！"
      retryCount: 1
  id: "message-delivery-attempt-1"
  deleteAfterSuccess: true

链式任务

# 第一步：收集数据
cron:add:
  at: "0m"
  payload:
    type: "systemEvent"
    event: "collect.data"
  id: "collect-data"
  deleteAfterSuccess: true
# 第二步：处理数据（在第一步后 5 分钟）
cron:add:
  at: "5m"
  payload:
    type: "systemEvent"
    event: "process.data"
  id: "process-data"
  deleteAfterSuccess: true
# 第三步：发送报告（在第二步后 10 分钟）
cron:add:
  at: "15m"
  payload:
    type: "systemEvent"
    event: "send.report"
  id: "send-report"
  deleteAfterSuccess: true

参考资料

• OpenClaw Cron 文档
• Crontab Guru - cron 表达式验证器
• OpenClaw 社区论坛