Solução de problemas15 min de leitura

Erros Comuns do OpenClaw e Como Corrigi-los

Guia completo para diagnosticar e corrigir erros comuns do OpenClaw, incluindo problemas de instalacao, erros de API, problemas de canal e problemas de desempenho.

OpenClaw Guides

Tutorial Authors

2025-02-04

Diagnostico Rapido

Antes de mergulhar em erros especificos, execute estes diagnosticos:

bash

# Verificar status geral
openclaw status

# Verificar configuracao
openclaw config validate

# Verificar logs para erros recentes
openclaw logs --tail 50 --level error

# Executar verificacao de saude
openclaw doctor

Erros de Instalacao

Erro: "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

Solucao:

bash

# Usando nvm (recomendado)
nvm install 22
nvm use 22
nvm alias default 22

# Ou usando Homebrew (macOS)
brew install node@22

# Verificar
node --version  # Deve mostrar v22.x.x

Erro: "EACCES permission denied"

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

Solucao: Nao use sudo. Em vez disso, corrija as permissoes do npm:

bash

# Opcao 1: Usar nvm (recomendado)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Opcao 2: Mudar o diretorio padrao do npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Entao reinstale
npm install -g openclaw@latest

Erro: "Cannot find module"

Error: Cannot find module '@openclaw/core'

Solucao:

bash

# Limpar cache do npm e reinstalar
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# Ou usar o script de instalacao
curl -fsSL https://openclaw.ai/install.sh | bash

Erro: "gyp ERR! build error" (Modulos nativos)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Solucao: Instale as ferramentas de build:

bash

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

Erros de API e Autenticacao

Erro: "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

Solucao:

bash

# Verificar se sua chave de API esta configurada
openclaw config get api-key

# Se vazia ou errada, configure novamente
openclaw config set api-key

# Verifique o formato da chave (chaves da Anthropic comecam com sk-ant-)
# Certifique-se de que nao ha espacos extras ou aspas

Erro: "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

Solucao:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

Para limitacao de taxa persistente, considere atualizar seu nivel de API ou usar um modelo diferente:

bash

openclaw config set default-model claude-3-5-haiku

Erro: "402 Payment Required"

Error: API request failed: Insufficient credits

Solucao:

Verifique o saldo do seu provedor de API
Adicione creditos a sua conta
Ou configure limites de uso:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

Erro: "Connection Refused" para API

Error: connect ECONNREFUSED api.anthropic.com:443

Solucao:

bash

# Verificar conexao com a internet
ping api.anthropic.com

# Verificar se esta atras de um proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Configurar proxy se necessario
openclaw config set proxy http://seu-proxy:8080

# Ou verificar configuracoes de firewall/VPN

Erros de Gateway

Erro: "EADDRINUSE: Port already in use"

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

Solucao:

bash

# Descobrir o que esta usando a porta
lsof -i :18789

# Encerrar o processo
kill -9 <PID>

# Ou usar uma porta diferente
openclaw gateway start --port 18790

# Atualizar config para usar nova porta
openclaw config set gateway-port 18790

Erro: "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

Solucao:

bash

# Validar sintaxe do arquivo de configuracao
openclaw config validate

# Se corrompido, redefinir para padroes
openclaw config reset --confirm

# Entao reconfigure
openclaw onboard

Erro: "Gateway not responding"

bash

# Verificar se o gateway esta rodando
openclaw status

# Se parado, verificar o motivo
openclaw logs --tail 100

# Tentar reiniciar
openclaw gateway restart

# Se ainda estiver falhando, verificar recursos do sistema
free -h  # Memoria
df -h    # Espaco em disco

Erros Especificos de Canal

WhatsApp: "Session expired"

Error: WhatsApp session invalid or expired

Solucao:

bash

# Re-autenticar
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# Escaneie o novo codigo QR

WhatsApp: "QR code not generating"

bash

# Verificar se outra sessao esta ativa
pkill -f "openclaw.*whatsapp"

# Limpar dados de sessao antigos
rm -rf ~/.openclaw/whatsapp-session

# Tentar novamente
openclaw channel connect whatsapp

Telegram: "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

Outra instancia esta usando o mesmo token do bot.

Solucao:

bash

# Parar todas as instancias do OpenClaw
pkill -f openclaw

# Verificar outras instancias em execucao
ps aux | grep openclaw

# Iniciar do zero
openclaw gateway start

Discord: "Invalid token"

Error: An invalid token was provided

Solucao:

bash

# Regenerar token no Portal de Desenvolvedores do Discord
# Bot → Reset Token

# Atualizar OpenClaw
openclaw config set discord-token NOVO_TOKEN
openclaw gateway restart

Discord: "Missing intents"

Error: Disallowed intents specified

Solucao:

Va ao Portal de Desenvolvedores do Discord
Selecione sua aplicacao → Bot
Ative as intents necessarias em "Privileged Gateway Intents"
Salve e reinicie o OpenClaw

Erros de Memoria e Desempenho

Erro: "JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solucao:

bash

# Aumentar limite de memoria do Node.js
export NODE_OPTIONS="--max-old-space-size=4096"

# Adicionar ao seu perfil de shell para persistencia
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# Reiniciar OpenClaw
openclaw gateway restart

Erro: "Too many open files"

Error: EMFILE: too many open files

Solucao:

bash

# Verificar limite atual
ulimit -n

# Aumentar limite (temporario)
ulimit -n 65535

# Aumentar limite (permanente - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

Tempos de Resposta Lentos

Diagnosticar:

bash

# Verificar latencia do modelo
openclaw benchmark

# Verificar recursos do sistema
openclaw stats

Solucao:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

Erros de Configuracao

Erro: "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

Solucao:

bash

# Validar YAML
openclaw config validate

# Problemas comuns:
# - Tabs em vez de espacos (use 2 espacos)
# - Dois-pontos faltando apos chaves
# - Caracteres especiais sem aspas

# Corrigir ou redefinir
openclaw config edit
# ou
openclaw config reset --confirm

Erro: "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

Solucao:

bash

# Verificar opcoes disponiveis
openclaw config list

# Remover chaves desconhecidas
openclaw config edit

Erro: "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

Solucao:

bash

# Adicionar ao arquivo .env
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# Ou exportar no shell
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Adicionar ao perfil do shell para persistencia
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

Erros de Banco de Dados e Armazenamento

Erro: "Database locked"

Error: SQLITE_BUSY: database is locked

Solucao:

bash

# Parar OpenClaw
openclaw gateway stop

# Verificar arquivos de bloqueio
ls -la ~/.openclaw/*.lock

# Remover bloqueios obsoletos
rm ~/.openclaw/*.lock

# Reiniciar
openclaw gateway start

Erro: "Disk quota exceeded"

Error: ENOSPC: no space left on device

Solucao:

bash

# Verificar uso de disco
df -h

# Limpar logs e cache do OpenClaw
openclaw cache clear
openclaw logs clear --older-than 7d

# Limpar sessoes antigas
rm -rf ~/.openclaw/sessions/*.old

Obtendo Mais Ajuda

Ativar Log de Debug

bash

# Definir modo debug
export OPENCLAW_DEBUG=true
openclaw gateway start

# Ou na configuracao
openclaw config set logLevel debug

Gerar Relatorio de Diagnostico

bash

openclaw doctor --report > relatorio-diagnostico.txt

Suporte da Comunidade

Discord: discord.gg/openclaw
GitHub Issues: github.com/openclaw/openclaw/issues
Documentacao: docs.openclaw.ai

Reportando um Bug

Ao reportar problemas, inclua:

bash

# Informacoes do sistema
openclaw --version
node --version
uname -a

# Configuracao (oculte dados sensiveis)
openclaw config show --redact

# Logs recentes
openclaw logs --tail 100

Diagnostico Rapido

Erros de Instalacao

Erro: "Node.js version too old"

Erro: "EACCES permission denied"

Erro: "Cannot find module"

Erro: "gyp ERR! build error" (Modulos nativos)

Erros de API e Autenticacao

Erro: "401 Unauthorized"

Erro: "429 Rate Limited"

Erro: "402 Payment Required"

Erro: "Connection Refused" para API

Erros de Gateway

Erro: "EADDRINUSE: Port already in use"

Erro: "Gateway failed to start"

Erro: "Gateway not responding"

Erros Especificos de Canal

WhatsApp: "Session expired"

WhatsApp: "QR code not generating"

Telegram: "Conflict: terminated by other getUpdates"

Discord: "Invalid token"

Discord: "Missing intents"

Erros de Memoria e Desempenho

Erro: "JavaScript heap out of memory"

Erro: "Too many open files"

Tempos de Resposta Lentos

Erros de Configuracao

Erro: "Invalid YAML syntax"

Erro: "Unknown configuration key"

Erro: "Environment variable not set"

Erros de Banco de Dados e Armazenamento

Erro: "Database locked"

Erro: "Disk quota exceeded"

Obtendo Mais Ajuda

Ativar Log de Debug

Gerar Relatorio de Diagnostico

Suporte da Comunidade

Reportando um Bug

Proximos Passos