Cron Mastery 1.0.3

---
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 喋喋不休。

**对于推送通知提醒（可靠）：**
```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 日之前，“先添加后更新”模式会导致死锁。虽然现在已经稳定下来，但直接在初始 `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💧此处是您的消息”`