7 Erros Comuns na Instalação do OpenClaw (e Como Resolver Cada Um)

Você seguiu o tutorial, digitou os comandos certinho, e… deu erro. Relaxa, acontece com todo mundo. Depois de analisar centenas de instalações, identificamos os 7 erros mais comuns que impedem as pessoas de usar o OpenClaw.

A boa notícia? Todos têm solução simples.

1. EACCES: Permission Denied (Erro de Permissões no Linux/macOS)

O sintoma

npm ERR! Error: EACCES: permission denied, access '/usr/lib/node_modules'
npm ERR! syscall access

Por que acontece

O npm está tentando instalar pacotes globais em uma pasta que pertence ao root (administrador). Isso acontece quando você instalou o Node.js via apt, brew ou outro gerenciador de pacotes.

✅ Solução (funciona em 2 minutos)

Configure um diretório próprio para pacotes globais:

# Criar diretório
mkdir -p ~/.npm-global

# Configurar npm para usar ele
npm config set prefix '~/.npm-global'

# Adicionar ao PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Para Zsh (macOS com Oh My Zsh):

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Agora reinstale:

npm install -g openclaw@latest

Como verificar

npm config get prefix
# Deve retornar: /home/seu-usuario/.npm-global

2. Node.js Versão Incompatível

O sintoma

error [email protected]: The engine "node" is incompatible with this module
Required: >=22.0.0  Got: 18.19.0

Ou erros de sintaxe estranhos durante a instalação.

Por que acontece

OpenClaw requer Node.js 22 ou superior (recomendado: 24 LTS). Versões antigas do Ubuntu/Debian vêm com Node 18 ou inferior.

✅ Solução

Use o nvm (Node Version Manager) para instalar a versão correta:

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Reiniciar terminal ou carregar nvm
source ~/.bashrc

# Instalar Node 24 LTS
nvm install 24
nvm use 24
nvm alias default 24

Como verificar

node --version
# Deve retornar: v24.x.x (ou v22.x.x mínimo)

3. Command Not Found: openclaw

O sintoma

$ openclaw onboard
bash: openclaw: command not found

A instalação pareceu funcionar, mas o comando não existe.

Por que acontece

O diretório de binários globais do npm não está no seu PATH. Isso é comum quando você usa nvm ou configurou um prefixo customizado.

✅ Solução

Descubra onde está instalado e adicione ao PATH:

# Encontrar onde está o openclaw
npm list -g --depth=0

# Ver o caminho de binários do npm
npm bin -g

Adicione o caminho ao seu .bashrc ou .zshrc:

# Para nvm
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

# Para npm-global customizado
export PATH="$HOME/.npm-global/bin:$PATH"

Depois execute:

source ~/.bashrc
openclaw --version

4. Gateway Não Inicia — Porta em Uso

O sintoma

Error: listen EADDRINUSE: address already in use :::3434

Ou o gateway parece iniciar mas morre imediatamente.

Por que acontece

Outra instância do OpenClaw (ou outro programa) já está usando a porta 3434.

✅ Solução

Opção A: Mate o processo antigo

# Encontrar o que está usando a porta
lsof -i :3434

# Matar o processo
pkill -f openclaw

# Tentar novamente
openclaw gateway start

Opção B: Use outra porta

Edite ~/.openclaw/config.yaml:

gateway:
  port: 3435

Como verificar

openclaw gateway status
# Deve mostrar: Gateway running on port XXXX

5. QR Code do WhatsApp Expira ou Não Carrega

O sintoma

• QR code aparece mas expira antes de você escanear
• QR code não aparece no terminal
• Fica em “Waiting for QR code…” indefinidamente

Por que acontece

• Expira rápido: Você tem 30 segundos para escanear
• Não carrega: Problema de dependências do Baileys (biblioteca WhatsApp)
• Loops infinitos: Sessão corrompida de tentativa anterior

✅ Solução

Passo 1: Limpe sessões antigas

rm -rf ~/.openclaw/whatsapp-session
openclaw gateway restart

Passo 2: Prepare-se ANTES do QR aparecer

• Abra o WhatsApp no celular
• Vá em Configurações > Dispositivos conectados
• Deixe pronto para escanear

Passo 3: Gere e escaneie RÁPIDO

openclaw gateway logs -f
# Em outra aba:
openclaw channel add whatsapp

Assim que o QR aparecer, escaneie imediatamente.

Passo 4: Se ainda falhar, verifique dependências

# Ubuntu/Debian
sudo apt install -y libwebp-dev libjpeg-dev libpng-dev

# Reinstalar OpenClaw
npm install -g openclaw@latest --force

6. Timeout no Primeiro Boot / API Key Inválida

O sintoma

Error: Request timed out
Error: Invalid API key
Error: 401 Unauthorized

O gateway inicia mas não consegue conectar com o Claude/GPT.

Por que acontece

• API key incorreta ou expirada
• Variáveis de ambiente não configuradas
• Firewall bloqueando conexões HTTPS

✅ Solução

Verificar API key:

# Ver configuração atual
cat ~/.openclaw/config.yaml | grep -A5 anthropic

Testar conexão direta:

curl -H "x-api-key: SUA_CHAVE_AQUI" \
  -H "anthropic-version: 2023-06-01" \
  https://api.anthropic.com/v1/messages \
  -d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

Se retornar erro de autenticação, a chave está errada. Gere uma nova no console.anthropic.com.

Verificar variáveis de ambiente:

# Se usa variáveis ao invés de config.yaml
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

7. Memória Insuficiente (VPS/Raspberry Pi)

O sintoma

• Sistema fica extremamente lento
• OpenClaw é morto pelo sistema operacional
• Erros de SIGKILL ou out of memory

Por que acontece

O OpenClaw + Node.js + dependências podem usar 500MB-1GB de RAM. Em VPS com 512MB ou Raspberry Pi com pouca memória, isso causa problemas.

✅ Solução

Passo 1: Adicione swap (memória virtual)

# Criar arquivo de swap de 2GB
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Tornar permanente
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Passo 2: Limite o histórico de conversas

No config.yaml:

memory:
  maxHistoryTokens: 50000  # Reduzir se necessário

Passo 3: Considere upgrade

Para uso 24/7, recomendamos no mínimo 1GB de RAM (2GB ideal). O Oracle Cloud Free Tier oferece VPS com 12GB grátis.

Como verificar

# Ver uso de memória
free -h

# Ver swap em uso
swapon --show

8. Erros de API: Rate Limit e Model Not Found

Rate Limit Exceeded

Sintoma: Erro 429 — muitas requisições em pouco tempo.

Error: 429 Too Many Requests

Solução: Configure rate limiting no config.yaml:

rateLimit:
  requestsPerMinute: 20
  delayMs: 500

Para uso intenso, considere upgrade de plano na Anthropic.

“Model not found”

Sintoma: O modelo especificado não existe ou está digitado errado.

Solução: Verifique o nome exato do modelo em config.yaml:

# Correto
model: anthropic/claude-3-5-sonnet-20241022

# Incorreto (nome incompleto)
model: claude-sonnet

9. Problemas com Canais: Telegram e Discord

Telegram: Bot Não Responde

Sintoma: Bot criado mas não recebe mensagens.

Verificações:

1. Teste se o token está correto:

curl "https://api.telegram.org/bot<SEU_TOKEN>/getMe"

Deve retornar JSON com informações do bot.

2. Verifique se seu ID está na allowList:

channels:
  telegram:
    allowList:
      - "123456789"  # Seu ID numérico

3. Confirme que o gateway está rodando:

openclaw gateway status

Discord: “Missing Permissions”

Sintoma: Bot não consegue enviar ou ler mensagens no Discord.

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.

10. Problemas de Memória e Contexto

“Context Window Exceeded”

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

Sintoma: Memória não está persistindo entre sessões.

Verificações:

1. ~/clawd/MEMORY.md existe?
2. Permissões de escrita no diretório?
3. Disco cheio?

df -h ~/clawd

11. Problemas de Performance

Respostas Muito Lentas (>30 segundos)

Causas comuns e soluções:

1. Modelo muito pesado:

# Use modelo mais leve
model: anthropic/claude-3-5-haiku-20241022

2. Contexto muito grande:

context:
  maxMessages: 20

3. Latência de rede: Considere VPS mais próximo da Anthropic (US-East).

Alto Uso de CPU/Memória

# Verificar uso
htop

# Reduzir workers no config.yaml
workers: 1

# Aumentar intervalo de heartbeat
heartbeat:
  intervalMinutes: 60

12. Mensagens Duplicadas

Sintoma: Bot responde duas vezes à mesma mensagem.

Causa: Múltiplas instâncias do OpenClaw rodando ao mesmo tempo.

Solução:

# Verificar processos duplicados
ps aux | grep openclaw

# Matar processos extras
pkill -f "openclaw gateway"

# Reiniciar apenas uma instância
openclaw gateway start

Debug Avançado

Quando as soluções acima não bastam, ative logs detalhados:

# Rodar em modo debug
DEBUG=openclaw:* openclaw gateway start

# Ou configurar no yaml
logging:
  level: debug

Teste a conexão com a API diretamente:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-3-5-haiku-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Resumo: Erros e Soluções

Checklist Rápido de Diagnóstico

Antes de pedir ajuda, rode estes comandos:

# Versão do Node
node --version

# Versão do OpenClaw
openclaw --version

# Status geral
openclaw doctor

# Logs em tempo real
openclaw gateway logs -f

Copie a saída ao reportar problemas.

Ainda Com Problemas?

Se nenhuma solução funcionou:

1. Logs completos: openclaw gateway logs -f > logs.txt
2. Discord da comunidade — Respostas em minutos
3. GitHub Issues — Bugs confirmados

Próximos Passos

Instalação funcionando? Hora de configurar:

• Guia completo de instalação
• Troubleshooting avançado
• O que fazer depois de instalar
• Configurar WhatsApp para negócios

Encontrou um erro que não está aqui? Compartilhe no Discord para adicionarmos à lista!