Debugging do OpenClaw — Diagnóstico Completo

Introdução

Algo não está funcionando como esperado no seu OpenClaw? O assistente não responde, as respostas estão erradas, uma skill parou de funcionar, ou o gateway caiu de surpresa? Diagnosticar problemas em sistemas de IA pode parecer complicado, mas o OpenClaw tem ferramentas excelentes de diagnóstico que tornam o processo muito mais direto do que você imagina.

Este guia aborda debugging de forma sistemática: começando pelos comandos mais rápidos de diagnóstico, passando pela leitura eficiente de logs, e chegando aos problemas mais complexos que exigem investigação aprofundada. A abordagem é prática — você vai encontrar o problema, entender por que está acontecendo e corrigi-lo.

O debugging eficaz segue uma lógica simples: coletar informação antes de agir. Tentativas de correção às cegas geralmente pioram o problema ou criam novos. Seguindo a metodologia deste guia, você vai diagnosticar a maioria dos problemas em menos de 10 minutos.

Pré-requisitos

Para usar este guia você precisa de:

Acesso ao terminal do servidor/máquina onde o OpenClaw está rodando
Permissões de leitura nos arquivos de log
Ao menos 5 minutos para diagnóstico inicial — não saia reiniciando tudo ao mesmo tempo

Diagnóstico Rápido (2 Minutos)

Antes de qualquer coisa, rode o diagnóstico completo:

# Diagnóstico completo — primeira coisa a fazer sempre
openclaw doctor

# Saída esperada quando tudo está OK:
# ✓ Node.js v20.x.x (compatível)
# ✓ OpenClaw v1.x.x instalado
# ✓ Gateway: rodando na porta 3434
# ✓ API Key Anthropic: válida (sk-ant-...xxxx)
# ✓ Canal WhatsApp: conectado
# ✓ Canal Telegram: conectado
# ✓ Memória disponível: 2.1GB
# ✓ Espaço em disco: 45GB disponível
# ✓ SOUL.md: encontrado e válido
# ✓ config.yaml: sem erros de sintaxe
# ✅ Tudo funcionando!

# Se aparecer algo com ✗, esse é o problema a investigar

# Status completo de todos os componentes
openclaw status
openclaw gateway status
openclaw channel status

Logs — Sua Principal Fonte de Informação

Ver Logs em Tempo Real

# Gateway — log principal do sistema
journalctl --user -u openclaw-gateway -f

# Ou, se não usa systemd:
openclaw gateway logs --follow

# Filtrar apenas erros:
openclaw gateway logs --level error --follow

Logs Históricos

# Últimas 100 linhas do log geral
openclaw gateway logs --last 100

# Logs do dia atual
openclaw gateway logs --since today

# Logs de um período específico
openclaw gateway logs --since "2026-03-20 09:00" --until "2026-03-20 12:00"

# Log de uma sessão específica
openclaw session logs --id SESSION_ID

Modo Verbose

Para diagnóstico detalhado de um problema específico:

# Iniciar gateway em modo verbose (mostra cada etapa do processamento)
openclaw gateway stop
openclaw gateway --verbose

# Com nível máximo de detalhe:
openclaw gateway --verbose --log-level debug

No modo verbose, você verá:

Cada mensagem recebida e pelo qual canal
O contexto sendo montado (quantos tokens)
A requisição sendo enviada para a API
A resposta sendo processada
Cada ação do agente sendo executada

Logs de Sessão (Histórico de Conversas)

# Ver histórico de sessões
ls ~/.openclaw/sessions/

# Ler sessão específica (formato JSON Lines)
cat ~/.openclaw/sessions/2026-03-22.jsonl | python3 -m json.tool | less

# Buscar por mensagens específicas
grep -i "erro\|error\|failed" ~/.openclaw/sessions/*.jsonl

Problemas Comuns e Como Diagnosticar

Problema 1: Assistente Não Responde

Sintomas: Você envia mensagem, nada acontece, sem resposta após 30+ segundos.

Diagnóstico passo a passo:

# Passo 1: Gateway está rodando?
openclaw gateway status
# Se não: openclaw gateway start

# Passo 2: Canal está conectado?
openclaw channel status
# Se WhatsApp: verificar se QR code não expirou
# Se Telegram: verificar se bot está ativo

# Passo 3: API key válida?
openclaw auth status
# Se inválida: openclaw auth add anthropic (e reconfigure a key)

# Passo 4: Ver logs ao vivo enquanto envia mensagem
openclaw gateway logs --follow
# Envie a mensagem e observe o que aparece nos logs

Soluções comuns:

# Reiniciar tudo na ordem correta
openclaw gateway stop
sleep 5
openclaw gateway start

# Reconectar WhatsApp
openclaw channel reconnect whatsapp

# Revalidar API key
openclaw auth verify anthropic

Problema 2: Respostas Incorretas ou Fora do Personagem

Sintomas: O assistente responde, mas ignora o SOUL.md, responde de forma genérica, “esqueceu” informações importantes, ou mistura contextos.

Diagnóstico:

# Verificar se SOUL.md está sendo carregado
openclaw debug context --last-session
# Mostra o contexto exato que foi enviado para a API

# Verificar sintaxe do SOUL.md
openclaw validate soul

# Ver o contexto atual da sessão
openclaw context show

# Verificar tamanho do SOUL.md
wc -w ~/clawd/SOUL.md
# Se muito grande (5000+ palavras), pode estar sendo truncado

Soluções:

# Reiniciar sessão com contexto limpo
openclaw session reset

# Verificar e corrigir SOUL.md
openclaw validate soul --fix

# Forçar recarregamento dos arquivos de memória
openclaw context reload

Problema 3: Lentidão nas Respostas

Sintomas: Respostas chegam, mas demoram 20-30+ segundos quando normalmente levam 3-5 segundos.

Diagnóstico:

# Testar latência da API
openclaw ping --model claude-sonnet-4
# Saída: Latência até API Anthropic: 245ms
# Latência API normal: 200-800ms. Acima de 2s = problema de rede.

# Ver uso de recursos do servidor
openclaw status --resources
# CPU: 12% | RAM: 847MB/2GB | Disk: 40GB free

# Verificar tamanho do contexto atual
openclaw status --context
# Se 80%+ cheio: compactação pode ajudar

# Ver se há queue de mensagens represadas
openclaw queue status

Soluções:

# Reduzir contexto
openclaw context compact

# Mudar para modelo mais rápido temporariamente
openclaw config set model.primary claude-haiku-3-5
openclaw gateway restart

# Verificar rede
curl -o /dev/null -s -w "%{time_total}" https://api.anthropic.com
# Tempo aceitável: < 1 segundo

Problema 4: Skill Não Funciona

Sintomas: Uma skill específica para de responder, dá erro ou não executa o esperado.

Diagnóstico:

# Listar skills instaladas e status
openclaw skills list --status

# Testar skill específica
openclaw skills test nome-da-skill

# Ver logs da skill
openclaw skills logs nome-da-skill --last 50

# Verificar configuração da skill
openclaw skills inspect nome-da-skill

Soluções:

# Recarregar skill sem reiniciar o gateway
openclaw skills reload nome-da-skill

# Reinstalar skill
openclaw skills uninstall nome-da-skill
openclaw skills install nome-da-skill

# Verificar dependências da skill
openclaw skills check-deps nome-da-skill

Problema 5: Gateway Cai Repetidamente

Sintomas: Gateway para sozinho a cada poucos minutos ou horas.

Diagnóstico:

# Ver histórico de crashes
journalctl --user -u openclaw-gateway --since "24 hours ago" | grep -i "error\|crash\|exit"

# Ver código de saída
openclaw gateway status --verbose
# Exit code 0: saída normal
# Exit code 1: erro genérico
# Exit code 137: killed (falta de memória)

# Monitorar memória em tempo real
watch -n 5 "openclaw status --resources"

Soluções:

# Configurar reinício automático com systemd
openclaw service install --auto-restart
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

# Se for falta de memória, reduzir uso:
openclaw config set agents.defaults.contextTokens 20000
openclaw config set sessions.maxOpen 5

Ferramentas de Debug Avançadas

Debug de Requisições à API

# Ver exatamente o que é enviado para a API
openclaw debug api --capture

# Salvar captura para análise
openclaw debug api --capture --output ~/debug-capture.json

# Replay de uma requisição específica
openclaw debug replay --session SESSION_ID --message INDEX

Inspetor de Contexto

# Ver o contexto montado para a última mensagem
openclaw debug context --last

# Simular o contexto para uma mensagem específica
openclaw debug context --simulate "Qual é o prazo do projeto?"

# Verificar o que seria enviado à API (sem enviar)
openclaw debug dry-run --message "teste de diagnóstico"

Análise de Performance

# Profile de performance da última hora
openclaw perf report --period 1h

# Saída:
# Média de latência: 2.3s
# Mediana: 1.8s
# P95: 6.2s (5% das requisições mais lentas)
# Tokens/minuto: 2.450
# Custo estimado: $0.72/hora

Relatório de Bug

Quando encontrar um bug que precisa de suporte:

# Gerar relatório completo (anonimizado)
openclaw report-bug

# Isso cria um arquivo com:
# - Versão do OpenClaw e dependências
# - Logs dos últimos 5 minutos (sem API keys ou dados pessoais)
# - Informações do sistema
# - Hash do config.yaml (sem valores sensíveis)

# Salvar em arquivo para enviar ao suporte
openclaw report-bug --output ~/openclaw-bug-report.txt

Erros Comuns e Soluções

Erro nos Logs	O Que Significa	Solução
`API key invalid or expired`	Key errada ou revogada	Reconfigure com `openclaw auth add anthropic`
`Rate limit exceeded (429)`	Muitas requisições por minuto	Aguarde 60s; configure `rateLimit.requestsPerMinute`
`Context length exceeded`	Mensagem + contexto maior que o limite	Compacte contexto: `openclaw context compact`
`Connection timeout`	Servidor da API inacessível	Verifique rede; teste `curl https://api.anthropic.com`
`ENOENT: no such file SOUL.md`	Arquivo de configuração ausente	Crie o arquivo ou restaure do backup
`YAML parse error in config.yaml`	Erro de sintaxe no config	Valide com `openclaw validate config`
`WhatsApp session expired`	QR code precisa ser renovado	`openclaw channel reconnect whatsapp`
`Skill execution failed`	Erro na execução da skill	`openclaw skills logs nome-skill` para detalhes
`Out of memory`	RAM insuficiente	Reduza contextTokens; reinicie gateway

Configuração Avançada de Logs

Logging Estruturado para Produção

# config.yaml
logging:
  level: "info"         # debug, info, warn, error
  format: "json"        # text, json (json facilita análise)
  output:
    - type: file
      path: ~/clawd/logs/openclaw.log
      rotation:
        maxSizeMB: 100
        maxFiles: 10
    - type: stdout

  # Alertas em tempo real para erros críticos
  alerts:
    - level: error
      channel: telegram
      throttle: 60  # Máximo 1 alerta por minuto

Monitoramento Externo

Para produção, considere integrar com sistemas de monitoramento:

# Exportar métricas para Prometheus
openclaw metrics export --format prometheus --port 9090

# Healthcheck endpoint para uptime monitors
curl http://localhost:3434/health
# {"status":"ok","uptime":3600,"version":"1.x.x"}

Boas Práticas

Nunca reinicie o gateway sem ver os logs primeiro: Um restart às cegas pode mascarar o problema real. Sempre leia os últimos 50 linhas de log antes de qualquer ação.
Diagnose antes de mudar configurações: Cada mudança de configuração sem entender a causa do problema cria novas variáveis. Isole o problema, entenda-o, então corrija especificamente.
Mantenha logs por pelo menos 7 dias: Problemas intermitentes (que aparecem uma vez e somem) só podem ser diagnosticados se você tiver histórico suficiente. Configure retenção de logs adequada.
Use o --verbose em produção temporariamente: Quando um problema persistente resiste ao diagnóstico normal, habilite verbose por 30-60 minutos durante o uso normal. O detalhe extra geralmente revela o problema.
Documente problemas resolvidos: Quando você resolve um problema não óbvio, documente no MEMORY.md ou em um arquivo de notas. A próxima vez que acontecer, você vai resolver em 2 minutos.
Configure alertas proativos: Não espere o usuário reclamar para descobrir um problema. Configure alertas para erros repetitivos e reinicializações automáticas do gateway.
Separe debug de produção: Use uma instância separada para testes e desenvolvimento. Problemas de debug em produção afetam usuários reais.

Perguntas Frequentes

O gateway reinicia mas cai novamente em minutos. O que fazer? Provavelmente um loop: o gateway inicia, encontra um erro fatal, cai, reinicia e encontra o mesmo erro. Use journalctl --user -u openclaw-gateway -n 50 para ver o que aconteceu imediatamente antes de cada crash. O padrão de erro vai indicar a causa: falta de memória (exit 137), erro de configuração (YAML inválido), ou dependência faltando.

Posso fazer debug sem parar o gateway de produção? Sim. Use openclaw debug em um terminal separado sem parar o gateway. O modo --capture funciona em paralelo com o processamento normal. Para mudanças de configuração, a maioria pode ser aplicada com openclaw gateway reload (sem stop/start).

Como sei se o problema é da minha configuração ou da API da Anthropic? Use openclaw ping --model claude-sonnet-4 para testar diretamente a API sem passar pela sua configuração. Se o ping falhar, o problema é de rede ou da API. Se o ping funcionar mas o assistente não responde, o problema está na sua configuração.

Os logs mostram mensagens mas o usuário diz que não recebeu resposta. Por quê? Provavelmente um problema no canal, não no processamento. O OpenClaw processou a mensagem e gerou resposta, mas a entrega falhou. Verifique com openclaw channel status e openclaw channel logs whatsapp --last 20 para ver erros de entrega.

Existe modo de debug gráfico/visual? O OpenClaw tem uma interface web de administração básica. Acesse http://localhost:3434/admin no seu servidor. Mostra status, logs e permite algumas ações básicas pelo browser. Para debug completo, o terminal continua sendo a ferramenta mais poderosa.

Próximos Passos

Troubleshooting Completo — Referência de todos os erros conhecidos
Guia de Segurança — Investigar problemas de segurança
Performance — Otimizar velocidade após resolver problemas
Backup — Garanta que você pode restaurar após incidentes
Canais — Problemas específicos de cada canal de comunicação

Primeiros Passos

Conectar

Aprender

Ajuda

Recursos

Buscar

Comunidade

Guia de Debugging — Diagnosticar Problemas

Debugging do OpenClaw — Diagnóstico Completo

Introdução

Pré-requisitos

Diagnóstico Rápido (2 Minutos)

Logs — Sua Principal Fonte de Informação

Ver Logs em Tempo Real

Logs Históricos

Modo Verbose

Logs de Sessão (Histórico de Conversas)

Problemas Comuns e Como Diagnosticar

Problema 1: Assistente Não Responde

Problema 2: Respostas Incorretas ou Fora do Personagem

Problema 3: Lentidão nas Respostas

Problema 4: Skill Não Funciona

Problema 5: Gateway Cai Repetidamente

Ferramentas de Debug Avançadas

Debug de Requisições à API

Inspetor de Contexto

Análise de Performance

Relatório de Bug

Erros Comuns e Soluções

Configuração Avançada de Logs

Logging Estruturado para Produção

Monitoramento Externo

Boas Práticas

Perguntas Frequentes

Próximos Passos