Gateway
Solução de problemas
Esta página é o runbook detalhado. Comece em /help/troubleshooting se quiser primeiro o fluxo rápido de triagem.
Sequência de comandos
Execute estes primeiro, nesta ordem:
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probeSinais esperados de integridade:
openclaw gateway statusmostraRuntime: running,Connectivity probe: oke uma linhaCapability: ....openclaw doctornão relata problemas bloqueantes de configuração/serviço.openclaw channels status --probemostra o status de transporte ativo por conta e, quando houver suporte, resultados de sondagem/auditoria comoworksouaudit ok.
Depois de uma atualização
Use isto quando uma atualização termina, mas o Gateway está fora do ar, os canais estão vazios ou as chamadas de modelo começam a falhar com 401.
openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restartProcure por:
Update restartemopenclaw status/openclaw status --all. Transferências pendentes ou com falha incluem o próximo comando a executar.plugin load failed: dependency tree corrupted; run openclaw doctor --fixem Channels. Isso significa que a configuração do canal ainda existe, mas o registro do plugin falhou antes que o canal pudesse ser carregado.- 401s do provedor após nova autenticação.
openclaw doctor --fixverifica sombras antigas de autenticação OAuth por agente e remove as cópias antigas para que todos os agentes resolvam o perfil compartilhado atual.
Instalações split brain e proteção de configuração mais nova
Use isto quando um serviço de gateway para inesperadamente após uma atualização, ou os logs mostram que um binário openclaw é mais antigo que a versão que gravou openclaw.json pela última vez.
O OpenClaw marca gravações de configuração com meta.lastTouchedVersion. Comandos somente leitura ainda podem inspecionar uma configuração gravada por um OpenClaw mais novo, mas mutações de processo e serviço se recusam a continuar a partir de um binário mais antigo. Ações bloqueadas incluem iniciar, parar, reiniciar e desinstalar o serviço do gateway, reinstalação forçada do serviço, inicialização do gateway em modo de serviço e limpeza de porta com gateway --force.
which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersionCorrigir PATH
Corrija PATH para que openclaw resolva para a instalação mais nova e, em seguida, execute novamente a ação.
Reinstalar o serviço do gateway
Reinstale o serviço de gateway pretendido a partir da instalação mais nova:
openclaw gateway install --forceopenclaw gateway restartRemover wrappers obsoletos
Remova entradas obsoletas de pacote do sistema ou wrappers antigos que ainda apontam para um binário openclaw antigo.
Incompatibilidade de protocolo após rollback
Use isto quando os logs continuam imprimindo protocol mismatch depois que você faz downgrade ou rollback do OpenClaw. Isso significa que um Gateway mais antigo está em execução, mas um processo de cliente local mais novo ainda está tentando se reconectar com um intervalo de protocolo que o Gateway mais antigo não consegue falar.
openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --followProcure por:
protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>nos logs do Gateway.Established clients:emopenclaw gateway status --deepouGateway clientsemopenclaw doctor --deep. Isso lista clientes TCP ativos conectados à porta do Gateway, incluindo PIDs e linhas de comando quando o SO permite.- Um processo de cliente cuja linha de comando aponta para a instalação ou wrapper mais novo do OpenClaw do qual você fez rollback.
Correção:
- Pare ou reinicie o processo de cliente OpenClaw obsoleto mostrado por
gateway status --deep. - Reinicie apps ou wrappers que incorporam o OpenClaw, como dashboards locais, editores, auxiliares de app-server ou shells
openclaw logs --followde longa duração. - Execute novamente
openclaw gateway status --deepouopenclaw doctor --deepe confirme que o PID do cliente obsoleto desapareceu.
Não faça um Gateway mais antigo aceitar um protocolo incompatível mais novo. Aumentos de protocolo protegem o contrato de comunicação; a recuperação de rollback é um problema de limpeza de processo/versão.
Symlink de Skill ignorado como escape de caminho
Use isto quando os logs incluírem:
Skipping escaped skill path outside its configured root: ... reason=symlink-escapeO OpenClaw trata cada raiz de skill como um limite de contenção. Um symlink em
~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills ou
~/.openclaw/skills é ignorado quando seu alvo real resolve para fora dessa raiz,
a menos que o alvo seja explicitamente confiável.
Inspecione o link:
ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.loadSe o alvo for intencional, configure tanto a raiz direta da skill quanto o alvo de symlink permitido:
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}Em seguida, inicie uma nova sessão ou aguarde o watcher de skills atualizar. Reinicie o gateway se o processo em execução for anterior à alteração de configuração.
Não use alvos amplos como ~, / ou uma pasta inteira de projeto sincronizado.
Mantenha allowSymlinkTargets restrito à raiz real de skills que contém diretórios
SKILL.md confiáveis.
Se o apply do Skill Workshop também deve gravar por esses caminhos de skill de workspace
com symlink confiável, habilite skills.workshop.allowSymlinkTargetWrites. Mantenha-o
desabilitado para raízes de skills compartilhadas somente leitura.
Relacionado:
Anthropic 429 exige uso extra para contexto longo
Use isto quando logs/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.modelsProcure por:
- O modelo Anthropic selecionado é um modelo Claude 4.x de 1M com capacidade GA, ou o modelo tem
params.context1m: truelegado. - A credencial Anthropic atual não é qualificada para uso de contexto longo.
- As solicitações falham apenas em sessões/execuções de modelo longas que precisam do caminho de contexto de 1M.
Opções de correção:
Usar uma janela de contexto padrão
Troque para um modelo com janela padrão, ou remova context1m legado de uma
configuração de modelo antiga que não tem capacidade GA para contexto de 1M.
Usar uma credencial qualificada
Use uma credencial Anthropic qualificada para solicitações de contexto longo, ou troque para uma chave de API Anthropic.
Configurar modelos de fallback
Configure modelos de fallback para que as execuções continuem quando solicitações Anthropic de contexto longo forem rejeitadas.
Relacionado:
Respostas upstream 403 bloqueadas
Use isto quando um provedor LLM upstream retornar um 403 genérico, como
Your request was blocked.
Não presuma que isso é sempre um problema de configuração do OpenClaw. A resposta pode vir de uma camada de segurança upstream, como CDN, WAF, regra de gerenciamento de bots ou proxy reverso na frente de um endpoint compatível com OpenAI.
openclaw statusopenclaw gateway statusopenclaw logs --followProcure por:
- vários modelos sob o mesmo provedor falhando da mesma forma
- HTML ou texto genérico de segurança em vez de um erro normal de API do provedor
- eventos de segurança do lado do provedor no mesmo horário da solicitação
- uma pequena sondagem direta com
curltendo sucesso 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 exceção com escopo estreito para o caminho de API que o OpenClaw usa, e evite desabilitar a proteção para o site inteiro.
Relacionado:
Backend local compatível com OpenAI passa em sondagens diretas, mas execuções de agente falham
Use isto quando:
curl ... /v1/modelsfunciona- chamadas diretas pequenas para
/v1/chat/completionsfuncionam - execuções de modelo do OpenClaw falham apenas em turnos normais de 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 --followProcure por:
- chamadas diretas pequenas têm sucesso, mas execuções do OpenClaw falham apenas em prompts maiores
- erros
model_not_foundou 404 mesmo que/v1/chat/completionsdireto funcione com o mesmo id de modelo simples - erros do backend sobre
messages[].contentesperando uma string - avisos intermitentes
incomplete turn detected ... stopReason=stop payloads=0com um backend local compatível com OpenAI - falhas do backend que aparecem apenas com contagens maiores de tokens de prompt ou prompts completos de runtime de agente
Assinaturas comuns
model_not_foundcom um servidor local no estilo MLX/vLLM → verifique sebaseUrlinclui/v1, seapié"openai-completions"para backends/v1/chat/completionse semodels.providers.<provider>.models[].idé o id local simples do provedor. Selecione-o com o prefixo do provedor uma vez, por exemplomlx/mlx-community/Qwen3-30B-A3B-6bit; mantenha a entrada do catálogo comomlx-community/Qwen3-30B-A3B-6bit.messages[...].content: invalid type: sequence, expected a string→ o backend rejeita partes de conteúdo estruturado do Chat Completions. Correção: definamodels.providers.<provider>.models[].compat.requiresStringContent: true.validation.keysou chaves de mensagem permitidas como["role","content"]→ o backend rejeita metadados de replay no estilo OpenAI em mensagens do Chat Completions. Correção: definamodels.providers.<provider>.models[].compat.strictMessageKeys: true.incomplete turn detected ... stopReason=stop payloads=0→ o backend concluiu a solicitação Chat Completions, mas não retornou texto de assistente visível ao usuário para esse turno. O OpenClaw tenta novamente turnos vazios compatíveis com OpenAI e seguros para replay uma vez; falhas persistentes geralmente significam que o backend está emitindo conteúdo vazio/não textual ou suprimindo o texto da resposta final.- solicitações diretas pequenas têm sucesso, mas execuções de agente do OpenClaw falham com crashes de backend/modelo (por exemplo, Gemma em alguns builds
inferrs) → o transporte do OpenClaw provavelmente já está correto; o backend está falhando no formato maior de prompt de runtime de agente. - falhas diminuem após desabilitar ferramentas, mas não desaparecem → os schemas de ferramentas faziam parte da pressão, mas o problema restante ainda é capacidade upstream do modelo/servidor ou um bug do backend.
Opções de correção
- Defina
compat.requiresStringContent: truepara backends Chat Completions que aceitam apenas string. - Defina
compat.strictMessageKeys: truepara backends Chat Completions estritos que só aceitamroleecontentem cada mensagem. - Defina
compat.supportsTools: falsepara modelos/backends que não conseguem lidar com a superfície de schema de ferramentas do OpenClaw de forma confiável. - Reduza a pressão de prompt quando possível: bootstrap menor do workspace, histórico de sessão mais curto, modelo local mais leve ou um backend com suporte mais forte a contexto longo.
- Se solicitações diretas pequenas continuarem passando enquanto turnos de agente do OpenClaw ainda travam dentro do backend, trate isso como uma limitação upstream de servidor/modelo e registre uma reprodução lá com o formato de payload aceito.
Relacionado:
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 --followProcure por:
- Pareamento pendente para remetentes de DM.
- Bloqueio por menção em grupo (
requireMention,mentionPatterns). - Incompatibilidades de allowlist de canal/grupo.
Assinaturas comuns:
drop guild message (mention required→ mensagem de grupo ignorada até haver menção.pairing request→ o remetente precisa de aprovação.blocked/allowlist→ o remetente/canal foi filtrado pela política.
Relacionado:
Conectividade da IU de controle do painel
Quando o painel/IU de controle não conectar, valide a URL, o modo de autenticação e as premissas de contexto seguro.
openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --jsonProcure por:
- URL de probe e URL do painel corretas.
- Incompatibilidade de modo/token de autenticação entre cliente e Gateway.
- Uso de HTTP onde identidade do dispositivo é necessária.
Se um navegador local não conseguir 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:18789Se curl retornar HTML do OpenClaw, o Gateway está funcionando e o problema restante
provavelmente é cache do navegador, um link profundo antigo ou estado obsoleto de aba. Abra
http://127.0.0.1:18789 diretamente e navegue a partir do painel. Se a reinicialização
não deixar o serviço em execução, execute openclaw gateway start e verifique novamente
openclaw gateway status.
Assinaturas de conexão / autenticação
device identity required→ contexto não seguro ou autenticação de dispositivo ausente.origin not allowed→ oOrigindo navegador não está emgateway.controlUi.allowedOrigins(ou você está conectando de uma origem de navegador que não é loopback sem uma allowlist explícita).device nonce required/device nonce mismatch→ o cliente não está concluindo o fluxo de autenticação de dispositivo baseado em desafio (connect.challenge+device.nonce).device signature invalid/device signature expired→ o cliente assinou o payload errado (ou um timestamp obsoleto) para o handshake atual.AUTH_TOKEN_MISMATCHcomcanRetryWithDeviceToken=true→ o cliente pode fazer uma nova tentativa confiável com token de dispositivo em cache.- Essa nova tentativa com token em cache reutiliza o conjunto de escopos em cache armazenado com o token de dispositivo pareado. Chamadores com
deviceTokenexplícito /scopesexplícitos mantêm o conjunto de escopos solicitado. AUTH_SCOPE_MISMATCH→ o token de dispositivo foi reconhecido, mas seus escopos aprovados não cobrem esta solicitação de conexão; repareie ou aprove o contrato de escopo solicitado em vez de rotacionar um token compartilhado de Gateway.- Fora desse caminho de nova tentativa, a precedência da autenticação de conexão é primeiro token/senha compartilhado explícito, depois
deviceTokenexplícito, depois token de dispositivo armazenado e, por fim, token de bootstrap. - No caminho assíncrono da IU de controle do Tailscale Serve, tentativas com falha para o mesmo
{scope, ip}são serializadas antes que o limitador registre a falha. Duas novas tentativas ruins simultâneas do mesmo cliente podem, portanto, exibirretry laterna segunda tentativa em vez de duas incompatibilidades simples. too many failed authentication attempts (retry later)de um cliente loopback com origem de navegador → falhas repetidas dessa mesmaOriginnormalizada são bloqueadas temporariamente; outra origem localhost usa um bucket separado.unauthorizedrepetido após essa nova tentativa → divergência de token compartilhado/token de dispositivo; atualize a configuração de token e reaprove/rotacione o token de dispositivo se necessário.gateway connect failed:→ alvo de host/porta/url incorreto.
Mapa rápido de códigos de detalhe de autenticação
Use error.details.code da resposta connect com falha para escolher a próxima ação:
| Código de detalhe | Significado | Ação recomendada |
|---|---|---|
AUTH_TOKEN_MISSING |
O cliente não enviou um token compartilhado obrigatório. | Cole/defina o token no cliente e tente novamente. Para caminhos do painel: openclaw config get gateway.auth.token e então cole nas configurações da IU de controle. |
AUTH_TOKEN_MISMATCH |
O token compartilhado não correspondeu ao token de autenticação do Gateway. | Se canRetryWithDeviceToken=true, permita uma nova tentativa confiável. Novas tentativas com token em cache reutilizam escopos aprovados armazenados; chamadores com deviceToken / scopes explícitos mantêm os escopos solicitados. Se ainda falhar, execute a lista de recuperação de divergência de token. |
AUTH_DEVICE_TOKEN_MISMATCH |
O token por dispositivo em cache está obsoleto ou revogado. | Rotacione/reaprove o token de dispositivo usando a CLI de dispositivos, depois reconecte. |
AUTH_SCOPE_MISMATCH |
O token de dispositivo é válido, mas sua função/escopos aprovados não cobrem esta solicitação de conexão. | Repareie o dispositivo ou aprove o contrato de escopo solicitado; não trate isso como divergência de token compartilhado. |
PAIRING_REQUIRED |
A identidade do dispositivo precisa de aprovação. Verifique error.details.reason para not-paired, scope-upgrade, role-upgrade ou metadata-upgrade, e use requestId / remediationHint quando presentes. |
Aprove a solicitação pendente: openclaw devices list e depois openclaw devices approve <requestId>. Upgrades de escopo/função usam o mesmo fluxo depois que você revisar o acesso solicitado. |
Verificação de migração de autenticação de dispositivo v2:
openclaw --versionopenclaw doctoropenclaw gateway statusSe os logs mostrarem erros de nonce/assinatura, atualize o cliente que está conectando e verifique:
Aguardar connect.challenge
O cliente aguarda o connect.challenge emitido pelo Gateway.
Assinar o payload
O cliente assina o payload vinculado ao desafio.
Enviar o nonce do dispositivo
O cliente envia connect.params.device.nonce com o mesmo nonce do desafio.
Se openclaw devices rotate / revoke / remove for negado inesperadamente:
- sessões de token de dispositivo pareado podem gerenciar apenas 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)
- IU de controle
- Dispositivos
- Acesso remoto
- Autenticação de proxy confiável
Serviço do Gateway não está em execução
Use isto quando o serviço estiver instalado, mas o processo não permanecer ativo.
openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep # also scan system-level servicesProcure por:
Runtime: stoppedcom dicas de saída.- Incompatibilidade de configuração de serviço (
Config (cli)vsConfig (service)). - Conflitos de porta/listener.
- Instalações extras de launchd/systemd/schtasks quando
--deepé usado. - Dicas de limpeza de
Other gateway-like services detected (best effort).
Assinaturas comuns
Gateway start blocked: set gateway.mode=localouexisting config is missing gateway.mode→ o modo de Gateway local não está habilitado, ou o arquivo de configuração foi sobrescrito e perdeugateway.mode. Correção: definagateway.mode="local"na sua configuração, ou execute novamenteopenclaw onboard --mode local/openclaw setuppara remarcar a configuração esperada de modo local. Se você estiver executando o OpenClaw via Podman, o caminho padrão da configuração é~/.openclaw/openclaw.json.refusing to bind gateway ... without auth→ bind que não é loopback sem um caminho válido de autenticação do Gateway (token/senha, ou proxy confiável quando configurado).another gateway instance is already listening/EADDRINUSE→ conflito de porta.Other gateway-like services detected (best effort)→ existem unidades launchd/systemd/schtasks obsoletas ou paralelas. A maioria das configurações deve manter um Gateway por máquina; se você precisar de mais de um, isole portas + configuração/estado/workspace. Veja /gateway#multiple-gateways-same-host.System-level OpenClaw gateway service detecteddo doctor → existe uma unidade de sistema systemd enquanto o serviço de usuário está ausente. Remova ou desabilite a duplicata antes de permitir que o doctor instale um serviço de usuário, ou definaOPENCLAW_SERVICE_REPAIR_POLICY=externalse a unidade de sistema for o supervisor pretendido.Gateway service port does not match current gateway config→ o supervisor instalado ainda fixa o--portantigo. Executeopenclaw doctor --fixouopenclaw gateway install --force, depois reinicie o serviço do Gateway.
Relacionado:
Gateway do macOS para de responder silenciosamente e depois retoma quando você toca no painel
Use isto quando canais (Telegram, WhatsApp etc.) em um host macOS ficam silenciosos por minutos a horas de cada vez, e o Gateway parece voltar no momento em que você abre a IU de controle, acessa via SSH ou interage de outra forma com o host. Normalmente não há sintoma óbvio em openclaw status porque, 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.jsonem~/.openclaw/logs/stability/comerror.codedefinido como um código de rede transitório, comoENETDOWN,ENETUNREACH,EHOSTUNREACHouECONNREFUSED. - Linhas de
pmset -g logcomoEntering Sleep state due to 'Maintenance Sleep'ouen0 driver is slow (msg: WillChangeState to 0)alinhadas com os carimbos de data/hora da falha. Power Nap / Maintenance Sleep coloca brevemente o driver de Wi-Fi no estado 0; qualquerconnect()de saída que caia nessa janela pode falhar comENETDOWN, mesmo em um host que, de outra forma, tem conectividade de rede completa. - Saída de
launchctl printmostrandostate = not runningcom váriasrunsrecentes 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 de proteção de respawn não documentada após uma rajada de falhas que pode parar de honrarKeepAlive=trueaté que um gatilho externo, como login interativo, conexão do dashboard oulaunchctl kickstart, a rearme.
Assinaturas comuns:
- Um pacote de estabilidade cujo
error.codeéENETDOWNou um código semelhante, com a pilha de chamadas apontando para NodenetlookupAndConnect/Socket.connect. O OpenClaw2026.5.26e versões mais recentes classificam isso como erros de rede transitórios benignos, então eles não são mais propagados para o manipulador de exceções não capturadas de nível superior; se você estiver em uma versão mais antiga, atualize primeiro. - Longos períodos silenciosos que terminam no instante em que você se conecta à Control UI ou acessa o host por SSH: a atividade visível para o usuário é o que rearma a barreira de respawn do launchd, não algo que o dashboard faz com o Gateway.
- Contagem de
runsaumentando ao longo do dia sem uma linha correspondentereceived SIG*; shutting downem~/Library/Logs/openclaw/gateway.log: desligamentos limpos registram um sinal; falhas transitórias não.
O que fazer:
-
Atualize o Gateway se você estiver executando uma versão anterior a
2026.5.26. Após a atualização, erros futurosENETDOWNserão registrados como avisos, em vez de encerrar o processo. -
Reduza a atividade de manutenção durante o repouso em hosts Mac mini / desktop destinados a funcionar como servidores sempre ativos:
bash sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0Isso reduz significativamente, mas não elimina por completo, a oscilação subjacente do driver. O sistema ainda pode executar alguns repousos de manutenção para TCP keepalive e manutenção de mDNS, independentemente dessas flags.
-
Adicione um watchdog de vivacidade para que uma futura rajada de falhas estacionada pelo launchd seja detectada rapidamente:
bash # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(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.gatewayfiO objetivo é rearmar externamente a barreira de respawn;
KeepAlive=truesozinho não é suficiente no macOS após uma rajada de falhas.
Relacionado:
Gateway sai durante alto uso de memória
Use isto quando o Gateway desaparecer sob carga, o supervisor relatar uma reinicialização no estilo OOM, ou os logs mencionarem critical memory pressure bundle written.
openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics exportProcure por:
Reason: diagnostic.memory.pressure.criticalno pacote de estabilidade mais recente.Memory pressure:comcritical/rss_threshold,critical/heap_thresholdoucritical/rss_growth.- Valores de
V8 heap:próximos ao limite de heap. - Entradas de
Largest session files:, comoagents/<agent>/sessions/<session>.jsonlousessions/<session>.jsonl. - Contadores de memória de cgroup do Linux quando o Gateway é executado dentro de um contêiner ou serviço com limite de memória.
Assinaturas comuns:
critical memory pressure bundle writtenaparece pouco antes da reinicialização → o OpenClaw capturou um pacote de estabilidade pré-OOM. Inspecione-o comopenclaw gateway stability --bundle latest.memory pressure: level=critical ... memoryPressureSnapshot=disabledaparece nos logs do Gateway → o OpenClaw detectou pressão de memória crítica, mas o snapshot de estabilidade pré-OOM está desativado.Largest session files:aponta para um caminho de transcrição redigida muito grande → reduza o histórico de sessões retido, inspecione o crescimento da sessão ou mova transcrições antigas para fora do armazenamento ativo antes de reiniciar.- Bytes usados de
V8 heap:estão próximos ao limite de heap → reduza a pressão de prompts/sessões, reduza o trabalho concorrente 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 dentro de uma janela de amostragem. Verifique os logs mais recentes em busca de uma importação grande, saída de ferramenta descontrolada, novas tentativas repetidas ou um lote de trabalho de agentes enfileirado.- Pressão de memória crítica aparece nos logs, mas não existe pacote → esse é o padrão. Defina
diagnostics.memoryPressureSnapshot: truepara capturar o pacote de estabilidade pré-OOM em eventos futuros de pressão de memória crítica.
O pacote de estabilidade não contém payloads. Ele inclui evidências operacionais de memória e caminhos relativos de arquivos redigidos, não texto de mensagens, corpos de webhook, credenciais, tokens, cookies ou ids brutos de sessão. Anexe a exportação de diagnósticos a relatórios de bug em vez de copiar logs brutos.
Relacionado:
Gateway rejeitou configuração inválida
Use isto quando a inicialização do Gateway falhar com Invalid config ou os logs de hot reload disserem
que uma edição inválida foi ignorada.
openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctorProcure por:
Invalid config at ...config reload skipped (invalid config): ...Config write rejected: ...- Um arquivo
openclaw.json.rejected.*com carimbo de data/hora ao lado da configuração ativa - Um arquivo
openclaw.json.clobbered.*com carimbo de data/hora sedoctor --fixreparou uma edição direta quebrada - O OpenClaw mantém os 32 arquivos
.clobbered.*mais recentes para cada caminho de configuração e alterna os mais antigos
O que aconteceu
- A configuração não foi validada durante a inicialização, o hot reload ou uma escrita pertencente ao OpenClaw.
- A inicialização do Gateway falha de forma fechada em vez de reescrever
openclaw.json. - O hot reload ignora edições externas inválidas e mantém a configuração de runtime atual ativa.
- Escritas pertencentes ao OpenClaw rejeitam payloads inválidos/destrutivos antes do commit e salvam
.rejected.*. openclaw doctor --fixé responsável pelo reparo. Ele pode remover prefixos não JSON ou restaurar a última cópia reconhecidamente boa, preservando o payload rejeitado como.clobbered.*.- Quando muitos reparos acontecem para um caminho de configuração, o OpenClaw alterna arquivos
.clobbered.*mais antigos para que o payload reparado mais recente ainda fique disponível.
Inspecionar e reparar
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 doctorAssinaturas comuns
.clobbered.*existe → o doctor preservou uma edição externa quebrada enquanto reparava a configuração ativa..rejected.*existe → uma escrita de configuração pertencente ao OpenClaw falhou nas verificações de schema ou sobrescrita antes do commit.Config write rejected:→ a escrita tentou remover a forma exigida, reduzir o arquivo de forma brusca ou persistir uma configuração inválida.config reload skipped (invalid config):→ uma edição direta falhou na validação e foi ignorada pelo Gateway em execução.Invalid config at ...→ a inicialização falhou antes que os serviços do Gateway fossem iniciados.missing-meta-vs-last-good,gateway-mode-missing-vs-last-goodousize-drop-vs-last-good:*→ uma escrita pertencente ao OpenClaw foi rejeitada porque perdeu campos ou tamanho em comparação com o backup reconhecidamente bom mais recente.Config last-known-good promotion skipped→ o candidato continha placeholders de segredo redigidos, como***.
Opções de correção
- Execute
openclaw doctor --fixpara deixar o doctor reparar uma configuração prefixada/sobrescrita ou restaurar a última configuração reconhecidamente boa. - Copie apenas as chaves pretendidas de
.clobbered.*ou.rejected.*e aplique-as comopenclaw config setouconfig.patch. - Execute
openclaw config validateantes de reiniciar. - Se você editar manualmente, mantenha a configuração JSON5 completa, não apenas o objeto parcial que queria alterar.
Relacionado:
Avisos de probe do Gateway
Use isto quando openclaw gateway probe alcançar algo, mas ainda imprimir um bloco de aviso.
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-hostProcure por:
warnings[].codeeprimaryTargetIdna saída JSON.- Se o aviso é sobre fallback de SSH, múltiplos 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 de SSH falhou, mas o comando ainda tentou alvos diretos configurados/de loopback.multiple reachable gateway identities detected→ gateways distintos responderam, ou o OpenClaw não conseguiu provar que os alvos alcançáveis são o mesmo Gateway. Um túnel SSH, URL de proxy ou URL remota configurada para o mesmo Gateway é tratado como um Gateway com vários transportes, mesmo quando as portas de transporte diferem.Read-probe diagnostics are limited by gateway scopes (missing operator.read)→ a conexão funcionou, mas o RPC de detalhes é limitado por escopo; emparelhe a identidade do dispositivo ou use credenciais comoperator.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 timeout ou falhou. Trate isso como um Gateway alcançável com diagnósticos degradados; compareconnect.okeconnect.rpcOkna saída de--json.Capability: pairing-pendingougateway 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
gateway.auth.*/gateway.remote.*não resolvido → o material de autenticação estava indisponível neste caminho de comando para o alvo com falha.
Relacionado:
Canal conectado, mensagens não fluem
Se o estado do canal está conectado, mas o fluxo de mensagens está parado, concentre-se em política, 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 channelsProcure por:
- Política de DM (
pairing,allowlist,open,disabled). - Allowlist de 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ção do grupo.- Rastros de
pairing/ 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 Cron ou Heartbeat não executou ou não entregou, verifique primeiro o estado do agendador e depois o alvo de entrega.
openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followProcure por:
- Cron habilitado e próximo despertar presente.
- Status do histórico de execução do job (
ok,skipped,error). - Motivos de pular Heartbeat (
quiet-hours,requests-in-flight,cron-in-progress,lanes-busy,alerts-disabled,empty-heartbeat-file,no-tasks-due).
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 skippedcomreason=quiet-hours→ fora da janela de horas ativas.heartbeat skippedcomreason=empty-heartbeat-file→HEARTBEAT.mdexiste, mas contém apenas estruturas vazias de linha em branco, comentário, cabeçalho, fence ou checklist vazia, então o OpenClaw pula a chamada ao modelo.heartbeat skippedcomreason=no-tasks-due→HEARTBEAT.mdcontém um blocotasks:, mas nenhuma tarefa está vencida neste tick.heartbeat: unknown accountId→ id de conta inválido para o destino de entrega do Heartbeat.heartbeat skippedcomreason=dm-blocked→ o destino do Heartbeat foi resolvido para um destino no estilo DM enquantoagents.defaults.heartbeat.directPolicy(ou a substituição por agente) está definido comoblock.
Relacionado:
Nó pareado, ferramenta falha
Se um nó estiver pareado, mas as ferramentas falharem, isole o estado de primeiro plano, permissão e aprovação.
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw statusProcure 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:
Ferramenta de navegador falha
Use isto quando as ações da ferramenta de navegador falharem, mesmo que o Gateway em si esteja íntegro.
openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctorProcure por:
- Se
plugins.allowestá definido e incluibrowser. - Caminho válido do executável do navegador.
- Acessibilidade do perfil CDP.
- Disponibilidade local do Chrome para perfis
existing-session/user.
Assinaturas de Plugin / executável
unknown command "browser"ouunknown command 'browser'→ o Plugin de navegador incluído foi excluído porplugins.allow.- ferramenta de navegador ausente / indisponível enquanto
browser.enabled=true→plugins.allowexcluibrowser, então o Plugin nunca foi carregado. Failed to start Chrome CDP on port→ falha ao iniciar o processo do navegador.browser.executablePath not found→ o caminho configurado é inválido.browser.cdpUrl must be http(s) or ws(s)→ a URL CDP configurada usa um esquema sem suporte, comofile:ouftp:.browser.cdpUrl has invalid port→ a URL CDP configurada tem uma porta inválida ou fora do intervalo.Playwright is not available in this gateway build; '<feature>' is unsupported.→ a instalação atual do Gateway não tem a dependência central de runtime do navegador; reinstale ou atualize o OpenClaw e reinicie o Gateway. Snapshots ARIA e capturas de tela básicas de páginas ainda podem funcionar, mas navegação, snapshots de IA, capturas de tela de elementos por seletor CSS e exportação para PDF permanecem indisponíveis.
Assinaturas de Chrome MCP / existing-session
Could not find DevToolsActivePort for chrome→ a existing-session do Chrome MCP ainda não conseguiu anexar ao diretório de dados do navegador selecionado. Abra a página de inspeção do navegador, habilite a depuração remota, mantenha o navegador aberto, aprove o primeiro prompt de anexação e tente novamente. Se o estado de login não for necessário, prefira o perfil gerenciadoopenclaw.No Chrome tabs found for profile="user"→ o perfil de anexação do Chrome MCP não tem abas locais do Chrome abertas.Remote CDP for profile "<name>" is not reachable→ o endpoint CDP remoto configurado não está acessível a partir do host do Gateway.Browser attachOnly is enabled ... not reachableouBrowser attachOnly is enabled and CDP websocket ... is not reachable→ o perfil somente anexação não tem um alvo acessível, ou o endpoint HTTP respondeu, mas ainda assim não foi possível abrir o WebSocket CDP.
Assinaturas de elemento / captura de tela / upload
fullPage is not supported for element screenshots→ a solicitação de captura de tela misturou--full-pagecom--refou--element.element screenshots are not supported for existing-session profiles; use ref from snapshot.→ chamadas de captura de tela do Chrome MCP /existing-sessiondevem usar captura de página ou uma--refde snapshot, não--elementCSS.existing-session file uploads do not support element selectors; use ref/inputRef.→ hooks de upload do Chrome MCP precisam de refs de snapshot, não seletores CSS.existing-session file uploads currently support one file at a time.→ envie um upload por chamada em perfis Chrome MCP.existing-session dialog handling does not support timeoutMs.→ hooks de diálogo em perfis Chrome MCP não aceitam substituições de timeout.existing-session type does not support timeoutMs overrides.→ omitatimeoutMsparaact:typeem perfisprofile="user"/ Chrome MCP existing-session, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.existing-session evaluate does not support timeoutMs overrides.→ omitatimeoutMsparaact:evaluateem perfisprofile="user"/ Chrome MCP existing-session, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.response body is not supported for existing-session profiles yet.→responsebodyainda exige um navegador gerenciado ou perfil CDP bruto.- substituições obsoletas de viewport / modo escuro / localidade / offline em perfis somente anexação ou CDP remoto → execute
openclaw browser stop --browser-profile <name>para fechar a sessão de controle ativa e liberar o estado de emulação Playwright/CDP sem reiniciar todo o Gateway.
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 sendo aplicados agora.
1. O comportamento de auth e substituição de URL mudou
openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.modeO que verificar:
- Se
gateway.mode=remote, chamadas da CLI podem estar apontando para remoto enquanto seu serviço local está íntegro. - Chamadas explícitas com
--urlnão recorrem a credenciais armazenadas.
Assinaturas comuns:
gateway connect failed:→ destino de URL errado.unauthorized→ endpoint acessível, mas auth incorreto.
2. Bind e proteções de auth estão mais rígidos
openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --followO que verificar:
- Binds não loopback (
lan,tailnet,custom) precisam de um caminho de auth do Gateway válido: auth por token/senha compartilhado ou uma implantaçãotrusted-proxynão loopback configurada corretamente. - Chaves antigas como
gateway.tokennão substituemgateway.auth.token.
Assinaturas comuns:
refusing to bind gateway ... without auth→ bind não loopback sem um caminho de auth do Gateway válido.Connectivity probe: failedenquanto o runtime está em execução → Gateway ativo, mas inacessível com o auth/url atual.
3. O estado de pareamento e identidade do dispositivo mudou
openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctorO que verificar:
- Aprovações de dispositivo pendentes para dashboard/nós.
- Aprovações de pareamento DM pendentes após mudanças de política ou identidade.
Assinaturas comuns:
device identity required→ auth do dispositivo não satisfeito.pairing required→ remetente/dispositivo deve ser aprovado.
Se a configuração do serviço e o runtime ainda divergirem após as verificações, reinstale os metadados do serviço a partir do mesmo diretório de perfil/estado:
openclaw gateway install --forceopenclaw gateway restartRelacionado: