--- title: "7 Erros Comuns na Instalação do OpenClaw (e Como Resolver Cada Um)" url: "https://openclaw.ia.br/blog/7-erros-comuns-instalacao-openclaw/" markdown_url: "https://openclaw.ia.br/blog/7-erros-comuns-instalacao-openclaw.MD" description: "Está travado na instalação do OpenClaw? Veja os 7 erros mais frequentes e soluções testadas que funcionam. De permissões no Linux a timeout no WhatsApp." date: "2026-02-01" author: "Equipe OpenClaw" --- # 7 Erros Comuns na Instalação do OpenClaw (e Como Resolver Cada Um) Está travado na instalação do OpenClaw? Veja os 7 erros mais frequentes e soluções testadas que funcionam. De permissões no Linux a timeout no WhatsApp. # 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: ```bash # 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):** ```bash echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc ``` Agora reinstale: ```bash npm install -g openclaw@latest ``` ### Como verificar ```bash 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: ```bash # 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 ```bash node --version # Deve retornar: v24.x.x (ou v22.x.x mínimo) ``` --- ## 3. Command Not Found: openclaw ### O sintoma ```bash $ 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: ```bash # 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`: ```bash # 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: ```bash 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 ```bash # 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`: ```yaml gateway: port: 3435 ``` ### Como verificar ```bash 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 ```bash 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 ```bash 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 ```bash # 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:** ```bash # Ver configuração atual cat ~/.openclaw/config.yaml | grep -A5 anthropic ``` **Testar conexão direta:** ```bash 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](https://console.anthropic.com/). **Verificar variáveis de ambiente:** ```bash # 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) ```bash # 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`: ```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](/blog/instalar-openclaw-gratis-oracle-cloud/) oferece VPS com **12GB grátis**. ### Como verificar ```bash # 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`: ```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`: ```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: ```bash curl "https://api.telegram.org/bot/getMe" ``` Deve retornar JSON com informações do bot. 2. Verifique se seu ID está na allowList: ```yaml channels: telegram: allowList: - "123456789" # Seu ID numérico ``` 3. Confirme que o gateway está rodando: ```bash 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:** ```yaml # 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? ```bash df -h ~/clawd ``` --- ## 11. Problemas de Performance ### Respostas Muito Lentas (>30 segundos) **Causas comuns e soluções:** 1. **Modelo muito pesado:** ```yaml # Use modelo mais leve model: anthropic/claude-3-5-haiku-20241022 ``` 2. **Contexto muito grande:** ```yaml context: maxMessages: 20 ``` 3. **Latência de rede:** Considere VPS mais próximo da Anthropic (US-East). ### Alto Uso de CPU/Memória ```bash # 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:** ```bash # 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: ```bash # Rodar em modo debug DEBUG=openclaw:* openclaw gateway start # Ou configurar no yaml logging: level: debug ``` Teste a conexão com a API diretamente: ```bash 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 | Erro | Solução Rápida | Tempo | |------|----------------|-------| | Permission denied (npm) | Configurar npm-global | 30s | | Command not found | Adicionar ao PATH | 20s | | Porta em uso | Matar processo / mudar porta | 15s | | QR expira | Limpar sessão WhatsApp | 45s | | Node incompatível | Instalar com nvm | 2min | | Sem memória | Adicionar swap 2GB | 3min | | API key inválida | Verificar chave no config.yaml | 1min | | Rate limit | Configurar rateLimit no yaml | 1min | | Telegram sem resposta | Verificar token e allowList | 2min | | Mensagens duplicadas | Matar processos extras | 30s | --- ## Checklist Rápido de Diagnóstico Antes de pedir ajuda, rode estes comandos: ```bash # 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](https://discord.gg/clawd)** — Respostas em minutos 3. **[GitHub Issues](https://github.com/openclaw/openclaw/issues)** — Bugs confirmados --- ## Próximos Passos Instalação funcionando? Hora de configurar: - [Guia completo de instalação](/instalacao/) - [Troubleshooting avançado](/troubleshooting/) - [O que fazer depois de instalar](/guias/pos-instalacao/) - [Configurar WhatsApp para negócios](/blog/automacao-whatsapp-ia-guia-completo/) --- *Encontrou um erro que não está aqui? Compartilhe no Discord para adicionarmos à lista!*