Erros Comuns do OpenClaw e Como Resolver
Instalou o OpenClaw e algo não está funcionando? Este guia cobre os erros mais comuns e suas soluções.
Erros de Instalação
“command not found: openclaw”
O npm não adicionou o binário ao PATH.
Solução:
# Adicionar ao PATH temporariamente
export PATH="$PATH:$(npm bin -g)"
# Ou encontrar onde foi instalado
npm list -g openclaw
# Adicionar permanentemente ao ~/.bashrc ou ~/.zshrc
echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.bashrc
source ~/.bashrc
“EACCES: permission denied”
Problema de permissões no npm global.
Solução:
# Opção 1: Usar npx (não precisa instalar global)
npx openclaw@latest onboard
# Opção 2: Configurar npm para usar diretório do usuário
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest
“Node.js version X is not supported”
Versão do Node muito antiga.
Solução:
# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# Instalar Node 22
nvm install 22
nvm use 22
nvm alias default 22
Erros de API
“ANTHROPIC_API_KEY not set” ou “Invalid API key”
A chave da API não está configurada ou está incorreta.
Solução:
- Verifique se a chave existe em
~/clawd/config.yaml:
anthropic:
apiKey: "sk-ant-api03-..."
- Ou configure via variável de ambiente:
export ANTHROPIC_API_KEY="sk-ant-api03-..."
- Confirme que a chave é válida no Console da Anthropic
“Rate limit exceeded”
Muitas requisições em pouco tempo.
Solução:
- Aguarde alguns minutos
- Configure rate limiting:
rateLimit:
requestsPerMinute: 20
- Considere upgrade do plano na Anthropic
“Model not found”
Modelo especificado não existe.
Solução:
Verifique o nome exato do modelo em config.yaml:
# Correto
model: anthropic/claude-3-5-sonnet-20241022
# Incorreto
model: claude-sonnet # Nome incompleto
Erros de Canais
WhatsApp: “QR code expired”
O QR code tem validade curta.
Solução:
# Reconectar
openclaw channel reconnect whatsapp
# Escaneie rapidamente quando o QR aparecer
WhatsApp: “Logged out”
Sessão desconectada (comum após atualizações do WhatsApp).
Solução:
# Remover sessão antiga
rm -rf ~/clawd/.wwebjs_auth
# Reconectar
openclaw channel add whatsapp
Telegram: “Bot not responding”
O bot está configurado mas não responde.
Verificações:
- Token está correto?
# Testar token
curl "https://api.telegram.org/bot<SEU_TOKEN>/getMe"
- Seu ID está na allowList?
channels:
telegram:
allowList:
- "123456789" # Seu ID numérico
- Gateway está rodando?
openclaw gateway status
Discord: “Missing permissions”
Bot não tem permissões necessárias.
Solução:
No Discord Developer Portal, verifique se o bot tem:
- Send Messages
- Read Message History
- Use Slash Commands
Regenere o link de convite com as permissões corretas
Erros do Gateway
“Port 3000 already in use”
Outra aplicação usando a porta.
Solução:
# Encontrar o que usa a porta
lsof -i :3000
# Matar o processo (se apropriado)
kill -9 <PID>
# Ou usar outra porta
# Em config.yaml:
server:
port: 3001
“Gateway failed to start”
Erro genérico de inicialização.
Diagnóstico:
# Ver logs detalhados
openclaw gateway logs -f
# Rodar em modo debug
DEBUG=* openclaw gateway start
Gateway trava ou reinicia
Geralmente falta de memória.
Solução:
# Verificar memória
free -h
# Adicionar swap se necessário
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Erros de Memória/Contexto
“Context window exceeded”
Conversa muito longa para o modelo.
Solução:
# Limitar histórico
context:
maxMessages: 30
summarizeAfter: 50
Ou peça ao assistente:
"Resume nossa conversa e limpa o contexto antigo"
Assistente “esquece” informações
Memória não persistindo.
Verificações:
~/clawd/MEMORY.mdexiste?- Permissões de escrita no diretório?
- Disco cheio?
df -h ~/clawd
Erros de Performance
Respostas muito lentas
Causas comuns:
- Modelo muito pesado:
# Use modelo mais leve
model: anthropic/claude-3-5-haiku-20241022
- Contexto muito grande:
context:
maxMessages: 20
- Conexão lenta com API (verifique sua internet)
Alto uso de CPU/memória
Solução:
# Verificar uso
htop
# Reduzir workers
# Em config.yaml:
workers: 1
# Limitar processos de background
heartbeat:
intervalMinutes: 60 # Aumentar intervalo
Comandos de Diagnóstico
# Status geral
openclaw status
# Diagnóstico completo
openclaw doctor
# Verificar configuração
openclaw config validate
# Logs em tempo real
openclaw gateway logs -f
# Testar conexão com API
openclaw test connection
# Verificar versão
openclaw --version
Ainda com Problemas?
- Busque no GitHub Issues: github.com/openclaw/openclaw/issues
- Pergunte no Discord: discord.gg/clawd
- Verifique a documentação: docs.openclaw.ai
Artigos relacionados: