Heartbeat Polling and Notification Rules for Agents

Note

Heartbeat is an automation. See Automation for guidance on choosing the system-owned monitor or an independently scheduled job.

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 - it does not create background task records. Task records are for detached work (ACP runs, subagents, isolated automation jobs).

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.

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" also disables only the recurring cadence. A targeted event-driven wake can still run one agent turn, such as the completion follow-up requested by a background exec task. It does not create or re-enable a recurring schedule. Use tool policy and sandboxing, rather than heartbeat cadence, to control whether those agent turns may execute commands.

Troubleshooting: Automations

Quick start (beginner)

Pick a cadence

Leave heartbeats enabled (default is 30m, or 1h when Anthropic OAuth/token auth is configured, including Claude CLI reuse) or set your own cadence.

Add monitor scratch (optional)

Store a tiny checklist in the heartbeat monitor's scratch with openclaw cron scratch <jobId> --set "...".

Decide where heartbeat messages should go

Heartbeat alerts go to the operator's direct message by default. Set commands.ownerAllowFrom or a concrete channel allowFrom; wildcard-only allowlists do not identify an owner.

Optional tuning

• Use lightweight bootstrap context if heartbeat runs only need the monitor scratch.
• Enable isolated sessions to avoid sending full conversation history each heartbeat.
• Restrict heartbeats to active hours (local time).

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" },
      },
    },
  },
}

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.
• 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 monitor automation job stays but is disabled, and its 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. 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.

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 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.entries.*.heartbeat.prompt) to a custom body (sent verbatim).

Response contract

• When there is nothing to flag, answer with NO_REPLY.
• Heartbeat invocations can instead pass heartbeat_respond with notify: false to suppress any visible change, or notify: true together with notificationText to raise an alert. If a structured tool response is supplied, it wins over the text fallback.
• A meaningful heartbeat_respond outcome paired with notify: false produces no output but is retained as limited internal context for the following user turn within that session. A generated notify: true alert whose delivery failed or went unconfirmed is likewise stored, complete with its alert text and the reason for delivery. This represents the session's most recent result, not a log of alerts or a queue for exact delivery retries. no_change confirmations and confirmed visible notifications are excluded from this storage.
• Older custom prompts might still emit the legacy HEARTBEAT_OK acknowledgment. OpenClaw recognizes it at the beginning or end of a response and discards the response if the remaining text is 300 characters or fewer; the suppression limit is fixed.
• A legacy HEARTBEAT_OK placed in the middle of a response is ignored.
• For alerts, output only the alert text; leave out any silent acknowledgment.
• Delivery picks the last outbound-capable payload that is not a reasoning payload. Separate reasoning or thinking payloads stay internal; a result containing only reasoning yields no alert.
• Tool error warnings stay active during heartbeat turns.

Outside of heartbeats, a stray HEARTBEAT_OK at the start/end of a message gets stripped and logged; a message consisting solely of HEARTBEAT_OK is discarded.

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 controls heartbeat behavior globally.
• agents.entries.*.heartbeat layers on top; when any agent defines a heartbeat block, only those agents execute heartbeats.
• Ambient ownership is resolved through agents.defaults.heartbeat.agentId, agents.defaults.systemAgent.agentId, the legacy default owner, and finally the sole agent; if no per-agent or default heartbeat block is present and that chain leaves a multi-agent roster without an owner, heartbeats remain off and trigger validation and Gateway warnings.
• channels.defaults.heartbeatVisibility establishes visibility defaults across all channels.
• channels.<channel>.heartbeatVisibility overrides channel defaults.
• channels.<channel>.accounts.<id>.heartbeatVisibility (for multi-account channels) overrides per-channel settings.

Per-agent heartbeats

If any agents.entries.* entry contains a heartbeat block, only those agents run heartbeats. The per-agent block layers on top of agents.defaults.heartbeat, letting you define shared defaults once and then override them per agent.

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "owner", // default: operator DM
      },
    },
    entries: {
      main: { default: true },
      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.",
        },
      },
    },
  },
}

Active hours example

Limit heartbeats to business hours in a particular 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 within the window runs as usual.

24/7 setup

To keep heartbeats running all day, apply one of these approaches:

• Leave out activeHours entirely (no time-window restriction; this is the default).
• Define a full-day window: activeHours: { start: "00:00", end: "24:00" }.

Warning

Avoid setting the same start and end time (for instance 08:00 to 08:00). This is interpreted as a zero-width window, so heartbeats are always skipped.

Multi-account example

Use accountId to aim at a particular account on multi-account channels such as Telegram:

{
  agents: {
    entries: {
      ops: {
        default: true,
        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

• every (string), Heartbeat interval (duration string; default unit = minutes).

• model (string), Optional model override for heartbeat runs (provider/model).

• lightContext (boolean, default: false), When true, heartbeat runs use lightweight bootstrap context and skip workspace bootstrap files. Monitor scratch is injected by the heartbeat runner in either case.

• isolatedSession (boolean, default: false), When true, each heartbeat runs in a fresh session with no prior conversation history. Uses the same isolation pattern as automation jobs with sessionTarget: "isolated". Dramatically reduces per-heartbeat token cost. Combine with lightContext: true for maximum savings. Delivery routing still uses the main session context.

• session (string), Optional session key for heartbeat runs. - main (default): agent main session. - Explicit session key (copy from openclaw sessions --json or the sessions CLI). - Session key formats: see Sessions and Groups.

• target (string), - owner (default): the initial resolvable operator DM from commands.ownerAllowFrom gets the delivery, followed by channel allowFrom. Groups and channels are never resolved through this path. - last: deliberately track the most recent external conversation, which covers groups and channels. - explicit channel: any configured channel or plugin id, such as discord, matrix, telegram, or whatsapp. - none: the heartbeat executes solely for internal state; external delivery is not performed.

• directPolicy (allow" | "block, default: allow), Governs how direct/DM sends are handled. allow: direct/DM heartbeat delivery is permitted. block: direct/DM delivery is blocked (reason=dm-blocked).

• to (string), The recipient for a specified channel target (for instance, E.164 for WhatsApp or a Telegram chat id). owner and a missing target cause to to be ignored. For Telegram topics/threads, employ <chatId>:topic:<messageThreadId>.

• accountId (string), Optional account identifier for channels supporting multiple accounts. When target: "last", the account id applies to the resolved last channel if accounts are supported; otherwise it gets disregarded. Should the account id not match a configured account for the resolved channel, the delivery is skipped.

• prompt (string), Replaces the default prompt body (no merging occurs).

• timeoutSeconds (number, default: global timeout or min(every, 600)), The maximum seconds a heartbeat agent turn can run before being aborted. Leaving it unset uses agents.defaults.timeoutSeconds when available; otherwise, the heartbeat cadence is capped at 600 seconds.

• activeHours (object), Limits heartbeat execution to a specific time window. An object with start (HH:MM, inclusive; 00:00 marks start-of-day), end (HH:MM exclusive; 24:00 is allowed for end-of-day), and optional timezone. - When omitted or "user": your agents.defaults.userTimezone is used if set, otherwise the host system timezone applies. - "local": the host system timezone is always used. - Any IANA identifier (e.g. America/New_York): used as given; an invalid one falls back to the "user" behavior described above. - For an active window, start and end must differ; equal values mean zero-width (always outside the window). - Outside the active window, heartbeats are deferred until the next tick within the window.

Note

Heartbeat configuration is strict: only the fields listed above are accepted. Acknowledgment suppression, reasoning visibility, system-prompt guidance, busy deferral, and tool-error warning behavior are fixed runtime policies rather than heartbeat configuration fields.

Delivery behavior

Session and target routing

• By default, heartbeats execute in the agent's main session (agent:<id>:<mainKey>), or global when session.scope = "global". To target a specific channel session (Discord/WhatsApp/etc.), set session as an override.
• session only influences the run context; delivery is managed by target and to.
• The default owner target picks an explicitly configured owner identity. The exact account/thread is reused only when the session's last route is a direct chat with that owner.
• A wake that includes a channel and recipient uses that named origin before owner discovery. This event destination can be a group because it is explicit, not inferred.
• For delivery to a specific channel/recipient, configure a channel target plus to. target: "last" serves as an explicit opt-in to the last external conversation, including groups.
• Heartbeat deliveries permit direct/DM targets by default. Setting directPolicy: "block" suppresses direct-target sends while the heartbeat turn still runs.
• Scheduled heartbeats are skipped and retried later when the main queue or automation work is busy, any reply or embedded run for the same agent is active, or the resolved target session has active or queued work. Immediate and manual wakes bypass only the broad same-agent active-run precheck.
• If owner has no concrete, DM-capable owner or configured channel, the poll is skipped as reason=no-route before the agent runs. Explicit last also skips when the session has no external route.
• The first alert delivered by the implicit owner default explains periodic checks and how to choose target: "none". Later alerts omit that line.

Visibility and skip behavior

• When showOk, showAlerts, and useIndicator are all turned off, the run gets skipped right away as reason=alerts-disabled.
• With only alert delivery turned off, OpenClaw still executes the heartbeat, refreshes due-task timestamps, restores the session idle timestamp, and holds back the outward alert payload.
• If the channel readiness check blocks an alert, OpenClaw logs the failed delivery and retries the heartbeat after a one-minute grace period without using up its cadence slot. That retry re-runs the heartbeat, not the exact earlier alert. Once a send reaches the durable delivery queue, transport retries are handled by that queue.
• When the resolved heartbeat target supports typing, OpenClaw displays typing while the heartbeat run is active. This uses the same target the heartbeat would send chat output to, and it is turned off by typingMode: "never".

Session lifecycle and audit

• Heartbeat-only replies do not keep the session alive. Heartbeat metadata may update the session row, but idle expiry relies on lastInteractionAt from the last real user/channel message, and daily expiry uses sessionStartedAt.
• Control UI and WebChat history hide heartbeat prompts and OK-only acknowledgments. The underlying session transcript can still contain those turns for audit/replay.
• Detached background tasks can enqueue a system event and wake heartbeat when the main session should notice something quickly. That wake does not turn the heartbeat run into a background task.

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 monitor automation job owns a private scratch document 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 scratch
openclaw cron scratch <jobId> --set "..."     # replace it with exact text
openclaw 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.

Note

Migrating from HEARTBEAT.md or config-only cadence? Run openclaw doctor --fix. Doctor first creates or updates the system-owned monitor rows from agents.*.heartbeat, then imports each agent's workspace HEARTBEAT.md into the monitor's scratch, converts any valid legacy tasks: entries into automation jobs, archives the original under the state directory (backups/heartbeat-migration/), and removes the file. Runtime heartbeat instructions come from database scratch only; the runtime never reads HEARTBEAT.md.

If scratch exists but is effectively empty (only blank lines, Markdown/HTML comments, Markdown headings like # Heading, fence markers, or empty checklist stubs), OpenClaw skips the heartbeat run to save API calls. That skip is reported as reason=empty-heartbeat-file. 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

Heartbeat 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, preserves its interval and previous last-run timing, and removes the retired block while keeping 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 prose 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.

Warning

Don't put secrets (API keys, phone numbers, private tokens) into monitor scratch - it becomes part of the prompt context.

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.

Related heartbeat controls in the same CLI group:

openclaw system heartbeat last     # show the last heartbeat event
openclaw system heartbeat enable   # enable heartbeats
openclaw system heartbeat disable  # disable heartbeats

Cost awareness

Heartbeats execute complete agent turns. When intervals are shorter, more tokens get consumed. To cut costs:

• Employ isolatedSession: true to skip sending the entire conversation history (roughly 100K tokens reduced to about 2-5K per run).
• Apply lightContext: true to bypass workspace bootstrap files during heartbeat runs.
• Opt for a less expensive model (for instance ollama/llama3.2:1b).
• Maintain a compact monitor scratch.
• Set target: "none" explicitly when only internal state updates are needed.

Context overflow after heartbeat

After a heartbeat finishes, the shared session's existing runtime model remains intact. So, if a heartbeat switches a session to a smaller local model (like an Ollama model with a 32k window), that model can persist for the next main-session turn. Should that turn then hit context overflow, and the session's last runtime model aligns with configured heartbeat.model, OpenClaw's recovery message flags heartbeat model bleed as the probable culprit and proposes a remedy.

To prevent this: use isolatedSession: true to run heartbeats in a fresh session (possibly paired with lightContext: true for the most minimal prompt), or pick a heartbeat model whose context window is large enough for the shared session.

Related

• Automation - a quick overview of all automation mechanisms
• Background Tasks - how detached work gets tracked
• Timezone - the effect of timezone on heartbeat scheduling
• Troubleshooting - resolving automation issues