¿Qué es la función Heartbeat de OpenClaw (Moltbot/Clawdbot)?

OpenClaw (anteriormente Moltbot/Clawdbot) se popularizó rápidamente porque se centra en la automatización local práctica: vigilar su máquina, detectar desviaciones y actuar antes de que los problemas se acumulen. La función de latido es fundamental para esa promesa.

Un latido es una señal periódica de salud y estado. En OpenClaw, hace más que simples pings de actividad. Ejecuta un pipeline de decisión en capas:

1. Primero, verificaciones deterministas económicas (proceso, archivos, profundidad de la cola, estado de la API).
2. Evaluación de reglas contra umbrales y políticas.
3. Escalada de modelo opcional solo cuando persiste la ambigüedad.

Este patrón de "verificaciones económicas primero, modelos solo cuando sea necesario" es exactamente lo que los desarrolladores pidieron en discusiones recientes de la comunidad: mejor control de costos, comportamiento más predecible y menos llamadas innecesarias a LLM.

Si está construyendo infraestructura de agentes, esta es la idea clave: los latidos son primitivas del plano de control, no solo eventos de monitoreo.

Arquitectura de latido de OpenClaw en una vista

En tiempo de ejecución, los latidos de OpenClaw suelen implementarse como un bucle con cinco etapas:

1. El programador activa los tics del latido (por ejemplo, cada 15s/30s/60s).
2. El ejecutor de sondas ejecuta sondas deterministas.
3. El motor de políticas calcula las transiciones de estado y la gravedad.
4. La puerta de escalada decide si se necesita un LLM/planificador de herramientas.
5. El despachador de acciones emite alertas, tareas de remediación o ninguna operación.

Un sobre de evento práctico se ve así:

{
  "agent_id": "desktop-a17",
  "heartbeat_id": "hb_01JX...",
  "ts": "2026-02-11T10:18:05Z",
  "probes": {
    "cpu_load": 0.72,
    "disk_free_gb": 21.4,
    "mail_queue_depth": 0,
    "service_api": {
      "status": 200,
      "latency_ms": 83
    }
  },
  "policy": {
    "state": "degraded",
    "reasons": [
      "disk_free_below_warn"
    ]
  },
  "escalation": {
    "llm_required": false,
    "confidence": 0.93
  }
}

El comportamiento clave del sistema:

• Los resultados de las sondas deterministas son la verdad primaria.
• Las salidas de las políticas son reproducibles y comprobables.
• El uso de LLM es escaso, auditable y limitado por puertas estrictas.

Lo que significa "verificaciones económicas primero" en la implementación

En OpenClaw, las verificaciones económicas deben ser:

• De baja latencia (milisegundos a unos pocos cientos de ms)
• De bajo costo (sin gasto de tokens del modelo)
• Deterministas (misma entrada => misma salida)
• Sin efectos secundarios por defecto

Categorías típicas de sondas:

• Tiempo de ejecución local: proceso activo, presión de memoria, recuento de hilos
• Salud de E/S: espacio libre en disco, presión de inodos, cambios de permisos
• Salud de la integración: código de estado de la API de destino, tiempo de espera, latencia p95
• Salud de la tarea: retraso de la cola, indicadores de tormenta de reintentos
• Precondiciones de la política: credenciales válidas, ventanas de caducidad del certificado

Contrato de sonda

Use un esquema de sonda estricto para que la lógica posterior sea estable:

yaml ProbeResult: name: string ok: boolean observed_at: datetime value: number|string|object|null severity_hint: info|warn|critical error: string|null ttl_ms: integer

El valor de ttl_ms es importante. Si los datos son lo suficientemente recientes, omita las verificaciones duplicadas durante las ventanas de ráfaga.

Cuándo OpenClaw debe escalar al razonamiento del modelo

La escalada del modelo solo debe ocurrir cuando la lógica determinista no puede decidir con seguridad.

Buenos disparadores de escalada:

• Señales de sonda contradictorias (API 200 pero KPI de negocio colapsando)
• Clusters de errores novedosos sin una firma conocida coincidente
• Planificación de remediación de varios pasos bajo restricciones
• Generación de resúmenes legibles por humanos para incidentes

Malos disparadores de escalada:

• Cada evento de advertencia
• Violaciones de umbrales estáticos con runbooks conocidos
• Fluctuación de alta frecuencia donde la eliminación de rebotes resolvería el ruido

Diseño de máquina de estados: evite el parpadeo de alertas

La mayor parte del problema de los latidos proviene de transiciones inestables. Use una máquina de estados con histéresis:

• sano
• degradado
• crítico
• recuperándose

Las reglas de transición deben incluir:

• Umbrales de entrada (ej., disco < 15% => degradado)
• Umbrales de salida (ej., disco > 20% durante 3 intervalos => sano)
• Ventanas de eliminación de rebotes (N muestras consecutivas)
• Enfriamiento de acción (evitar remediaciones repetidas)

Ejemplo:

yaml transitions: healthy->degraded: condition: disk_free_pct < 15 consecutive: 2 degraded->critical: condition: disk_free_pct < 8 consecutive: 1 degraded->healthy: condition: disk_free_pct > 20 consecutive: 3 critical->recovering: condition: remediation_applied == true recovering->healthy: condition: disk_free_pct > 20 consecutive: 2

Esto reduce drásticamente la oscilación ruidosa.

Diseño de API para la ingesta y el control de latidos

Si expone API de latidos, manténgalas explícitas e idempotentes siempre que sea posible.

Puntos finales sugeridos:

• POST /v1/heartbeats — ingesta de eventos de latido
• GET /v1/agents/{id}/status — último estado calculado
• POST /v1/heartbeats/{id}/ack — reconocimiento del operador
• POST /v1/policies/simulate — simulación de política contra carga útil de ejemplo

Límites de seguridad para los latidos del agente

El interés de la comunidad en el sandboxing y la ejecución segura de agentes está creciendo por una buena razón. Los latidos a menudo desencadenan acciones, por lo que los límites de seguridad no son negociables.

Controles mínimos:

• Cargas útiles de latidos firmadas (HMAC o identidad mTLS)
• Tokens con ámbito por agente (privilegio mínimo)
• Listas blancas de políticas/acciones (sin invocación arbitraria de herramientas)
• Ejecución en sandbox para remediaciones
• Ruta de auditoría para cada transición de estado y acción

Si un modelo está involucrado:

• Trate la salida de LLM como texto de planificación no confiable
• Valide las llamadas a herramientas contra el esquema y la política
• Requiera verificaciones de guardia deterministas antes de la ejecución

En resumen: la detección de latidos puede ser flexible; las acciones de latidos deben ser restringidas.

Estrategia de observabilidad y depuración

Para depurar sistemas de latidos, instrumente primero estas métricas:

• tasa de ingesta de latidos
• proporción de latidos tardíos/perdidos
• latencia de la sonda por tipo
• latencia de evaluación de políticas
• tasa de escalada (%)
• gasto de tokens del modelo por agente/día
• etiquetas de incidentes de falsos positivos y falsos negativos

Prueba de API de latidos estilo OpenClaw con Apidog

Los sistemas de latidos fallan en los límites: cargas útiles mal formadas, eventos de repetición y condiciones de carrera. Apidog le ayuda a probar esos límites en un solo espacio de trabajo.

Un flujo práctico:

1. Defina puntos finales de latido usando OpenAPI en el diseñador visual de Apidog.
2. Construya escenarios de prueba para eventos de latido normales, retrasados, duplicados y corruptos.
3. Agregue aserciones visuales sobre las transiciones de estado y las salidas de acción.
4. Simule canales descendentes (Slack/webhook/servicio de remediación) con respuestas dinámicas.
5. Ejecute suites en CI/CD como una puerta de regresión.

Ejemplos de casos de prueba

• ingest_valid_heartbeat_returns_200
• duplicate_idempotency_key_no_duplicate_action
• critical_state_triggers_single_alert_with_cooldown
• invalid_signature_returns_401
• novelty_trigger_causes_model_escalation_when_enabled

Dado que Apidog combina diseño, prueba, simulación y documentación, su contrato y comportamiento de API se mantienen alineados a medida que evoluciona la lógica del latido.

Si su equipo actualmente divide esto en múltiples herramientas, consolidarlo en Apidog reduce la deriva y acelera la depuración.

Casos extremos que los ingenieros suelen pasar por alto

Desfase horario

• Las marcas de tiempo del agente pueden desviarse.
• Acepte una desviación limitada y almacene el tiempo recibido por el servidor por separado.

Particiones de red

• Los latidos pueden llegar en ráfagas después de la reconexión.
• Use números de secuencia y ventanas de reordenamiento.

Tormentas de contrapresión

• Si el motor de políticas se ralentiza, las colas pueden amplificar el retraso.
• Aplique control de admisión y degrade con gracia.

Fallo silencioso de la sonda

• "Sin datos" no es "sano".
• Codifique el estado desconocido explícitamente.

Bucles de remediación descontrolados

• Una acción desencadena una condición que desencadena la misma acción repetidamente.
• Agregue enfriamiento por acción y presupuestos máximos de reintentos.

Deriva del modelo en los resultados de la escalada

• Conserve los accesorios de evaluación para las decisiones asistidas por modelos.
• Revalide en caso de cambios de modelo/versión.

Nota de migración: Moltbot/Clawdbot a la denominación OpenClaw

El historial de cambios de nombre causó confusión en los nombres de paquetes, la documentación y los prefijos de los puntos finales. Si mantiene integraciones:

• Mantenga alias retrocompatibles durante un período de deprecación.
• Versionar los esquemas de eventos explícitamente (event_version).
• Publique un mapa de migración (nombres de temas antiguos -> nombres de temas nuevos).
• Agregue pruebas de contrato tanto para cargas útiles heredadas como actuales.

Esto reduce la ruptura del ecosistema mientras la comunidad converge en la denominación OpenClaw.

Línea base de producción recomendada

Si desea un valor predeterminado sensato para la implementación de latidos:

• Intervalo: 30s
• Tiempo de espera de la sonda: 500ms cada una, presupuesto total de 2s
• Eliminación de rebotes: 2 fallos consecutivos para advertencia
• Enfriamiento: 5 minutos por tipo de acción
• Límite de escalada: un máximo del 5% de los latidos invocan al modelo
• Retención: 30 días en caliente, 180 días en frío para auditorías

Luego, ajústelo por carga de trabajo. Los agentes de escritorio de desarrollador y los agentes de servidor suelen necesitar políticas diferentes.

Conclusiones finales

La función de latido de OpenClaw es valiosa porque trata la salud del agente como un bucle de control disciplinado, no como un flujo de trabajo centrado en el chat. El patrón ganador es claro:

• primero, sondas deterministas,
• segundo, máquina de estados de política explícita,
• escalada del modelo solo para la incertidumbre.

Ese diseño le brinda menor costo, mayor predictibilidad y automatización más segura.

Cuando implemente API de latidos, invierta mucho en contratos, idempotencia, simulación de políticas y automatización de pruebas. Apidog es una excelente opción aquí porque puede diseñar especificaciones OpenAPI, simular dependencias, ejecutar pruebas de regresión y publicar documentos en un solo lugar.

Si está construyendo o integrando latidos estilo OpenClaw ahora, comience con reglas deterministas estrictas y agregue inteligencia de modelo gradualmente. La confiabilidad proviene primero de las restricciones, luego de la inteligencia.