O que é o Heartbeat do OpenClaw (Moltbot/Clawdbot)?

OpenClaw (anteriormente Moltbot/Clawdbot) rapidamente se tornou popular porque se concentra na automação local prática: observe sua máquina, detecte desvios e aja antes que os problemas se acumulem. O recurso de batimento cardíaco (heartbeat) é fundamental para essa promessa.

Um heartbeat (batimento cardíaco) é um sinal periódico de saúde e estado. No OpenClaw, ele faz mais do que pings de tempo de atividade. Ele executa um pipeline de decisão em camadas:

1. Verificações determinísticas baratas primeiro (processo, arquivos, profundidade da fila, status da API)
2. Avaliação de regras contra limites e políticas
3. Escalada opcional do modelo apenas quando a ambiguidade persistir

Este padrão de "verificações baratas primeiro, modelos apenas quando necessário" é exatamente o que os desenvolvedores pediram nas recentes discussões da comunidade: melhor controle de custos, comportamento mais previsível e menos chamadas desnecessárias de LLM.

Se você está construindo uma infraestrutura de agente, esta é a ideia chave: heartbeats são primitivas do plano de controle, não apenas eventos de monitoramento.

Arquitetura de heartbeat do OpenClaw em uma visão

Em tempo de execução, os heartbeats do OpenClaw são tipicamente implementados como um loop com cinco estágios:

1. O Scheduler (agendador) dispara os ticks do heartbeat (por exemplo, a cada 15s/30s/60s).
2. O Probe runner (executor de sondas) executa sondas determinísticas.
3. O Policy engine (motor de políticas) calcula as transições de estado e a gravidade.
4. O Escalation gate (portão de escalada) decide se um LLM/planejador de ferramentas é necessário.
5. O Action dispatcher (despachante de ações) emite alertas, tarefas de remediação ou nenhuma operação (no-op).

Um envelope de evento prático se parece com isto:

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

O comportamento chave do sistema:

• Os resultados das sondas determinísticas são a verdade primária.
• As saídas da política são reproduzíveis e testáveis.
• O uso de LLM é esparso, auditável e limitado por portões estritos.

O que "verificações baratas primeiro" significa na implementação

No OpenClaw, as verificações baratas devem ser:

• De baixa latência (milissegundos a poucas centenas de ms)
• De baixo custo (nenhum gasto de token de modelo)
• Determinísticas (mesma entrada => mesma saída)
• Sem efeitos colaterais por padrão

Categorias típicas de sondas:

• Tempo de execução local: processo ativo, pressão de memória, contagem de threads
• Saúde de E/S: disco livre, pressão de inodes, mudanças de permissões
• Saúde de integração: código de status da API de destino, tempo limite, latência p95
• Saúde da tarefa: atraso na fila, indicadores de tempestade de retentativas
• Pré-condições da política: credenciais válidas, janelas de expiração de certificados

Contrato da Sonda

Use um esquema de sonda rigoroso para que a lógica downstream seja estável:

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

ttl_ms importa. Se os dados estiverem suficientemente recentes, ignore verificações duplicadas durante janelas de pico.

Quando o OpenClaw deve escalar para o raciocínio do modelo

A escalada do modelo deve ocorrer apenas quando a lógica determinística não puder decidir com segurança.

Bons gatilhos de escalada:

• Sinais de sonda conflitantes (API 200, mas KPI de negócios em colapso)
• Agrupamentos de erros novos sem assinatura conhecida correspondente
• Planejamento de remediação em várias etapas sob restrições
• Geração de resumo legível por humanos para incidentes

Maus gatilhos de escalada:

• Todo evento de aviso
• Violações de limites estáticos com runbooks conhecidos
• Flutuações de alta frequência onde a eliminação de ruído (debounce) resolveria o problema

Design de máquina de estados: evite alertas intermitentes

A maioria dos problemas de heartbeat decorre de transições instáveis. Use uma máquina de estados com histerese:

• healthy (saudável)
• degraded (degradado)
• critical (crítico)
• recovering (recuperando)

As regras de transição devem incluir:

• Limites de entrada (por exemplo, disco < 15% => degradado)
• Limites de saída (por exemplo, disco > 20% por 3 intervalos => saudável)
• Janelas de eliminação de ruído (Debounce) (N amostras consecutivas)
• Resfriamento de ação (Cooldown) (evitar remediação repetida)

Exemplo:

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

Isso reduz drasticamente a oscilação ruidosa.

Design de API para ingestão e controle de heartbeat

Se você expõe APIs de heartbeat, mantenha-as explícitas e idempotentes sempre que possível.

Endpoints sugeridos:

• POST /v1/heartbeats — ingerir evento de heartbeat
• GET /v1/agents/{id}/status — último estado calculado
• POST /v1/heartbeats/{id}/ack — reconhecimento do operador
• POST /v1/policies/simulate — simular política contra payload de amostra

Limites de segurança para heartbeats de agentes

O interesse da comunidade em torno do sandboxing e da execução segura de agentes está crescendo por um bom motivo. Heartbeats frequentemente disparam ações, então os limites de segurança são inegociáveis.

Controles mínimos:

• Payloads de heartbeat assinados (HMAC ou identidade mTLS)
• Tokens com escopo por agente (privilégio mínimo)
• Listas de permissão de políticas/ações (nenhuma invocação arbitrária de ferramenta)
• Execução em sandbox para remediações
• Trilha de auditoria para cada transição de estado e ação

Se um modelo estiver envolvido:

• Trate a saída do LLM como texto de planejamento não confiável
• Valide as chamadas de ferramentas contra o esquema e a política
• Exija verificações de guarda determinísticas antes da execução

Em resumo: a detecção de heartbeat pode ser flexível; as ações de heartbeat devem ser restritas.

Estratégia de observabilidade e depuração

Para depurar sistemas de heartbeat, instrumente estas métricas primeiro:

• taxa de ingestão de heartbeat
• proporção de heartbeats atrasados/perdidos
• latência da sonda por tipo
• latência de avaliação da política
• taxa de escalada (%)
• gasto de tokens do modelo por agente/dia
• rótulos de incidentes de falso positivo e falso negativo

Testando APIs de heartbeat estilo OpenClaw com Apidog

Os sistemas de heartbeat falham nos limites: payloads malformados, eventos de replay e condições de corrida. O Apidog ajuda você a testar esses limites em um único workspace.

Um fluxo prático:

1. Defina endpoints de heartbeat usando OpenAPI no designer visual do Apidog.
2. Crie cenários de teste para eventos de heartbeat normais, atrasados, duplicados e corrompidos.
3. Adicione asserções visuais nas transições de estado e saídas de ação.
4. Simule canais downstream (Slack/webhook/serviço de remediação) com respostas dinâmicas.
5. Execute suítes em CI/CD como um portão de regressão.

Exemplos de casos de teste

• 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

Como o Apidog combina design, teste, mocking e documentação, seu contrato de API e comportamento permanecem alinhados à medida que a lógica de heartbeat evolui.

Se sua equipe atualmente divide isso entre várias ferramentas, consolidar no Apidog reduz a divergência e acelera a depuração.

Casos extremos que os engenheiros geralmente perdem

Desvio de relógio (Clock skew)

• Os timestamps do agente podem desviar.
• Aceite desvio limitado e armazene o tempo recebido pelo servidor separadamente.

Partições de rede

• Heartbeats podem chegar em rajadas após a reconexão.
• Use números de sequência e janelas de reordenação.

Tempestades de contrapressão (Backpressure storms)

• Se o motor de políticas atrasar, as filas podem amplificar o lag.
• Aplique controle de admissão e degrade graciosamente.

Falha silenciosa da sonda

• "Sem dados" não significa "saudável".
• Codifique o estado desconhecido explicitamente.

Loops de remediação descontrolados

• A ação dispara uma condição que dispara a mesma ação repetidamente.
• Adicione resfriamento por ação e orçamentos máximos de retentativas.

Desvio do modelo nos resultados de escalada

• Mantenha os acessórios de avaliação para decisões assistidas por modelo.
• Revalide em mudanças de modelo/versão.

Nota de migração: Nomenclatura Moltbot/Clawdbot para OpenClaw

O histórico de renomeação causou confusão em nomes de pacotes, documentação e prefixos de endpoints. Se você mantém integrações:

• Mantenha aliases de compatibilidade retroativa para uma janela de depreciação.
• Esquemas de evento de versão explicitamente (event_version).
• Publique um mapa de migração (nomes de tópicos antigos -> novos nomes de tópicos).
• Adicione testes de contrato para payloads legados e atuais.

Isso reduz a quebra do ecossistema enquanto a comunidade converge para a nomenclatura OpenClaw.

Linha de base de produção recomendada

Se você deseja um padrão sensato para a implantação de heartbeat:

• Intervalo: 30s
• Tempo limite da sonda: 500ms cada, 2s de orçamento total
• Debounce: 2 falhas consecutivas para aviso
• Cooldown: 5 minutos por tipo de ação
• Limite de escalada: no máximo 5% dos heartbeats invocam o modelo
• Retenção: 30 dias ativos, 180 dias frios para auditorias

Em seguida, ajuste pela carga de trabalho. Agentes de desktop de desenvolvedor e agentes de servidor geralmente precisam de políticas diferentes.

Conclusões finais

O recurso de heartbeat do OpenClaw é valioso porque trata a saúde do agente como um loop de controle disciplinado, não um fluxo de trabalho focado em chat. O padrão vencedor é claro:

• sondas determinísticas primeiro,
• máquina de estado de política explícita em segundo,
• escalada de modelo apenas para incerteza.

Esse design oferece menor custo, maior previsibilidade e automação mais segura.

Ao implementar APIs de heartbeat, invista fortemente em contratos, idempotência, simulação de políticas e automação de testes. O Apidog é uma ótima opção aqui porque você pode projetar especificações OpenAPI, simular dependências, executar testes de regressão e publicar documentação em um só lugar.

Se você está construindo ou integrando heartbeats estilo OpenClaw agora, comece com regras determinísticas estritas e adicione inteligência de modelo gradualmente. A confiabilidade vem das restrições primeiro, da inteligência em segundo lugar.