---
title: "Guia de Debugging — Diagnosticar Problemas"
url: "https://openclaw.ia.br/guias/debugging/"
markdown_url: "https://openclaw.ia.br/guias/debugging.MD"
description: "Como diagnosticar problemas no OpenClaw. Logs, erros comuns e ferramentas de debug."
date: ""
author: ""
---

# Guia de Debugging — Diagnosticar Problemas

Como diagnosticar problemas no OpenClaw. Logs, erros comuns e ferramentas de debug.


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

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

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

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

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

```bash
# 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)

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

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

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

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

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

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

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

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

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

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

```yaml
# 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:

```bash
# 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](/troubleshooting/) — Referência de todos os erros conhecidos
- [Guia de Segurança](/guias/seguranca/) — Investigar problemas de segurança
- [Performance](/guias/performance/) — Otimizar velocidade após resolver problemas
- [Backup](/guias/backup/) — Garanta que você pode restaurar após incidentes
- [Canais](/canais/) — Problemas específicos de cada canal de comunicação