名称： cron-mastery
描述： 精通 OpenClaw 的定时系统。用于安排可靠的提醒、设置定期维护（清理任务），并理解何时对时间敏感任务使用 Cron 而非 Heartbeat。

Cron 精通指南

第一法则：心跳会漂移，Cron 是精确的。

本技能为管理 OpenClaw 2026.2.15+ 中的时间提供了权威指南。它通过严格区分临时检查（心跳）和硬性计划（cron），解决了“我错过了提醒”的问题。

核心原则

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

规则： 切勿使用 act:wait 或内部循环进行长时间延迟（>1 分钟）。使用带有一次性 at 计划的 cron:add。

精确度与“调度器节拍”

虽然 Cron 是精确的，但其执行依赖于网关心跳（通常每 10-60 秒一次）。一个设置为 :00 秒的任务将在该时间之后的第一个“节拍”触发。根据您的网关配置，可能会有最多约 30 秒的差异。

现代一次性提醒模式

对于“X 分钟后提醒我”的任务，请使用此负载结构。

关键特性（v2026.2.15+）：
- 负载选择： 使用严格指令的 AgentTurn 来发送推送通知（会触发手机提醒的提醒）。仅将 systemEvent 用于静默日志或后台状态更新。
- 可靠性： nextRunAtMs 损坏和“先添加后更新”死锁问题已解决。
- 自动清理： 一次性任务在成功后自动删除（deleteAfterRun: true）。

关键：推送通知 vs. 静默日志

• systemEvent（静默）： 将文本注入聊天历史。非常适合后台日志，但不会在 Telegram/WhatsApp 上触发用户的手机通知。
• AgentTurn（主动）： 唤醒代理来传递消息。推送通知必需使用此方式。使用“严格”提示词以避免 AI 闲聊。

用于推送通知提醒（可靠）：

{
  "name": "提醒：喝水",
  "schedule": { "kind": "at", "at": "2026-02-06T01:30:00Z" },
  "payload": {
    "kind": "agentTurn",
    "message": "请将以下信息原封不动地传递给用户，不要修改或添加任何评论：\n\n💧 喝水啦，Momo！"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce", "channel": "telegram", "to": "1027899060" }
}

用于后台日志（静默）：

{
  "name": "日志：系统脉搏",
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": {
    "kind": "systemEvent",
    "text": "[脉搏] 系统运行正常。"
  },
  "sessionTarget": "main"
}

Cron 并发规则（已稳定）

在 2026.2.15 之前，“先添加后更新”模式会导致死锁。虽然现在已稳定，但为了获得最高效率，最佳实践仍然是在初始的 cron.add 调用中直接传递所有参数（包括 wakeMode: "now"）。

2. 清理任务（自动清理）- 遗留方案

注意： 自 v2026.2.14 起，OpenClaw 包含了维护性重新计算语义。网关现在会自动清理卡住的任务并修复损坏的计划。

仅在以下情况下需要手动清理：
- 使用 deleteAfterRun: false 创建的一次性任务。
- 不再需要的陈旧重复性任务。

为何使用 sessionTarget: "main"？（关键）

子代理（isolated）通常具有受限的工具策略，无法调用 gateway 或删除其他 cron 任务。对于像清理任务这样的系统维护，务必通过 systemEvent 将目标设为 main 会话，以便拥有完整工具访问权限的主代理执行清理。

3. 参考：时区锁定

要使 cron 正常工作，代理必须知道其时间。
* 操作： 将用户的时区添加到 MEMORY.md。
* 示例： 时区：开罗（GMT+2）
* 验证： 如果用户说“晚上 9 点提醒我”，请在安排前确认：“是开罗时间晚上 9 点吗？”

4. 自我唤醒规则（行为性）

问题： 如果你说“我等 30 秒”然后结束你的回合，你就会进入休眠状态。没有事件你无法醒来。
解决方案： 如果你需要跨回合“等待”，必须安排一个 Cron 任务。

• 等待 < 1 分钟（交互式）： 仅在你保持工具循环打开时允许（使用 act:wait）。
• 等待 > 1 分钟（异步）： 使用带有 wakeMode: "now" 的 Cron。

5. 遗留迁移指南

如果您有使用以下模式的旧 cron 任务，请更新它们：

故障排除

• “我的提醒没有触发”： 检查 cron:list。确认 at 时间戳是未来的（ISO 8601 格式）。确保设置了 wakeMode: "now"。
• “网关超时（10000ms）”： 如果 cron 工具耗时过长（任务列表巨大或文件锁），会发生此错误。
  • 修复方法 1： 如果文件损坏，手动删除 ~/.openclaw/state/cron/jobs.json 并重启网关。
  • 修复方法 2： 运行手动扫描以减少任务数量。
• “任务运行了但我没收到消息”： 确保您正在使用严格指令模式，即 agentTurn + announce 模式，以进行主动推送。
• “提醒消息有额外评论”： 子代理正在闲聊。请使用严格的提示词模式："请将以下信息原封不动地传递给用户，不要修改或添加任何评论：\n\n💧 您的消息写在这里"