Solução de problemas do gateway do OpenClaw

Quando a página de triagem rápida não basta, a documentação manda você para o runbook aprofundado do gateway. Ele é um índice, e não um paredão de correções: uma escada de comandos, os sinais que um gateway saudável mostra e seis páginas por área de sintoma com âncoras estáveis. A seção mais útil dele é a lista curta do que quebra logo depois de uma atualização. Aqui está o mapa.

A escada e as seis páginas

• Execute, nessa ordem, os comandos status, gateway status, acompanhamento de logs, doctor e sonda de canais; saudável significa que gateway status mostra um runtime em execução, uma sonda de conectividade ok e uma linha de capacidade, que doctor não relata nenhum problema bloqueante de configuração ou de serviço e que a sonda mostra o status de transporte ao vivo por conta, com um marcador works ou audit ok onde houver suporte.
• Atualizações e rollbacks cobre um gateway que ficou fora do ar ou incompatível depois de uma atualização, um downgrade ou uma instalação split-brain: após uma atualização, o timeout de publicação do runtime de modelo preparado, a proteção contra configuração mais nova, a correção do caminho de busca, a reinstalação do serviço, a remoção de wrappers obsoletos e uma incompatibilidade de protocolo após o rollback. Skills e provedores de modelo cobre uma raiz de skill ignorada, o erro de limite de taxa para contexto longo com as correções de janela padrão, credencial elegível e modelo de fallback, respostas bloqueadas no upstream e um backend local compatível com OpenAI que passa nas sondas, mas falha nas execuções do agente.
• Respostas do agente e interface de controle cobre uma execução que falha com erro de armazenamento, nenhuma resposta chegando, a conectividade do painel, as assinaturas de erro de conexão e de autenticação, com um mapa rápido dos códigos de detalhe de autenticação e as etapas de desafio de conexão, assinatura do payload e nonce do dispositivo. Serviço e processo do gateway cobre um serviço que não roda ou não se mantém no ar, um gateway no macOS que para silenciosamente até que o painel seja acessado, um loop do supervisor com launch agents duplicados e uma saída sob alto uso de memória.
• Validação de configuração e sondas cobre uma configuração inválida rejeitada, o que aconteceu, inspeção e reparo, as assinaturas de erro comuns e as opções de correção, e os avisos da sonda do gateway. Entrega nos canais e ferramentas cobre um canal conectado sem mensagens circulando, a entrega agendada e de heartbeat, um nó pareado cuja ferramenta falha, falhas da ferramenta de navegador, assinaturas de plugin e de executável, assinaturas de sessão do navegador e assinaturas de elemento, captura de tela e upload; toda âncora antiga da página única ainda leva ao novo lugar.

A maior parte das quebras após uma atualização é desvio de configuração ou padrões mais rígidos que agora passaram a ser aplicados.

Se você atualizou e algo quebrou

O índice mantém três verificações na própria página. Primeiro, o comportamento de autenticação e de substituição de URL: leia o modo do gateway, a URL remota e o modo de autenticação, porque, com o modo definido como remote, a linha de comando pode estar apontando para um gateway remoto enquanto o serviço local está bem, e chamadas com URL explícita não recorrem às credenciais armazenadas; uma assinatura connect-failed significa o destino de URL errado, e uma assinatura unauthorized significa que o endpoint está acessível, mas com a autenticação errada. Segundo, as proteções de bind e de autenticação estão mais rígidas: binds fora do loopback precisam de um caminho de autenticação válido, seja um token ou uma senha compartilhados, seja um proxy confiável fora do loopback configurado corretamente, e a chave de token antiga não substitui a chave de token de autenticação atual; a recusa em fazer o bind sem autenticação e uma sonda de conectividade que falha com o runtime em execução são as assinaturas. Terceiro, o estado de pareamento e de identidade do dispositivo: liste os dispositivos e os pareamentos de canal e procure aprovações de dispositivo pendentes para o painel ou para os nós, e aprovações pendentes após uma mudança de política ou de identidade; device identity required e pairing required são as assinaturas. Se a configuração do serviço e o runtime ainda divergirem, reinstale os metadados do serviço a partir do mesmo perfil e do mesmo diretório de estado e reinicie.

Lendo os sinais

• Um runtime em execução com uma sonda de conectividade que falha é a combinação mais reveladora: o processo está vivo, mas a linha de comando não consegue alcançá-lo com a URL e a autenticação atuais, então a correção está no modo, na URL ou no token, e não no serviço.
• Uma assinatura device identity required depois de uma atualização não é um bug no cliente; a autenticação de dispositivo agora é obrigatória, e o painel ou o nó precisa da aprovação pendente dele, que as listas de dispositivos e de pareamento mostram.
• A sonda é por conta: um canal com duas contas pode mostrar um transporte funcionando e outro falhando, o que a linha de status sozinha não revela.

A solução de problemas de canais do OpenClaw é o guia complementar, no nível dos canais, para o caso em que o transporte conecta, mas o comportamento está errado, e o guia do OpenClaw doctor explica o comando de reparo em que a escada se apoia.

Por que um índice

Dividir o runbook por área de sintoma mantém cada página curta o bastante para ser lida enquanto algo está fora do ar, e as âncoras preservadas fazem com que links de threads e issues antigas ainda caiam na seção certa. A ordem da escada também é deliberada: ela vai do sinal mais amplo ao mais estreito, e doctor vem antes da sonda porque corrige as configurações erradas que a sonda, de outra forma, relataria como falhas. O pareamento do OpenClaw cobre as aprovações que a terceira verificação procura, e a configuração do OpenClaw, as chaves que as duas primeiras verificações leem.

Na Diali

Na Diali, a configuração do runtime é gerada a partir do painel e substituída a cada versão, o que elimina a maior parte do desvio que a seção pós-atualização descreve, e a mesma escada roda no runtime hospedado. O OpenClaw hospedado na Diali descreve o assistente hospedado, e a página de segurança da Diali, a fronteira em torno dele.

• Cinco comandos em ordem; runtime em execução mais sonda ok significa saudável.
• Seis páginas de sintomas; toda âncora antiga ainda leva ao lugar certo.
• Após uma atualização: modo e URL, bind e autenticação, estado de pareamento.