Cron vs Heartbeat

Both heartbeats and cron jobs allow you to run tasks on a schedule. This guide helps you choose the right mechanism for your use case.

| Use case | Recommended | Why |

| --- | --- | --- |

| Session | Main | Main (via system event) |

| History | Shared | Shared | Fresh each run |

| Context | Full | Full | None (clean start) |

| Model | Main session model | Main session model | Can override |

| Output | Delivered if not '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'HEARTBEAT_OK'</code>' | Heartbeat prompt + event | Summary posted to main |

#

Use '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--session main'</code>' with '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--system-event'</code>' when you need:

- Reminders/events that appear in main session context

- Agent to process it during next heartbeat with full context

- No separate isolated run

openclaw cron add   --name "Check project"   --every "4h"   --session main   --system-event "Time for a project health check"   --wake now

#

Use '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--session isolated'</code>' when you need:

- Clean slate without prior context

- Different model or thinking settings

- Output delivered directly to channel (summary still posted to main by default)

- History doesn't clutter main session

openclaw cron add   --name "Deep analysis"   --cron "0 6 * * 0"   --session isolated   --message "Weekly codebase analysis..."   --model opus   --thinking high   --deliver

| Mechanism | Cost profile |

| --- | --- |

| Heartbeat | Runs every N minutes; scales with HEARTBEAT.md size |

| Cron (main) | Adds event to next heartbeat (no isolated turn) |

| Cron (isolated) | Full agent turn per job; can use cheaper models |

<strong>Tips</strong>:

- Keep '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'HEARTBEAT.md'</code>' small to minimize token costs.

- Batch similar checks into heartbeat instead of multiple cron jobs.

- Use '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'target: &quot;none&quot;'</code>' on heartbeat if you only need internal processing.

- Use isolated cron with cheaper models for routine tasks.

- '<a href="/gateway/heartbeat" className="text-emerald-400 hover:text-emerald-300 transition-colors">'Heartbeat'</a>' - Full heartbeat configuration

- '<a href="/automation/cron-jobs" className="text-emerald-400 hover:text-emerald-300 transition-colors">'Cron jobs'</a>' - Full cron CLI and API reference

- '<a href="/cli/system" className="text-emerald-400 hover:text-emerald-300 transition-colors">'System'</a>' - System events + heartbeat control