---
title: "Healthcheck do OpenClaw no Docker: o que monitorar"
url: "https://openclaw.ia.br/blog/openclaw-docker-healthcheck-monitoramento/"
markdown_url: "https://openclaw.ia.br/blog/openclaw-docker-healthcheck-monitoramento.MD"
description: "Monitore o OpenClaw no Docker com healthz, startupz e readyz. Diferencie processo ativo, inicialização e falha de canal sem gerar chamadas ao modelo de IA."
date: "2026-10-13"
author: "OpenClaw Brasil"
---

# Healthcheck do OpenClaw no Docker: o que monitorar

Monitore o OpenClaw no Docker com healthz, startupz e readyz. Diferencie processo ativo, inicialização e falha de canal sem gerar chamadas ao modelo de IA.


**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](https://docs.openclaw.ai/gateway/health) e na [documentação oficial de Docker](https://docs.openclaw.ai/install/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

| Verificação | Pergunta que responde | Uso recomendado | O que não comprova |
|---|---|---|---|
| `/healthz` | O servidor HTTP está vivo? | Liveness, disponibilidade do listener | Que a inicialização terminou ou que um canal funciona |
| `/startupz` | A preparação de inicialização terminou e o Gateway não está em drenagem? | Acompanhamento de startup e atualização | Que todos os canais e agentes estão disponíveis |
| `/readyz` | O Gateway está pronto segundo suas verificações de disponibilidade? | Alertas operacionais e admissão de tráfego | Que uma tarefa completa com o modelo vai funcionar |

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:

```bash
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](/instalacao/). Para dados que somem depois de recriar containers, o problema é outro: confira o [guia de volumes e persistência do OpenClaw](/blog/openclaw-docker-perde-configuracao-volumes/).

## 2. Consulte os endpoints sem chamar o modelo

Com a porta padrão publicada no host local:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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](/troubleshooting/whatsapp-desconecta/) ou o [guia para OpenClaw que não responde](/blog/openclaw-nao-responde-guia-diagnostico/). 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](/blog/boas-praticas-openclaw-producao/).

## 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.