Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
¿Heartbeat o cron? Consulta Automatización para obtener orientación sobre cuándo usar cada uno.
Inicio rápido (principiante)
Pick a cadence
Deja Heartbeat habilitado (el valor predeterminado es
30m, o 1h para autenticación OAuth/token de Anthropic, incluida la reutilización de Claude CLI) o configura tu propia cadencia.Add HEARTBEAT.md (optional)
Crea una pequeña lista de comprobación
HEARTBEAT.md o un bloque tasks: en el espacio de trabajo del agente.Decide where heartbeat messages should go
target: "none" es el valor predeterminado; establece target: "last" para enrutar al último contacto.Optional tuning
- Habilita la entrega de razonamiento de Heartbeat para mayor transparencia.
- Usa contexto de arranque ligero si las ejecuciones de Heartbeat solo necesitan
HEARTBEAT.md. - Habilita sesiones aisladas para evitar enviar todo el historial de conversación en cada Heartbeat.
- Restringe los Heartbeat a horas activas (hora local).
Valores predeterminados
- Intervalo:
30m(o1hcuando el modo de autenticación detectado es OAuth/token de Anthropic, incluida la reutilización de Claude CLI). Configuraagents.defaults.heartbeat.everyoagents.list[].heartbeat.everypor agente; usa0mpara deshabilitar. - 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 mensaje del usuario. El prompt del sistema incluye una sección “Heartbeat” solo cuando los Heartbeat están habilitados para el agente predeterminado, y la ejecución se marca internamente.
- Cuando los Heartbeat se deshabilitan con
0m, las ejecuciones normales también omitenHEARTBEAT.mddel contexto de arranque para que el modelo no vea instrucciones exclusivas de Heartbeat. - Las horas activas (
heartbeat.activeHours) se comprueban en la zona horaria configurada. Fuera de la ventana, los Heartbeat se omiten hasta el siguiente tick dentro de la ventana. - Los Heartbeat se posponen automáticamente mientras haya trabajo Cron activo o en cola. Establece
heartbeat.skipWhenBusy: truepara posponer también un agente en sus propios carriles de subagente con clave de sesión o de comandos anidados; los agentes hermanos ya no se pausan solo porque otro agente tenga trabajo de subagente en curso.
Para qué sirve el prompt de Heartbeat
El prompt predeterminado es intencionalmente amplio:- Tareas en segundo plano: “Consider outstanding tasks” impulsa al agente a revisar seguimientos (bandeja de entrada, calendario, recordatorios, trabajo en cola) y señalar cualquier cosa urgente.
- Comprobación humana: “Checkup sometimes on your human during day time” impulsa un mensaje ocasional y ligero de “¿necesitas algo?”, pero evita el spam nocturno usando tu zona horaria local configurada (consulta Zona horaria).
agents.defaults.heartbeat.prompt (o agents.list[].heartbeat.prompt) en un cuerpo personalizado (enviado literalmente).
Contrato de respuesta
- Si nada requiere atención, responde con
HEARTBEAT_OK. - Las ejecuciones de Heartbeat con capacidad de herramientas pueden llamar en su lugar a
heartbeat_respondconnotify: falsepara no mostrar ninguna actualización visible, onotify: truemásnotificationTextpara una alerta. Cuando está presente, la respuesta estructurada de la herramienta tiene prioridad sobre la alternativa de texto. - Durante las ejecuciones de Heartbeat, OpenClaw trata
HEARTBEAT_OKcomo una confirmación cuando aparece al inicio o al final de la respuesta. El token se elimina y la respuesta se descarta si el contenido restante es ≤ackMaxChars(valor predeterminado: 300). - Si
HEARTBEAT_OKaparece en el medio de una respuesta, no recibe ningún tratamiento especial. - Para alertas, no incluyas
HEARTBEAT_OK; devuelve solo el texto de la alerta.
HEARTBEAT_OK aislado al inicio/final de un mensaje se elimina y se registra; un mensaje que es solo HEARTBEAT_OK se descarta.
Configuración
Alcance y precedencia
agents.defaults.heartbeatestablece el comportamiento global de Heartbeat.agents.list[].heartbeatse fusiona encima; si algún agente tiene un bloqueheartbeat, solo esos agentes ejecutan Heartbeat.channels.defaults.heartbeatestablece los valores predeterminados de visibilidad para todos los canales.channels.<channel>.heartbeatanula los valores predeterminados del canal.channels.<channel>.accounts.<id>.heartbeat(canales multicuenta) anula la configuración por canal.
Heartbeat por agente
Si alguna entrada deagents.list[] incluye un bloque heartbeat, solo esos agentes ejecutan Heartbeat. El bloque por agente se fusiona encima de agents.defaults.heartbeat (así puedes establecer valores predeterminados compartidos una vez y anularlos por agente).
Ejemplo: dos agentes, solo el segundo agente ejecuta Heartbeat.
Ejemplo de horas activas
Restringe los Heartbeat al horario laboral en una zona horaria específica:Configuración 24/7
Si quieres que los Heartbeat se ejecuten todo el día, usa uno de estos patrones:- Omite
activeHourspor completo (sin restricción de ventana horaria; este es el comportamiento predeterminado). - Establece una ventana de día completo:
activeHours: { start: "00:00", end: "24:00" }.
Ejemplo multicuenta
UsaaccountId para dirigir a una cuenta específica en canales multicuenta como Telegram:
Notas de campos
Intervalo de Heartbeat (cadena de duración; unidad predeterminada = minutos).
Anulación opcional del modelo para ejecuciones de Heartbeat (
provider/model).Cuando está habilitado, también entrega el mensaje separado
Reasoning: cuando está disponible (misma forma que /reasoning on).Cuando es true, las ejecuciones de Heartbeat usan contexto de arranque ligero y conservan solo
HEARTBEAT.md de los archivos de arranque del espacio de trabajo.Cuando 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 costo de tokens por Heartbeat. Combínalo con lightContext: true para obtener el máximo ahorro. El enrutamiento de entrega sigue usando el contexto de la sesión principal.Cuando es true, las ejecuciones de Heartbeat se posponen en los carriles ocupados adicionales de ese agente: su propio subagente con clave de sesión o trabajo de comandos anidados. Los carriles de Cron siempre posponen los Heartbeat, incluso sin esta marca, para que los hosts de modelos locales no ejecuten prompts de Cron y Heartbeat al mismo tiempo.
Clave de sesión opcional para ejecuciones de Heartbeat.
main(predeterminado): sesión principal del agente.- Clave de sesión explícita (copia desde
openclaw sessions --jsono la CLI de sesiones). - Formatos de clave de sesión: consulta Sesiones y Grupos.
last: entregar al último canal externo usado.- canal explícito: cualquier canal configurado o id de Plugin, por ejemplo
discord,matrix,telegramowhatsapp. none(predeterminado): ejecutar el Heartbeat pero no entregar externamente.
Controla el comportamiento de entrega directa/DM.
allow: permite la entrega directa/DM de Heartbeat. block: suprime la entrega directa/DM (reason=dm-blocked).Anulación opcional del destinatario (id específico del canal, por ejemplo E.164 para WhatsApp o un id de chat de Telegram). Para temas/hilos de Telegram, usa
<chatId>:topic:<messageThreadId>.Id de cuenta opcional para canales multicuenta. Cuando
target: "last", el id de cuenta se aplica al último canal resuelto si admite cuentas; de lo contrario, se ignora. Si el id de cuenta no coincide con una cuenta configurada para el canal resuelto, la entrega se omite.Sobrescribe el cuerpo del prompt predeterminado (no se fusiona).
Caracteres máximos permitidos después de
HEARTBEAT_OK antes de la entrega.Cuando es true, suprime las cargas de advertencia de errores de herramientas durante las ejecuciones de heartbeat.
Restringe las ejecuciones de 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 tuagents.defaults.userTimezonesi 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 (por ejemplo,
America/New_York): se usa directamente; si no es válido, recurre al comportamiento"user"anterior. startyendno 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 omiten hasta el siguiente tick dentro de la ventana.
Comportamiento de entrega
Enrutamiento de sesión y destino
Enrutamiento de sesión y destino
- Los heartbeats se ejecutan en la sesión principal del agente de forma predeterminada (
agent:<id>:<mainKey>), oglobalcuandosession.scope = "global". Configurasessionpara sobrescribirlo a una sesión de canal específica (Discord/WhatsApp/etc.). sessionsolo afecta al contexto de ejecución; la entrega la controlantargetyto.- Para entregar a un canal/destinatario específico, configura
target+to. Contarget: "last", la entrega usa el último canal externo de esa sesión. - Las entregas de heartbeat permiten destinos directos/DM de forma predeterminada. Configura
directPolicy: "block"para suprimir envíos a destinos directos mientras se sigue ejecutando el turno de heartbeat. - Si la cola principal, el carril de sesión de destino, el carril de cron o un trabajo de cron activo están ocupados, el heartbeat se omite y se reintenta más tarde.
- Si
skipWhenBusy: true, el subagente con clave de sesión de este agente y los carriles anidados también aplazan las ejecuciones de heartbeat. Los carriles ocupados de otros agentes no aplazan este agente. - Si
targetno se resuelve a ningún destino externo, la ejecución sigue ocurriendo, pero no se envía ningún mensaje saliente.
Visibilidad y comportamiento de omisión
Visibilidad y comportamiento de omisión
- Si
showOk,showAlertsyuseIndicatorestán todos deshabilitados, la ejecución se omite desde el principio comoreason=alerts-disabled. - Si solo la entrega de alertas está deshabilitada, OpenClaw todavía puede ejecutar el heartbeat, actualizar marcas de tiempo de tareas vencidas, restaurar la marca de tiempo de inactividad de la sesión y suprimir la carga de alerta externa.
- Si el destino de heartbeat resuelto admite escritura, OpenClaw muestra escritura mientras la ejecución de heartbeat está activa. Esto usa el mismo destino al que el heartbeat enviaría la salida de chat, y se deshabilita con
typingMode: "never".
Ciclo de vida de sesión y auditoría
Ciclo de vida de sesión y auditoría
- Las respuestas solo de heartbeat no mantienen viva la sesión. Los metadatos de heartbeat pueden actualizar la fila de sesión, pero la expiración por inactividad usa
lastInteractionAtdel último mensaje real de usuario/canal, y la expiración diaria usasessionStartedAt. - La interfaz de control y el historial de WebChat ocultan los prompts de heartbeat y las confirmaciones solo OK. La transcripción de sesión subyacente todavía puede contener esos turnos para auditoría/reproducción.
- Las tareas en segundo plano desacopladas pueden poner en cola un evento del sistema y despertar el heartbeat cuando la sesión principal deba notar algo rápidamente. Ese despertar no convierte la ejecución de heartbeat en una tarea en segundo plano.
Controles de visibilidad
De forma predeterminada, las confirmacionesHEARTBEAT_OK se suprimen mientras se entrega el contenido de alerta. Puedes ajustar esto por canal o por cuenta:
Qué hace cada indicador
showOk: envía una confirmaciónHEARTBEAT_OKcuando el modelo devuelve una respuesta solo OK.showAlerts: envía el contenido de alerta cuando el modelo devuelve una respuesta que no es OK.useIndicator: emite eventos indicadores para superficies de estado de la interfaz.
Ejemplos por canal frente a por cuenta
Patrones comunes
| Objetivo | Configuración |
|---|---|
| Comportamiento predeterminado (OK silenciosos, alertas activadas) | (no se necesita configuración) |
| Totalmente 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 } |
| OK solo en un canal | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md (opcional)
Si existe un archivoHEARTBEAT.md en el espacio de trabajo, el prompt predeterminado le indica al agente que lo lea. Piensa en él como tu “lista de comprobación de heartbeat”: pequeña, estable y segura de incluir cada 30 minutos.
En ejecuciones normales, HEARTBEAT.md solo se inyecta cuando la guía de heartbeat está habilitada para el agente predeterminado. Deshabilitar la cadencia de heartbeat con 0m o configurar includeSystemPromptSection: false lo omite del contexto de arranque normal.
Si HEARTBEAT.md existe pero está efectivamente vacío (solo líneas en blanco y encabezados markdown como # Heading), OpenClaw omite la ejecución de heartbeat para ahorrar llamadas API. Esa omisión se reporta como reason=empty-heartbeat-file. Si falta el archivo, el heartbeat todavía se ejecuta y el modelo decide qué hacer.
Mantenlo muy pequeño (lista de comprobación o recordatorios breves) para evitar inflar el prompt.
Ejemplo de HEARTBEAT.md:
Bloques tasks:
HEARTBEAT.md también admite un pequeño bloque estructurado tasks: para comprobaciones basadas en intervalos dentro del propio heartbeat.
Ejemplo:
Comportamiento
Comportamiento
- OpenClaw analiza el bloque
tasks:y comprueba cada tarea contra su propiointerval. - Solo las tareas vencidas se incluyen en el prompt de heartbeat para ese tick.
- Si no hay tareas vencidas, el heartbeat se omite por completo (
reason=no-tasks-due) para evitar una llamada al modelo desperdiciada. - El contenido que no es de tareas en
HEARTBEAT.mdse conserva y se añade como contexto adicional después de la lista de tareas vencidas. - Las marcas de tiempo de última ejecución de tareas se almacenan en el estado de sesión (
heartbeatTaskState), por lo que los intervalos sobreviven a reinicios normales. - Las marcas de tiempo de tareas solo avanzan después de que una ejecución de heartbeat completa su ruta normal de respuesta. Las ejecuciones omitidas
empty-heartbeat-file/no-tasks-dueno marcan tareas como completadas.
¿Puede el agente actualizar HEARTBEAT.md?
Sí, si se lo pides.HEARTBEAT.md es simplemente un archivo normal en el espacio de trabajo del agente, así que puedes decirle al agente (en un chat normal) algo como:
- “Actualiza
HEARTBEAT.mdpara agregar una comprobación diaria del calendario.” - “Reescribe
HEARTBEAT.mdpara que sea más corto y esté enfocado en seguimientos de la bandeja de entrada.”
Despertar manual (bajo demanda)
Puedes poner en cola un evento del sistema y activar un heartbeat inmediato con:heartbeat configurado, un despertar manual ejecuta cada uno de esos heartbeats de agente inmediatamente.
Usa --mode next-heartbeat para esperar al siguiente tick programado.
Entrega de razonamiento (opcional)
De forma predeterminada, los heartbeats entregan solo la carga final de “respuesta”. Si quieres transparencia, habilita:agents.defaults.heartbeat.includeReasoning: true
Reasoning: (la misma forma que /reasoning on). Esto puede ser útil cuando el agente gestiona varias sesiones/codexes y quieres ver por qué decidió avisarte, pero también puede filtrar más detalles internos de los que deseas. Es preferible mantenerlo desactivado en chats grupales.
Conciencia de costos
Los heartbeats ejecutan turnos completos de agente. Los intervalos más cortos consumen más tokens. Para reducir el costo:- Usa
isolatedSession: truepara evitar enviar todo el historial de conversación (de ~100K tokens a ~2-5K por ejecución). - Usa
lightContext: truepara limitar los archivos de arranque solo aHEARTBEAT.md. - Configura un
modelmás económico (por ejemplo,ollama/llama3.2:1b). - Mantén
HEARTBEAT.mdpequeño. - Usa
target: "none"si solo quieres actualizaciones de estado internas.
Desbordamiento de contexto después de heartbeat
Si un heartbeat dejó previamente una sesión existente en un modelo local más pequeño, por ejemplo un modelo Ollama con una ventana de 32k, y el siguiente turno de sesión principal informa desbordamiento de contexto, restablece el modelo de ejecución de la sesión al modelo primario configurado. El mensaje de restablecimiento de OpenClaw lo indica cuando el último modelo de ejecución coincide con elheartbeat.model configurado.
Los heartbeats actuales conservan el modelo de ejecución existente de la sesión compartida después de que la ejecución se completa. Todavía puedes usar isolatedSession: true para ejecutar heartbeats en una sesión nueva, combinarlo con lightContext: true para el prompt más pequeño, o elegir un modelo de heartbeat con una ventana de contexto lo suficientemente grande para la sesión compartida.
Relacionado
- Automatización: todos los mecanismos de automatización de un vistazo
- Tareas en segundo plano: cómo se rastrea el trabajo desacoplado
- Zona horaria: cómo la zona horaria afecta la programación de heartbeat
- Solución de problemas: depuración de problemas de automatización