Heartbeat

Heartbeat is a system-owned automation that runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you.

Heartbeat is a scheduled main-session turn. ACP runs, subagents, and isolated automation jobs use their own execution owners.

Under the hood, heartbeat cadence is owned by the Automations scheduler: the gateway maintains one system-owned automation job per heartbeat-enabled agent (visible in openclaw cron list --all as Heartbeat (agent-id)). Heartbeat config remains the desired-state input, while the persisted monitor schedule owns the actual tick and the runner's later cooldown. The gateway writes config changes through at startup and on config reload. openclaw doctor --fix can materialize missing or stale monitor rows before the next gateway start. Edit agents.*.heartbeat, not the automation job. If saving monitor rows fails after a config change is accepted, the Gateway keeps the accepted config and reports that recovery is required. Monitor retries use the current accepted config. Rejected changes never become retry targets.

Scheduled heartbeats require automations. When cron.enabled is false or OPENCLAW_SKIP_CRON=1, the gateway logs a startup warning and does not run scheduled heartbeats. Manual and event-driven heartbeat wakes remain available. There is no separate heartbeat fallback timer.

Setting heartbeat.every: "0m" disables only the recurring cadence. A targeted event-driven wake can still run one agent turn, such as a background exec completion. It does not create or re-enable a recurring schedule. To keep background exec without automatic completion turns or their model calls, set tools.exec.notifyOnExit: false; check agents.entries.<id>.tools.exec.notifyOnExit for per-agent overrides. Collect results with process poll. See Background exec notifications. Tool policy and sandboxing control whether agent turns may execute commands.

Heartbeat-owned event wakes retain the same per-agent rate limits when recurring cadence is disabled. Those limits are a 30-second minimum between event turns, and a flood guard after five starts within 60 seconds. Deferred work resumes when its guard expires. Config reloads preserve this accounting without enrolling the agent in recurring or broadcast heartbeats.

Transcript markers distinguish [OpenClaw heartbeat poll] from an exec completion, cron wake, or session event. Scheduled polls use the configured heartbeat session, which is the agent's main session by default. Targeted completion events return to the session that owns the work. Event markers retain their source provenance without copying internal instructions into chat history. Silent acknowledgment pairs remain hidden.

Troubleshooting: Automations

Quick start (beginner)

Example config:

{  commands: {    ownerAllowFrom: ["telegram:123456789"],  },  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "owner", // default: operator DM from ownerAllowFrom or channel allowFrom        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: skip workspace bootstrap files for heartbeat runs        isolatedSession: true, // optional: fresh session each run (no conversation history)        // activeHours: { start: "08:00", end: "24:00" },      },    },  },}

For a configured Telegram bot, set the owner with a JSON array, even when there is only one entry. Replace 123456789 with your Telegram user ID and include any existing owners you want to keep:

openclaw config set commands.ownerAllowFrom '["telegram:123456789"]'

To select a recipient explicitly, set the channel and recipient separately:

openclaw config set agents.defaults.heartbeat.to '"123456789"'openclaw config set agents.defaults.heartbeat.target telegram

Keep the inner double quotes around the numeric chat ID so to is stored as a string. heartbeat.target accepts owner, last, none, or a channel ID such as telegram; telegram:123456789 belongs in commands.ownerAllowFrom, not target.

Defaults

• Interval: 30m. Applying Anthropic provider defaults bumps this to 1h when the resolved auth mode is OAuth/token (including Claude CLI reuse), but only while heartbeat.every is unset. Set agents.defaults.heartbeat.every or per-agent agents.entries.*.heartbeat.every. Use 0m to disable recurring cadence.
• Delivery target: owner. OpenClaw uses the first concrete commands.ownerAllowFrom entry, then channel allowFrom, and never sends this route to a group. Without a resolvable owner DM, ambient polls skip with reason=no-route. Set target: "last" to follow the most recent conversation, including groups, or target: "none" for internal-only runs.
• Prompt body (configurable via agents.defaults.heartbeat.prompt): Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.
• Timeout: unset heartbeat turns use agents.defaults.timeoutSeconds when set. Otherwise, they use the heartbeat cadence capped at 600 seconds. Set agents.defaults.heartbeat.timeoutSeconds or per-agent agents.entries.*.heartbeat.timeoutSeconds for longer heartbeat work. Turns that resume work after a background command completes or process background-task review, blocked-task events, and recovered restart work use the ordinary agent timeout (48 hours by default); heartbeat cadence and timeout settings do not shorten these continuations. The event must be included in the turn; an isolated monitor does not inherit the budget of work pending in its base session.
• The heartbeat prompt is sent verbatim as the scheduled user message. Heartbeat runs use the same system prompt as ordinary agent turns. There is no heartbeat-specific system-prompt section.
• When recurring heartbeats are disabled with 0m, the automation job stays but is disabled. Doctor reports a disabled monitor when creating or updating this job, rather than showing its retained interval as an active cadence. Its monitor scratch is retained for when you re-enable the cadence. Targeted event-driven wakes remain available.
• When automations are disabled entirely, scheduled heartbeats do not run even if heartbeat cadence remains enabled.
• Active hours (heartbeat.activeHours) are checked in the configured timezone. Outside the window, heartbeats are skipped until the next tick inside the window.
• Scheduled heartbeats defer while the main queue or automation work is active or queued, while any reply or embedded run for the same agent is active, and while the resolved target session has active or queued work. An event-free plain monitor poll that has not begun preparation is recorded as skipped and waits for its next persisted cadence tick, instead of keeping a running automation open behind busy work. Wakes carrying queued events or scheduled tasks, and work already admitted or retained after execution, still retry. Immediate and manual wakes bypass the broad same-agent active-run check, but still honor the main, automation, and target-session busy guards. Sibling agents do not pause each other.
• A host background-command completion uses ordinary session execution and waits only for its own session. Heartbeat-owned node completions retain their existing busy and delivery-recovery guards.

What the heartbeat prompt is for

The default prompt is intentionally narrow: follow the heartbeat monitor scratch context when provided, keep recurring work in automation jobs, and reply NO_REPLY when nothing needs attention. It explicitly tells the agent not to infer or repeat old tasks from prior chats, so a default install stays quiet instead of rehashing stale conversation context.

Proactive heartbeat behavior is opt-in:

• Recurring checks: create automations for inbox review, calendar sweeps, or queued follow-ups. Each job executes its configured payload on its own schedule. The default heartbeat does not infer recurring work from prior chats.
• Human check-in: create a scheduled job if you want an occasional lightweight "anything you need?" message, and constrain its schedule to avoid night-time pings in your configured local timezone (see Timezone).

Heartbeat still handles node completion events. Host exec, CLI watchdog, ACP parent relay, immediate HTTP hooks, restart continuations, and session-state notices use ordinary session execution. A completion carrying a captured delivery route returns to that account, conversation, and thread; the monitor's configured target, to, or accountId cannot redirect it. Intentional target: "none", direct-message restrictions, notification opt-outs, and disabled heartbeat controls still apply. Plugin normalization that would change the captured route fails closed. Ordinary scheduled heartbeats retain their configured destinations.

Heartbeat-owned node completions with different delivery routes run in separate turns, including different accounts or topics. Identical completion text does not suppress a different completion occurrence.

If a heartbeat-owned completion cannot enter delivery, its original-route event remains available for the existing bounded wake retry. Once the durable delivery queue owns an attempt, that queue owns transport retries; an unrelated wake must not regenerate its result. An unresolved attempt without confirmed delivery custody is withheld from model replay. Use process poll to collect an exec result, and verify whether a message arrived before manually resending an ambiguous delivery. This does not change node protocol negotiation or legacy notification behavior.

If you want a heartbeat to do something very specific (e.g. "check Gmail PubSub stats" or "verify gateway health"), set agents.defaults.heartbeat.prompt (or agents.entries.*.heartbeat.prompt) to a custom body (sent verbatim).

Immediate session events

Host background commands, CLI watchdog completions, ACP parent notifications, immediate HTTP hook wakes, restart continuations, and session-state notices enter the ordinary reply queue. They keep the originating session's history and captured delivery route, wait behind its existing work, and use its current permissions. Heartbeat cadence, active hours, model, and visibility settings do not control these events. An originating run's automatic-delivery opt-out remains in effect.

Session-state notices for the same watcher and captured delivery route collect for up to 20 seconds and enter one reconciliation turn. The turn retains every notice's permission limits and acknowledges the watched sessions only when it is adopted. If one notice is consumed before adoption, the remaining original notices keep their own reconciliation work.

Each occurrence has one execution owner. Periodic heartbeat polls and incoming user turns cannot consume an event waiting in the ordinary queue. Acceptance confirms that the owner retained the event; it does not prove execution or delivery completed. Resetting or deleting the target session cancels the retained event rather than moving it into the replacement session. A NO_REPLY result remains silent.

Response contract

• If nothing needs attention, reply with NO_REPLY.
• Heartbeat runs may instead call heartbeat_respond with notify: false for no visible update, or notify: true plus notificationText for an alert. When present, the structured tool response takes precedence over the text fallback.
• A meaningful heartbeat_respond result with notify: false remains silent but is remembered as bounded internal context for the next user turn in that session. A generated notify: true alert whose delivery is blocked or unconfirmed is also recorded, including its alert text and delivery reason. This is the latest outcome for the session, not an alert history or exact-delivery replay queue. no_change acknowledgments and confirmed visible notifications are not stored this way.
• Existing custom prompts may still return the legacy HEARTBEAT_OK acknowledgment. OpenClaw accepts it at the start or end of a reply and drops the reply when its remaining content is at most 300 characters. The suppression budget is fixed.
• A legacy HEARTBEAT_OK in the middle of a reply is not treated specially.
• For alerts, return only the alert text. Do not include a silent acknowledgment.
• Delivery selects the last outbound-capable non-reasoning payload. Separate reasoning or thinking payloads remain internal. A reasoning-only result produces no alert.
• Tool error warnings remain enabled during heartbeat turns.
• openclaw system heartbeat last --json reports a confirmed message-tool send to the heartbeat recipient as sent, without sending another acknowledgment.
• If the heartbeat starts background work without sending an update, its status event reports skipped with reason background-work. Check the task for completion. This is not an all-clear acknowledgment.

Outside heartbeats, stray HEARTBEAT_OK at the start/end of a message is stripped and logged. A message that is only HEARTBEAT_OK is dropped.

Config

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        lightContext: false, // default: false; true skips workspace bootstrap files for heartbeat runs        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        target: "owner", // default | options: last | none | <channel id>        accountId: "ops-bot", // optional multi-account channel id        prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.",      },    },  },}

Scope and precedence

• agents.defaults.heartbeat sets global heartbeat behavior.
• agents.entries.*.heartbeat merges on top. If any agent has a heartbeat block, only those agents run heartbeats.
• Ambient ownership resolves through agents.defaults.heartbeat.agentId, agents.defaults.systemAgent.agentId, then the sole agent. When no per-agent or default heartbeat block applies and that chain leaves a multi-agent roster ownerless, heartbeats stay disabled and emit validation and Gateway warnings.
• channels.defaults.heartbeatVisibility sets visibility defaults for all channels.
• channels.<channel>.heartbeatVisibility overrides channel defaults.
• channels.<channel>.accounts.<id>.heartbeatVisibility (multi-account channels) overrides per-channel settings.

Per-agent heartbeats

If any agents.entries.* entry includes a heartbeat block, only those agents run heartbeats. The per-agent block merges on top of agents.defaults.heartbeat (so you can set shared defaults once and override per agent).

Example: two agents, only the second agent runs heartbeats.

{  agents: {    ownership: "explicit",    defaults: {      systemAgent: { agentId: "main" },      heartbeat: {        every: "30m",        target: "owner", // default: operator DM      },    },    entries: {      main: { workspace: "~/.openclaw/workspace" },      ops: {        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.",        },      },    },  },  talk: { agentId: "main" },}

Active hours example

Restrict heartbeats to business hours in a specific timezone:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "owner", // default: operator DM        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

Outside this window (before 9am or after 10pm Eastern), heartbeats are skipped. The next scheduled tick inside the window will run normally.

24/7 setup

If you want heartbeats to run all day, use one of these patterns:

• Omit activeHours entirely (no time-window restriction, which is the default behavior).
• Set a full-day window: activeHours: { start: "00:00", end: "24:00" }.

Multi-account example

Use accountId to target a specific account on multi-account channels like Telegram:

{  agents: {    entries: {      ops: {        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          accountId: "ops-bot",        },      },    },  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

Field notes

Delivery behavior

Visibility controls

By default, quiet heartbeat acknowledgments are suppressed while alert content is delivered. You can adjust this per channel or per account:

{  channels: {    defaults: {      heartbeatVisibility: {        showOk: false, // Hide HEARTBEAT_OK (default)        showAlerts: true, // Show alert messages (default)        useIndicator: true, // Emit indicator events (default)      },    },    telegram: {      heartbeatVisibility: {        showOk: true, // Show OK acknowledgments on Telegram      },    },    whatsapp: {      accounts: {        work: {          heartbeatVisibility: {            showAlerts: false, // Suppress alert delivery for this account          },        },      },    },  },}

Precedence: per-account → per-channel → channel defaults → built-in defaults.

What each flag does

• showOk: sends a HEARTBEAT_OK acknowledgment when the model returns an OK-only reply.
• showAlerts: sends the alert content when the model returns a non-OK reply.
• useIndicator: emits indicator events for UI status surfaces.

If all three are false, OpenClaw skips the heartbeat run entirely (no model call).

Per-channel vs per-account examples

{  channels: {    defaults: {      heartbeatVisibility: {        showOk: false,        showAlerts: true,        useIndicator: true,      },    },    slack: {      heartbeatVisibility: {        showOk: true, // all Slack accounts      },      accounts: {        ops: {          heartbeatVisibility: {            showAlerts: false, // suppress alerts for the ops account only          },        },      },    },    telegram: {      heartbeatVisibility: {        showOk: true,      },    },  },}

Common patterns

Monitor scratch (optional)

Each heartbeat automation job owns a private monitor scratch stored in the shared state database. Think of it as your "heartbeat checklist": small, stable, and safe to consider every 30 minutes. When scratch exists, its content is appended to the heartbeat prompt.

Manage it with the automations CLI (the job id comes from openclaw cron list --all):

openclaw cron scratch <jobId>                 # print the current scratchopenclaw cron scratch <jobId> --set "..."     # replace it with exact textopenclaw cron scratch <jobId> --file notes.md # replace it from a file (- for stdin)openclaw cron scratch <jobId> --unset         # remove it

Writes are compare-and-swap guarded: pass --expected-revision <n> to fail instead of overwriting a concurrent edit. Scratch is capped at 256 KiB and never appears in cron list/cron runs output.

The agent can also update its own scratch: during a heartbeat turn, heartbeat_respond accepts an optional scratch string that fully replaces the monitor's scratch for future heartbeats.

OpenClaw skips the heartbeat run to save API calls when scratch exists but is effectively empty. Effectively empty means only blank lines, Markdown or HTML comments, Markdown headings like # Heading, fence markers, or empty checklist stubs. That skip is reported as reason=empty-heartbeat-file. Scheduled interval monitors without due tasks resolve this skip before deferring behind busy execution queues. If no scratch exists, the heartbeat still runs and the model decides what to do.

Keep it tiny (short checklist or reminders) to avoid prompt bloat.

Example scratch:

# Heartbeat checklist - Quick scan: anything urgent in inboxes?- If it's daytime, do a lightweight check-in if nothing else is pending.- If a task is blocked, write down _what is missing_ and ask Peter next time.

Schedule recurring checks with automations

Monitor scratch is prompt context, not a scheduler. Create each recurring check as an automation job so it has its own cadence, enable/disable state, and run history. Automation jobs can still target the main session when the check should use the normal conversation context.

Older scratch may contain a structured tasks: block. Run openclaw doctor --fix once after upgrading: Doctor converts every valid entry into an independently scheduled automation job. It preserves each entry's interval and previous last-run timing. It removes the retired block and keeps the surrounding scratch prose. Runtime heartbeat turns do not parse tasks: text as schedules.

Doctor-created heartbeat task jobs keep heartbeat active-hours, cooldown, flood, and busy guards. Jobs due together can coalesce into one heartbeat turn. An occurrence outside active hours is skipped and tried again at its next scheduled occurrence.

Can the agent update its scratch?

Yes. During a heartbeat turn, the agent can pass a scratch value to heartbeat_respond to fully replace the monitor scratch for future heartbeats. You can also ask it in a normal chat to run openclaw cron scratch <jobId> --set ..., or edit the scratch yourself with the same command. Manage recurring schedules with automations instead of writing scheduler syntax into scratch.

Manual wake (on-demand)

Use openclaw system event to enqueue a system event and optionally trigger an immediate heartbeat:

openclaw system event --text "Check for urgent follow-ups" --mode now

If no --session-key is given and multiple agents have heartbeat configured, --mode now runs each of those agent heartbeats immediately.

Broadcast completion reports an agent failure even if another agent succeeded or was quietly skipped. Busy retries and guarded deferrals keep their existing retry behavior.

Related heartbeat controls in the same CLI group:

openclaw system heartbeat last     # show the last heartbeat eventopenclaw system heartbeat enable   # enable heartbeatsopenclaw system heartbeat disable  # disable heartbeats

Cost awareness

Heartbeats run full agent turns. Shorter intervals burn more tokens. To reduce cost:

• Use isolatedSession: true to avoid sending full conversation history (~100K tokens down to ~2-5K per run).
• Use lightContext: true to skip workspace bootstrap files for heartbeat runs.
• Set a cheaper model (e.g. ollama/llama3.2:1b).
• Keep the monitor scratch small.
• Set target: "none" explicitly if you only want internal state updates.

Context overflow after heartbeat

Heartbeats preserve the shared session's existing runtime model after the run completes. A heartbeat that switched a session to a smaller local model can therefore leave that model in place for the next main-session turn. An Ollama model with a 32k window is one example. That next turn may report context overflow. If the session's last runtime model also matches configured heartbeat.model, OpenClaw's recovery message calls out heartbeat model bleed as the likely cause. The message also suggests a fix.

To avoid this, use isolatedSession: true to run heartbeats in a fresh session. You can combine it with lightContext: true for the smallest prompt. Otherwise choose a heartbeat model with a context window large enough for the shared session.

Related

• Automation - all automation mechanisms at a glance
• Timezone - how timezone affects heartbeat scheduling
• Troubleshooting - debugging automation issues