Blog

Como Corrigir Erros OpenClaw: 15 Problemas Comuns e Soluções

Ashley Innocent

Ashley Innocent

5 março 2026

Como Corrigir Erros OpenClaw: 15 Problemas Comuns e Soluções

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

TL;DR

A solução de problemas do OpenClaw abrange quedas de conexão, falhas de autenticação, erros de roteamento e problemas de desempenho. A maioria dos problemas decorre de instabilidade da rede, chaves de API incorretas ou canais mal configurados. Este guia fornece correções passo a passo para os 15 erros mais comuns do OpenClaw.

Problemas de Instalação e Configuração

Incompatibilidade da versão do Node.js

Problema: Comando openclaw não encontrado ou falha com "unsupported Node version" (versão do Node não suportada).

Causa: OpenClaw requer Node.js 22 ou posterior. Versões mais antigas não possuem os recursos necessários.

Correção:

Verifique sua versão do Node:

node --version

Se for inferior a 22, atualize o Node:

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

# Ou baixe de nodejs.org

Reinstale o OpenClaw:

npm install -g openclaw@latest

Verifique a instalação:

openclaw --version

Permissão negada durante a instalação

Problema: npm install -g openclaw falha com EACCES ou erros de permissão.

Causa: npm tenta gravar em diretórios do sistema sem as permissões adequadas.

Correção:

Não use sudo. Em vez disso, configure o npm para usar um diretório de usuário:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Adicione ao seu perfil de shell (~/.zshrc ou ~/.bashrc):

export PATH=~/.npm-global/bin:$PATH

Recarregue seu shell:

source ~/.zshrc

Instale o OpenClaw:

npm install -g openclaw@latest

Arquivo de configuração não encontrado

Problema: OpenClaw não consegue encontrar ~/.openclaw/config.json após a instalação.

Causa: O assistente de integração não foi executado ou falhou silenciosamente.

Correção:

Execute a integração manualmente:

openclaw onboard

Se isso falhar, crie o diretório de configuração:

mkdir -p ~/.openclaw

Crie um arquivo de configuração mínimo:

cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF

Execute a integração novamente:

openclaw onboard

Problemas de Conexão do Canal

Código QR do WhatsApp não escaneia

Problema: O código QR aparece, mas o aplicativo do WhatsApp diz "QR code inválido" ou não responde.

Causa: O código QR expirou ou há problemas de rede entre seu telefone e o OpenClaw.

Correção:

  1. Certifique-se de que seu telefone e computador estejam na mesma rede
  2. Regenere o código QR:
openclaw channels logout whatsapp
openclaw channels login whatsapp
  1. Escaneie dentro de 30 segundos (códigos QR expiram rapidamente)
  2. Se ainda falhar, verifique as configurações do firewall:
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node

# Linux (ufw)
sudo ufw allow 18789/tcp

WhatsApp desconecta após algumas horas

Problema: WhatsApp funciona inicialmente, mas desconecta após 2-4 horas.

Causa: O protocolo do WhatsApp requer "heartbeats" periódicos. Mudanças na rede ou o modo de suspensão interrompem a conexão.

Correção:

Habilite a reconexão automática:

openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300

Isso verifica a conexão a cada 5 minutos e reconecta se necessário.

Se você estiver em um laptop, evite que ele entre em suspensão enquanto o OpenClaw estiver em execução:

# macOS
caffeinate -i openclaw gateway

# Linux
systemd-inhibit --what=sleep openclaw gateway

Para produção, execute o OpenClaw em um servidor em vez de um laptop.

Bot do Telegram não recebe mensagens

Problema: O bot está online, mas não responde às mensagens.

Causa: O bot não possui as permissões necessárias ou o token é inválido.

Correção:

Teste o token do bot:

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

Se isso retornar um erro, regenere o token:

  1. Abra o Telegram e envie mensagem para @BotFather
  2. Envie /mybots
  3. Selecione seu bot
  4. Escolha "API Token" → "Regenerate Token"
  5. Atualize o OpenClaw:
openclaw channels update telegram --token NOVO_TOKEN

Para chats em grupo, adicione o bot como administrador com a permissão "Ler Mensagens".

Bot do Discord aparece offline

Problema: O bot aparece offline na lista de servidores do Discord.

Causa: "Message Content Intent" ausente ou token inválido.

Correção:

  1. Vá para o Portal do Desenvolvedor do Discord
  2. Selecione seu aplicativo
  3. Vá para a guia "Bot"
  4. Habilite "Message Content Intent" em Privileged Gateway Intents
  5. Salve as alterações
  6. Reinicie o OpenClaw:
openclaw gateway restart

Se o bot ainda estiver offline, verifique o token:

openclaw channels test discord

Se falhar, regenere o token no Portal do Desenvolvedor e atualize o OpenClaw.

Ponte iMessage não funciona (macOS)

Problema: O canal iMessage mostra "desconectado" ou não recebe mensagens.

Causa: Permissões de acessibilidade ausentes ou o aplicativo Mensagens não está em execução.

Correção:

  1. Abra as Configurações do Sistema → Privacidade e Segurança → Acessibilidade
  2. Adicione o Terminal (ou seu aplicativo de terminal) à lista permitida
  3. Reinicie o OpenClaw:
openclaw gateway restart
  1. Certifique-se de que o aplicativo Mensagens esteja em execução e logado
  2. Teste enviando uma mensagem para você mesmo

Se ainda não funcionar, verifique o processo da ponte:

ps aux | grep openclaw-imessage-bridge

Se não estiver em execução, inicie-o manualmente:

openclaw channels restart imessage

Erros de Autenticação e API

Chave de API inválida

Problema: Erros de "Authentication failed" (Autenticação falhou) ou "Invalid API key" (Chave de API inválida) nos logs.

Causa: Chave de API errada, chave expirada ou chave sem as permissões adequadas.

Correção:

Verifique sua chave de API:

# Para Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: SUA_CHAVE" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# Para OpenAI
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'

Se o comando curl falhar, sua chave é inválida. Obtenha uma nova no painel do seu provedor.

Atualize o OpenClaw:

openclaw config set --provider anthropic --api-key NOVA_CHAVE

Reinicie o Gateway:

openclaw gateway restart

Limite de taxa excedido

Problema: Erros "Rate limit exceeded" (Limite de taxa excedido) ou "Too many requests" (Muitas requisições).

Causa: Você está enviando muitas requisições ao seu provedor de IA.

Correção:

Verifique seu uso:

openclaw stats --period 1h

Habilite o controle de taxa (rate limiting):

openclaw limits set --max-requests 50 --window 3600

Isso limita você a 50 requisições por hora. Ajuste com base nos limites do seu provedor.

Para tráfego em rajada, habilite o enfileiramento (queuing):

openclaw config set --enable-queue true --queue-max-size 100

As mensagens são enfileiradas quando você atinge o limite de taxa e processadas quando a capacidade está disponível.

Modelo não encontrado

Problema: Erros "Model not found" (Modelo não encontrado) ou "Invalid model" (Modelo inválido).

Causa: Você especificou um modelo que não existe ou não está disponível para sua conta.

Correção:

Liste os modelos disponíveis:

# Anthropic
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: SUA_CHAVE"

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer SUA_CHAVE"

Atualize a configuração do seu agente:

openclaw agents update default --model claude-sonnet-4-6

Reinicie o Gateway:

openclaw gateway restart

Créditos insuficientes

Problema: Erros "Insufficient credits" (Créditos insuficientes) ou "Payment required" (Pagamento necessário).

Causa: Sua conta de provedor de IA ficou sem créditos ou atingiu os limites de faturamento.

Correção:

Verifique o saldo da sua conta no painel do seu provedor:

Adicione créditos ou atualize seu método de pagamento.

Enquanto espera, roteie para um modelo gratuito ou local:

openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback

Falhas no Roteamento de Mensagens

Mensagens vão para o agente errado

Problema: As mensagens são roteadas para o agente de IA errado, apesar das regras de roteamento.

Causa: As regras de roteamento entram em conflito ou têm prioridades incorretas.

Correção:

Liste todas as regras de roteamento:

openclaw routing list

Verifique conflitos. Regras com maior prioridade são correspondidas primeiro. Se você tiver:

Prioridade 5: canal=whatsapp → agente=default
Prioridade 10: remetente=+1234567890 → agente=vip

Mensagens de +1234567890 no WhatsApp vão para vip (prioridade 10 vence).

Remova regras conflitantes:

openclaw routing remove <id-da-regra>

Adicione regras com as prioridades corretas:

openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10

Teste o roteamento:

openclaw routing test --channel whatsapp --sender +1234567890 --message "teste"

Isso mostra qual agente manipularia a mensagem sem realmente enviá-la.

Roteamento por palavra-chave não funciona

Problema: Mensagens com palavras-chave específicas não são roteadas para o agente configurado.

Causa: As palavras-chave diferenciam maiúsculas de minúsculas ou a mensagem não contém a palavra-chave exata.

Correção:

Torne as palavras-chave insensíveis a maiúsculas e minúsculas:

openclaw routing add --keyword "debug" --agent debugging --case-insensitive

Use regex para correspondência flexível:

openclaw routing add --pattern "debug|error|bug" --agent debugging

Isso corresponde a "debug", "error" ou "bug" em qualquer lugar da mensagem.

Teste a correspondência de palavras-chave:

openclaw routing test --message "Encontrei um problema de debug"

Erros de função de roteamento personalizada

Problema: A função de roteamento personalizada lança erros ou não é executada.

Causa: Erros de sintaxe, dependências ausentes ou valores de retorno incorretos.

Correção:

Teste sua função de roteamento:

openclaw routing test-custom ~/.openclaw/routing.js --message "teste"

Isso executa sua função e mostra o resultado ou erro.

Problemas comuns:

  1. Erros de sintaxe: Verifique sua sintaxe JavaScript
  2. Retorno ausente: Sempre retorne um nome de agente
  3. Funções assíncronas: Não use async/await em funções de roteamento (elas devem ser síncronas)

Exemplo de função correta:

module.exports = function route(message) {
  // Sempre retorne uma string (nome do agente)
  if (message.channel === 'whatsapp') {
    return 'whatsapp-agent';
  }
  return 'default';
};

Exemplo de função incorreta:

// NÃO FAÇA ISSO
module.exports = async function route(message) {
  const result = await someAsyncOperation();
  return result; // Funções assíncronas não são suportadas
};

Agente de fallback não acionado

Problema: Quando o agente principal falha, as mensagens não são roteadas para o fallback.

Causa: Fallback não configurado ou agente principal não relata falhas corretamente.

Correção:

Configure o fallback:

openclaw routing set-fallback backup-agent

Teste o fallback:

# Desabilite temporariamente o agente principal
openclaw agents disable default

# Envie uma mensagem de teste
openclaw routing test --message "teste"

# Deve mostrar o agente de fallback

Reabilite o agente principal:

openclaw agents enable default

Problemas de Desempenho e Memória

Uso de memória alto

Problema: OpenClaw usa mais de 2GB de RAM e continua crescendo.

Causa: Dados da sessão acumulam ao longo do tempo sem limpeza.

Correção:

Verifique o uso de memória:

openclaw stats --memory

Limpe sessões antigas:

openclaw sessions clear --older-than 7d

Reduza o tempo limite da sessão:

openclaw config set --session-timeout 1800

As sessões agora expiram após 30 minutos de inatividade em vez do padrão de 1 hora.

Habilite a limpeza automática:

openclaw config set --auto-cleanup true --cleanup-interval 3600

Isso executa a limpeza a cada hora.

Tempos de resposta lentos

Problema: Respostas da IA levam mais de 30 segundos ou atingem o tempo limite.

Causa: Latência de rede, provedor de IA lento ou backlog de fila.

Correção:

Verifique o status da fila:

openclaw queue status

Se a fila tiver mais de 50 mensagens, aumente a simultaneidade:

openclaw config set --max-concurrent-requests 10

Isso processa 10 mensagens simultaneamente em vez do padrão de 3.

Verifique a latência da rede para o seu provedor de IA:

# Anthropic
ping api.anthropic.com

# OpenAI
ping api.openai.com

Se a latência for alta (>200ms), considere usar um provedor diferente ou um modelo local.

Habilite o tempo limite da requisição:

openclaw config set --request-timeout 30000

Requisições que demoram mais de 30 segundos falham e são retentadas.

Gateway fica sem resposta

Problema: O Gateway para de responder a mensagens ou chamadas de API.

Causa: Deadlock, loop infinito ou exaustão de recursos.

Correção:

Verifique o status do Gateway:

openclaw gateway status

Se estiver travado, obtenha um thread dump:

kill -SIGUSR1 $(pgrep -f "openclaw gateway")

Isso escreve um thread dump em ~/.openclaw/gateway.log. Procure por operações travadas.

Reinicie o Gateway:

openclaw gateway restart

Habilite verificações de saúde:

openclaw config set --health-check-interval 60

O Gateway agora verifica sua própria saúde a cada 60 segundos e reinicia se não responder.

Picos de uso da CPU

Problema: OpenClaw usa 100% da CPU constantemente.

Causa: Loop infinito, log excessivo ou inundação de mensagens.

Correção:

Verifique o que está consumindo CPU:

top -p $(pgrep -f "openclaw gateway")

Reduza o nível de log:

openclaw config set --log-level warn

Isso desabilita os logs de depuração e informação, reduzindo I/O.

Verifique se há inundações de mensagens:

openclaw stats --messages --period 1h

Se você estiver recebendo mais de 1000 mensagens por hora, habilite o controle de taxa por canal:

openclaw channels config whatsapp --rate-limit 100 --rate-window 3600

Falhas e Reinícios do Gateway

Gateway falha na inicialização

Problema: openclaw gateway falha imediatamente sem mensagem de erro.

Causa: Arquivo de configuração corrompido ou dependências ausentes.

Correção:

Execute em modo de depuração:

openclaw gateway --debug

Isso mostra mensagens de erro detalhadas.

Causas comuns:

  1. Configuração corrompida: Faça backup e redefina a configuração
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard
  1. Dependências ausentes: Reinstale o OpenClaw
npm uninstall -g openclaw
npm install -g openclaw@latest
  1. Porta já em uso: Mude a porta
openclaw gateway --port 18790

Gateway falha durante a operação

Problema: O Gateway funciona por um tempo e depois falha inesperadamente.

Causa: Exceção não tratada, vazamento de memória ou processo externo o encerrando.

Correção:

Verifique os logs de falha:

tail -100 ~/.openclaw/gateway.log

Procure por stack traces ou mensagens de erro antes da falha.

Habilite despejos de falha (crash dumps):

openclaw config set --enable-crash-dumps true

A próxima falha gravará um dump em ~/.openclaw/crashes/. Compartilhe isso com a equipe do OpenClaw para depuração.

Execute o Gateway com reinício automático:

openclaw gateway --auto-restart

O Gateway reinicia automaticamente após falhas.

Para produção, use um gerenciador de processos:

# Usando pm2
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup

Dados da sessão perdidos após o reinício

Problema: As conversas são redefinidas após o reinício do Gateway.

Causa: Sessões não persistidas em disco ou arquivo de sessão corrompido.

Correção:

Habilite a persistência de sessão:

openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db

As sessões agora são salvas em disco a cada 30 segundos.

Verifique o arquivo de sessão:

ls -lh ~/.openclaw/sessions.db

Se estiver com 0 bytes ou faltando, as sessões não estão sendo salvas. Verifique o espaço em disco:

df -h ~

Se o disco estiver cheio, libere espaço e reinicie o Gateway.

Restaure a partir do backup:

cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart

Problemas Específicos da Plataforma

macOS: "openclaw" não pode ser aberto

Problema: macOS bloqueia o OpenClaw com o aviso "desenvolvedor não identificado".

Causa: Recurso de segurança Gatekeeper do macOS.

Correção:

Permitir OpenClaw:

xattr -d com.apple.quarantine $(which openclaw)

Ou vá para Configurações do Sistema → Privacidade e Segurança e clique em "Permitir Mesmo Assim" ao lado do aviso do OpenClaw.

Linux: Permissão negada para inotify

Problema: "ENOSPC: Limite do sistema para número de observadores de arquivo atingido."

Causa: Linux limita o número de arquivos que um processo pode observar.

Correção:

Aumente o limite:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Reinicie o OpenClaw:

openclaw gateway restart

Windows: Comando não encontrado

Problema: Comando openclaw não reconhecido no Windows.

Causa: O diretório global bin do npm não está no PATH.

Correção:

Encontre o diretório global do npm:

npm config get prefix

Adicione-o ao PATH:

  1. Abra Propriedades do Sistema → Variáveis de Ambiente
  2. Edite "Path" em Variáveis de usuário
  3. Adicione C:\Users\SeuNome\AppData\Roaming\npm (ou o caminho obtido acima)
  4. Clique em OK e reinicie seu terminal

Verifique:

openclaw --version

Docker: Problemas de rede

Problema: OpenClaw no Docker não consegue conectar-se a plataformas de mensagens.

Causa: Isolamento de rede do Docker.

Correção:

Execute com a rede do host:

docker run --network host openclaw/openclaw gateway

Ou exponha a porta do Gateway:

docker run -p 18789:18789 openclaw/openclaw gateway

Para WhatsApp, você precisa expor portas adicionais para o escaneamento do código QR:

docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway

Ferramentas de Depuração e Logs

Habilitar log de depuração

Obtenha logs detalhados:

openclaw config set --log-level debug
openclaw gateway restart

Os logs vão para ~/.openclaw/gateway.log por padrão.

Observe os logs em tempo real:

tail -f ~/.openclaw/gateway.log

Teste componentes individuais

Teste canais:

openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord

Teste agentes:

openclaw agents test default --message "Olá"

Teste roteamento:

openclaw routing test --channel whatsapp --sender +1234567890 --message "problema de depuração"

Inspecione o estado do Gateway

Obtenha o estado atual:

openclaw gateway inspect

Isso mostra:

Exportar diagnósticos

Gere um relatório de diagnóstico:

openclaw diagnostics export > openclaw-diagnostics.json

Isso inclui:

Compartilhe isso com o suporte ao relatar problemas.

Depuração de rede

Teste a conectividade com provedores de IA:

openclaw network test anthropic
openclaw network test openai

Isso verifica:

Se alguma verificação falhar, você tem um problema de rede.

FAQ

Por que o OpenClaw usa tanta memória?

O OpenClaw mantém o histórico de sessões na memória para acesso rápido. Cada sessão armazena o contexto completo da conversa. Se você tiver 100 sessões ativas com 50 mensagens cada, isso representa 5000 mensagens na memória.

Reduza o uso de memória:

  1. Diminua o tempo limite da sessão
  2. Habilite a limpeza automática
  3. Limite o comprimento do contexto por sessão
openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50

Posso executar o OpenClaw sem internet?

Sim, se você usar um modelo de IA local. Instale o Ollama e configure o OpenClaw para usá-lo:

# Instale o Ollama
curl https://ollama.ai/install.sh | sh

# Baixe um modelo
ollama pull llama2

# Configure o OpenClaw
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434

As plataformas de mensagens ainda precisam de internet, mas a inferência de IA é executada localmente.

Como faço para migrar para uma nova máquina?

Exporte sua configuração:

openclaw config export > openclaw-backup.json

Copie openclaw-backup.json para a nova máquina.

Instale o OpenClaw:

npm install -g openclaw@latest

Importe a configuração:

openclaw config import openclaw-backup.json

Reconecte os canais (códigos QR e tokens não são transferidos):

openclaw channels login whatsapp
openclaw channels update telegram --token SEU_TOKEN

Por que as mensagens chegam fora de ordem?

O OpenClaw processa mensagens concorrentemente. Se você enviar 3 mensagens rapidamente, elas podem chegar ao provedor de IA em ordens diferentes, dependendo do tempo da rede.

Habilite o processamento sequencial:

openclaw config set --max-concurrent-requests 1

Isso processa uma mensagem por vez, preservando a ordem. É mais lento, mas garante a sequência.

Posso usar o OpenClaw para produção?

Sim, mas siga estas diretrizes:

  1. Execute em um servidor, não em um laptop
  2. Use um gerenciador de processos (pm2, systemd)
  3. Habilite a persistência de sessão
  4. Configure monitoramento e alertas
  5. Configure limites de taxa
  6. Use um proxy reverso (nginx) para a UI de controle
  7. Habilite HTTPS
  8. Faça backup da configuração regularmente

Exemplo de serviço systemd:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Como faço para relatar bugs?

  1. Gere diagnósticos:
openclaw diagnostics export > diagnostics.json
  1. Abra uma issue no GitHub
  2. Inclua:

Conclusão

A maioria dos problemas do OpenClaw decorre de problemas de rede, configuração incorreta ou peculiaridades específicas da plataforma. Este guia aborda os 15 erros mais comuns e suas correções.

Principais passos para solução de problemas:

  1. Verifique os logs primeiro (~/.openclaw/gateway.log)
  2. Teste os componentes individualmente (canais, agentes, roteamento)
  3. Habilite o modo de depuração para erros detalhados
  4. Use ferramentas de diagnóstico para exportar o estado
  5. Junte-se à comunidade para obter ajuda

Se você estiver construindo fluxos de trabalho de API junto com o OpenClaw, confira o Apidog para design, teste e documentação de API. Ele complementa a interface conversacional do OpenClaw com gerenciamento de API estruturado.

botão

Próximos passos:

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar
Como Corrigir Erros OpenClaw: 15 Problemas Comuns e Soluções