Solução de problemas

Este é o runbook detalhado. Comece por /help/troubleshooting para seguir primeiro o fluxo rápido de triagem.

Sequência de comandos

Execute nesta ordem:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Sinais de funcionamento normal:

• openclaw gateway status mostra Runtime: running, Connectivity probe: ok e uma linha Capability: ....
• openclaw doctor não relata problemas impeditivos de configuração ou serviço.
• openclaw channels status --probe mostra o status atual do transporte por conta e, quando houver suporte, works ou audit ok.

Após uma atualização

Use quando uma atualização terminar, mas o Gateway estiver inativo, os canais estiverem vazios ou as chamadas de modelo falharem com erros 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Procure por:

• Update restart em openclaw status / openclaw status --all. Transferências pendentes ou com falha incluem o próximo comando a ser executado.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix em Canais: a configuração do canal ainda existe, mas o registro do plugin falhou antes que o canal pudesse ser carregado.
• Erros 401 do provedor após uma nova autenticação: openclaw doctor --fix verifica se há cópias obsoletas de autenticação OAuth por agente que estejam ocultando a autenticação atual e remove as cópias antigas para que todos os agentes resolvam o perfil compartilhado atual.

Instalações divergentes e proteção contra configurações mais recentes

Use quando um serviço do Gateway parar inesperadamente após uma atualização ou quando os logs mostrarem que um binário openclaw é mais antigo do que a versão que gravou openclaw.json pela última vez.

O OpenClaw marca as gravações de configuração com meta.lastTouchedVersion. Comandos somente leitura podem inspecionar uma configuração gravada por uma versão mais recente do OpenClaw, mas mutações de processos e serviços se recusam a ser executadas por um binário mais antigo. Ações bloqueadas: iniciar/parar/reiniciar/desinstalar o serviço do Gateway, reinstalação forçada do serviço, inicialização do Gateway no modo de serviço e limpeza de porta com gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Incompatibilidade de protocolo após reversão

Use quando os logs continuarem exibindo protocol mismatch após um downgrade ou uma reversão. Um Gateway mais antigo está em execução, mas um processo cliente local mais recente ainda está tentando se reconectar com um intervalo de protocolo que o Gateway mais antigo não consegue usar.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Procure por:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> nos logs do Gateway.
• Established clients: em openclaw gateway status --deep ou Gateway clients em openclaw doctor --deep: clientes TCP ativos conectados à porta do Gateway, com PIDs e linhas de comando quando o sistema operacional permitir.
• Um processo cliente cuja linha de comando aponte para a instalação ou o wrapper mais recente do OpenClaw a partir do qual você fez a reversão.

Correção:

1. Pare ou reinicie o processo cliente obsoleto do OpenClaw exibido por gateway status --deep.
2. Reinicie aplicativos ou wrappers que incorporem o OpenClaw: painéis locais, editores, auxiliares de servidores de aplicativos ou shells de longa duração com openclaw logs --follow.
3. Execute novamente openclaw gateway status --deep ou openclaw doctor --deep e confirme que o PID do cliente obsoleto desapareceu.

Não faça um Gateway mais antigo aceitar um protocolo mais recente e incompatível. Os incrementos de versão do protocolo protegem o contrato de comunicação; a recuperação após reversão é um problema de limpeza de processos e versões.

Link simbólico de Skill ignorado por escapar do caminho

Use quando os logs incluírem:

Ignorando caminho de Skill que escapou de sua raiz configurada: ... reason=symlink-escape

Cada raiz de Skill é um limite de contenção. Um link simbólico em ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills ou ~/.openclaw/skills é ignorado quando seu destino real é resolvido fora dessa raiz, a menos que o destino seja explicitamente confiável.

Inspecione o link:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Se o destino for intencional, configure tanto a raiz direta de Skills quanto o destino permitido do link simbólico:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Em seguida, inicie uma nova sessão ou aguarde a atualização do monitor de Skills. Reinicie o Gateway se o processo em execução for anterior à alteração da configuração.

Não use destinos abrangentes, como ~, / ou uma pasta inteira de projeto sincronizado. Restrinja allowSymlinkTargets à raiz real de Skills que contém diretórios SKILL.md confiáveis.

Se a aplicação do Skill Workshop também precisar gravar por meio desses caminhos confiáveis de Skills do espaço de trabalho vinculados simbolicamente, ative skills.workshop.allowSymlinkTargetWrites. Mantenha essa opção desativada para raízes compartilhadas de Skills somente leitura.

Relacionado:

• Configuração de Skills
• Exemplos de configuração

Uso adicional exigido pelo erro 429 da Anthropic para contexto longo

Use quando os logs ou erros incluírem: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Procure por:

• O modelo Anthropic selecionado é um modelo Claude 4.x com disponibilidade geral e capacidade para 1M (Opus 4.6/4.7/4.8, Sonnet 4.6), ou a configuração do modelo ainda contém o parâmetro legado params.context1m: true.
• A credencial atual da Anthropic não está qualificada para uso de contexto longo.
• As solicitações falham somente em sessões longas ou execuções de modelos que precisam do caminho de contexto de 1M.

Opções de correção:

Relacionado:

• Anthropic
• Uso e custos de tokens
• Por que estou recebendo HTTP 429 da Anthropic?

Respostas 403 bloqueadas pelo serviço upstream

Use quando um provedor upstream de LLM retornar um erro 403 genérico, como Your request was blocked.

Não presuma que isso seja sempre um problema de configuração do OpenClaw. A resposta pode vir de uma camada de segurança upstream, como uma CDN, WAF, regra de gerenciamento de bots ou proxy reverso diante de um endpoint compatível com OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Procure por:

• Vários modelos do mesmo provedor falhando da mesma maneira.
• HTML ou texto genérico de segurança em vez de um erro normal da API do provedor.
• Eventos de segurança do lado do provedor correspondentes ao mesmo horário da solicitação.
• Uma pequena sondagem direta com curl funcionando enquanto solicitações normais no formato do SDK falham.

Corrija primeiro a filtragem do lado do provedor quando as evidências apontarem para um bloqueio de WAF/CDN. Prefira uma regra de permissão ou de desvio com escopo restrito ao caminho da API usado pelo OpenClaw e evite desativar a proteção de todo o site.

Relacionado:

• Endpoints compatíveis com OpenAI
• Configuração de provedores
• Logs

Backend local compatível com OpenAI passa em sondagens diretas, mas as execuções do agente falham

Use quando:

• curl ... /v1/models funciona.
• Chamadas diretas pequenas para /v1/chat/completions funcionam.
• As execuções de modelos do OpenClaw falham somente em interações normais do agente.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

Procure por:

• Chamadas diretas pequenas funcionam, mas as execuções do OpenClaw falham somente com prompts maiores.
• Erros model_not_found ou 404, embora /v1/chat/completions funcione diretamente com o mesmo ID simples de modelo.
• Erros do backend informando que messages[].content esperava uma string.
• Avisos intermitentes incomplete turn detected ... stopReason=stop payloads=0 com um backend local compatível com OpenAI.
• Falhas do backend que aparecem somente com contagens maiores de tokens do prompt ou prompts completos do runtime do agente.

Relacionado:

• Configuração
• Modelos locais
• Endpoints compatíveis com OpenAI

Sem respostas

Se os canais estiverem ativos, mas nada responder, verifique o roteamento e a política antes de reconectar qualquer coisa.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

Procure por:

• Pareamento pendente para remetentes de mensagens diretas.
• Restrição por menção em grupos (requireMention, mentionPatterns).
• Incompatibilidades na lista de permissões do canal/grupo.

Assinaturas comuns:

• drop guild message (mention required → mensagem de grupo ignorada até haver uma menção.
• pairing request → o remetente precisa de aprovação.
• blocked / allowlist → o remetente/canal foi filtrado pela política.

Relacionado:

• Solução de problemas de canais
• Grupos
• Pareamento

Conectividade da interface de controle do painel

Quando o painel/interface de controle não se conectar, valide a URL, o modo de autenticação e as premissas de contexto seguro.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Procure por:

• URL de sondagem e URL do painel corretas.
• Incompatibilidade de modo/token de autenticação entre o cliente e o Gateway.
• Uso de HTTP quando a identidade do dispositivo é obrigatória.

Se um navegador local não conseguir se conectar a 127.0.0.1:18789 após uma atualização, primeiro recupere o serviço local do Gateway e confirme que ele está servindo o painel:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Se curl retornar HTML do OpenClaw, o Gateway está funcionando, e o problema restante provavelmente é o cache do navegador, um link direto antigo ou o estado obsoleto de uma aba. Abra http://127.0.0.1:18789 diretamente e navegue a partir do painel. Se a reinicialização não mantiver o serviço em execução, execute openclaw gateway start e verifique novamente openclaw gateway status.

Mapa rápido dos códigos de detalhes de autenticação

Use error.details.code da resposta de connect com falha para escolher a próxima ação:

Verificação da migração da autenticação de dispositivo v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Se os logs mostrarem erros de nonce/assinatura, atualize o cliente que está se conectando e verifique-o:

Se openclaw devices rotate / revoke / remove for negado inesperadamente:

• Sessões com token de dispositivo pareado podem gerenciar somente seu próprio dispositivo, a menos que o chamador também tenha operator.admin.
• openclaw devices rotate --scope ... só pode solicitar escopos de operador que a sessão do chamador já possui.

Relacionado:

• Configuração (modos de autenticação do Gateway)
• Interface de controle
• Dispositivos
• Acesso remoto
• Autenticação por proxy confiável

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

Use quando o serviço estiver instalado, mas o processo não permanecer em execução.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # também verifica serviços no nível do sistema

Procure por:

• Runtime: stopped com indicações de saída.
• Incompatibilidade na configuração do serviço (Config (cli) em comparação com Config (service)).
• Conflitos de porta/listener.
• Instalações adicionais de launchd/systemd/schtasks quando --deep é usado.
• Dicas de limpeza em Other gateway-like services detected (best effort).

Relacionado:

• Execução em segundo plano e ferramenta de processos
• Configuração
• Doctor

O Gateway no macOS para silenciosamente de responder e retoma quando você interage com o painel

Use quando os canais (Telegram, WhatsApp etc.) em um host macOS ficam inativos por minutos ou horas, e o Gateway parece voltar assim que você abre a interface de controle, acessa via SSH ou interage de outra forma com o host. Geralmente, não há nenhum sintoma evidente em openclaw status, pois, quando você verifica, o Gateway já está ativo novamente.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Procure por:

• Um ou mais pacotes *-uncaught_exception.json em ~/.openclaw/logs/stability/ com error.code definido como um código transitório de rede, como ENETDOWN, ENETUNREACH, EHOSTUNREACH ou ECONNREFUSED.
• Linhas de pmset -g log como Entering Sleep state due to 'Maintenance Sleep' ou en0 driver is slow (msg: WillChangeState to 0) alinhadas aos horários das falhas. Power Nap / Maintenance Sleep coloca brevemente o driver de Wi-Fi no estado 0; qualquer connect() de saída que ocorra nessa janela pode falhar com ENETDOWN, mesmo em um host que normalmente tenha conectividade de rede completa.
• Saída de launchctl print mostrando state = not running com várias execuções (runs) recentes e um código de saída, especialmente quando o intervalo entre a falha e a próxima inicialização é da ordem de uma hora, em vez de segundos. O launchd do macOS aplica uma barreira não documentada de proteção contra reinicializações após uma sequência de falhas, que pode deixar de respeitar KeepAlive=true até que um gatilho externo, como login interativo, conexão com o painel ou launchctl kickstart, a reative.

Assinaturas comuns:

• Um pacote de estabilidade cujo error.code seja ENETDOWN ou um código relacionado, com a pilha de chamadas apontando para lookupAndConnect / Socket.connect do módulo net do Node. O OpenClaw 2026.5.26 e versões posteriores classificam esses casos como erros transitórios de rede inofensivos, portanto eles não chegam mais ao manipulador de exceções não capturadas de nível superior; se você estiver em uma versão anterior, atualize primeiro.
• Longos períodos de inatividade que terminam no instante em que você se conecta à interface de controle ou acessa o host por SSH: é a atividade visível ao usuário que reativa a barreira de reinicialização do launchd, não alguma ação do painel sobre o Gateway.
• A contagem de runs aumentando ao longo do dia sem uma linha correspondente received SIG*; shutting down em ~/Library/Logs/openclaw/gateway.log: encerramentos normais registram um sinal; falhas transitórias não.

O que fazer:

1. Atualize o Gateway se estiver executando uma versão anterior à 2026.5.26. Após a atualização, futuros erros ENETDOWN serão registrados como avisos, em vez de encerrar o processo.

2. Reduza a atividade de suspensão para manutenção em hosts Mac mini / desktop destinados a funcionar como servidores sempre ativos:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Isso reduz significativamente, mas não elimina por completo, a oscilação subjacente do driver. O sistema ainda pode realizar algumas suspensões para manutenção de keepalive TCP e manutenção de mDNS, independentemente dessas opções.

3. Adicione um monitor de atividade para que uma futura sequência de falhas estacionada pelo launchd seja detectada rapidamente:

   # Exemplo de verificação de atividade compatível com launchd, adequada para um Cron ou LaunchAgent executado a cada 5 minutosstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   O objetivo é reativar externamente a barreira de reinicialização; KeepAlive=true por si só não é suficiente no macOS após uma sequência de falhas.

Relacionado:

• Observações sobre a plataforma macOS
• Logs
• Doctor

Loop de supervisão do launchd no macOS com LaunchAgents duplicados de Gateway/Node

Use isto quando uma instalação do macOS continuar reiniciando a cada poucos segundos, as verificações de integridade do openclaw alternarem entre disponível e indisponível e o encaminhamento de canais travar, mesmo que o serviço pareça estar em execução.

Isso foi observado em instalações antigas nas quais os LaunchAgents ai.openclaw.gateway e ai.openclaw.node estavam ativos e cada um injetava OPENCLAW_LAUNCHD_LABEL. Nesse estado, o OpenClaw pode detectar a supervisão do launchd, tentar devolver o controle da reinicialização ao launchd e entrar em um loop rápido de EADDRINUSE/reinicialização, em vez de manter um único processo estável do Gateway.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Procure por:

• Mais de um PID do Gateway ao longo da amostra de 30 segundos, em vez de um único processo estável.
• EADDRINUSE, another gateway instance is already listening ou linhas repetidas de reinicialização/transferência em gateway.log.
• Tanto ~/Library/LaunchAgents/ai.openclaw.gateway.plist quanto ~/Library/LaunchAgents/ai.openclaw.node.plist carregados ao mesmo tempo em um host que deveria executar apenas um serviço gerenciado do Gateway.

O que fazer:

1. Se este host deve executar somente o serviço do Gateway, remova o serviço gerenciado do Node por meio do OpenClaw. Pule esta etapa se você utiliza ativamente o serviço do Node para recursos remotos do Node; desinstalá-lo interrompe esses recursos neste host:

   openclaw node uninstall

2. Instale um wrapper persistente do Gateway que remova os marcadores herdados do launchd antes de iniciar o OpenClaw. Use a opção compatível --wrapper; não edite o arquivo gerado em ~/.openclaw/service-env/, pois a reinstalação do serviço, a atualização e o reparo do Doctor regeneram esse arquivo:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install mantém o caminho do wrapper entre reinstalações forçadas, atualizações e reparos do Doctor.

3. Verifique se o Gateway está estável e atendendo RPC, não apenas escutando:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   A amostra de PIDs deve mostrar um único processo estável, em vez de um conjunto rotativo de PIDs, e o encaminhamento de canais de entrada deve ser retomado.

4. Depois de atualizar para uma versão na qual o loop subjacente de dois LaunchAgents esteja corrigido, remova a solução alternativa e reinstale o serviço gerenciado normal:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Relacionado:

• Observações sobre a plataforma macOS
• Doctor
• CLI do Gateway

O Gateway é encerrado durante alto uso de memória

Use quando o Gateway desaparecer sob carga, o supervisor relatar uma reinicialização semelhante a OOM ou os logs mencionarem critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Procure por:

• Reason: diagnostic.memory.pressure.critical no pacote de estabilidade mais recente.
• Memory pressure: com critical/rss_threshold, critical/heap_threshold ou critical/rss_growth.
• Valores de V8 heap: próximos ao limite do heap.
• Entradas de Largest session files: como agents/<agent>/sessions/<session>.jsonl ou sessions/<session>.jsonl.
• Contadores de memória de cgroup do Linux quando o Gateway é executado dentro de um contêiner ou serviço com memória limitada.

Assinaturas comuns:

• critical memory pressure bundle written aparece pouco antes da reinicialização → o OpenClaw capturou um pacote de estabilidade anterior ao OOM. Inspecione-o com openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled aparece nos logs do Gateway → o OpenClaw detectou pressão crítica de memória, mas o instantâneo de estabilidade anterior ao OOM está desativado.
• Largest session files: aponta para um caminho de transcrição anonimizado muito grande → reduza o histórico de sessões mantido, inspecione o crescimento das sessões ou mova transcrições antigas para fora do armazenamento ativo antes de reiniciar.
• Os bytes usados em V8 heap: estão próximos ao limite do heap → reduza a pressão de prompts/sessões, diminua o trabalho simultâneo ou aumente o limite de heap do Node somente após confirmar que a carga de trabalho é esperada.
• Memory pressure: critical/rss_growth → a memória cresceu rapidamente em uma única janela de amostragem. Verifique nos logs mais recentes se houve uma importação grande, saída descontrolada de uma ferramenta, tentativas repetidas ou um lote de trabalhos de agentes enfileirados.
• A pressão crítica de memória aparece nos logs, mas não existe pacote → esse é o padrão. Defina diagnostics.memoryPressureSnapshot: true para capturar o pacote de estabilidade anterior ao OOM em futuros eventos de pressão crítica de memória.

O pacote de estabilidade não contém cargas úteis. Ele inclui evidências operacionais de memória e caminhos relativos de arquivos anonimizados, não texto de mensagens, corpos de Webhook, credenciais, tokens, cookies nem IDs brutos de sessão. Anexe a exportação de diagnóstico aos relatórios de bugs, em vez de copiar os logs brutos.

Relacionado:

• Integridade do Gateway
• Exportação de diagnóstico
• Sessões

O Gateway rejeitou uma configuração inválida

Use quando a inicialização do Gateway falhar com Invalid config ou quando os logs de recarga dinâmica indicarem que uma edição inválida foi ignorada.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Procure por:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Um arquivo openclaw.json.rejected.* com data e hora ao lado da configuração ativa.
• Um arquivo openclaw.json.clobbered.* com data e hora se doctor --fix tiver reparado uma edição direta corrompida.
• O OpenClaw mantém os 32 arquivos .clobbered.* mais recentes de cada caminho de configuração e remove os mais antigos por rotação.

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

Relacionado:

• Configuração
• Configuração: recarga dinâmica
• Configuração: validação estrita
• Doctor

Avisos da sondagem do Gateway

Use quando openclaw gateway probe alcançar algum destino, mas ainda exibir um bloco de avisos.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Procure por:

• warnings[].code e primaryTargetId na saída JSON.
• Se o aviso é sobre fallback de SSH, vários gateways, escopos ausentes ou referências de autenticação não resolvidas.

Assinaturas comuns:

• SSH tunnel failed to start; falling back to direct probes. → a configuração do SSH falhou, mas o comando ainda tentou sondagens diretas nos destinos configurados/de loopback.
• multiple reachable gateway identities detected → gateways distintos responderam, ou o OpenClaw não conseguiu comprovar que os destinos alcançáveis são o mesmo gateway. Um túnel SSH, uma URL de proxy ou uma URL remota configurada para o mesmo gateway é tratado como um único gateway com vários transportes, mesmo quando as portas de transporte são diferentes.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → a conexão funcionou, mas a RPC de detalhes está limitada pelo escopo; emparelhe a identidade do dispositivo ou use credenciais com operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → a conexão funcionou, mas o conjunto completo de RPCs de diagnóstico atingiu o tempo limite ou falhou. Trate isso como um Gateway alcançável com diagnósticos degradados; compare connect.ok e connect.rpcOk na saída de --json.
• Capability: pairing-pending ou gateway closed (1008): pairing required → o gateway respondeu, mas este cliente ainda precisa de emparelhamento/aprovação antes do acesso normal de operador.
• Texto de aviso de SecretRef não resolvida em gateway.auth.* / gateway.remote.* → o material de autenticação não estava disponível neste caminho de comando para o destino que falhou.

Relacionado:

• Gateway
• Vários gateways no mesmo host
• Acesso remoto

Canal conectado, mas as mensagens não fluem

Se o estado do canal estiver conectado, mas o fluxo de mensagens estiver inativo, concentre-se em políticas, permissões e regras de entrega específicas do canal.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Procure por:

• Política de mensagens diretas (pairing, allowlist, open, disabled).
• Lista de permissões do grupo e requisitos de menção.
• Permissões/escopos ausentes da API do canal.

Assinaturas comuns:

• mention required → mensagem ignorada pela política de menções do 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:

• Solução de problemas de canais
• Discord
• Telegram
• WhatsApp

Entrega de Cron e Heartbeat

Se o Cron ou o Heartbeat não tiver sido executado ou não tiver feito a entrega, verifique primeiro o estado do agendador e depois o destino de entrega.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Procure por:

• Cron habilitado e próximo despertar presente.
• Status do histórico de execução da tarefa (ok, skipped, error).
• Motivos para ignorar o Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Relacionado:

• Heartbeat
• Tarefas agendadas
• Tarefas agendadas: solução de problemas

Node emparelhado, ferramenta falha

Se um Node estiver emparelhado, mas as ferramentas falharem, isole o estado de primeiro plano, permissões e aprovação.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

Procure por:

• Node online com os recursos esperados.
• Concessões de permissão do sistema operacional para câmera/microfone/localização/tela.
• Estado das aprovações de execução e da lista de permissões.

Assinaturas comuns:

• NODE_BACKGROUND_UNAVAILABLE → o aplicativo do Node deve estar em primeiro plano.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → permissão do sistema operacional ausente.
• SYSTEM_RUN_DENIED: approval required → aprovação de execução pendente.
• SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado pela lista de permissões.

Relacionado:

• Aprovações de execução
• Solução de problemas de Node
• Nodes

A ferramenta de navegador falha

Use quando as ações da ferramenta de navegador falharem, mesmo que o próprio gateway esteja íntegro.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Procure por:

• Se plugins.allow está definido e inclui browser.
• Caminho válido para o executável do navegador.
• Acessibilidade do perfil CDP.
• Disponibilidade local do Chrome para perfis existing-session / user.

Relacionado:

• Navegador (gerenciado pelo OpenClaw)
• Solução de problemas do navegador

Se você atualizou e algo parou de funcionar repentinamente

A maioria das falhas após uma atualização ocorre por divergência de configuração ou porque padrões mais rigorosos passaram a ser aplicados.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

Se a configuração do serviço e o runtime ainda estiverem divergentes após as verificações, reinstale os metadados do serviço usando o mesmo diretório de perfil/estado:

openclaw gateway install --forceopenclaw gateway restart

Relacionado:

• Autenticação
• Execução em segundo plano e ferramenta de processos
• Emparelhamento de Node

Relacionado

• Doctor
• Perguntas frequentes
• Guia operacional do Gateway