Chapter 6: Time-Based Automation (Cron)
Cron is Unix's oldest automation primitive, running since 1975, and OpenClaw builds on it with natural language task descriptions that make scheduling accessible. Cron expressions are five fields: minute, hour, day-of-month, month, day-of-week (e.g., 0 7 1-5 = weekdays at 7:00 AM). OpenClaw stores cron jobs in openclaw.json as an array of {schedule, task} objects, where the task is written in natural language rather than shell commands. Task descriptions should be specific: what data to use, what to do with it, where to write outputs. Vague tasks produce inconsistent results. After any cron change, restart the Gateway (openclaw gateway restart). The openclaw gateway status command confirms when cron jobs are loaded and active.
The heartbeat pattern is a periodic health check that verifies the automation system is functioning and surfaces problems proactively. The Kelly Router pattern uses a 2-hour heartbeat executing a HEARTBEAT.md checklist that includes checking active project sessions, reviewing error logs, verifying disk usage (alert if above 80%), confirming the Gateway is running, checking for unacknowledged operator messages, and logging findings. Alert conditions are explicit: ERROR in logs → WhatsApp alert, disk > 80% → warning, project stuck > 24h → alert. The power of this pattern is that problems surface within 2 hours instead of "whenever you remember to check."
Timezone is a common gotcha—cron schedules run in the server's timezone (typically UTC), not your local timezone. A 0 7 * set for 7am local time in CST actually fires at 1am CST. Fixes include converting to UTC explicitly in the schedule, or using a timezone config key if OpenClaw supports it, and including a comment in the task description noting the local time equivalent. Monitoring scheduled jobs requires cron job logging to logs/cron-history.log with timestamps and success/failure status, detecting missing jobs (a job that should run every 2 hours but hasn't run in 6 hours is a problem), and testing manually by triggering the task outside its normal schedule.
Key Patterns
- **Five-field cron syntax:** `minute hour day-of-month month day-of-week` (crontab.guru for generation help)
- **Natural language tasks in openclaw.json:** `{schedule: "0 7 * * 1-5", task: "Morning briefing..."}` — no shell commands needed
- **Heartbeat every 2 hours:** Execute HEARTBEAT.md checklist; alert on ERROR, disk > 80%, or project stuck > 24h
- **Proactive silence:** Only alert when something needs attention; "system normal" messages cause alert fatigue
- **Always log + detect missing runs:** cron-history.log with timestamps; heartbeat checks for missed jobs
Related Concepts
- [[kelly-handbook-ch3-file-automation]] for the file pipelines that cron triggers
- [[kelly-handbook-ch5-communication-automation]] for alert routing and WhatsApp integration
- [[kelly-handbook-ch7-multi-agent]] for multi-agent orchestration and RALPH escalation
- [[kelly-handbook-ch8-memory]] for the daily memory logs that cron updates write to