Heartbeat (Gateway)

Heartbeat runs periodic agent turns in the main session so the model can

surface anything that needs attention without spamming you.

1. Leave heartbeats enabled (default is ''30m'', or ''1h'' for Anthropic OAuth/setup-token) or set your own cadence.

2. Create a tiny ''HEARTBEAT.md'' checklist in the agent workspace (optional but recommended).

3. Decide where heartbeat messages should go (''target: "last"'' is the default).

4. Optional: enable heartbeat reasoning delivery for transparency.

5. Optional: restrict heartbeats to active hours (local time).

Example config:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

- Interval: ''30m'' (or ''1h'' when Anthropic OAuth/setup-token is the detected auth mode). Set ''agents.defaults.heartbeat.every'' or per-agent ''agents.list[].heartbeat.every''; use ''0m'' to disable.

- Prompt body (configurable via ''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.''

- The heartbeat prompt is sent verbatim as the user message. The system

prompt includes a "Heartbeat" section and the run is flagged internally.

- Active hours (''heartbeat.activeHours'') are checked in the configured timezone.

Outside the window, heartbeats are skipped until the next tick inside the window.

El prompt predeterminado es intencionalmente amplio:

- 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 ''/concepts/timezone'').

Si quieres que un heartbeat haga algo muy específico (ej. "revisar Gmail PubSub

stats" or "verify gateway health"), set ''agents.defaults.heartbeat.prompt'' (or

''agents.list[].heartbeat.prompt'') to a custom body (sent verbatim).

- If nothing needs attention, reply with ''''HEARTBEAT_OK''''.

- 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 ''≤ ''ackMaxChars'''' (default: 300).

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

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-5",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific override
        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.''.heartbeat'' overrides channel defaults.

- ''channels.''.accounts.''.heartbeat'' (multi-account channels) overrides per-channel settings.

#

Si alguna entrada de ''agents.list[]'' incluye un bloque ''heartbeat'', ''solo esos agentes''

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",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          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.",
        },
      },
    ],
  },
}

#

- ''every'': heartbeat interval (duration string; default unit = minutes).

- ''model'': optional model override for heartbeat runs (''provider/model'').

- ''includeReasoning'': when enabled, also deliver the separate ''Reasoning:'' message when available (same shape as ''/reasoning on'').

- ''session'': 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'':

- ''last'' (default): deliver to the last used external channel.

- explicit channel: ''whatsapp'' / ''telegram'' / ''discord'' / ''googlechat'' / ''slack'' / ''msteams'' / ''signal'' / ''imessage''.

- ''none'': run the heartbeat but ''do not deliver'' externally.

- ''to'': optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id).

- ''prompt'': overrides the default prompt body (not merged).

- ''ackMaxChars'': max chars allowed after ''HEARTBEAT_OK'' before delivery.

- Heartbeats run in the agent's main session by default (''agent:'':'''')

or ''global'' when ''session.scope = "global"''. Set ''session'' to override to a

specific channel session (Discord/WhatsApp/etc.).

- ''session'' only affects the run context; delivery is controlled by ''target'' and ''to''.

- To deliver to a specific channel/recipient, set ''target'' + ''to''.

With ''target: "last"'', delivery uses the last external channel for that session.

- If the main queue is busy, the heartbeat is skipped and retried later.

- If ''target'' resolves to no external destination, the run still happens but no

outbound message is sent.

- Heartbeat-only replies do ''not'' keep the session alive; the last ''updatedAt''

is restored so idle expiry behaves normally.

Por defecto, los reconocimientos ''HEARTBEAT_OK'' se suprimen mientras se entrega contenido de alerta.

Puedes ajustar esto por canal o por cuenta:

channels:
  defaults:
    heartbeat:
      showOk: false # Ocultar HEARTBEAT_OK (predeterminado)
      showAlerts: true # Mostrar mensajes de alerta (predeterminado)
      useIndicator: true # Emitir eventos indicadores (predeterminado)
  telegram:
    heartbeat:
      showOk: true # Mostrar reconocimientos OK en Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suprimir entrega de alertas para esta cuenta

Precedencia: por-cuenta → por-canal → valores predeterminados de canal → valores predeterminados integrados.

#

- ''showOk'': envía un reconocimiento ''HEARTBEAT_OK'' cuando el modelo retorna una respuesta solo-OK.

- ''showAlerts'': envía el contenido de alerta cuando el modelo retorna una respuesta no-OK.

- ''useIndicator'': emite eventos indicadores para superficies de estado de UI.

Si <strong>los tres</strong> son false, OpenClaw salta la ejecución del heartbeat completamente (sin llamada al modelo).

#

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # todas las cuentas Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suprimir alertas solo para cuenta ops
  telegram:
    heartbeat:
      showOk: true

#

| Objetivo | Config |

| - |

| Comportamiento predeterminado (OKs silenciosos, alertas activadas) | _(sin configuración necesaria)_ |

| Completamente silencioso (sin mensajes, sin indicador) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }' |

| Solo indicador (sin mensajes) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }' |

| OKs en un solo canal | channels.telegram.heartbeat: { showOk: true }' |

Si existe un archivo ''HEARTBEAT.md'' en el workspace, el prompt predeterminado le dice al

agente que lo lea. Piénsalo como tu "checklist de heartbeat": pequeño, estable, y

seguro de incluir cada 30 minutos.

Si ''HEARTBEAT.md'' existe pero está efectivamente vacío (solo líneas en blanco y encabezados

markdown como ''# Heading''), OpenClaw salta la ejecución del heartbeat para ahorrar llamadas API.

Si el archivo falta, el heartbeat aún se ejecuta y el modelo decide qué hacer.

Mantenlo pequeño (checklist corto o recordatorios) para evitar inflar el prompt.

Ejemplo de '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'HEARTBEAT.md'</code>':