Troubleshooting OpenClaw: Resolvendo os 10 Erros Mais Comuns
Erros acontecem. Aqui estão os 10 problemas mais comuns e como resolver cada um rapidamente.
1. “API key inválida” ou “Authentication failed”
Sintoma: OpenClaw não conecta, mostra erro de autenticação.
Causa: Chave da API expirada, incorreta ou sem créditos.
Solução:
# Verifique a chave configurada
openclaw config get api.key
# Reconfigure a chave
openclaw auth login
Dica: Verifique seu saldo em console.anthropic.com ou no painel do provedor que você usa.
2. “Channel disconnected” (WhatsApp)
Sintoma: WhatsApp para de responder, sessão desconectada.
Causa: Sessão do WhatsApp Web expirou ou foi deslogada no celular.
Solução:
# Reconecte o WhatsApp
openclaw whatsapp link
Escaneie o novo QR code. Se persistir:
# Limpe sessão antiga e reconecte
rm -rf ~/.openclaw/whatsapp-session
openclaw whatsapp link
3. “Connection refused” ou “ECONNREFUSED”
Sintoma: OpenClaw não inicia, erro de conexão.
Causa: Gateway não está rodando ou porta ocupada.
Solução:
# Verifique se o gateway está rodando
openclaw gateway status
# Se não estiver, inicie
openclaw gateway start
# Se porta ocupada, encontre o processo
lsof -i :3000 # ou a porta configurada
4. Respostas muito lentas (>30 segundos)
Sintoma: Claude demora muito para responder.
Causa: Modelo pesado, contexto grande ou rede lenta.
Soluções:
# config.yaml - use modelo mais rápido
model: claude-3-haiku-20240307
# Ou reduza o contexto máximo
maxContextTokens: 50000
Para latência de rede, considere VPS mais próximo da Anthropic (US-East).
5. “Rate limit exceeded”
Sintoma: Erro 429, muitas requisições.
Causa: Excedeu o limite de requisições por minuto.
Solução:
# config.yaml - adicione delay entre mensagens
rateLimit:
messagesPerMinute: 20
delayMs: 500
Para uso intenso, considere tier pago com limites maiores.
6. “Out of memory” ou processo morto
Sintoma: OpenClaw fecha sozinho, especialmente em VPS pequeno.
Causa: Memória insuficiente (comum em VPS de 512MB-1GB).
Soluções:
# Adicione swap (2GB recomendado)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Torne permanente
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# config.yaml - reduza uso de memória
maxContextTokens: 30000
7. “Permission denied” em arquivos
Sintoma: OpenClaw não consegue ler/escrever arquivos.
Causa: Permissões incorretas no diretório de trabalho.
Solução:
# Corrija permissões do workspace
chmod -R u+rw ~/clawd
# Se rodando como serviço, verifique usuário
sudo chown -R $USER:$USER ~/.openclaw
8. Telegram bot não responde
Sintoma: Bot criado mas não recebe mensagens.
Causa: Webhook não configurado ou token incorreto.
Solução:
# Verifique se token está correto
openclaw config get channels.telegram.token
# Teste conectividade
curl "https://api.telegram.org/bot<SEU_TOKEN>/getMe"
Deve retornar JSON com informações do bot. Se não:
- Verifique token com @BotFather
- Certifique-se que bot não está em grupo sem permissão de mensagens
9. “Skill not found” ou skill não funciona
Sintoma: Skill configurada mas não executa.
Causa: Skill não instalada ou caminho incorreto.
Solução:
# Liste skills disponíveis
openclaw skills list
# Instale skill faltante
openclaw skills install <nome-da-skill>
# Verifique caminho no config
openclaw config get skills.path
10. Mensagens duplicadas
Sintoma: Bot responde duas vezes à mesma mensagem.
Causa: Múltiplas instâncias rodando ou webhook duplicado.
Solução:
# Verifique processos duplicados
ps aux | grep openclaw
# Mate processos extras
pkill -f "openclaw gateway"
# Reinicie apenas uma instância
openclaw gateway start
Debug Avançado
Ativar logs detalhados
# Rode com debug
DEBUG=openclaw:* openclaw gateway start
# Ou configure no yaml
logging:
level: debug
Verificar status completo
openclaw status
Testar conexão com API
# Teste direto com curl
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "content-type: application/json" \
-d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'
Ainda com problemas?
- Logs: Verifique
~/.openclaw/logs/ - GitHub Issues: github.com/openclaw/openclaw/issues
- Discord: Comunidade ativa em discord.gg/clawd
Inclua sempre:
- Versão do OpenClaw (
openclaw --version) - Sistema operacional
- Mensagem de erro completa
- Passos para reproduzir