Heartbeat

​

Inicio rápido (principiantes)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita al último contacto (el valor predeterminado es "none")
        directPolicy: "allow", // valor predeterminado: permitir destinos directos/DM; establece "block" para suprimirlos
        lightContext: true, // opcional: omitir los archivos de arranque del espacio de trabajo en las ejecuciones de Heartbeat
        isolatedSession: true, // opcional: sesión nueva en cada ejecución (sin historial de conversación)
        // activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

​

Valores predeterminados

• Intervalo: 30m. Al aplicar los valores predeterminados del proveedor Anthropic, aumenta a 1h cuando el modo de autenticación resuelto es OAuth/token (incluida la reutilización de Claude CLI), pero solo mientras heartbeat.every no esté definido. Establece agents.defaults.heartbeat.every o agents.entries.*.heartbeat.every por agente; usa 0m para deshabilitarlo.
• Cuerpo del prompt (configurable mediante 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.
• Tiempo de espera: los turnos de Heartbeat sin un valor definido usan agents.defaults.timeoutSeconds cuando está configurado. De lo contrario, usan la cadencia de Heartbeat con un límite de 600 segundos. Establece agents.defaults.heartbeat.timeoutSeconds o agents.entries.*.heartbeat.timeoutSeconds por agente para trabajos de Heartbeat más largos.
• El prompt de Heartbeat se envía textualmente como mensaje del usuario. El prompt del sistema incluye una sección «Heartbeats» cuando están habilitados para el agente predeterminado, y la ejecución se marca internamente.
• Cuando los Heartbeats se deshabilitan con 0m, el trabajo de cron del monitor permanece, pero se deshabilita, y sus notas temporales se conservan para cuando vuelvas a habilitar la cadencia.
• Cuando cron está deshabilitado, los Heartbeats programados no se ejecutan aunque la cadencia de Heartbeat siga habilitada.
• El horario activo (heartbeat.activeHours) se comprueba en la zona horaria configurada. Fuera de ese intervalo, los Heartbeats se omiten hasta el siguiente tick dentro del intervalo.
• Los Heartbeats se aplazan automáticamente mientras haya trabajo de cron activo o en cola, o mientras estén ocupados los subagentes vinculados a la clave de sesión de ese agente o los canales de comandos anidados. Los agentes relacionados no se pausan entre sí.

​

Para qué sirve el prompt de Heartbeat

• Tareas en segundo plano: «Considera las tareas pendientes» anima al agente a revisar los seguimientos (bandeja de entrada, calendario, recordatorios y trabajo en cola) y señalar cualquier asunto urgente.
• Comprobación con la persona: «Comprueba ocasionalmente cómo está la persona durante el día» invita a enviar de vez en cuando un breve mensaje del tipo «¿Necesitas algo?», pero evita los mensajes nocturnos mediante la zona horaria local configurada (consulta Zona horaria).

​

Contrato de respuesta

• Si nada requiere atención, responde con HEARTBEAT_OK.
• En su lugar, las ejecuciones de Heartbeat pueden llamar a heartbeat_respond con notify: false para no mostrar ninguna actualización visible, o a notify: true junto con notificationText para emitir una alerta. Cuando existe, la respuesta estructurada de la herramienta tiene prioridad sobre la alternativa de texto.
• Un resultado significativo de heartbeat_respond con notify: false permanece silencioso, pero se recuerda como contexto interno acotado para el siguiente turno del usuario en esa sesión. Las confirmaciones de no_change y las notificaciones visibles no se almacenan de esta forma.
• Durante las ejecuciones de Heartbeat, OpenClaw considera HEARTBEAT_OK una confirmación cuando aparece al principio o al final de la respuesta. El token se elimina y la respuesta se descarta si el contenido restante tiene como máximo 300 caracteres.
• Si HEARTBEAT_OK aparece en el medio de una respuesta, no recibe ningún tratamiento especial.
• Para las alertas, no incluyas HEARTBEAT_OK; devuelve únicamente el texto de la alerta.

​

Configuración

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // valor predeterminado: 30m (0m lo deshabilita)
        model: "anthropic/claude-opus-4-6",
        lightContext: false, // valor predeterminado: false; true omite los archivos de arranque del espacio de trabajo en las ejecuciones de Heartbeat
        isolatedSession: false, // valor predeterminado: false; true ejecuta cada Heartbeat en una sesión nueva (sin historial de conversación)
        target: "last", // valor predeterminado: none | opciones: last | none | <channel id> (núcleo o plugin, p. ej., "imessage")
        to: "+15551234567", // anulación opcional específica del canal
        accountId: "ops-bot", // id. opcional del canal con varias cuentas
        prompt: "Sigue el contexto de las notas temporales del monitor de Heartbeat cuando se proporcione. Las tareas recurrentes son trabajos de cron; crea o modifica sus programaciones con las herramientas de cron o la CLI de cron de openclaw, no con las notas temporales de Heartbeat. No deduzcas ni repitas tareas antiguas de chats anteriores. Si nada requiere atención, responde HEARTBEAT_OK.",
      },
    },
  },
}

​

Alcance y precedencia

• agents.defaults.heartbeat establece el comportamiento global de Heartbeat.
• agents.entries.*.heartbeat se combina por encima; si algún agente tiene un bloque heartbeat, solo esos agentes ejecutan Heartbeats.
• channels.defaults.heartbeatVisibility establece los valores predeterminados de visibilidad para todos los canales.
• channels.<channel>.heartbeatVisibility anula los valores predeterminados del canal.
• channels.<channel>.accounts.<id>.heartbeatVisibility (canales con varias cuentas) anula la configuración de cada canal.

​

Heartbeats por agente

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita al último contacto (el valor predeterminado es "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          timeoutSeconds: 45,
          prompt: "Sigue el contexto de las notas temporales del monitor de Heartbeat cuando se proporcione. Las tareas recurrentes son trabajos de cron; crea o modifica sus programaciones con las herramientas de cron o la CLI de cron de openclaw, no con las notas temporales de Heartbeat. No deduzcas ni repitas tareas antiguas de chats anteriores. Si nada requiere atención, responde HEARTBEAT_OK.",
        },
      },
    ],
  },
}

​

Ejemplo de horario activo

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita al último contacto (el valor predeterminado es "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // opcional; usa userTimezone si está definido; de lo contrario, la zona horaria del host
        },
      },
    },
  },
}

​

Configuración de 24/7

• Omite por completo activeHours (sin restricción de intervalo horario; este es el comportamiento predeterminado).
• Establece un intervalo de día completo: activeHours: { start: "00:00", end: "24:00" }.

​

Ejemplo con varias cuentas

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // opcional: dirigir a un tema/hilo específico
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Notas sobre los campos

​

Comportamiento de entrega

​

Controles de visibilidad

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

​

Función de cada indicador

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

​

Ejemplos por canal y por cuenta

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

​

Patrones habituales

​

Documento auxiliar del monitor (opcional)

openclaw cron scratch <jobId>                 # mostrar el documento auxiliar actual
openclaw cron scratch <jobId> --set "..."     # reemplazarlo con el texto exacto
openclaw cron scratch <jobId> --file notes.md # reemplazarlo desde un archivo (- para stdin)
openclaw cron scratch <jobId> --unset         # eliminarlo

# Lista de comprobación del Heartbeat

- Revisión rápida: ¿hay algo urgente en las bandejas de entrada?
- Si es de día y no hay nada más pendiente, realizar una comprobación ligera.
- Si una tarea está bloqueada, anotar _qué falta_ y preguntar a Peter la próxima vez.

​

Programación de comprobaciones recurrentes con Cron

​

¿Puede el agente actualizar su documento auxiliar?

​

Activación manual (bajo demanda)

openclaw system event --text "Comprobar si hay seguimientos urgentes" --mode now

openclaw system heartbeat last     # muestra el último evento de Heartbeat
openclaw system heartbeat enable   # habilita los Heartbeats
openclaw system heartbeat disable  # deshabilita los Heartbeats

​

Consideraciones sobre los costes

• Utilice isolatedSession: true para evitar enviar el historial completo de la conversación (de ~100K tokens a ~2-5K por ejecución).
• Utilice lightContext: true para omitir los archivos de inicialización del espacio de trabajo en las ejecuciones de Heartbeat.
• Configure un model más económico (p. ej., ollama/llama3.2:1b).
• Mantenga pequeño el espacio temporal del monitor.
• Utilice target: "none" si solo desea actualizar el estado interno.

​

Desbordamiento de contexto después de un Heartbeat

​

Contenido relacionado

• Automatización - todos los mecanismos de automatización de un vistazo
• Tareas en segundo plano - cómo se realiza el seguimiento del trabajo separado
• Zona horaria - cómo afecta la zona horaria a la programación de Heartbeat
• Solución de problemas - depuración de problemas de automatización