cron-mastery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cron Mastery

Cron 使用精通

Rule #1: Heartbeats drift. Cron is precise.

This skill provides the definitive guide for managing time in OpenClaw. It solves the "I missed my reminder" problem by enforcing a strict separation between casual checks (heartbeat) and hard schedules (cron).

规则1：Heartbeat会产生时间偏移，Cron则精准无误。

本技能为管理OpenClaw中的时间提供了权威指南，通过严格区分常规检查（Heartbeat）与硬性调度（Cron），解决了「我错过提醒」的问题。

The Core Principle

核心原则

System	Behavior	Best For	Risk
Heartbeat	"I'll check in when I can" (e.g., every 30-60m)	Email checks, casual news summaries, low-priority polling.	Drift: A "remind me in 10m" task will fail if the heartbeat is 30m.
Cron	"I will run at exactly X time"	Reminders ("in 5 mins"), daily reports, system maintenance.	Clutter: Creates one-off jobs that need cleanup.

系统	行为	适用场景	风险
Heartbeat	「我会在方便时进行检查」（例如，每30-60分钟一次）	邮件检查、日常新闻摘要、低优先级轮询	时间偏移：如果心跳间隔为30分钟，「10分钟后提醒我」的任务会失败。
Cron	「我会在精确的X时间运行」	提醒（「5分钟后」）、每日报告、系统维护	任务冗余：会创建需要清理的一次性任务。

1. Setting Reliable Reminders

1. 设置可靠提醒

Never use

act:wait

or internal loops for long delays (>1 min). Use

cron:add

with a one-shot

at

schedule.

绝对不要使用

act:wait

或内部循环来处理长延迟（超过1分钟）。请使用带有一次性

at

调度的

cron:add

。

Standard Reminder Pattern (JSON)

标准提醒模板（JSON）

Use this payload structure for "remind me in X minutes" tasks:

json

{
  "name": "Remind: Drink Water",
  "schedule": {
    "kind": "at",
    "atMs": <CURRENT_MS + DELAY_MS>
  },
  "payload": {
    "kind": "agentTurn",
    "message": "⏰ Reminder: Drink water!",
    "deliver": true
  },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat"
}

Note: Even with
wakeMode: "next-heartbeat"
, the cron system forces an event injection at
atMs
. Use
mode: "now"
in the
cron:wake
tool if you need to force an immediate wake outside of a job payload.

以下是「X分钟后提醒我」任务的负载结构：

json

{
  "name": "Remind: Drink Water",
  "schedule": {
    "kind": "at",
    "atMs": <CURRENT_MS + DELAY_MS>
  },
  "payload": {
    "kind": "agentTurn",
    "message": "⏰ Reminder: Drink water!",
    "deliver": true
  },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat"
}

注意：即使设置了
wakeMode: "next-heartbeat"
，Cron系统也会在
atMs
时间强制注入事件。如果需要在任务负载之外强制立即唤醒，请在
cron:wake
工具中使用
mode: "now"
。

2. The Janitor (Auto-Cleanup)

2. 清理任务（自动清理）

One-shot cron jobs (kind:

at

) disable themselves after running but stay in the list as "ghosts" (

enabled: false

lastStatus: ok

). To prevent clutter, install the Daily Janitor.

一次性Cron任务（类型：

at

）在运行后会自动禁用，但会以「幽灵任务」的形式留在任务列表中（

enabled: false

，

lastStatus: ok

）。为避免任务列表冗余，请安装每日清理任务。

Setup Instructions

设置步骤

Check current jobs:
```
cron:list
```
(includeDisabled: true)
Create the Janitor:
- Name:
```
Daily Cron Cleanup
```
- Schedule: Every 24 hours (
```
everyMs: 86400000
```
  )
- Payload: An agent turn that runs a specific prompt.

查看当前任务：
```
cron:list
```
（includeDisabled: true）
创建清理任务：
- 名称：
```
Daily Cron Cleanup
```
- 调度：每24小时一次（
```
everyMs: 86400000
```
  ）
- 负载：执行特定提示词的agentTurn。

The Janitor Prompt (Agent Turn)

清理任务提示词（Agent轮次）

"Time for the 24-hour cron sweep. List all cron jobs including disabled ones. If you find any jobs that are
enabled: false
and have
lastStatus: ok
(finished one-shots), delete them to keep the list clean. Do not delete active recurring jobs. Log what you deleted."

「现在开始24小时Cron任务清理。列出所有Cron任务，包括已禁用的任务。如果发现任何
enabled: false
且
lastStatus: ok
的任务（已完成的一次性任务），请将其删除以保持列表整洁。不要删除活跃的周期性任务。记录已删除的任务。」

3. Reference: Timezone Lock

3. 参考：时区锁定

For cron to work, the agent must know its time.

Action: Add the user's timezone to
```
MEMORY.md
```
.
Example:
```
Timezone: Cairo (GMT+2)
```
Validation: If a user says "remind me at 9 PM," confirm: "9 PM Cairo time?" before scheduling.

为确保Cron正常工作，Agent必须知晓当前时区。

操作：将用户的时区添加到
```
MEMORY.md
```
中。
示例：
```
Timezone: Cairo (GMT+2)
```
验证：如果用户说「晚上9点提醒我」，请先确认：「是开罗时间晚上9点吗？」再进行调度。

4. The Self-Wake Rule (Behavioral)

4. 自唤醒规则（行为规范）

Problem: If you say "I'll wait 30 seconds" and end your turn, you go to sleep. You cannot wake up without an event. Solution: If you need to "wait" across turns, you MUST schedule a Cron job.

Wait < 1 minute (interactive): Only allowed if you keep the tool loop open (using
```
act:wait
```
).
Wait > 1 minute (async): Use Cron with
```
wakeMode: "now"
```
.

Example Payload for "Checking back in 30s":

json

{
  "schedule": { "kind": "at", "atMs": <NOW + 30000> },
  "payload": { "kind": "agentTurn", "message": "⏱️ 30s check-in. Report status." },
  "wakeMode": "now"
}

问题：如果你说「我将等待30秒」并结束轮次，Agent会进入休眠状态。没有事件触发的话无法唤醒。 解决方案：如果需要在轮次之间「等待」，你必须调度一个Cron任务。

等待<1分钟（交互式）：仅允许在保持工具循环开启时使用（通过
```
act:wait
```
）。
等待>1分钟（异步）：使用Cron并设置
```
wakeMode: "now"
```
。

「30秒后回访」的示例负载：

json

{
  "schedule": { "kind": "at", "atMs": <NOW + 30000> },
  "payload": { "kind": "agentTurn", "message": "⏱️ 30s check-in. Report status." },
  "wakeMode": "now"
}

Troubleshooting

故障排查

"My reminder didn't fire": Check
```
cron:list
```
. If the job exists but didn't fire, check the system clock vs
```
atMs
```
.
"I have 50 old jobs": Run the Janitor manually immediately.

「我的提醒没有触发」：查看
```
cron:list
```
。如果任务存在但未触发，请检查系统时钟与
```
atMs
```
是否一致。
「我有50个旧任务」：立即手动运行清理任务。