Configura Heartbeat en tu Gateway

Seguro que alguna vez has sentido que tu agente se queda inactivo si no le escribes tú primero. Es frustrante tener que estar pendiente de la herramienta cuando debería ser al revés. Heartbeat soluciona esto permitiendo que el agente tome la iniciativa de forma periódica para que siempre esté un paso por delante de tus necesidades.

Heartbeat ejecuta turnos de agente periódicos en la sesión principal para que el modelo pueda mostrar cualquier cosa que requiera atención sin saturarte de mensajes.

Heartbeat es un turno programado en la sesión principal; no crea registros de background task. Los registros de tareas son para trabajos independientes (ejecuciones de ACP, subagentes o trabajos cron aislados).

Si tienes problemas, consulta: /automation/troubleshooting

Inicio rápido (principiante)

Deja los heartbeats activados (el valor por defecto es 30m, o 1h para Anthropic OAuth/setup-token) o define tu propia frecuencia.
Crea una pequeña lista de verificación HEARTBEAT.md en el workspace del agente (es opcional pero te lo recomiendo).
Decide a dónde deben ir los mensajes de heartbeat (el valor por defecto es target: "none"; usa target: "last" para enviarlos al último contacto).
Opcional: activa la entrega del razonamiento del heartbeat para mayor transparencia.
Opcional: usa un contexto de arranque ligero si los heartbeats solo necesitan leer HEARTBEAT.md.
Opcional: activa las sesiones aisladas para evitar enviar todo el historial de la conversación en cada heartbeat.
Opcional: restringe los heartbeats a tus horas activas (hora local).

Ejemplo de configuración:

{
  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)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

Valores por defecto

Intervalo: 30m (o 1h cuando se detecta Anthropic OAuth/setup-token como modo de autenticación). Configura agents.defaults.heartbeat.every o agents.list[].heartbeat.every por agente; usa 0m para desactivarlo.
Cuerpo del prompt (configurable mediante 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.
El prompt de heartbeat se envía literalmente como un mensaje de usuario. El prompt del sistema incluye una sección de “Heartbeat” y la ejecución se marca internamente.
Las horas activas (heartbeat.activeHours) se verifican en la zona horaria configurada. Fuera de ese horario, los heartbeats se omiten hasta el siguiente intervalo dentro de la ventana permitida.

Para qué sirve el prompt de heartbeat

El prompt por defecto es intencionadamente amplio:

Tareas en segundo plano: “Consider outstanding tasks” anima al agente a revisar seguimientos (bandeja de entrada, calendario, recordatorios, trabajo en cola) y mostrar cualquier cosa urgente.
Control del estado humano: “Checkup sometimes on your human during day time” permite un mensaje ocasional y ligero de “¿necesitas algo?”, pero evita el spam nocturno usando tu zona horaria local configurada (ver /concepts/timezone).

Heartbeat puede reaccionar a background tasks completadas, pero una ejecución de heartbeat en sí misma no crea un registro de tarea.

Si quieres que un heartbeat haga algo muy específico (por ejemplo, “revisar estadísticas de Gmail PubSub” o “verificar el estado del Gateway”), configura agents.defaults.heartbeat.prompt (o agents.list[].heartbeat.prompt) con un cuerpo personalizado (que se enviará literalmente).

Contrato de respuesta

Si nada requiere atención, la respuesta debe ser HEARTBEAT_OK.
Durante las ejecuciones de heartbeat, OpenClaw trata HEARTBEAT_OK como un acuse de recibo (ack) cuando aparece al principio o al final de la respuesta. El token se elimina y la respuesta se descarta si el contenido restante es ≤ ackMaxChars (por defecto: 300).
Si HEARTBEAT_OK aparece en medio de una respuesta, no recibe un trato especial.
Para las alertas, no incluyas HEARTBEAT_OK; devuelve solo el texto de la alerta.

Fuera de los heartbeats, cualquier HEARTBEAT_OK suelto al principio o al final de un mensaje se elimina y se registra; si un mensaje contiene únicamente HEARTBEAT_OK, se descarta.

AI Setup Assistant

Pasos siguientes

Configuración

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

Alcance y precedencia

agents.defaults.heartbeat define el comportamiento global del heartbeat.
agents.list[].heartbeat se fusiona encima; si algún agent tiene un bloque heartbeat, solo esos agents ejecutarán heartbeats.
channels.defaults.heartbeat establece los valores por defecto de visibilidad para todos los channels.
channels.<channel>.heartbeat sobrescribe los valores por defecto del channel.
channels.<channel>.accounts.<id>.heartbeat (channels multi-cuenta) sobrescribe la configuración por channel.

Heartbeats por agent

Si alguna entrada en agents.list[] incluye un bloque heartbeat, solo esos agents ejecutarán heartbeats. El bloque por agent se fusiona sobre agents.defaults.heartbeat (así puedes configurar valores compartidos una vez y sobrescribirlos por cada agent).

Ejemplo: dos agents, donde solo el segundo ejecuta 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",
          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.",
        },
      },
    ],
  },
}

Ejemplo de horas activas

Restringe los heartbeats al horario laboral en una zona horaria específica:

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

Fuera de esta ventana (antes de las 9 am o después de las 10 pm hora del Este), los heartbeats se saltan. El siguiente tick programado dentro de la ventana se ejecutará normalmente.

Configuración 24/7

Si quieres que los heartbeats funcionen todo el día, usa uno de estos patrones:

Omite activeHours por completo (sin restricción de ventana de tiempo; este es el comportamiento por defecto).
Configura una ventana de día completo: activeHours: { start: "00:00", end: "24:00" }.

No pongas la misma hora de start y end (por ejemplo, de 08:00 a 08:00). Eso se trata como una ventana de ancho cero, por lo que los heartbeats siempre se saltarán.

Ejemplo multi-cuenta

Usa accountId para dirigirte a una cuenta específica en channels multi-cuenta como Telegram:

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

Notas sobre los campos

every: intervalo del heartbeat (cadena de duración; unidad por defecto = minutos).
model: sobrescritura opcional del model para las ejecuciones del heartbeat (provider/model).
includeReasoning: cuando está activado, también entrega el mensaje Reasoning: por separado si está disponible (mismo formato que /reasoning on).
lightContext: si es true, las ejecuciones del heartbeat usan un contexto de bootstrap ligero y solo mantienen HEARTBEAT.md de los archivos de bootstrap del workspace.
isolatedSession: si es true, cada heartbeat se ejecuta en una sesión nueva sin historial de conversación previo. Usa el mismo patrón de aislamiento que cron sessionTarget: "isolated". Reduce drásticamente el coste de tokens por heartbeat. Combínalo con lightContext: true para ahorrar al máximo. El enrutamiento de la entrega sigue usando el contexto de la sesión principal.
session: clave de sesión opcional para las ejecuciones del heartbeat.
- main (por defecto): sesión principal del agent.
- Clave de sesión explícita (cópiala de openclaw sessions --json o de la CLI de sessions).
- Formatos de clave de sesión: consulta Sessions y Groups.
target:
- last: entrega al último channel externo utilizado.
- channel explícito: cualquier ID de channel o plugin configurado, por ejemplo discord, matrix, telegram o whatsapp.
- none (por defecto): ejecuta el heartbeat pero no lo entrega externamente.
directPolicy: controla el comportamiento de entrega directa/DM:
- allow (por defecto): permite la entrega de heartbeats por directo/DM.
- block: suprime la entrega por directo/DM (reason=dm-blocked).
to: sobrescritura opcional del destinatario (ID específico del channel, ej. E.164 para WhatsApp o un ID de chat de Telegram). Para temas/hilos de Telegram, usa <chatId>:topic:<messageThreadId>.
accountId: ID de cuenta opcional para channels multi-cuenta. Cuando target: "last", el ID de cuenta se aplica al último channel resuelto si admite cuentas; de lo contrario, se ignora. Si el ID de cuenta no coincide con una cuenta configurada para el channel resuelto, se salta la entrega.
prompt: sobrescribe el cuerpo del prompt por defecto (no se fusiona).
ackMaxChars: máximo de caracteres permitidos después de HEARTBEAT_OK antes de la entrega.
suppressToolErrorWarnings: si es true, suprime los avisos de errores de herramientas durante las ejecuciones del heartbeat.
activeHours: restringe las ejecuciones del heartbeat a una ventana de tiempo. Objeto con start (HH:MM, inclusivo; usa 00:00 para el inicio del día), end (HH:MM exclusivo; se permite 24:00 para el final del día) y timezone opcional.
- Omitido o "user": usa tu agents.defaults.userTimezone si está configurado; de lo contrario, recurre a la zona horaria del sistema host.
- "local": siempre usa la zona horaria del sistema host.
- Cualquier identificador IANA (ej. America/New_York): se usa directamente; si no es válido, recurre al comportamiento "user" mencionado arriba.
- start y end no deben ser iguales para una ventana activa; los valores iguales se tratan como ancho cero (siempre fuera de la ventana).
- Fuera de la ventana activa, los heartbeats se saltan hasta el siguiente tick dentro de la ventana.

Comportamiento de entrega

Los heartbeats se ejecutan en la sesión principal del agent por defecto (agent:<id>:<mainKey>), o en global cuando session.scope = "global". Configura session para sobrescribir a una sesión de channel específica (Discord/WhatsApp/etc.).
session solo afecta al contexto de ejecución; la entrega se controla mediante target y to.
Para entregar a un channel/destinatario específico, configura target + to. Con target: "last", la entrega usa el último channel externo para esa sesión.
Las entregas de heartbeat permiten objetivos directos/DM por defecto. Configura directPolicy: "block" para suprimir los envíos a objetivos directos mientras se sigue ejecutando el turno del heartbeat.
Si la cola principal está ocupada, el heartbeat se salta y se reintenta más tarde.
Si target no resuelve ninguna destinación externa, la ejecución ocurre igual pero no se envía ningún mensaje de salida.
Las respuestas exclusivas de heartbeat no mantienen la sesión activa; se restaura el último updatedAt para que la expiración por inactividad funcione normalmente.
Las background tasks independientes pueden encolar un evento del sistema y despertar al heartbeat cuando la sesión principal deba notar algo rápido. Ese despertar no hace que el heartbeat ejecute una background task.

Controles de visibilidad

Por defecto, las confirmaciones HEARTBEAT_OK se ocultan mientras se entrega el contenido de la alerta. Puedes ajustar esto por canal o por cuenta:

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

Precedencia: por cuenta → por canal → valores por defecto del canal → valores por defecto integrados.

Qué hace cada flag

showOk: envía una confirmación HEARTBEAT_OK cuando el modelo devuelve una respuesta que solo es OK.
showAlerts: envía el contenido de la alerta cuando el modelo devuelve una respuesta que no es OK.
useIndicator: emite eventos de indicador para superficies de estado de la UI.

Si los tres son falsos, OpenClaw se salta la ejecución del heartbeat por completo (sin llamada al modelo).

Ejemplos por canal vs. por cuenta

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

Patrones comunes

Objetivo	Config
Comportamiento por defecto (OKs en silencio)	(no requiere configuración)
Silencio total (sin mensajes ni indicador)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
Solo indicador (sin mensajes)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
OKs solo en un canal	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (opcional)

Si existe un archivo HEARTBEAT.md en el workspace, el prompt por defecto le dice al agente que lo lea. Piénsalo como tu “lista de verificación del heartbeat”: pequeña, estable y segura de incluir cada 30 minutos.

Si HEARTBEAT.md existe pero está prácticamente vacío (solo líneas en blanco y encabezados markdown como # Heading), OpenClaw se salta la ejecución del heartbeat para ahorrar llamadas a la API. Si el archivo no existe, el heartbeat se ejecuta igual y el modelo decide qué hacer.

Mantenlo diminuto (listas cortas o recordatorios) para evitar que el prompt se vuelva demasiado pesado.

Ejemplo de HEARTBEAT.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.

¿Puede el agente actualizar HEARTBEAT.md?

Sí, si se lo pides.

HEARTBEAT.md es un archivo normal en el workspace del agente, así que puedes decirle al agente (en un chat normal) algo como:

“Actualiza HEARTBEAT.md para añadir una revisión diaria del calendario.”
“Reescribe HEARTBEAT.md para que sea más corto y se centre en el seguimiento de la bandeja de entrada.”

Si quieres que esto pase de forma proactiva, también puedes incluir una línea explícita en tu prompt de heartbeat como: “Si la lista de verificación se queda obsoleta, actualiza HEARTBEAT.md con una mejor”.

Nota de seguridad: no pongas secretos (API keys, números de teléfono o tokens privados) en HEARTBEAT.md, ya que pasa a formar parte del contexto del prompt.

Activación manual (bajo demanda)

Puedes encolar un evento del sistema y activar un heartbeat inmediato con este comando:

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

Si tienes varios agentes con el heartbeat configurado, una activación manual ejecuta los heartbeats de cada uno de esos agentes al instante.

Usa --mode next-heartbeat si prefieres esperar al siguiente tick programado.

Entrega de razonamiento (opcional)

Por defecto, los heartbeats solo entregan el payload de la “respuesta” final.

Si quieres más transparencia, activa esta opción:

agents.defaults.heartbeat.includeReasoning: true

Cuando está activada, los heartbeats también enviarán un mensaje separado con el prefijo Reasoning: (con el mismo formato que /reasoning on). Esto te resultará útil cuando el agente gestione varias sesiones o codexes y quieras entender por qué decidió avisarte. Ten en cuenta que esta opción puede mostrar más detalles internos de los que te gustaría, así que es mejor dejarla desactivada en chats grupales.

Conciencia de costes

Los Heartbeats ejecutan turnos completos del agente. Los intervalos más cortos consumen más tokens. Para reducir costes, te recomiendo seguir estas pautas:

Usa isolatedSession: true para evitar enviar todo el historial de la conversación (esto reduce el consumo de unos ~100K tokens a solo ~2-5K por ejecución).
Usa lightContext: true para limitar los archivos de bootstrap únicamente a HEARTBEAT.md.
Configura un model más económico (por ejemplo, ollama/llama3.2:1b).
Mantén el archivo HEARTBEAT.md con un tamaño reducido.
Usa target: "none" si solo necesitas actualizaciones de estado interno.

Relacionado

Automation Overview — todos los mecanismos de automatización de un vistazo
Cron vs Heartbeat — cuándo utilizar cada uno
Background Tasks — cómo se rastrea el trabajo en segundo plano
Timezone — cómo influye la zona horaria en la programación de heartbeats
Troubleshooting — resolución de problemas de automatización

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.