5 Erros Comuns na Instalação do OpenClaw (e Como Resolver em Segundos)

Você seguiu o tutorial, copiou os comandos, e… erro.

Calma. Você não é o único — e a solução geralmente leva menos de 30 segundos.

Este guia cobre os 5 erros mais comuns na instalação do OpenClaw. Todos testados por milhares de usuários.

1. EACCES: Permission Denied (Permissão Negada)

O Erro

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Por Que Acontece

O npm está tentando instalar pacotes globais em uma pasta do sistema que requer permissões de administrador.

A Solução (30 segundos)

Não use sudo npm install! Isso cria mais problemas. Faça isso:

# Criar pasta para pacotes globais no seu usuário
mkdir -p ~/.npm-global

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

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

# Agora sim, instale
npm install -g openclaw@latest

macOS com zsh? Use ~/.zshrc em vez de ~/.bashrc.

✅ Resultado: Instalação funciona sem erros de permissão.

2. Command Not Found: openclaw

O Erro

bash: openclaw: command not found

ou

zsh: command not found: openclaw

Por Que Acontece

O npm instalou o OpenClaw, mas o terminal não sabe onde encontrá-lo. O diretório de binários globais não está no PATH.

A Solução (20 segundos)

Se você usa nvm:

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

Se configurou npm-global (solução do erro #1):

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

Torne permanente adicionando a linha ao seu ~/.bashrc ou ~/.zshrc:

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

Verificar se funcionou:

which openclaw
# Deve mostrar: /home/seu-usuario/.npm-global/bin/openclaw

✅ Resultado: openclaw reconhecido em qualquer terminal.

3. Gateway Não Inicia (Porta em Uso)

O Erro

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

Por Que Acontece

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

A Solução (15 segundos)

Opção 1: Matar o processo existente

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

# Matar processo do OpenClaw
pkill -f openclaw

# Reiniciar
openclaw gateway restart

Opção 2: Usar outra porta

Edite ~/.openclaw/config.yaml (ou ~/clawd/config.yaml):

gateway:
  port: 3435  # Qualquer porta livre

Depois: openclaw gateway restart

✅ Resultado: Gateway inicia sem conflitos.

4. QR Code do WhatsApp Expira ou Não Aparece

O Erro

• QR code some antes de escanear
• QR code não aparece no terminal
• “Session expired” após escanear

Por Que Acontece

• Outras sessões WhatsApp Web abertas
• Conexão lenta
• Sessão corrompida

A Solução (45 segundos)

Passo 1: Feche TODAS as abas de WhatsApp Web em outros navegadores

Passo 2: Limpe a sessão anterior

rm -rf ~/.openclaw/whatsapp-session

Passo 3: Reinicie e escaneie rápido

openclaw gateway restart

Quando o QR aparecer, escaneie em até 20 segundos.

Ainda não funciona? Verifique se seu WhatsApp está atualizado no celular.

✅ Resultado: WhatsApp conecta e permanece conectado.

5. Node.js: Versão Incompatível ou Não Instalado

O Erro

error openclaw@1.x.x: The engine "node" is incompatible
Required: >=22.0.0

ou

node: command not found

Por Que Acontece

O OpenClaw requer Node.js 22 ou superior. Muitos sistemas vêm com versões antigas ou sem Node instalado.

A Solução (2 minutos)

Instale o nvm (Node Version Manager):

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

IMPORTANTE: Feche e abra o terminal!

Instale Node.js 24:

nvm install 24
nvm use 24
nvm alias default 24

Verifique:

node --version
# Deve mostrar: v24.x.x

✅ Resultado: Node.js correto instalado e funcionando.

Diagnóstico Rápido: O Comando Mágico

Não sabe qual é o problema? Use o comando de diagnóstico:

openclaw doctor

Ele verifica:

• Versão do Node.js
• Configuração do gateway
• Conexões de canais
• Permissões de arquivos

Ainda Com Problemas?

Se nenhuma solução acima funcionou:

1. Verifique os logs:

   openclaw gateway logs -f
   

2. Pergunte na comunidade: Discord OpenClaw — resposta em minutos!

3. Consulte o guia completo: Troubleshooting Completo →

Conclusão

A maioria dos erros de instalação do OpenClaw se resolve em menos de 1 minuto:

Pronto para instalar? Volte ao guia de instalação →

Instalou com sucesso? Veja o que fazer depois →

Encontrou outro erro não listado aqui? Abra uma issue ou conte no Discord para adicionarmos ao guia!