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 openclaw@x.x.x: 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

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

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

Próximos Passos

Instalação funcionando? Hora de configurar:

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