| name | cron-mastery |
| description | 掌握 OpenClaw 的计时系统。用于安排可靠的提醒、设置定期维护（管理员作业）以及了解何时使用 Cron 与 Heartbeat 来执行时间敏感的任务。 |
掌握 Cron
规则#1：心跳漂移。 Cron 是精确的。
该技能为 OpenClaw 2026.2.15+ 中的时间管理提供了权威指南。它通过严格区分临时检查（心跳）和硬性计划（cron）来解决“我错过了提醒”的问题。
核心原则
| 系统 | 行为 | 最适合 | 风险 |
|---|
| 心跳 | “我会尽可能检查”（例如，每 30-60m） | 电子邮件检查、随意的新闻摘要、低优先级的民意调查。 | 漂移： 如果心跳为 30m，“10m 内提醒我”任务将会失败。 |
| 计划 | “我会在 X 时间跑步” | 提醒（“5 分钟内”）、每日报告、系统维护。 | 混乱： 创建需要清理的一次性作业。 |
1.设置可靠的提醒（2026.2.15+标准）
规则： 切勿使用 act:wait 或内部循环来实现长时间延迟（>1 分钟）。将“cron:add”与一次性“at”计划结合使用。
精度和“调度器刻度”
虽然 Cron 很精确，但执行取决于 网关心跳（通常每 10-60 秒一次）。设置为 :00 秒的作业将在该时间之后的第一个“tick”处触发。根据您的网关配置，预计会有大约 30 秒的差异。
现代一次性提醒模式
使用此有效负载结构来执行“X 分钟内提醒我”的任务。
主要功能（v2026.2.15+）：
- 有效负载选择： 使用 AgentTurn 和 严格说明 来推送通知（对您的手机执行 ping 操作的提醒）。仅将 systemEvent 用于静默日志或后台状态更新。
- 可靠性：
nextRunAtMs 损坏和“先添加后更新”死锁已得到解决。
- 自动清理： 成功后自动删除一次性作业（
deleteAfterRun: true）。
关键：推送通知与静默日志
- systemEvent（无声）： 将文本插入聊天历史记录中。非常适合后台日志，但 不会 在 Telegram/WhatsApp 上 ping 用户的手机。
- AgentTurn（主动）： 唤醒代理以传递消息。 推送通知所需。使用“严格”提示来避免 AI 喋喋不休。
对于推送通知提醒（可靠）：
{
"name": "Remind: Water",
"schedule": { "kind": "at", "at": "2026-02-06T01:30:00Z" },
"payload": {
"kind": "agentTurn",
"message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Drink water, Momo!"
},
"sessionTarget": "isolated",
"delivery": { "mode": "announce", "channel": "telegram", "to": "1027899060" }
}
对于后台日志（静默）：
{
"name": "Log: System Pulse",
"schedule": { "kind": "every", "everyMs": 3600000 },
"payload": {
"kind": "systemEvent",
"text": "[PULSE] System healthy."
},
"sessionTarget": "main"
}
Cron 并发规则（稳定）
在 2026 年 2 月 15 日之前，“先添加后更新”模式会导致死锁。虽然现在已经稳定下来，但直接在初始 cron.add 调用中传递所有参数（包括 wakeMode: "now"）仍然是最佳实践，以获得最大效率。
2. 看门人（自动清理）- 遗产
注意： 自 v2026.2.14 起，OpenClaw 包含 维护重新计算语义。网关现在会自动清理卡住的作业并修复损坏的计划。
仅需要手动清理：
- 使用“deleteAfterRun: false”创建的一次性作业。
- 您不再需要的陈旧的重复工作。
为什么使用 sessionTarget: "main"？ （重要）
子代理（“隔离”）通常具有受限制的工具策略，并且无法调用“gateway”或删除其他“cron”作业。对于像 Janitor 这样的系统维护，始终通过“systemEvent”以“main”会话为目标，以便主代理（具有完整的工具访问权限）执行清理工作。
3.参考：时区锁定
为了让 cron 工作，代理必须知道它的时间。
- 操作： 将用户的时区添加到
MEMORY.md。
- 示例：
时区：开罗 (GMT+2)
- 验证： 如果用户说“晚上 9 点提醒我”，请确认：“开罗时间晚上 9 点？”在安排之前。
4.自我唤醒规则（行为）
问题： 如果你说“我等 30 秒”并结束你的回合，你就会去睡觉。如果没有发生任何事件，你就无法醒来。
解决方案： 如果您需要轮流“等待”，您 必须 安排一个 Cron 作业。
- 等待 < 1 分钟（交互式）： 仅当您保持工具循环打开时才允许（使用
act:wait）。
- 等待 > 1 分钟（异步）： 将 Cron 与
wakeMode: "now" 一起使用。
5. 旧版迁移指南
如果您有使用这些模式的旧 cron 作业，请更新它们：
| 旧版（2026.2.3 之前） | 现代（2026.2.15+） |
|---|
"schedule": {"kind": "at", "atMs": 1234567890} | "schedule": {"kind": "at", "at": "2026-02-06T01:30:00Z"} |
有效负载中的 "deliver": true | 不需要 - ‘announce’ 模式处理交付 |
"sessionTarget": "main" | "sessionTarget": "isolated"（默认行为） |
| 需要手动清理幽灵 | 一次性自动删除 (deleteAfterRun: true) |
cron.add 之后的 cron.update具有所有属性的单步“cron.add” | |
故障排除
- “我的提醒没有触发”： 检查
cron:list。验证“at”时间戳是否为将来的时间戳（ISO 8601 格式）。确保设置了“wakeMode：“now””。
- “网关超时（10000ms）”： 如果
cron 工具花费太长时间（巨大的作业列表或文件锁定），就会发生这种情况。
- 修复 1： 手动删除
~/.openclaw/state/cron/jobs.json 并在网关损坏时重新启动网关。
- 修复 2： 运行手动扫描以减少作业数量。
- “作业已运行，但我没有收到消息”： 确保您使用 严格指令模式 和
agentTurn + announce 模式来进行主动 ping。
- “提醒消息有额外的评论”： 子代理正在对话。使用严格的提示模式：“将这条确切的消息传递给用户，无需修改或注释：\n\n💧此处是您的消息”`
