cron-mastery

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💧此处是您的消息”`