Solucao de Problemas

Deu problema? Calma! Siga os passos abaixo e a maioria dos problemas voce resolve sozinho.

🔍 Escada de diagnostico (siga a ordem)

Quando o OpenClaw apresentar algum problema, siga essa ordem de investigacao:

Verifique o status de execucao

openclaw status

Veja se o OpenClaw ainda esta rodando. Se aparecer "stopped" ou algum erro, tente reiniciar.

Verifique o status do gateway

openclaw gateway status

O gateway e a ponte que conecta o OpenClaw as plataformas de chat. Se o status do gateway estiver anormal, as mensagens nao vao funcionar.

Veja os logs

openclaw logs

Os logs registram todos os detalhes da execucao do OpenClaw. Se houver erros, geralmente os logs mostram mensagens em vermelho indicando o que deu errado.

Execute a verificacao de saude

openclaw doctor

Verificacao completa de saude que mostra quais componentes estao funcionando e quais tem problemas.

Verifique a conexao dos canais

openclaw channels status

Veja o status de conexao de cada canal de chat pra identificar se algum desconectou.

🐛 Erros comuns e como resolver

Erro: "openclaw: command not found"

Causa: O sistema nao encontra o comando openclaw, geralmente e um problema com a variavel de ambiente PATH.

Solucao:

# Verifique onde o openclaw esta instalado
npm list -g openclaw

# Adicione o diretorio global do npm ao PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Adicione o comando acima ao arquivo de configuracao do shell pra ficar permanente
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Erro: Conflito de porta (EADDRINUSE: address already in use :::18789)

Causa: A porta 18789 ja esta sendo usada por outro programa.

Solucao:

# Encontre o processo usando a porta
lsof -i :18789

# Pare o processo antigo do OpenClaw
openclaw stop

# Se nao for um processo do OpenClaw, voce pode trocar a porta na configuracao
# Edite ~/.openclaw/openclaw.json e mude o valor de port

Erro: 429 Too Many Requests (limite de taxa)

Causa: Voce esta mandando requisicoes rapido demais. O provedor do modelo de IA tem limites de frequencia pra chamadas de API.

Solucao:

Espere alguns minutos e tente de novo
Diminua a frequencia de envio de mensagens
Faca upgrade do seu plano de API pra ter limites mais altos
Considere trocar pra um provedor com limites mais flexiveis

Erro: Gateway nao inicia

Causa: Pode ser Bot Token invalido, problema de conexao de rede ou mudanca na API da plataforma de chat.

Solucao:

# Verifique os logs do gateway
openclaw gateway logs

# Confirme se o Bot Token e valido
openclaw channels verify

# Reinicie o gateway
openclaw gateway restart

Erro: Mensagens nao estao sendo enviadas

Causa: Pode ser configuracao errada do canal, problema de rede ou permissoes insuficientes do Bot.

Solucao:

Verifique o status dos canais: openclaw channels status
Confirme que o Bot tem permissao pra enviar mensagens na plataforma
Verifique se a conexao de rede esta funcionando
Procure mensagens de erro especificas nos logs

Erro: Painel de controle nao abre

Causa: O servico do OpenClaw pode nao estar rodando, ou a configuracao de porta esta errada.

Solucao:

# Confirme que o OpenClaw esta rodando
openclaw status

# Se nao estiver rodando, inicie
openclaw start

# Depois tente abrir o painel de controle
openclaw dashboard

# Ou acesse direto no navegador
# http://127.0.0.1:18789/

🆘 Nao conseguiu resolver?

Se os metodos acima nao resolveram seu problema, voce pode:

Buscar ou abrir uma issue no GitHub Issues
Entrar na comunidade do OpenClaw no Discord pra pedir ajuda
Ao perguntar, inclua a saida dos comandos openclaw doctor e openclaw logs