介绍
# Cron Mastery
**规则 #1：心跳会漂移。Cron 是精确的。**
本技能提供了在 OpenClaw 2026.2.15+ 版本中管理时间的权威指南。它通过强制将非正式检查（心跳）与硬性计划严格分离，解决了“我错过了提醒”的问题。
## 核心原则
| 系统 | 行为 | 最适用场景 | 风险 | | :--- | :--- | :--- | :--- | | **心跳** | “我会尽可能检查”（例如每 30-60 分钟） | 邮件检查、非正式新闻摘要、低优先级轮询。 | **漂移：** 如果心跳间隔为 30 分钟，“10 分钟后提醒我”的任务将会失败。 | | **Cron** | “我会在准确的 X 时间运行” | 提醒（“5 分钟后”）、每日报告、系统维护。 | **杂乱：** 会创建需要清理的一次性任务。 |
## 1. 设置可靠的提醒（2026.2.15+ 标准）
**规则：** 绝不要使用 `act:wait` 或内部循环来处理长时间延迟（>1 分钟）。请使用带有一次性 `at` 计划的 `cron:add`。
### 精度与“调度器刻度” 虽然 Cron 是精确的，但执行取决于 **网关心跳**（通常每 10-60 秒）。设置为 `:00` 秒的任务将在该时间之后的第一个“刻度”触发。根据您的网关配置，预计会有最多约 30 秒的差异。
### 现代一次性提醒模式 请使用此负载结构来处理“X 分钟后提醒我”的任务。
**主要特性 (v2026.2.15+)：** - **负载选择：** 使用 **AgentTurn** 配合 **严格指令** 用于推送通知（会通过手机震动提醒您的提醒）。仅将 **systemEvent** 用于静默日志或后台状态更新。 - **可靠性：** `nextRunAtMs` 损坏和“添加后更新”的死锁问题已解决。 - **自动清理：** 一次性任务在成功后会自动删除（`deleteAfterRun: true`）。
**关键：推送通知与静默日志**
- **systemEvent (静默)：** 将文本注入聊天记录。非常适合后台日志，但在 Telegram/WhatsApp 上 **不会** 推送通知到用户的手机。 - **AgentTurn (主动)：** 唤醒代理以传递消息。推送通知 **必须** 使用此方式。使用“严格”提示词以避免 AI 闲聊。
**用于推送通知提醒（可靠）：** ```json { "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" } } ```
**用于后台日志（静默）：** ```json { "name": "Log: System Pulse", "schedule": { "kind": "every", "everyMs": 3600000 }, "payload": { "kind": "systemEvent", "text": "[PULSE] System healthy." }, "sessionTarget": "main" } ```
### Cron 并发规则（已稳定） 在 2026.2.15 之前，“添加后更新”模式会导致死锁。虽然现在已稳定，但为了实现最高效率，将所有参数（包括 `wakeMode: "now"`）直接在初始 `cron.add` 调用中传递仍然是 **最佳实践**。
## 2. 清理工（自动清理）- 遗留模式
**注意：** 自 v2026.2.14 起，OpenClaw 包含 **维护重算语义**。网关现在会自动清理卡住的任务并修复损坏的计划。
**仅在以下情况需要手动清理：** - 使用 `deleteAfterRun: false` 创建的一次性任务。 - 您不再需要的过时的循环任务。
### 为什么要使用 `sessionTarget: "main"`？（关键） 子代理（`isolated`）通常受限于工具策略，无法调用 `gateway` 或删除其他 `cron` 任务。对于像清理工这样的系统维护，请务必通过 `systemEvent` 定位到 `main` 会话，以便主代理（拥有完整工具访问权限）执行清理。
## 3. 参考：时区锁定
为了使 cron 正常工作，代理 **必须** 知道其时间。 * **操作：** 将用户的时区添加到 `MEMORY.md`。 * **示例：** `Timezone: Cairo (GMT+2)` * **验证：** 如果用户说“晚上 9 点提醒我”，在排程前请确认：“是开罗时间晚上 9 点吗？”。
## 4. 自唤醒规则（行为）
**问题：** 如果你说“我会等待 30 秒”并结束你的回合，你就会进入睡眠。如果没有事件，你无法唤醒自己。 **解决方案：** 如果你需要跨回合“等待”，你 **必须** 安排一个 Cron 任务。
* **等待 < 1 分钟（交互式）：** 仅允许在保持工具循环开启时使用（使用 `act:wait`）。 * **等待 > 1 分钟（异步）：** 使用 Cron 并设置 `wakeMode: "now"`。
## 5. 遗留迁移指南
如果您有使用以下模式的旧 cron 任务，请更新它们：
| 遗留 (Pre-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.update` 在 `cron.add` 之后 | 单步 `cron.add` 包含所有属性 |
## 故障排除
* **“我的提醒没有触发”：** 检查 `cron:list`。验证 `at` 时间戳是否在未来（ISO 8601 格式）。确保设置了 `wakeMode: "now"`。 * **“网关超时 (10000ms)”：** 如果 `cron` 工具耗时过长（任务列表过大或文件锁定），会发生此情况。 - **修复 1：** 如果文件已损坏，请手动删除 `~/.openclaw/state/cron/jobs.json` 并重启网关。 - **修复 2：** 运行手动扫描以减少任务数量。 * **“任务已运行但我未收到消息”：** 确保对主动唤醒使用了 **严格指令模式**，结合 `agentTurn` + `announce` 模式。 * **“提醒消息包含额外评论”：** 子代理正在进行对话式交流。请使用严格提示词模式：`"DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Your message here"`