Heartbeat Configuration Guide
A heartbeat is a periodic main-session agent turn that runs without a user message. It is a
system-owned automation: the gateway keeps one monitor job per heartbeat-enabled agent (visible as
Heartbeat (<agent-id>) in openclaw automations list --all; openclaw cron is an alias of the same
commands). Every heartbeat is a full agent turn, so keep what it has to do SHORT.
HEARTBEAT.md is retired
The workspace file HEARTBEAT.md is no longer created in new workspaces and the runtime never
reads it. What it used to hold now lives in two places:
| What | Where it lives now |
|---|---|
| Cadence, target, quiet hours, model, context weight | agents.defaults.heartbeat (per agent: agents.entries.<id>.heartbeat) in openclaw.json |
| The checklist the heartbeat follows | the monitor's scratch, stored in the shared state database |
Read and change the scratch with the monitor job id from openclaw automations list --all:
openclaw automations scratch <jobId>
openclaw automations scratch <jobId> --set "<checklist>"
openclaw automations scratch <jobId> --file <notes.md>
openclaw automations scratch <jobId> --unset
Setting the scratch changes agent behaviour from the next tick, so it is an R2 change: show the old and
the new text first, and keep the old text in the plan's ROLLBACK as an executable --set/--file line.
A workspace that still has HEARTBEAT.md
The file is dead weight on a current release. The doctor's repair mode imports it into the monitor
scratch, converts valid legacy tasks: entries into automation jobs, archives the original under the
state directory and removes the file. That mode rewrites what it does not understand, so in this plugin
it is an R4 plan with a typed confirmation (backup first, eight blocks, no --yes in the turn the plan
is shown) — never a routine step after an edit. The alternative is to copy the checklist into the
scratch by hand and leave the file for the plan that retires it. Confirm current behaviour with the
docs-research skill before acting; the upstream page is the "Retired HEARTBEAT.md workspace file"
template page.
Config Mechanics
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"model": "<provider>/<model-id>",
"lightContext": true,
"isolatedSession": true
}
}
}
}
every— cadence;"0m"disables only the recurring tick (event-driven wakes still work). Unset, the default is30m, or1hwhen Anthropic OAuth/token auth is in use.model— an exact model reference for heartbeat turns. Take it from the instance's own model catalogue, never from memory; a model id typed from memory isfleet.config.model-id-unverified.lightContext: true— skip workspace bootstrap files for heartbeat runs; the monitor scratch is injected either way.isolatedSession: true— a fresh session per run, with no conversation history. This is the single biggest token saver.activeHours(start,end, local time) — quiet hours: outside the window the tick is skipped.target— where alerts go:owner(default, the operator DM),last,none, or a channel id.- The heartbeat object is strict: an unknown field refuses the config. Check the field list against
the running build (
openclaw config schema) before adding anything. - Scheduled heartbeats need automations: with
cron.enabledfalse, nothing ticks.
Config changes go through the config-surgery procedure (snapshot, patch with base hash, validate,
verify from the runtime) — never a plain file write against a running gateway.
Response Contract
If nothing needs attention, the heartbeat replies NO_REPLY (or calls heartbeat_respond with
notify: false). An alert is the alert text only, with no silent acknowledgment attached.
Example Scratch Checklist
# Periodic Checks
- Check the inbox for urgent messages only
- Check Telegram mentions in monitored groups
- Calendar: events in the next 2 hours
Quiet hours belong in activeHours, not in the checklist text.
Heartbeat or Automation?
The default heartbeat prompt tells the agent not to infer or repeat old tasks from earlier chats and
that recurring tasks are automations. Use the scratch for a small awareness checklist; create a
separate automation (openclaw automations create …) for anything with its own schedule, its own
delivery, or its own approval rules.
Standing Orders Integration
Standing orders live in docs/standing-orders/ and are referenced from AGENTS.md. Trigger them from
an automation, not from the heartbeat scratch, so each program keeps its own cadence and run history.
See the standing-orders skill for design patterns.
Token-Efficient Heartbeats
Every heartbeat costs tokens. Minimise cost:
- Isolate the session —
isolatedSession: true - Use a cheap model — set
heartbeat.modelto a small model from the instance's catalogue - Keep the checklist short — 3-5 items max
- Use
lightContext: true— loads minimal context - Set an appropriate cadence — do not tick every minute unless needed
- Define quiet hours —
activeHours
What Data Is Needed
| Input | Source | What It Determines |
|---|---|---|
| Business hours | Client timezone + schedule | activeHours |
| Monitoring needs | Client requirements | What the scratch checks |
| News/legal sources | Domain-specific | Sites/feeds to monitor |
| Standing orders | docs/standing-orders/ | Scheduled tasks (as automations) |
| Channel activity | openclaw.json channels | Which platforms to monitor |
| Alert recipient | commands.ownerAllowFrom or channel allowFrom |
Where heartbeat alerts go |
Signals That Improve the Heartbeat
- User asks "did anything happen?" → add relevant monitoring to the scratch
- User wants periodic reports → create an automation
- Agent burns tokens on useless checks → remove from the scratch, isolate the session
- Missed important event → add monitoring for that event type
- Too many notifications → refine filters, add
activeHours
Best Practices
- Start with an empty scratch — add only what's needed
- Keep to 3-5 checklist items
- Always define quiet hours
- Use the cheapest model that can handle the tasks
- Do not create a separate state file for "already checked" bookkeeping
- Review token costs weekly — remove low-value checks