docs/gateway/heartbeat.md
Heartbeat 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 — it does not create background task records. Task records are for detached work (ACP runs, subagents, isolated cron jobs).
Troubleshooting: Scheduled Tasks
Example config:
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last", // explicit delivery to last contact (default is "none")
directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files
isolatedSession: true, // optional: fresh session each run (no conversation history)
skipWhenBusy: true, // optional: also defer when subagent or nested lanes are busy
// activeHours: { start: "08:00", end: "24:00" },
// includeReasoning: true, // optional: send separate `Reasoning:` message too
},
},
},
}
30m (or 1h when Anthropic OAuth/token auth is the detected auth mode, including Claude CLI reuse). Set agents.defaults.heartbeat.every or per-agent agents.list[].heartbeat.every; use 0m to disable.agents.defaults.heartbeat.prompt): Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.0m, normal runs also omit HEARTBEAT.md from bootstrap context so the model does not see heartbeat-only instructions.heartbeat.activeHours) are checked in the configured timezone. Outside the window, heartbeats are skipped until the next tick inside the window.heartbeat.skipWhenBusy: true to defer on extra busy lanes (subagent or nested command work) as well; this is useful for local Ollama and other constrained single-runtime hosts.The default prompt is intentionally broad:
Heartbeat can react to completed background tasks, but a heartbeat run itself does not create a task record.
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.list[].heartbeat.prompt) to a custom body (sent verbatim).
HEARTBEAT_OK.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.HEARTBEAT_OK as an ack when it appears at the start or end of the reply. The token is stripped and the reply is dropped if the remaining content is ≤ ackMaxChars (default: 300).HEARTBEAT_OK appears in the middle of a reply, it is not treated specially.HEARTBEAT_OK; return only the alert text.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.
{
agents: {
defaults: {
heartbeat: {
every: "30m", // default: 30m (0m disables)
model: "anthropic/claude-opus-4-6",
includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "bluebubbles")
to: "+15551234567", // optional channel-specific override
accountId: "ops-bot", // optional multi-account channel id
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
},
},
},
}
agents.defaults.heartbeat sets global heartbeat behavior.agents.list[].heartbeat merges on top; if any agent has a heartbeat block, only those agents run heartbeats.channels.defaults.heartbeat sets visibility defaults for all channels.channels.<channel>.heartbeat overrides channel defaults.channels.<channel>.accounts.<id>.heartbeat (multi-account channels) overrides per-channel settings.If any agents.list[] 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: {
defaults: {
heartbeat: {
every: "30m",
target: "last", // explicit delivery to last contact (default is "none")
},
},
list: [
{ id: "main", default: true },
{
id: "ops",
heartbeat: {
every: "1h",
target: "whatsapp",
to: "+15551234567",
timeoutSeconds: 45,
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
},
},
],
},
}
Restrict heartbeats to business hours in a specific timezone:
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last", // explicit delivery to last contact (default is "none")
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.
If you want heartbeats to run all day, use one of these patterns:
activeHours entirely (no time-window restriction; this is the default behavior).activeHours: { start: "00:00", end: "24:00" }.Use accountId to target a specific account on multi-account channels like Telegram:
{
agents: {
list: [
{
id: "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" },
},
},
},
}
main (default): agent main session.openclaw sessions --json or the sessions CLI)."user": uses your agents.defaults.userTimezone if set, otherwise falls back to the host system timezone."local": always uses the host system timezone.America/New_York): used directly; if invalid, falls back to the "user" behavior above.start and end must not be equal for an active window; equal values are treated as zero-width (always outside the window).By default, HEARTBEAT_OK acknowledgments are suppressed while alert content is delivered. You can adjust this per channel or per account:
channels:
defaults:
heartbeat:
showOk: false # Hide HEARTBEAT_OK (default)
showAlerts: true # Show alert messages (default)
useIndicator: true # Emit indicator events (default)
telegram:
heartbeat:
showOk: true # Show OK acknowledgments on Telegram
whatsapp:
accounts:
work:
heartbeat:
showAlerts: false # Suppress alert delivery for this account
Precedence: per-account → per-channel → channel defaults → built-in defaults.
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).
channels:
defaults:
heartbeat:
showOk: false
showAlerts: true
useIndicator: true
slack:
heartbeat:
showOk: true # all Slack accounts
accounts:
ops:
heartbeat:
showAlerts: false # suppress alerts for the ops account only
telegram:
heartbeat:
showOk: true
| Goal | Config |
|---|---|
| Default behavior (silent OKs, alerts on) | (no config needed) |
| Fully silent (no messages, no indicator) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false } |
| Indicator-only (no messages) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true } |
| OKs in one channel only | channels.telegram.heartbeat: { showOk: true } |
If a HEARTBEAT.md file exists in the workspace, the default prompt tells the agent to read it. Think of it as your "heartbeat checklist": small, stable, and safe to include every 30 minutes.
On normal runs, HEARTBEAT.md is only injected when heartbeat guidance is enabled for the default agent. Disabling the heartbeat cadence with 0m or setting includeSystemPromptSection: false omits it from normal bootstrap context.
If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown headers like # Heading), OpenClaw skips the heartbeat run to save API calls. That skip is reported as reason=empty-heartbeat-file. If the file is missing, the heartbeat still runs and the model decides what to do.
Keep it tiny (short checklist or reminders) to avoid prompt bloat.
Example HEARTBEAT.md:
# 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.
tasks: blocksHEARTBEAT.md also supports a small structured tasks: block for interval-based checks inside heartbeat itself.
Example:
tasks:
- name: inbox-triage
interval: 30m
prompt: "Check for urgent unread emails and flag anything time sensitive."
- name: calendar-scan
interval: 2h
prompt: "Check for upcoming meetings that need prep or follow-up."
# Additional instructions
- Keep alerts short.
- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.
Task mode is useful when you want one heartbeat file to hold several periodic checks without paying for all of them every tick.
Yes — if you ask it to.
HEARTBEAT.md is just a normal file in the agent workspace, so you can tell the agent (in a normal chat) something like:
HEARTBEAT.md to add a daily calendar check."HEARTBEAT.md so it's shorter and focused on inbox follow-ups."If you want this to happen proactively, you can also include an explicit line in your heartbeat prompt like: "If the checklist becomes stale, update HEARTBEAT.md with a better one."
<Warning> Don't put secrets (API keys, phone numbers, private tokens) into `HEARTBEAT.md` — it becomes part of the prompt context. </Warning>You can enqueue a system event and trigger an immediate heartbeat with:
openclaw system event --text "Check for urgent follow-ups" --mode now
If multiple agents have heartbeat configured, a manual wake runs each of those agent heartbeats immediately.
Use --mode next-heartbeat to wait for the next scheduled tick.
By default, heartbeats deliver only the final "answer" payload.
If you want transparency, enable:
agents.defaults.heartbeat.includeReasoning: trueWhen enabled, heartbeats will also deliver a separate message prefixed Reasoning: (same shape as /reasoning on). This can be useful when the agent is managing multiple sessions/codexes and you want to see why it decided to ping you — but it can also leak more internal detail than you want. Prefer keeping it off in group chats.
Heartbeats run full agent turns. Shorter intervals burn more tokens. To reduce cost:
isolatedSession: true to avoid sending full conversation history (~100K tokens down to ~2-5K per run).lightContext: true to limit bootstrap files to just HEARTBEAT.md.model (e.g. ollama/llama3.2:1b).HEARTBEAT.md small.target: "none" if you only want internal state updates.If a heartbeat previously left an existing session on a smaller local model, for example an Ollama model with a 32k window, and the next main-session turn reports context overflow, reset the session runtime model back to the configured primary model. OpenClaw's reset message calls this out when the last runtime model matches configured heartbeat.model.
Current heartbeats preserve the shared session's existing runtime model after the run completes. You can still use isolatedSession: true to run heartbeats in a fresh session, combine it with lightContext: true for the smallest prompt, or choose a heartbeat model with a context window large enough for the shared session.