OpenClaw Heartbeat Guide: Audit HEARTBEAT.md Before It Audits Your Bill

My HEARTBEAT.md once had eleven lines in it. Each one had seemed reasonable on the day I added it, usually right after something went wrong and I wanted the agent to watch for it next time. Nobody ever took a line out.

The heartbeat is the feature that makes an OpenClaw agent feel awake. On a timer (thirty minutes by default on the versions I run), the gateway wakes the agent with a short poll prompt, the agent reads HEARTBEAT.md from its workspace, does whatever the checklist asks, and either reports something or replies HEARTBEAT_OK and goes quiet. It is cheap to set up. It is not cheap to leave alone.

This guide covers the setup, briefly, and then spends most of its length on the part the official docs and the popular write-ups skip: going through the checklist one line at a time and asking whether each line has earned its 48 runs a day.

How a Heartbeat Turn Actually Runs

A heartbeat is a full agent turn. That sentence is the whole cost model, and it took me longer than I would like to admit to take it seriously.

When the timer fires, the agent gets its usual context: bootstrap files, the tool list, whatever session history the heartbeat runs in (the main session, unless you configure otherwise). Then it reads the checklist and acts. If nothing needs attention, the reply is HEARTBEAT_OK, and the gateway drops that acknowledgment instead of sending it to you. If something does need attention, the agent drops the token and writes a real message, which goes wherever your target setting points.

Two details matter for budgeting. If HEARTBEAT.md exists but is effectively empty (blank lines and headings only), OpenClaw skips the run instead of paying for a turn that has nothing to do. And everything the context budget guide says about bloated bootstrap files applies here with a multiplier, because the heartbeat reloads that context on every tick whether or not you are around to read the result.

The Minimal Config

Heartbeat settings live under agents.defaults.heartbeat in openclaw.json, and individual agents can override them. Key names have moved around between releases, so check openclaw doctor output and your version's docs before pasting. This is roughly what mine looks like now:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "1h",
        activeHours: { start: "07:30", end: "22:00" },
        target: "last",
        lightContext: true
      }
    }
  }
}

every is the interval, and "0m" turns the recurring tick off. activeHours stops the agent from checking anything while I sleep, which matters less for cost than for sanity, since a 3am alert about a stale queue is an alert I will read at 8am anyway. target: "last" sends real alerts to whichever channel I talked to the agent on most recently. lightContext skips the workspace bootstrap files on heartbeat turns, which is the single biggest saving available if your checklist does not depend on them.

There is also a per-heartbeat model override. Use it. The cost optimization guide moved heartbeat checks and similar background work onto a local gemma3:12b model and credits that move with cutting daily token spend by about 40%. Your main model is probably overqualified for "is this file older than six hours."

Write the Checklist Like a Preflight Card

The heartbeat prompt tells the agent to follow HEARTBEAT.md strictly and not to resurrect old tasks from earlier chats. That instruction is only as good as the file. Mine now reads like this:

# Heartbeat

- If ~/.openclaw/workspace/inbox/urgent.md has entries newer than my
  last heartbeat, summarize them and alert.
- If any deploy in deploys/pending.json is older than 2 hours and still
  pending, alert with the slug.
- Otherwise reply HEARTBEAT_OK. Do not report that things are fine.

Every line names a file and says exactly what to do when a condition is true. No line says "keep an eye on" anything. "Keep an eye on the inbox" is an invitation for the agent to read the whole inbox, form an opinion about it, and share that opinion with you at 2:30 on a Tuesday afternoon.

The Audit: Price Every Line

None of the guides ranking for this topic do this part. Treat each checklist line as a recurring charge and price it.

The arithmetic is not subtle. Thirty-minute heartbeats with no active-hours window mean 48 turns a day. A window from 07:30 to 22:00 at the same interval cuts that to 29 or so. Move to hourly and you are near 15. Every line in the file rides along on every one of those turns, and a line that makes the agent open a large file or call an MCP tool adds real tokens and real latency each time, even on the 47 runs where nothing was wrong.

Then go down the file one line at a time.

If the answer is a number or a yes, it goes to a script. "Is the deploy older than two hours" is a comparison. A shell script answers it for free. If the answer is a number or a boolean, the line belongs in a script on a schedule, and the cron automation guide has the wrapper pattern (lock file plus state file) I use for those. The script can still write into a file the heartbeat reads, so the agent only spends tokens when there is something to think about.

If it has not fired in a month, delete it. A line that has never once produced an alert means either the problem it watches for has gone away or the line cannot detect it. Both are reasons to delete it. Search your logs or session history for the alert text before you decide; the gateway doctor guide covers where those logs live.

My eleven lines became four. Four moved to cron scripts that write a one-line status file. Two merged into one. Two had never fired and went in the bin, including one that watched for a WhatsApp disconnect I had fixed months before.

Heartbeat or Cron

Short version: heartbeats are for checks that need the agent's context and judgment on a loose rhythm, and cron is for anything with an exact time or a deterministic answer. Morning briefings go in cron, because you want them at 7:00 sharp in a fresh session. Heartbeats drift with queue load and get deferred while the agent is busy, which is fine for "soon" and wrong for "Monday at 9." A weekly review of stale GitHub issues does not improve when you run it 336 times a week. "Did anyone reply to the thread I flagged this morning, and does the reply need me?" is heartbeat work, since it depends on what happened in the main session today.

The best setups I have seen use both, wired together. Cron does the cheap measuring and writes results to disk. The heartbeat reads those results and decides whether a human should hear about it.

Let the Agent Edit the File, Then Read the Diff

Agents add things to HEARTBEAT.md on their own if you let them, usually after you say something like "watch for that next time." That is useful and also exactly how my file reached eleven lines. Keep the workspace in git (the backup and migration guide explains the setup) and run git log -p HEARTBEAT.md once a month. It is the shortest diff in the repo and the one with the largest bill attached.

Common Failure Modes

Final Verdict

Keep the heartbeat on. Run it hourly inside waking hours, point it at a cheap model, and keep the checklist to the few lines that genuinely need an agent to read them. Push everything with an exact time or a yes-or-no answer into cron.

Then delete one line a month. You will not miss it.