Healthcheck do OpenClaw no Docker: o que monitorar

Para monitorar o OpenClaw no Docker, use /healthz para verificar se o servidor HTTP está vivo, /startupz para acompanhar a inicialização e /readyz para saber se o Gateway está pronto, incluindo as verificações dos canais configurados. Um container em execução não prova que o WhatsApp recebe mensagens. Da mesma forma, uma falha de canal não significa necessariamente que o processo inteiro precisa reiniciar.

Este guia ajuda a escolher o sinal correto para alertas e diagnóstico. Os endpoints e comandos foram conferidos na documentação oficial de saúde do Gateway e na documentação oficial de Docker em 13 de outubro de 2026. Versões anteriores podem ter outro comportamento: consulte a documentação correspondente à imagem instalada antes de alterar seu monitoramento.

Três verificações, três perguntas diferentes

A documentação também oferece os pares /health, /startup e /ready. Os caminhos de probe permanecem na raiz do servidor mesmo quando a interface usa um gateway.controlUi.basePath personalizado.

Não transforme uma indisponibilidade de canal em um ciclo automático de reinicialização do Gateway. Um WhatsApp desconectado pode exigir autenticação ou intervenção do operador; reiniciar todos os serviços repetidamente não corrige uma sessão revogada e pode interromper os canais que ainda funcionam.

1. Identifique a instalação e a porta publicadas

No host que executa o Docker, abra o diretório do projeto Compose e confira os serviços:

docker compose ps -a

Os exemplos seguintes usam o serviço oficial openclaw-gateway. Se você usa arquivos -f, outro nome de projeto com -p ou um override, mantenha os mesmos argumentos em todos os comandos. Não crie um projeto Compose diferente só para investigar.

O exemplo da documentação usa a porta 18789. Confira o mapeamento real da sua instalação: outra porta no host ou um Gateway remoto exige outra URL. 127.0.0.1 aponta para a máquina onde o comando está sendo executado, não automaticamente para o seu servidor.

Se ainda está montando o ambiente, comece pelo guia de instalação. Para dados que somem depois de recriar containers, o problema é outro: confira o guia de volumes e persistência do OpenClaw.

2. Consulte os endpoints sem chamar o modelo

Com a porta padrão publicada no host local:

curl --max-time 10 -sS -i http://127.0.0.1:18789/healthz
curl --max-time 10 -sS -i http://127.0.0.1:18789/startupz
curl --max-time 10 -sS -i http://127.0.0.1:18789/readyz

A opção -i mostra o código HTTP junto com o corpo. O limite de dez segundos é apenas um exemplo para o cliente de diagnóstico, não uma garantia de tempo de inicialização do OpenClaw.

Interprete os resultados em conjunto:

• healthz com 200 e startupz com 503: o servidor está vivo, mas a inicialização pode estar em andamento ou o Gateway em drenagem. Leia o corpo e acompanhe os logs antes de declarar uma falha permanente.
• startupz com 200 e readyz com 503: a preparação terminou, mas há uma condição impedindo a disponibilidade. Um canal com falha ou um problema de estado pode ser a causa.
• Os três com 200: as verificações passaram naquele momento. Ainda falta testar a tarefa real, as permissões e o acesso ao provedor do modelo.
• Conexão recusada ou timeout: verifique endereço, porta, publicação Docker e rede. Isso não é a mesma coisa que receber um HTTP 503 do Gateway.
• 404: confirme se chegou ao Gateway correto e se a versão instalada oferece o endpoint. Não trate ausência de rota como diagnóstico de um canal.

Chamadas remotas sem autenticação podem receber somente um resumo. Respostas locais diretas ou autenticadas podem trazer mais detalhes, conforme o endpoint. Não publique o Gateway na internet para obter um diagnóstico mais completo: use acesso local ou uma rede privada controlada.

3. Diferencie estado do Docker de estado do OpenClaw

Up indica que o container está em execução. O estado healthy ou unhealthy, quando existe, depende do comando de healthcheck configurado no container. Ele não representa, por definição, todos os recursos do assistente.

Para inspecionar somente o estado, sem despejar as variáveis de ambiente:

CID=$(docker compose ps -a -q openclaw-gateway)

Confirme que a variável contém exatamente um ID. Se estiver vazia, confira o diretório e o nome do projeto antes de prosseguir.

docker inspect "$CID" --format \
  'Status={{.State.Status}} ExitCode={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}} RestartCount={{.RestartCount}}'

docker inspect "$CID" --format '{{json .State.Health}}'

O segundo comando pode retornar null quando não há healthcheck configurado. Quando houver, veja o resultado da execução do probe e seus erros. Um comando de probe inválido ou uma dependência ausente na imagem também pode produzir unhealthy.

Não presuma que marcar um container como unhealthy fará o Docker Compose reiniciá-lo automaticamente. A política de reinício do Docker trata a saída do processo; ações baseadas em saúde dependem da infraestrutura e de mecanismos adicionais. Confira o comportamento do ambiente que você realmente usa.

4. Investigue o canal sem derrubar todo o serviço

Colete um trecho recente dos logs:

docker compose logs --tail 100 openclaw-gateway

Procure eventos próximos ao horário da falha. Reinicializações contínuas, erro de permissão, falha de autenticação e indisponibilidade de canal são hipóteses diferentes. Não aplique uma correção de memória a um erro de credencial só porque ambos fazem o assistente parecer offline.

Na instalação com a CLI disponível e configurada para o Gateway correto, a documentação recomenda:

openclaw status --deep
openclaw health --verbose
openclaw health --json

--verbose força uma verificação ao vivo; a consulta padrão de saúde pode usar um snapshot em cache. Os comandos dependem de conectividade e autenticação com o Gateway. Não copie o endereço de loopback do host para um container separado esperando que ele aponte para o mesmo processo.

Um ok: true no snapshot de saúde significa que o Gateway produziu a resposta, não que toda fila e todo canal estejam sem problemas. Examine os campos de canais e eventuais avisos de fila, em vez de extrair somente um booleano.

Para uma falha específica, continue com o diagnóstico de WhatsApp desconectando ou o guia para OpenClaw que não responde. Evite apagar credenciais e volumes como primeiro passo.

5. Monte alertas que não gerem custo de IA

Use probes HTTP para disponibilidade; não use uma conversa com o modelo como ping de uptime. A documentação recomenda não consultar /v1/chat/completions como healthcheck: esse caminho pode criar sessões e acionar chamadas ao modelo. Um monitor de disponibilidade não precisa gerar uma resposta de IA a cada intervalo.

Uma configuração operacional útil separa três sinais:

1. Processo indisponível: falha de conexão ou liveness fora do esperado. Verifique container, listener e rede.
2. Inicialização pendente: startup ainda não terminou. Use uma janela de tolerância baseada no seu ambiente e observe o progresso.
3. Serviço degradado: readiness falhou após a inicialização. Avise o operador com o horário e investigue o subsistema afetado.

Não há um intervalo universal ideal. Defina frequência, timeout e número de falhas consecutivas conforme o tempo de resposta necessário e o comportamento observado. Registre esses parâmetros para não confundir uma janela de atualização prevista com uma pane.

Um monitor externo não consegue acessar 127.0.0.1 do seu servidor. Se o Gateway deve permanecer privado, execute o monitor na mesma rede ou use um coletor interno. Não abra a porta pública apenas para encaixar a URL em um serviço de uptime. Veja também as boas práticas para OpenClaw em produção.

Checklist de validação depois de uma mudança

• Confirme que os probes consultam a porta e o Gateway certos.
• Espere a inicialização concluir antes de avaliar readiness como falha persistente.
• Confira se os canais necessários estão disponíveis.
• Envie uma mensagem de teste por um remetente autorizado e verifique a resposta.
• Teste uma tarefa inofensiva para validar o modelo e as ferramentas necessárias.
• Verifique que o monitor não cria conversas nem chama o modelo periodicamente.
• Remova tokens, números de telefone e conteúdo de mensagens antes de compartilhar logs.

Esse teste de ponta a ponta complementa o monitoramento: não deve substituí-lo nem ser executado continuamente como probe barato. Um endpoint saudável não garante que a API de um provedor externo tenha saldo, que uma ferramenta possua permissão ou que a tarefa desejada esteja correta.

Perguntas frequentes

Qual endpoint usar no healthcheck do OpenClaw no Docker?

Use /healthz para liveness. Para acompanhar inicialização, use /startupz. Use /readyz quando o monitor deve detectar indisponibilidade que inclui canais e outras condições de readiness. Escolha conforme a ação associada ao resultado, não apenas pelo nome do endpoint.

Por que healthz retorna 200, mas readyz retorna 503?

O servidor HTTP pode estar vivo enquanto a inicialização ainda está pendente ou alguma condição de disponibilidade falhou. Consulte também /startupz, o corpo das respostas e os logs. Não conclua que o processo morreu só pelo 503 de readiness.

O container healthy garante que o WhatsApp funciona?

Não. O resultado depende do probe configurado. Um probe de liveness pode passar com um canal indisponível. Confira readiness, status do canal e uma mensagem de teste de ponta a ponta.

Docker Compose reinicia automaticamente um container unhealthy?

Não apenas por esse estado. A política de restart do Docker responde à saída do processo. Automação baseada em healthcheck exige mecanismos adicionais e precisa ser verificada na infraestrutura utilizada.

Posso usar uma mensagem ao modelo como monitor de uptime?

Não é a escolha recomendada. Use os endpoints HTTP de probe, que não precisam criar uma conversa nem executar inferência. Reserve chamadas ao modelo para testes controlados de ponta a ponta, com orçamento e objetivo definidos.

Preciso expor o Gateway publicamente para monitorar?

Não. Um monitor interno ou conectado à rede privada pode consultar os endpoints. Mantenha o acesso restrito e não publique a porta do Gateway somente para atender um serviço externo de uptime.