Heartbeat

​

Quick start (beginner)

{
  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: 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.
• Prompt body (configurable via agents.defaults.heartbeat.prompt): Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• 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 user message. The system prompt automatically includes a “Heartbeats” section when cadence is enabled for the default agent; that guidance has no separate heartbeat toggle.
• When heartbeats are disabled with 0m, the monitor cron job stays but is disabled, and its scratch is retained for when you re-enable the cadence.
• When cron itself is disabled, 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 cron 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, cron, and target-session busy guards. Sibling agents do not pause each other.

​

What the heartbeat prompt is for

• Recurring checks: create scheduled jobs 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).

​

Response contract

• If nothing needs attention, reply with HEARTBEAT_OK.
• 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. no_change acknowledgments and visible notifications are not stored this way.
• During heartbeat runs, OpenClaw treats 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 at most 300 characters. This suppression budget is fixed, not configurable per heartbeat.
• If HEARTBEAT_OK appears in the middle of a reply, it is not treated specially.
• For alerts, do not include HEARTBEAT_OK; return only the alert text.
• 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.

​

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: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")
        to: "+15551234567", // optional channel-specific override
        accountId: "ops-bot", // optional multi-account channel id
        prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
      },
    },
  },
}

​

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

{
  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: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        },
      },
    ],
  },
}

​

Active hours example

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

​

24/7 setup

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

​

Multi-account example

{
  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

​

Delivery behavior

​

Visibility controls

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

​

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.

​

Per-channel vs per-account examples

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

​

Monitor scratch (optional)

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

# 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 cron

​

Can the agent update its scratch?

​

Manual wake (on-demand)

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

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

​

Cost awareness

• 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.
• Use target: "none" if you only want internal state updates.

​

Context overflow after heartbeat

​

Related

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