Cron vs Heartbeat: cuándo usar cada uno

Tanto los heartbeats como las tareas cron permiten ejecutar tareas de forma programada. Esta guía te ayuda a elegir el mecanismo adecuado para tu caso de uso.

Guía rápida de decisión

Heartbeat: conciencia periódica

Los heartbeats se ejecutan en la sesión principal a un intervalo regular (por defecto: 30 min). Están diseñados para que el agente revise cosas y destaque lo importante.

Cuándo usar heartbeat

• Múltiples verificaciones periódicas: en lugar de 5 tareas cron separadas revisando bandeja, calendario, clima, notificaciones y estado del proyecto, un solo heartbeat puede agrupar todo.
• Decisiones con contexto: el agente tiene el contexto completo de la sesión principal, así que puede tomar decisiones inteligentes sobre qué es urgente y qué puede esperar.
• Continuidad conversacional: las ejecuciones del heartbeat comparten la misma sesión, así que el agente recuerda conversaciones recientes y puede dar seguimiento de forma natural.
• Monitoreo ligero: un heartbeat reemplaza muchas tareas de sondeo pequeñas.

Ventajas del heartbeat

• Agrupa múltiples verificaciones: un solo turno del agente puede revisar bandeja, calendario y notificaciones juntos.
• Reduce llamadas a la API: un solo heartbeat es más económico que 5 tareas cron aisladas.
• Con contexto: el agente sabe en qué has estado trabajando y puede priorizar según eso.
• Supresión inteligente: si no hay nada que atender, el agente responde HEARTBEAT_OK y no se entrega ningún mensaje.
• Temporización natural: se desfasa ligeramente según la carga de la cola, lo cual está bien para la mayoría del monitoreo.

Ejemplo de heartbeat: lista de verificación en HEARTBEAT.md

# Lista de verificación del heartbeat

- Revisar correo en busca de mensajes urgentes
- Revisar calendario por eventos en las próximas 2 horas
- Si una tarea en segundo plano terminó, resumir resultados
- Si lleva 8+ horas inactivo, enviar un breve check-in

El agente lee esto en cada heartbeat y maneja todos los puntos en un solo turno.

Configurar heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // intervalo
        target: "last", // destino explícito de entrega de alertas (por defecto es "none")
        activeHours: { start: "08:00", end: "22:00" }, // opcional
      },
    },
  },
}

Consulta Heartbeat para la configuración completa.

Cron: programación precisa

Las tareas cron se ejecutan en horarios precisos y pueden ejecutarse en sesiones aisladas sin afectar el contexto principal. Los horarios recurrentes al inicio de la hora se distribuyen automáticamente con un desfase determinístico por tarea en una ventana de 0-5 minutos.

Cuándo usar cron

• Se requiere hora exacta: “envía esto a las 9:00 AM cada lunes” (no “por ahí de las 9”).
• Tareas independientes: tareas que no necesitan contexto conversacional.
• Modelo/razonamiento diferente: análisis pesado que justifica un modelo más potente.
• Recordatorios únicos: “recuérdame en 20 minutos” con --at.
• Tareas ruidosas/frecuentes: tareas que llenarían el historial de la sesión principal.
• Disparadores externos: tareas que deben ejecutarse independientemente de si el agente está activo.

Ventajas del cron

• Temporización precisa: expresiones cron de 5 o 6 campos (segundos) con soporte de zona horaria.
• Distribución de carga integrada: los horarios recurrentes al inicio de la hora se desfasan hasta 5 minutos por defecto.
• Control por tarea: sobreescribe el desfase con --stagger <duración> o fuerza hora exacta con --exact.
• Aislamiento de sesión: se ejecuta en cron:<jobId> sin contaminar el historial principal.
• Sobreescritura de modelo: usa un modelo más económico o más potente por tarea.
• Control de entrega: las tareas aisladas usan announce (resumen) por defecto; elige none si lo necesitas.
• Entrega inmediata: el modo announce publica directamente sin esperar al heartbeat.
• No necesita contexto del agente: se ejecuta incluso si la sesión principal está inactiva o compactada.
• Soporte de ejecución única: --at para marcas de tiempo futuras precisas.

Ejemplo de cron: resumen matutino diario

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

Esto se ejecuta exactamente a las 7:00 AM hora de Nueva York, usa Opus para calidad, y envía un resumen directamente a WhatsApp.

Ejemplo de cron: recordatorio único

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

Consulta Tareas cron para la referencia completa del CLI.

Diagrama de decisión

¿La tarea necesita ejecutarse en una hora EXACTA?
  SÍ -> Usa cron
  NO -> Continúa...

¿La tarea necesita aislamiento de la sesión principal?
  SÍ -> Usa cron (aislado)
  NO -> Continúa...

¿Se puede agrupar esta tarea con otras verificaciones periódicas?
  SÍ -> Usa heartbeat (agrégala a HEARTBEAT.md)
  NO -> Usa cron

¿Es un recordatorio de una sola vez?
  SÍ -> Usa cron con --at
  NO -> Continúa...

¿Necesita un modelo o nivel de razonamiento diferente?
  SÍ -> Usa cron (aislado) con --model/--thinking
  NO -> Usa heartbeat

Combinar ambos

La configuración más eficiente usa ambos:

1. Heartbeat gestiona el monitoreo de rutina (bandeja, calendario, notificaciones) en un solo turno agrupado cada 30 minutos.
2. Cron gestiona horarios precisos (reportes diarios, revisiones semanales) y recordatorios únicos.

Ejemplo: configuración de automatización eficiente

HEARTBEAT.md (se revisa cada 30 min):

# Lista de verificación del heartbeat

- Escanear bandeja en busca de correos urgentes
- Revisar calendario por eventos en las próximas 2h
- Revisar tareas pendientes
- Check-in ligero si lleva 8+ horas en silencio

Tareas cron (hora precisa):

# Resumen matutino diario a las 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Revisión semanal del proyecto los lunes a las 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# Recordatorio único
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster: flujos de trabajo determinísticos con aprobaciones

Lobster es el runtime de flujos de trabajo para pipelines de herramientas multi-paso que necesitan ejecución determinística y aprobaciones explícitas. Úsalo cuando la tarea es más que un solo turno del agente y quieres un flujo reanudable con puntos de control humanos.

Cuándo encaja Lobster

• Automatización multi-paso: necesitas un pipeline fijo de llamadas a herramientas, no un prompt puntual.
• Puertas de aprobación: los efectos secundarios deben pausarse hasta que apruebes, luego continuar.
• Ejecuciones reanudables: continúa un flujo pausado sin re-ejecutar pasos anteriores.

Cómo se complementa con heartbeat y cron

• Heartbeat/cron deciden cuándo ocurre una ejecución.
• Lobster define qué pasos ocurren una vez que la ejecución comienza.

Para flujos programados, usa cron o heartbeat para disparar un turno del agente que llame a Lobster. Para flujos ad-hoc, llama a Lobster directamente.

Notas operativas (del código)

• Lobster se ejecuta como un subproceso local (CLI lobster) en modo herramienta y devuelve un sobre JSON.
• Si la herramienta devuelve needs_approval, reanudas con un resumeToken y la bandera approve.
• La herramienta es un plugin opcional; habilítalo de forma aditiva vía tools.alsoAllow: ["lobster"] (recomendado).
• Lobster espera que el CLI lobster esté disponible en el PATH.

Consulta Lobster para uso completo y ejemplos.

Sesión principal vs sesión aislada

Tanto heartbeat como cron pueden interactuar con la sesión principal, pero de forma diferente:

Cuándo usar cron en sesión principal

Usa --session main con --system-event cuando quieras:

• Que el recordatorio/evento aparezca en el contexto de la sesión principal
• Que el agente lo maneje durante el próximo heartbeat con contexto completo
• Sin ejecución aislada separada

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

Cuándo usar cron aislado

Usa --session isolated cuando quieras:

• Empezar de cero sin contexto previo
• Configuración de modelo o razonamiento diferente
• Enviar resúmenes directamente a un canal
• Historial que no sature la sesión principal

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

Consideraciones de costo

Consejos:

• Mantén HEARTBEAT.md pequeño para minimizar el overhead de tokens.
• Agrupa verificaciones similares en el heartbeat en lugar de múltiples tareas cron.
• Usa target: "none" en el heartbeat si solo quieres procesamiento interno.
• Usa cron aislado con un modelo más económico para tareas de rutina.

Relacionado

• Heartbeat - configuración completa del heartbeat
• Tareas cron - referencia completa del CLI y API de cron
• System - eventos del sistema + controles de heartbeat