On this page
🔀 Three automation primitives
| Mechanism | Trigger | Session | Best for |
|---|---|---|---|
| Heartbeat | Every N minutes (default 30m) | Main session | Periodic checks, batching multiple monitors |
| Cron | Cron expression or exact time | Main or isolated | Scheduled tasks, reports, reminders |
| Hooks | OpenClaw event fires | Varies | Event-driven: new session, reset, channel connect |
💡 Rule of thumb: Use heartbeat when you want the agent to periodically check whether anything needs attention. Use cron when timing matters ("exactly at 7 AM every Monday"). Use hooks when an event should trigger an action.
💓 Heartbeat
Heartbeat is a periodic check that runs in the main session. The agent reads HEARTBEAT.md and decides if anything needs attention. If nothing does, it replies HEARTBEAT_OK and the message is silently dropped.
Configuration
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"target": "last",
"activeHours": { "start": "08:00", "end": "22:00" }
}
}
}
}
HEARTBEAT.md example
# Heartbeat Checklist
- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in
If nothing needs attention, reply HEARTBEAT_OK.
Why heartbeat instead of multiple cron jobs?
- Batches checks — one agent turn reviews email, calendar, and notifications together
- Context-aware — has full main-session context, can make smart urgency decisions
- Low overhead — one heartbeat replaces many small polling tasks
- Silent when nothing happens —
HEARTBEAT_OKgets dropped, no noise
✅ Cost tip: Use a cheap model for heartbeats. 95% of heartbeats end in HEARTBEAT_OK. Configure: "heartbeat": { "model": "openrouter/openai/gpt-5-nano" }
⏰ Cron jobs
Cron is the gateway's built-in scheduler. Jobs persist under ~/.openclaw/cron/ and survive restarts.
v2026.3.11 breaking change: Isolated cron jobs can no longer notify through ad hoc agent sends or fallback main-session summaries. If your cron notifications stopped working after upgrade, run openclaw doctor --fix to migrate legacy cron storage and notify/webhook delivery metadata.
Add a cron job
# Morning briefing at 7 AM every day
openclaw cron add \
--name "Morning briefing" \
--cron "0 7 * * *" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Generate today's briefing: weather, calendar, top emails, priorities."
# Weekly deep analysis every Monday 6 AM
openclaw cron add \
--name "Weekly review" \
--cron "0 6 * * 1" \
--session isolated \
--model "anthropic/claude-opus-4-6" \
--thinking high \
--message "Weekly deep analysis of project progress."
Manage cron jobs
openclaw cron list # List all jobs
openclaw cron list --verbose # With next run times
openclaw cron run <jobId> --force # Force immediate run
openclaw cron edit <jobId> --cron "0 8 * * *" # Change schedule
openclaw cron rm <jobId> # Delete job
Delivery modes
| Mode | Behavior |
|---|---|
announce | Posts summary to your main session / channel (default for isolated jobs) |
deliver | Delivers to a specific channel + contact |
none | Runs silently — internal processing only |
⚠️ Recurring top-of-hour schedules (like 0 * * * *) are automatically staggered by up to 5 minutes to prevent load spikes. Use --exact to override if you need precise timing.
⏱ One-shot reminders
Need a single reminder in 20 minutes? Use --at instead of --cron:
# Reminder in 20 minutes
openclaw cron add \
--name "Calendar check" \
--at "20m" \
--session main \
--system-event "Check calendar for the meeting."
# Specific time
openclaw cron add \
--name "Meeting prep" \
--at "2026-02-26T13:30:00+02:00" \
--session main \
--system-event "Board meeting in 30 minutes. Review the deck."
One-shot jobs run once and can auto-delete with --delete-after-run.
🪝 Hooks — event-driven reactions
Hooks fire automatically when an OpenClaw lifecycle event occurs:
- Session start — pull in last conversation summaries for context
- Session reset — clean up project directory, pre-load configs
- Channel connect — log when a new channel comes online
- Gateway boot — run startup checks (read BOOT.md)
Hooks are configured as extensions/plugins and are more advanced than heartbeat and cron. Most users won't need custom hooks — heartbeat + cron cover 90% of automation needs.
🔒 Session isolation & model overrides
Isolated cron jobs are powerful because they get their own clean context:
- No context pollution — the job doesn't see your conversation history
- Privacy — no accidental reference to private DM content
- Model override — use a powerful model for complex tasks, cheap model for simple checks
- Clean history — automated task output doesn't clutter your main session
# Night shift: autonomous coding with Opus
openclaw cron add \
--name "Night shift" \
--cron "0 0 * * *" \
--session isolated \
--model "anthropic/claude-opus-4-6" \
--thinking high \
--deliver --channel telegram \
--message "Pick the highest-priority task and work on it for 30 minutes."
🍳 5 real-world recipes
1. Morning briefing
openclaw cron add --name "Morning brief" --cron "0 7 * * *" \
--tz "Europe/Bucharest" --session isolated \
--deliver --channel telegram \
--message "Good morning. Calendar today, urgent emails, top 3 priorities."
2. End-of-day recap
openclaw cron add --name "EOD recap" --cron "0 18 * * 1-5" \
--session isolated --deliver --channel telegram \
--message "Summarize what was accomplished today and what carries over."
3. Weekly review
openclaw cron add --name "Weekly review" --cron "0 9 * * 0" \
--session isolated --model "anthropic/claude-opus-4-6" \
--deliver --channel telegram \
--message "Weekly review: progress on each project, blockers, priorities for next week."
4. Memory cleanup reminder
openclaw cron add --name "Memory check" --cron "0 10 * * 6" \
--session main \
--system-event "Review MEMORY.md for stale entries and duplicates."
5. Health monitoring
openclaw cron add --name "Health check" --cron "*/15 * * * *" \
--session isolated --model "openrouter/openai/gpt-5-nano" \
--message "Run openclaw doctor. If issues found, announce summary." \
--announce
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| Cron job never fires | Check openclaw cron list --verbose for next run. Ensure gateway is running continuously. |
| Job runs but no message received | Check delivery mode. none = silent. Add --deliver --channel telegram. |
| Heartbeat interrupts active work | Set activeHours or increase interval. Agent should skip heartbeat during active conversations. |
| Main session cron doesn't work | Main session cron requires heartbeat enabled. Enable heartbeat or use isolated sessions. |
| "Scheduler disabled" error | Check cron.enabled in config and OPENCLAW_SKIP_CRON env var. |
| Wrong timezone | Always specify --tz. Without it, the gateway host's local timezone is used. |