Saltar para o conteúdo principal

​
Solução de problemas do Gateway

Esta página é o runbook aprofundado. Comece em /help/troubleshooting se você quiser primeiro o fluxo rápido de triagem.

​
Escada de comandos

Execute estes primeiro, nesta ordem: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Sinais esperados de funcionamento saudável:
  • openclaw gateway status mostra Runtime: running e RPC probe: ok.
  • openclaw doctor relata nenhum problema de configuração/serviço bloqueante.
  • openclaw channels status --probe mostra canais conectados/prontos.

​
Sem respostas

Se os canais estiverem ativos, mas nada responder, verifique o roteamento e a política antes de reconectar qualquer coisa. 
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow
Procure por:
  • Pareamento pendente para remetentes de DM.
  • Restrição por menção em grupo (requireMention, mentionPatterns).
  • Incompatibilidades na lista de permissões de canal/grupo.
Assinaturas comuns:
  • drop guild message (mention required → mensagem de grupo ignorada até menção.
  • pairing request → o remetente precisa de aprovação.
  • blocked / allowlist → remetente/canal foi filtrado pela política.
Relacionado:

​
Conectividade da UI de controle do dashboard

Quando a UI de controle do dashboard não conecta, valide a URL, o modo de autenticação e as suposições de contexto seguro. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
Procure por:
  • URL de probe correta e URL do dashboard.
  • Incompatibilidade de modo/token de autenticação entre cliente e gateway.
  • Uso de HTTP onde a identidade do dispositivo é exigida.
Assinaturas comuns:
  • device identity required → contexto não seguro ou autenticação de dispositivo ausente.
  • unauthorized / loop de reconexão → incompatibilidade de token/senha.
  • gateway connect failed: → host/porta/URL de destino incorretos.
Relacionado:

​
Serviço do Gateway não está em execução

Use isto quando o serviço está instalado, mas o processo não se mantém ativo. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep
Procure por:
  • Runtime: stopped com dicas de saída.
  • Incompatibilidade de configuração do serviço (Config (cli) vs Config (service)).
  • Conflitos de porta/listener.
Assinaturas comuns:
  • Gateway start blocked: set gateway.mode=local → o modo de gateway local não está habilitado. Correção: defina gateway.mode="local" na sua configuração (ou execute openclaw configure). Se você estiver executando o OpenClaw via Podman usando o usuário dedicado openclaw, a configuração fica em ~openclaw/.openclaw/openclaw.json.
  • refusing to bind gateway ... without auth → bind fora do loopback sem token/senha.
  • another gateway instance is already listening / EADDRINUSE → conflito de porta.
Relacionado:

​
Canal conectado, mensagens não fluem

Se o estado do canal está conectado, mas o fluxo de mensagens morreu, foque em política, permissões e regras específicas de entrega do canal. 
openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels
Procure por:
  • Política de DM (pairing, allowlist, open, disabled).
  • Lista de permissões de grupo e requisitos de menção.
  • Permissões/escopos de API do canal ausentes.
Assinaturas comuns:
  • mention required → mensagem ignorada pela política de menção em grupo.
  • pairing / rastros de aprovação pendente → o remetente não está aprovado.
  • missing_scope, not_in_channel, Forbidden, 401/403 → problema de autenticação/permissões do canal.
Relacionado:

​
Entrega de cron e heartbeat

Se o cron ou o heartbeat não executou ou não entregou, verifique primeiro o estado do agendador e depois o destino de entrega. 
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
Procure por:
  • Cron habilitado e próxima ativação presente.
  • Status do histórico de execução do job (ok, skipped, error).
  • Motivos de pulo do heartbeat (quiet-hours, requests-in-flight, alerts-disabled).
Assinaturas comuns:
  • cron: scheduler disabled; jobs will not run automatically → cron desabilitado.
  • cron: timer tick failed → tick do agendador falhou; verifique erros de arquivo/log/runtime.
  • heartbeat skipped com reason=quiet-hours → fora da janela de horas ativas.
  • heartbeat: unknown accountId → id de conta inválido para o destino de entrega do heartbeat.
Relacionado:

​
Ferramenta emparelhada de nó falhou

Se um nó está pareado, mas as ferramentas falham, isole estado de primeiro plano, permissões e aprovação. 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
Procure por:
  • Nó online com as capacidades esperadas.
  • Concessões de permissão do SO para câmera/microfone/localização/tela.
  • Aprovações de exec e estado da lista de permissões.
Assinaturas comuns:
  • NODE_BACKGROUND_UNAVAILABLE → o app do nó deve estar em primeiro plano.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → permissão do SO ausente.
  • SYSTEM_RUN_DENIED: approval required → aprovação de exec pendente.
  • SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado pela lista de permissões.
Relacionado:

​
Falha da ferramenta de navegador

Use isto quando ações da ferramenta de navegador falham mesmo que o gateway em si esteja saudável. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
Procure por:
  • Caminho válido do executável do navegador.
  • Acessibilidade do perfil CDP.
  • Anexação da aba de relay da extensão para profile="chrome".
Assinaturas comuns:
  • Failed to start Chrome CDP on port → o processo do navegador falhou ao iniciar.
  • browser.executablePath not found → o caminho configurado é inválido.
  • Chrome extension relay is running, but no tab is connected → relay da extensão não anexado.
  • Browser attachOnly is enabled ... not reachable → perfil apenas de anexação não tem alvo acessível.
Relacionado:

​
Se você atualizou e algo quebrou de repente

A maioria das quebras pós-atualização é desvio de configuração ou padrões mais rígidos agora sendo aplicados.

​
1. O comportamento de autenticação e sobrescrita de URL mudou

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
O que verificar:
  • Se gateway.mode=remote, chamadas da CLI podem estar apontando para remoto enquanto seu serviço local está ok.
  • Chamadas explícitas de --url não fazem fallback para credenciais armazenadas.
Assinaturas comuns:
  • gateway connect failed: → URL de destino incorreta.
  • unauthorized → endpoint alcançável, mas autenticação errada.

​
2. Guardrails de bind e autenticação estão mais rígidos

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
O que verificar:
  • Binds fora do loopback (lan, tailnet, custom) precisam de autenticação configurada.
  • Chaves antigas como gateway.token não substituem gateway.auth.token.
Assinaturas comuns:
  • refusing to bind gateway ... without auth → incompatibilidade entre bind e autenticação.
  • RPC probe: failed enquanto o runtime está em execução → gateway ativo, mas inacessível com a autenticação/URL atuais.

​
3. O estado de pareamento e identidade do dispositivo mudou

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor
O que verificar:
  • Aprovações de dispositivo pendentes para dashboard/nós.
  • Aprovações de pareamento de DM pendentes após mudanças de política ou identidade.
Assinaturas comuns:
  • device identity required → autenticação do dispositivo não satisfeita.
  • pairing required → remetente/dispositivo deve ser aprovado.
Se a configuração do serviço e o runtime ainda discordarem após as verificações, reinstale os metadados do serviço a partir do mesmo diretório de perfil/estado: 
openclaw gateway install --force
openclaw gateway restart
Relacionado: