OpenClaw cron vs heartbeat: the production rule that actually works

Use an OpenClaw Automation when a job needs its own schedule, run history, timeout, or delivery path. Use heartbeat when one short, approximate check benefits from the main session's context. That is the current product boundary, and it is a much better rule than 'cron for exact time, heartbeat for everything else.'

The name causes confusion. People hear heartbeat and imagine a scheduler. In current OpenClaw, heartbeat is closer to a periodic glance around the room. Automations are the actual alarms. Background Tasks record detached work. Task Flow coordinates several dependent phases.

The short answer

If you remember one line, use this one: heartbeat notices; Automations own. The component that owns the schedule should also own the timeout, run record, and failure signal.

Why the old HEARTBEAT.md advice is stale

Older OpenClaw setups often put several natural-language schedules in HEARTBEAT.md and tracked the last run in a state file. That worked, but it mixed a monitor, scheduler, state machine, and executor in one recurring prompt. It was easy to build and hard to know when it had quietly stopped doing what you thought.

Current OpenClaw documentation treats recurring work as Automations. Heartbeat scratch is monitor context. It stays useful, but it should stay small. A heartbeat can decide that an inbox message deserves attention. It should not pretend to be the durable ledger for a weekly publishing pipeline.

A real failure: schedule state is not completion state

We learned this through a boring marketing failure. A broad portfolio heartbeat ran every five days. It marked the cycle as started, then launched a worker to research, write, validate, and deploy content across several products. If the worker timed out after that first state update, the scheduler still believed the cycle had happened.

The sites were healthy. The date filters were healthy. The content queues simply reached their last scheduled post and sat empty until the next successful refill. Two properties published through July 27, then had nothing scheduled until August 5. The missing posts were an operating-control bug, not a rendering bug.

The fix is not a more elaborate prompt. It is separate state: due, started, and completed. Only successful closeout should advance completion. A timed-out run should remain visible as failed or incomplete, and the next check should be allowed to retry safely.

Choose by failure mode, not by convenience

1. If late execution is unacceptable, use an Automation with an explicit timezone.
2. If the job needs a fresh context or different model, use an isolated Automation.
3. If several tiny checks naturally belong in one conversation, batch them in heartbeat.
4. If the work has dependent phases, use Task Flow or bounded background tasks with a durable status artifact.
5. If the action is deterministic, frequent, and cheap to express in code, use a script and let the agent handle exceptions.

The fifth rule matters. Asking a capable model to make the same HTTP health request every five minutes is not agentic. It is expensive cron with prose around it. Let code detect the condition. Wake the agent when diagnosis or communication needs judgment.

A production checklist

• Give every scheduled job one owner and one success definition.
• Record started and completed separately.
• Set a time budget that is shorter than the interval between runs.
• Make retries safe before enabling retries.
• Check the task record and the business artifact. A green task without the expected file, post, or message is not success.
• Keep heartbeat quiet by default. No finding should mean no interruption.
• Keep the Gateway online for jobs that must run while your laptop sleeps.

The practical split

Put awareness in heartbeat. Put commitments in Automations. Put multi-step execution in Task Flow or bounded tasks. Put deterministic polling in code. This split is less magical than one giant HEARTBEAT.md, which is exactly why it survives longer.