Eu vi o OpenClaw fazer coisas estranhas. Travar sem mensagens de erro. Responder na língua errada sem razão. Recusar-se a reconhecer que um canal do Slack perfeitamente configurado existe. Uma vez, começou a responder a cada mensagem com um haiku. Eu não pedi o modo haiku. Não existe modo haiku.
Após oito meses e aproximadamente 400 momentos de “que diabos?”, compilei os 10 problemas que vi com mais frequência — da minha própria experiência e de ajudar pessoas na comunidade do Discord. Estes não são problemas teóricos de casos extremos da documentação. Estas são as coisas que realmente quebram em instalações reais.
1. Síndrome do “Funcionava Ontem”
O problema mais comum do OpenClaw não é um bug — é uma chave de API que expirou, um modelo que foi descontinuado ou um endpoint de serviço que mudou. Você não mudou nada, mas algo a montante fez isso.
Diagnóstico: Verifique a página de status do seu provedor de modelos primeiro. Depois verifique a validade da sua chave de API. Então verifique se o nome do modelo na sua configuração ainda existe. Nove vezes em dez, o problema é externo.
Solução: Atualize a chave, o nome do modelo ou o endpoint. E defina um lembrete no calendário para verificar esses itens mensalmente, porque os provedores mudam as coisas sem te enviar um e-mail.
2. O Vazamento de Memória Que Come o Seu Servidor
Depois de funcionar por alguns dias, o OpenClaw fica lento, depois mais lento, até travar. O uso de memória sobe constantemente até que o sistema operacional mate o processo.
Diagnóstico: Quase sempre se trata de um contexto de conversa que está crescendo sem limites. Cada mensagem adiciona ao contexto, e se mensagens antigas não forem podadas, o contexto eventualmente consome toda a memória disponível.
Solução: Configure a compactação de contexto. Defina um tamanho máximo de contexto. Habilite a poda automática de mensagens antigas. Reinicie o serviço após a solução e monitore o uso de memória por 24 horas para confirmar que estabilizou.
3. Bot do Slack/Discord Não Respondendo
Você configurou tudo, o bot mostra “online” no Slack/Discord, mas não responde a nenhuma mensagem.
Diagnóstico: Geralmente um problema de permissões. O bot precisa de permissões específicas (ler mensagens, escrever mensagens, ler canais) e precisa ser convidado a cada canal explicitamente. Outra causa comum: a URL do webhook não é acessível externamente.
Solução: Verifique as permissões do bot no console do desenvolvedor da plataforma. Verifique se o bot é membro do canal em que você está testando. Teste a URL do webhook a partir de uma fonte externa (use um serviço como httpbin ou requestbin para verificar se seu endpoint é acessível).
4. Tarefas Cron Executando, Mas Produzindo Saída Vazia
Sua tarefa agendada roda no horário (você pode vê-la nos logs), mas a saída é vazia ou sem sentido.
Diagnóstico: O prompt provavelmente é muito vago ou referencia dados que o agente não pode acessar. “Resuma as métricas de hoje” falha se o agente não tem acesso ao banco de dados de métricas. A tarefa é executada, a IA não tem nada para trabalhar e produz lixo.
Solução: Teste o prompt exato como uma tarefa manual primeiro. Certifique-se de que todas as fontes de dados sejam acessíveis. Inclua instruções explícitas sobre onde encontrar os dados.
5. Respostas São Doravante Lentas
Cada resposta leva de 15 a 30 segundos em vez dos esperados 2 a 3 segundos.
Diagnóstico: Três causas comuns. Primeiro: seu contexto de conversa é muito grande (o modelo tem que processar milhares de tokens de histórico antes de gerar uma resposta). Segundo: a API do modelo é lenta (verifique o status do provedor). Terceiro: latência de rede entre seu servidor e o endpoint da API.
Solução: Para o tamanho do contexto: habilite a compactação, limite o comprimento do histórico. Para lentidão da API: aguarde, mude temporariamente de provedor ou use uma resposta em cache quando possível. Para rede: considere hospedar mais próximo da região do provedor da API.
6. Erros de “Limite de Taxa”
Explosões súbitas de erros 429, ou o bot ficando em silêncio durante o pico de uso.
Diagnóstico: Você está excedendo o limite de taxa do seu provedor de API. Isso acontece quando vários usuários interagem simultaneamente ou quando um fluxo de trabalho aciona muitas chamadas de API em rápida sucessão.
Solução: Implemente enfileiramento de solicitações com agendamento ciente do limite de taxa. Faça upgrade no seu nível de API se o nível gratuito for muito restritivo. Para cenários de picos, adicione um backoff exponencial (aguarde e tente novamente com atrasos crescentes).
7. O Agente Diz Coisas Que Não Deveria
O agente revela detalhes do prompt do sistema, responde de forma inadequada ou se desvia do assunto de maneiras que parecem injeção de prompt.
Diagnóstico: Se o agente estiver exposto a entradas não confiáveis (canais públicos, mensagens de usuários), a injeção de prompt é provável. Alguém elaborou uma entrada que substitui suas instruções de sistema.
Correção: Adicione filtragem de saída para padrões sensíveis (chaves de API, fragmentos de prompts do sistema). Implemente validação de entrada para padrões de injeção conhecidos. Para configurações de alta segurança, processe entradas não confiáveis em um contexto separado das instruções do sistema.
8. Falhas de Conexão com o Banco de Dados
O agente não consegue se conectar ao seu banco de dados, ou as conexões caem intermitentemente.
Diagnóstico: Exaustão do pool de conexões (muitas conexões abertas), problemas de autenticação (senha alterada, certificado SSL expirado) ou problemas de rede (firewall bloqueando, falha na resolução de DNS).
Correção: Verifique as configurações do pool de conexões e aumente, se necessário. Verifique as credenciais. Teste a conexão de forma independente (use um cliente de banco de dados para confirmar que você pode se conectar com as mesmas credenciais do mesmo servidor).
9. Permissões do Sistema de Arquivos
O agente não consegue ler ou gravar arquivos, embora os caminhos pareçam corretos.
Diagnóstico: O processo OpenClaw é executado sob uma conta de usuário específica. Essa conta de usuário precisa de permissões de leitura/gravação nos diretórios que o agente está tentando acessar.
Correção: Verifique qual usuário o OpenClaw está executando. Verifique se esse usuário tem as permissões apropriadas nos diretórios-alvo. No Linux: ls -la para verificar, chown ou chmod para corrigir. Não use permissões 777 — forneça o mínimo de acesso necessário.
10. Atualizações Quebram Tudo
Você atualiza o OpenClaw e sua configuração cuidadosamente ajustada para de funcionar.
Diagnóstico: Mudanças no formato de configuração entre versões, recursos obsoletos removidos ou conflitos de dependências. Este é o problema mais frustrante porque você não alterou seu código — você apenas queria os recursos mais recentes.
Correção: Leia o changelog antes de atualizar. Faça backup da sua configuração antes de atualizar. Teste a atualização primeiro em uma instância de desenvolvimento. Se algo quebrar, seu backup permite que você reverta imediatamente. Nunca atualize a produção sem um backup verificado e um plano de reversão.
A Abordagem Universal de Depuração
Quando algo quebrar e você não souber o porquê:
1. Verifique os logs (90% das respostas estão nos logs)
2. Verifique serviços externos (status da API, conexão com o banco de dados, rede)
3. Verifique o que mudou (você atualizou algo? O provedor mudou algo?)
4. Reproduza o problema (você pode acioná-lo consistentemente?)
5. Pesquise no Discord da comunidade (provavelmente alguém mais já encontrou isso)
E quando tudo mais falhar: reinicie o serviço e veja se o problema desaparece. Isso não deve ser o primeiro passo, mas é um último recurso válido. Às vezes, os computadores são apenas computadores.
🕒 Published: