clawdbot/docs/heartbeat.md

summary, read_when

summary	read_when
Plan for heartbeat polling messages and notification rules	Adjusting heartbeat cadence or messaging

Heartbeat (Gateway)

Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming the user.

Prompt contract

• Heartbeat body defaults to HEARTBEAT (configurable via agent.heartbeat.prompt).
• If nothing needs attention, the model must reply exactly HEARTBEAT_OK.
• For alerts, do not include HEARTBEAT_OK; return only the alert text.

Config

{
  agent: {
    heartbeat: {
      every: "30m",           // duration string: ms|s|m|h (0m disables)
      model: "anthropic/claude-opus-4-5",
      target: "last",          // last | whatsapp | telegram | none
      to: "+15551234567",      // optional override for whatsapp/telegram
      prompt: "HEARTBEAT"      // optional override
    }
  }
}

Fields

• every: heartbeat interval (duration string; default unit minutes). Omit or set to 0m to disable.
• model: optional model override for heartbeat runs (provider/model).
• target: where heartbeat output is delivered.
  • last (default): send to the last used external channel.
  • whatsapp / telegram: force the channel (optionally set to).
  • none: do not deliver externally; output stays in the session (WebChat-visible).
• to: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
• prompt: optional override for the heartbeat body (default: HEARTBEAT).

Behavior

• Runs in the main session (session.mainKey, or global when scope is global).
• Uses the main lane queue; if requests are in flight, the wake is retried.
• Empty output or HEARTBEAT_OK is treated as “ok” and does not keep the session alive (updatedAt is restored).
• If target resolves to no external destination (no last route or none), the heartbeat still runs but no outbound message is sent.

Wake hook

• The gateway exposes a heartbeat wake hook so cron/jobs/webhooks can request an immediate run (requestHeartbeatNow).
• wake endpoints should enqueue system events and optionally trigger a wake; the heartbeat runner picks those up on the next tick or immediately.