Use this file to discover all available pages before exploring further.

Heartbeat

note

**Heartbeat vs cron?** See [Automation & Tasks](/automation) for guidance on when to use each.

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

Quick start (beginner)

Pick a cadence

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

Add HEARTBEAT.md (optional)

Create a tiny `HEARTBEAT.md` checklist or `tasks:` block in the agent workspace.

Decide where heartbeat messages should go

`target: "none"` is the default; set `target: "last"` to route to the last contact.

Optional tuning

* Enable heartbeat reasoning delivery for transparency. * Use lightweight bootstrap context if heartbeat runs only need `HEARTBEAT.md`. * Enable isolated sessions to avoid sending full conversation history each heartbeat. * Restrict heartbeats to active hours (local time).

Example config:


json5
{
  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
      },
    },
  },
}

Defaults

Interval:
text
30m
(or
text
1h
when Anthropic OAuth/token auth is the detected auth mode, including Claude CLI reuse). Set
text
agents.defaults.heartbeat.every
or per-agent
text
agents.list[].heartbeat.every
; use
text
0m
to disable.
Prompt body (configurable via
text
agents.defaults.heartbeat.prompt
):
text
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.
The heartbeat prompt is sent verbatim as the user message. The system prompt includes a "Heartbeat" section only when heartbeats are enabled for the default agent, and the run is flagged internally.
When heartbeats are disabled with
text
0m
, normal runs also omit
text
HEARTBEAT.md
from bootstrap context so the model does not see heartbeat-only instructions.
Active hours (
text
heartbeat.activeHours
) are checked in the configured timezone. Outside the window, heartbeats are skipped until the next tick inside the window.
Heartbeats automatically defer while cron work is active or queued. Set
text
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.

What the heartbeat prompt is for

The default prompt is intentionally broad:

Background tasks: "Consider outstanding tasks" nudges the agent to review follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.
Human check-in: "Checkup sometimes on your human during day time" nudges an occasional lightweight "anything you need?" message, but avoids night-time spam by using 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

text

agents.defaults.heartbeat.prompt

(or

text

agents.list[].heartbeat.prompt

) to a custom body (sent verbatim).

Response contract

If nothing needs attention, reply with
text
HEARTBEAT_OK
.
During heartbeat runs, OpenClaw treats
text
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 ≤
text
ackMaxChars
(default: 300).
If
text
HEARTBEAT_OK
appears in the middle of a reply, it is not treated specially.
For alerts, do not include
text
HEARTBEAT_OK
; return only the alert text.

Outside heartbeats, stray

text

HEARTBEAT_OK

at the start/end of a message is stripped and logged; a message that is only

text

HEARTBEAT_OK

is dropped.

Config


json5
{
  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
      },
    },
  },
}

Scope and precedence

text
agents.defaults.heartbeat
sets global heartbeat behavior.
text
agents.list[].heartbeat
merges on top; if any agent has a
text
heartbeat
block, only those agents run heartbeats.
text
channels.defaults.heartbeat
sets visibility defaults for all channels.
text
channels.<channel>.heartbeat
overrides channel defaults.
text
channels.<channel>.accounts.<id>.heartbeat
(multi-account channels) overrides per-channel settings.

Per-agent heartbeats

If any

text

agents.list[]

entry includes a

text

heartbeat

block, only those agents run heartbeats. The per-agent block merges on top of

text

agents.defaults.heartbeat

(so you can set shared defaults once and override per agent).

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


json5
{
  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.",
        },
      },
    ],
  },
}

Active hours example

Restrict heartbeats to business hours in a specific timezone:


json5
{
  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.

24/7 setup

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

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

warning

Do not set the same `start` and `end` time (for example `08:00` to `08:00`). That is treated as a zero-width window, so heartbeats are always skipped.

Multi-account example

Use

text

accountId

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


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

Field notes

Heartbeat interval (duration string; default unit = minutes). Optional model override for heartbeat runs (`provider/model`). When enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`). When true, heartbeat runs use lightweight bootstrap context and keep only `HEARTBEAT.md` from workspace bootstrap files. When true, each heartbeat runs in a fresh session with no prior conversation history. Uses the same isolation pattern as cron `sessionTarget: "isolated"`. Dramatically reduces per-heartbeat token cost. Combine with `lightContext: true` for maximum savings. Delivery routing still uses the main session context. When true, heartbeat runs defer on extra busy lanes: subagent or nested command work. Cron lanes always defer heartbeats, even without this flag, so local-model hosts do not run cron and heartbeat prompts at the same time. Optional session key for heartbeat runs.

text
main
(default): agent main session.
Explicit session key (copy from
text
openclaw sessions --json
or the sessions CLI).
Session key formats: see Sessions and Groups.

* `last`: deliver to the last used external channel. * explicit channel: any configured channel or plugin id, for example `discord`, `matrix`, `telegram`, or `whatsapp`. * `none` (default): run the heartbeat but **do not deliver** externally. Controls direct/DM delivery behavior. `allow`: allow direct/DM heartbeat delivery. `block`: suppress direct/DM delivery (`reason=dm-blocked`). Optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id). For Telegram topics/threads, use `:topic:`. Optional account id for multi-account channels. When `target: "last"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped. Overrides the default prompt body (not merged). Max chars allowed after `HEARTBEAT_OK` before delivery. When true, suppresses tool error warning payloads during heartbeat runs. Restricts heartbeat runs to a time window. Object with `start` (HH:MM, inclusive; use `00:00` for start-of-day), `end` (HH:MM exclusive; `24:00` allowed for end-of-day), and optional `timezone`.

Omitted or
text
"user"
: uses your
text
agents.defaults.userTimezone
if set, otherwise falls back to the host system timezone.
text
"local"
: always uses the host system timezone.
Any IANA identifier (e.g.
text
America/New_York
): used directly; if invalid, falls back to the
text
"user"
behavior above.
text
start
and
text
end
must not be equal for an active window; equal values are treated as zero-width (always outside the window).
Outside the active window, heartbeats are skipped until the next tick inside the window.

Delivery behavior

Visibility controls

By default,

text

HEARTBEAT_OK

acknowledgments are suppressed while alert content is delivered. You can adjust this per channel or per account:


yaml
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.

What each flag does

text
showOk
: sends a
text
HEARTBEAT_OK
acknowledgment when the model returns an OK-only reply.
text
showAlerts
: sends the alert content when the model returns a non-OK reply.
text
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


yaml
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

Common patterns

Goal	Config
Default behavior (silent OKs, alerts on)	(no config needed)
Fully silent (no messages, no indicator)	text `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
Indicator-only (no messages)	text `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
OKs in one channel only	text `channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (optional)

If a

text

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,

text

HEARTBEAT.md

is only injected when heartbeat guidance is enabled for the default agent. Disabling the heartbeat cadence with

text

0m

or setting

text

includeSystemPromptSection: false

omits it from normal bootstrap context.

text

HEARTBEAT.md

exists but is effectively empty (only blank lines and markdown headers like

text

# Heading

), OpenClaw skips the heartbeat run to save API calls. That skip is reported as

text

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

text

HEARTBEAT.md


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.

text
`tasks:`
blocks

text

HEARTBEAT.md

also supports a small structured

text

tasks:

block for interval-based checks inside heartbeat itself.

Example:


md
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.

Can the agent update HEARTBEAT.md?

Yes — if you ask it to.

text

HEARTBEAT.md

is just a normal file in the agent workspace, so you can tell the agent (in a normal chat) something like:

"Update
text
HEARTBEAT.md
to add a daily calendar check."
"Rewrite
text
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.

Manual wake (on-demand)

You can enqueue a system event and trigger an immediate heartbeat with:


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

If multiple agents have

text

heartbeat

configured, a manual wake runs each of those agent heartbeats immediately.

Use

text

--mode next-heartbeat

to wait for the next scheduled tick.

Reasoning delivery (optional)

By default, heartbeats deliver only the final "answer" payload.

If you want transparency, enable:

text
agents.defaults.heartbeat.includeReasoning: true

When enabled, heartbeats will also deliver a separate message prefixed

text

Reasoning:

(same shape as

text

/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.

Cost awareness

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

Use
text
isolatedSession: true
to avoid sending full conversation history (~100K tokens down to ~2-5K per run).
Use
text
lightContext: true
to limit bootstrap files to just
text
HEARTBEAT.md
.
Set a cheaper
text
model
(e.g.
text
ollama/llama3.2:1b
).
Keep
text
HEARTBEAT.md
small.
Use
text
target: "none"
if you only want internal state updates.

Context overflow after heartbeat

If a heartbeat uses a smaller local model, for example an Ollama model with a 32k window, and the next main-session turn reports context overflow, check whether the previous heartbeat left the session on the heartbeat model. OpenClaw's reset message calls this out when the last runtime model matches configured

text

heartbeat.model

Use

text

isolatedSession: true

to run heartbeats in a fresh session, combine it with

text

lightContext: true

for the smallest prompt, or choose a heartbeat model with a context window large enough for the shared session.

Automation & Tasks — all automation mechanisms at a glance
Background Tasks — how detached work is tracked
Timezone — how timezone affects heartbeat scheduling
Troubleshooting — debugging automation issues

OpenClaw Docs

Heartbeat

note

Quick start (beginner)

Pick a cadence

Add HEARTBEAT.md (optional)

Decide where heartbeat messages should go

Optional tuning

Defaults

What the heartbeat prompt is for

Response contract

Config

Scope and precedence

Per-agent heartbeats

Active hours example

24/7 setup

warning

Multi-account example

Field notes

Delivery behavior

Visibility controls

What each flag does

Per-channel vs per-account examples

Common patterns

HEARTBEAT.md (optional)

text
`tasks:`
blocks

Can the agent update HEARTBEAT.md?

warning

Manual wake (on-demand)

Reasoning delivery (optional)

Cost awareness

Context overflow after heartbeat

Related

OpenClaw Docs

Heartbeat

note

Quick start (beginner)

Pick a cadence

Add HEARTBEAT.md (optional)

Decide where heartbeat messages should go

Optional tuning

Defaults

What the heartbeat prompt is for

Response contract

Config

Scope and precedence

Per-agent heartbeats

Active hours example

24/7 setup

warning

Multi-account example

Field notes

Delivery behavior

Visibility controls

What each flag does

Per-channel vs per-account examples

Common patterns

HEARTBEAT.md (optional)

textCopytasks: blocks

Can the agent update HEARTBEAT.md?

warning

Manual wake (on-demand)

Reasoning delivery (optional)

Cost awareness

Context overflow after heartbeat

Related

text
`tasks:`
blocks