OpenClaw Cron vs Heartbeat
Cron (Scheduled Tasks)
Runs inside the Gateway process; jobs persist at ~/.openclaw/cron/jobs.json and survive restarts.
Three schedule types:
--at— one-shot, ISO 8601 or relative expression--every— fixed interval recurrence--cron— standard 5/6-field expression with optional--tz
Four execution styles (the key architectural lever):
--session |
Where it runs |
|---|---|
main |
Enqueued into next heartbeat turn |
isolated |
Fresh cron:<jobId> session (default for reports/background work) |
current |
Session bound at creation time |
session:xxx |
Persistent named session |
Delivery modes: announce (post to Slack/Telegram), webhook (HTTP POST), or none.
Every cron execution creates a Background Task record — fully auditable.
Heartbeat
A periodic turn that fires in the main session (default: every 30 minutes). Driven by a HEARTBEAT.md checklist or tasks: blocks.
- No Background Task record created per tick — lower overhead
- Respects
activeHoursconfig (won't fire outside working hours) - Not precise — fuzzy polling, not a scheduler
Key Differences
| Dimension | Cron | Heartbeat |
|---|---|---|
| Timing precision | Exact (to the second, with optional stagger) | Fuzzy (~30 min default) |
| Session isolation | Supports isolated/named/custom sessions | Always main session |
| Audit record | Yes — Background Task per run | No |
| External delivery | Slack, Telegram, webhook | None |
| Retry on failure | Yes (3× with backoff) | No |
| Use case | Reports, external notifications, precise triggers | Routine monitoring, queue polling |
| Overhead | Higher (task record, session lifecycle) | Lower |
How They Interact
- A cron job with
--session mainenqueues its message into the next heartbeat turn — cron can feed the heartbeat. - A cron job with
--wakecan trigger an early heartbeat before the 30-minute interval expires. - The heartbeat's
HEARTBEAT.mdchecklist is what makes it "fuzzy monitoring" — the agent decides what's worth acting on each tick.
Decision Rule
Use Heartbeat for always-on lightweight monitoring where timing doesn't matter. Use Cron when you need a precise schedule, isolated execution, external delivery, or an audit trail.