Solução de problemas

​

Sequência de comandos

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

• 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

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

• 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

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
openclaw gateway restart

​

Incompatibilidade de protocolo após reversão

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

• 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.

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.

​

Link simbólico de Skill ignorado por escapar do caminho

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

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

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

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

​

Uso adicional exigido pelo erro 429 da Anthropic para contexto longo

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• 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.

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

​

Respostas 403 bloqueadas pelo serviço upstream

openclaw status
openclaw gateway status
openclaw logs --follow

• 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.

• 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

• 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/models
curl 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" --json
openclaw logs --follow

• 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.

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

​

Sem respostas

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

• 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.

• 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.

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

​

Conectividade da interface de controle do painel

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

• 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.

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

​

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

openclaw --version
openclaw doctor
openclaw gateway status

• 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.

• 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

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

• 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).

• 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

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

• 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.

• 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.

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 minutos
   state=$(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.gateway
   fi
   
   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.

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

​

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

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

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

• 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.

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/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 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 10
   done
   
   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 --force
   rm ~/.local/bin/openclaw-launchd-workaround
   

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

​

O Gateway é encerrado durante alto uso de memória

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

• 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.

• 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.

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

​

O Gateway rejeitou uma configuração inválida

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

• 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 | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

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

​

Avisos da sondagem do Gateway

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• 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.

• 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.

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

​

Canal conectado, mas as mensagens não fluem

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

• 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.

• 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.

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

​

Entrega de Cron e Heartbeat

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

• 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).

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

​

Node emparelhado, ferramenta falha

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

• 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.

• 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.

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

​

A ferramenta de navegador falha

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

• 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.

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

​

Se você atualizou e algo parou de funcionar repentinamente

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

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

openclaw gateway install --force
openclaw gateway restart

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

​

Relacionado

• Doctor
• Perguntas frequentes
• Guia operacional do Gateway