Eu vi a OpenClaw fazer coisas estranhas. Travar sem mensagens de erro. Responder na língua errada sem razão. Recusar-se a reconhecer que um canal Slack perfeitamente configurado existe. Uma vez, começou a responder a cada mensagem com um haicai. Eu não pedi o modo haicai. Não há modo haicai.
Após oito meses e cerca de 400 momentos de “o que está acontecendo?”, compilei os 10 problemas que vi com mais frequência — com base na minha própria experiência e ajudando pessoas no Discord da comunidade. Esses não são problemas teóricos derivados de casos limites na documentação. São as coisas que realmente quebram em instalações reais.
1. Síndrome “Funcionava Ontem”
O problema mais comum com a OpenClaw não é um bug — é uma chave API que expirou, um modelo que foi depreciado ou um ponto de extremidade de serviço que mudou. Você não mudou nada, mas algo a montante fez.
Diagnóstico: Verifique primeiro a página de status do seu fornecedor de modelo. Em seguida, verifique a validade da sua chave API. Depois, 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 ponto de extremidade. E defina um lembrete no seu calendário para verificar esses itens todo mês, pois os fornecedores mudam coisas sem te enviar um e-mail.
2. A Fuga de Memória Que Aguenta Seu Servidor
Após alguns dias de execução, a OpenClaw fica lenta, depois mais lenta, e então trava. O uso de memória sobe regularmente até que o sistema operacional mate o processo.
Diagnóstico: É quase sempre um contexto de conversa que cresce sem limites. Cada mensagem se adiciona ao contexto, e se as mensagens antigas não forem podadas, o contexto acaba consumindo toda a memória disponível.
Solução: Configure a compressão de contexto. Defina um tamanho de contexto máximo. Ative a poda automática de mensagens antigas. Reinicie o serviço após aplicar a solução e monitorize o uso de memória por 24 horas para confirmar que se estabiliza.
3. O Bot do Slack/Discord Não Responde
Você configurou tudo, o bot aparece “online” no Slack/Discord, mas não responde a nenhuma mensagem.
Diagnóstico: Geralmente é um problema de autorização. O bot precisa de permissões específicas (ler mensagens, escrever mensagens, ler canais) e deve ser convidado em cada canal explicitamente. Outra causa comum: a URL do webhook não é acessível de fora.
Solução: Verifique as permissões do bot no console de desenvolvedor da plataforma. Verifique se o bot é membro do canal onde 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 ponto de extremidade é acessível).
4. As Tarefas Cron Funcionam, Mas Produzem Saída Vazia
Sua tarefa programada é executada na hora (você pode ver isso nos logs), mas a saída está vazia ou inconsistente.
Diagnóstico: O prompt provavelmente é muito vago ou faz referência a dados que o agente não tem acesso. “Resuma as métricas de hoje” falha se o agente não tem acesso ao banco de dados das métricas. O trabalho é executado, a IA não tem nada com que trabalhar, e ela produz coisas inutilizáveis.
Solução: Teste o prompt exato como uma tarefa manual primeiro. Certifique-se de que todas as fontes de dados são acessíveis. Inclua instruções explícitas sobre onde encontrar os dados.
5. As Respostas São Dolorosamente Lentas
Cada resposta leva de 15 a 30 segundos em vez dos 2 a 3 segundos esperados.
Diagnóstico: Três causas comuns. Primeiramente: seu contexto de conversa é muito grande (o modelo precisa processar milhares de tokens de histórico antes de gerar uma resposta). Em segundo lugar: a API do modelo é lenta (verifique o status do fornecedor). Em terceiro lugar: latência de rede entre seu servidor e o ponto de extremidade da API.
Solução : Para o tamanho do contexto: ative a compressão, limite o comprimento do histórico. Para a lentidão da API: aguarde, mude temporariamente de fornecedor ou use uma resposta em cache sempre que possível. Para a rede: considere hospedar mais perto da região do fornecedor da API.
6. Erros “Taxa Limitada”
Raios repentinos de erros 429, ou o bot se tornando silencioso durante períodos de alta utilização.
Diagnóstico : Você está ultrapassando o limite de taxa do seu fornecedor de API. Isso acontece quando vários usuários interagem simultaneamente ou quando um fluxo de trabalho desencadeia muitas chamadas de API em rápida sucessão.
Solução : Implemente uma fila de requisições com um planejador ciente dos limites de taxa. Atualize seu nível de API se o nível gratuito for muito restritivo. Para cenários de pico, adicione um atraso exponencial (aguarde e tente novamente com atrasos crescentes).
7. O Agente Diz Coisas Que Não Deveria
O agente revela detalhes sobre o prompt do sistema, responde de maneira inadequada ou se desvia do assunto de maneiras que parecem ser uma injeção de prompt.
Diagnóstico : Se o agente estiver exposto a uma entrada não confiável (canais públicos, mensagens de usuários), uma injeção de prompt é provável. Alguém criou uma entrada que substitui suas instruções do sistema.
Solução : Adicione um filtro de saída para padrões sensíveis (chaves de API, fragmentos de prompt do sistema). Implemente uma validação de entrada para padrões de injeção conhecidos. Para configurações de alta segurança, trate entradas não confiáveis em um contexto separado das instruções do sistema.
8. Falhas de Conexão ao Banco de Dados
O agente não consegue se conectar ao seu banco de dados, ou as conexões caem intermitentemente.
Diagnóstico : Esgotamento 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 de resolução DNS).
Solução : Verifique os parâmetros do pool de conexões e aumente-os 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 a partir do mesmo servidor).
9. Permissões do Sistema de Arquivos
O agente não consegue ler ou escrever arquivos, mesmo que os caminhos pareçam corretos.
Diagnóstico : O processo OpenClaw está sendo 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 tenta acessar.
Solução : Verifique sob qual usuário o OpenClaw está sendo executado. 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. As Atualizações Quebram Tudo
Você atualiza o OpenClaw e sua configuração cuidadosamente ajustada deixa de funcionar.
Diagnóstico : Mudanças no formato de configuração entre versões, funcionalidades depreciadas removidas ou conflitos de dependências. Este é o problema mais frustrante, pois você não alterou seu código — você apenas queria as últimas funcionalidades.
Solução : Leia o changelog antes de atualizar. Faça backup de sua configuração antes de atualizar. Teste a atualização em uma instância de desenvolvimento primeiro. Se algo quebrar, seu backup permite que você volte imediatamente. Nunca atualize a produção sem um backup verificado e um plano de reversão.
A Abordagem Universal de Depuração
Quando algo quebra e você não sabe por quê:
1. Verifique os logs (90% das respostas estão nos logs)
2. Verifique os serviços externos (status da API, conexão ao banco de dados, rede)
3. Verifique o que mudou (você atualizou algo? O fornecedor mudou algo?)
4. Reproduza o problema (você consegue acioná-lo de forma consistente?)
5. Pesquise no Discord da comunidade (alguém provavelmente já encontrou esse problema)
É quando tudo falha: reinicie o serviço e veja se o problema desaparece. Isso não deve ser o primeiro passo, mas é um recurso de último recurso válido. Às vezes, os computadores apenas fazem o que querem.
🕒 Published: