English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Start here

Solução geral de problemas

Se você tem apenas 2 minutos, use esta página como ponto de entrada para triagem.

Primeiros 60 segundos

Execute esta sequência exata em ordem:

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

Boa saída em uma linha:

  • openclaw status → mostra os canais configurados e nenhum erro óbvio de autenticação.
  • openclaw status --all → o relatório completo está presente e pode ser compartilhado.
  • openclaw gateway probe → o alvo de Gateway esperado está acessível (Reachable: yes). Capability: ... informa qual nível de autenticação a sonda conseguiu comprovar, e Read probe: limited - missing scope: operator.read é diagnóstico degradado, não uma falha de conexão.
  • openclaw gateway status → Runtime: running, Connectivity probe: ok e uma linha Capability: ... plausível. Use --require-rpc se você também precisar de prova RPC com escopo de leitura.
  • openclaw doctor → nenhum erro bloqueante de configuração/serviço.
  • openclaw channels status --probe → um Gateway acessível retorna o estado de transporte ao vivo por conta mais resultados de sonda/auditoria, como works ou audit ok; se o Gateway estiver inacessível, o comando recorre a resumos baseados apenas na configuração.
  • openclaw logs --follow → atividade estável, sem erros fatais repetidos.

Anthropic contexto longo 429

Se você vir: HTTP 429: rate_limit_error: Extra usage is required for long context requests, acesse /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

Backend local compatível com OpenAI funciona diretamente, mas falha no OpenClaw

Se o seu backend local ou auto-hospedado /v1 responde a pequenas sondas diretas /v1/chat/completions, mas falha em openclaw infer model run ou em rodadas normais do agente:

  1. Se o erro mencionar que messages[].content espera uma string, defina models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Se o backend ainda falhar apenas em rodadas do agente OpenClaw, defina models.providers.<provider>.models[].compat.supportsTools: false e tente novamente.
  3. Se chamadas diretas mínimas ainda funcionarem, mas prompts maiores do OpenClaw travarem o backend, trate o problema restante como uma limitação do modelo/servidor upstream e continue no runbook detalhado: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

Instalação de Plugin falha com extensões openclaw ausentes

Se a instalação falhar com package.json missing openclaw.extensions, o pacote do Plugin está usando um formato antigo que o OpenClaw não aceita mais.

Corrija no pacote do Plugin:

  1. Adicione openclaw.extensions ao package.json.
  2. Aponte as entradas para arquivos de runtime compilados (geralmente ./dist/index.js).
  3. Republique o Plugin e execute openclaw plugins install <package> novamente.

Exemplo:

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Referência: Arquitetura de Plugin

Plugin presente, mas bloqueado por propriedade suspeita

Se openclaw doctor, a configuração inicial ou avisos de inicialização mostrarem:

blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
plugin present but blocked

os arquivos do Plugin pertencem a um usuário Unix diferente do processo que os carrega. Não remova a configuração do Plugin. Corrija a propriedade dos arquivos ou execute o OpenClaw como o mesmo usuário que possui o diretório de estado.

Instalações Docker normalmente rodam como node (uid 1000). Para a configuração Docker padrão, repare as montagens bind do host:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

Se você executa intencionalmente o OpenClaw como root, repare a raiz gerenciada do Plugin para propriedade de root:

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

Documentação mais detalhada:

Árvore de decisão

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]
Sem respostas 
openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow

Uma boa saída se parece com:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable
  • Seu canal mostra o transporte conectado e, quando houver suporte, works ou audit ok em channels status --probe
  • O remetente aparece como aprovado (ou a política de DM está aberta/lista de permissões)

Assinaturas comuns nos logs:

  • drop guild message (mention required → o bloqueio por menção impediu a mensagem no Discord.
  • pairing request → o remetente não está aprovado e aguarda aprovação de pareamento por DM.
  • blocked / allowlist nos logs do canal → o remetente, sala ou grupo está filtrado.

Páginas detalhadas:

O Painel ou a Interface de Controle não conecta 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Uma boa saída se parece com:

  • Dashboard: http://... é mostrado em openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable
  • Nenhum loop de autenticação nos logs

Assinaturas comuns nos logs:

  • device identity required → o contexto HTTP/não seguro não consegue concluir a autenticação do dispositivo.
  • origin not allowed → o Origin do navegador não é permitido para o alvo de Gateway da Interface de Controle.
  • AUTH_TOKEN_MISMATCH com dicas de nova tentativa (canRetryWithDeviceToken=true) → uma nova tentativa confiável com token de dispositivo pode ocorrer automaticamente.
  • Essa nova tentativa com token em cache reutiliza o conjunto de escopos em cache armazenado com o token de dispositivo pareado. Chamadores com deviceToken explícito / scopes explícitos mantêm o conjunto de escopos solicitado.
  • No caminho assíncrono da Interface de Controle via Tailscale Serve, tentativas com falha para o mesmo {scope, ip} são serializadas antes que o limitador registre a falha, então uma segunda nova tentativa ruim concorrente já pode mostrar retry later.
  • too many failed authentication attempts (retry later) de uma origem de navegador localhost → falhas repetidas desse mesmo Origin são bloqueadas temporariamente; outra origem localhost usa um bucket separado.
  • unauthorized repetido após essa nova tentativa → token/senha incorreto, incompatibilidade de modo de autenticação ou token de dispositivo pareado obsoleto.
  • gateway connect failed: → a UI está apontando para a URL/porta errada ou para um Gateway inacessível.

Páginas detalhadas:

O Gateway não inicia ou o serviço está instalado, mas não está em execução 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Uma boa saída se parece com:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable

Assinaturas comuns nos logs:

  • Gateway start blocked: set gateway.mode=local ou existing config is missing gateway.mode → o modo do Gateway é remoto, ou o arquivo de configuração não tem a marcação de modo local e deve ser reparado.
  • refusing to bind gateway ... without auth → bind fora de local 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 ou EADDRINUSE → a porta já está em uso.

Páginas detalhadas:

O canal conecta, mas as mensagens não fluem 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Uma boa saída se parece com:

  • O transporte do canal está conectado.
  • As verificações de pareamento/lista de permissões passam.
  • Menções são detectadas quando exigidas.

Assinaturas comuns nos logs:

  • mention required → o bloqueio por menção em grupo impediu o processamento.
  • pairing / pending → o remetente de DM ainda não está aprovado.
  • not_in_channel, missing_scope, Forbidden, 401/403 → problema de token de permissão do canal.

Páginas detalhadas:

Cron ou Heartbeat não disparou ou não entregou 
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

Uma boa saída se parece com:

  • cron.status mostra habilitado com o próximo despertar.
  • cron runs mostra entradas ok recentes.
  • Heartbeat está habilitado e não está fora do horário ativo.

Assinaturas comuns nos logs:

  • cron: scheduler disabled; jobs will not run automatically → Cron está desabilitado.
  • heartbeat skipped com reason=quiet-hours → fora dos horários ativos configurados.
  • heartbeat skipped com reason=empty-heartbeat-file → HEARTBEAT.md existe, mas contém apenas estrutura vazia/somente com cabeçalho.
  • heartbeat skipped com reason=no-tasks-due → o modo de tarefas de HEARTBEAT.md está ativo, mas nenhum dos intervalos de tarefa venceu ainda.
  • heartbeat skipped com reason=alerts-disabled → toda a visibilidade do Heartbeat está desabilitada (showOk, showAlerts e useIndicator estão todos desligados).
  • requests-in-flight → a via principal está ocupada; o despertar do Heartbeat foi adiado.
  • unknown accountId → a conta de destino de entrega do Heartbeat não existe.

Páginas detalhadas:

O Node está pareado, mas a ferramenta falha em camera canvas screen exec 
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

Uma boa saída se parece com:

  • O Node aparece como conectado e pareado para a função node.
  • Existe capacidade para o comando que você está invocando.
  • O estado de permissão está concedido para a ferramenta.

Assinaturas comuns nos logs:

  • NODE_BACKGROUND_UNAVAILABLE → traga o app Node para o primeiro plano.
  • *_PERMISSION_REQUIRED → a permissão do SO foi negada/está ausente.
  • SYSTEM_RUN_DENIED: approval required → a aprovação de exec está pendente.
  • SYSTEM_RUN_DENIED: allowlist miss → comando não está na lista de permissões de exec.

Páginas detalhadas:

Exec pede aprovação de repente 
openclaw config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask
openclaw gateway restart

O que mudou:

  • Se tools.exec.host não estiver definido, o padrão é auto.
  • host=auto resolve para sandbox quando um runtime de sandbox está ativo; caso contrário, para gateway.
  • host=auto é apenas roteamento; o comportamento sem prompt "YOLO" vem de security=full mais ask=off no Gateway/Node.
  • Em gateway e node, tools.exec.security não definido usa full como padrão.
  • tools.exec.ask não definido usa off como padrão.
  • Resultado: se você está vendo aprovações, alguma política local do host ou por sessão tornou exec mais restrito do que os padrões atuais.

Restaurar o comportamento padrão atual sem aprovação:

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

Alternativas mais seguras:

  • Defina apenas tools.exec.host=gateway se você só quiser roteamento estável do host.
  • Use security=allowlist com ask=on-miss se você quiser exec no host, mas ainda quiser revisão em falhas da lista de permissões.
  • Ative o modo sandbox se você quiser que host=auto volte a resolver para sandbox.

Assinaturas comuns de log:

  • Approval required. → comando está aguardando /approve ....
  • SYSTEM_RUN_DENIED: approval required → a aprovação de exec no host Node está pendente.
  • exec host=sandbox requires a sandbox runtime for this session → seleção implícita/explícita de sandbox, mas o modo sandbox está desativado.

Páginas detalhadas:

Ferramenta de navegador falha 
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor

Uma boa saída se parece com:

  • O status do navegador mostra running: true e um navegador/perfil escolhido.
  • openclaw inicia, ou user consegue ver abas locais do Chrome.

Assinaturas comuns de log:

  • unknown command "browser" ou unknown command 'browser' → plugins.allow está definido e não inclui browser.
  • Failed to start Chrome CDP on port → a inicialização do navegador local falhou.
  • browser.executablePath not found → o caminho do binário configurado está errado.
  • browser.cdpUrl must be http(s) or ws(s) → a URL CDP configurada usa um esquema sem suporte.
  • browser.cdpUrl has invalid port → a URL CDP configurada tem uma porta inválida ou fora do intervalo.
  • No Chrome tabs found for profile="user" → o perfil de anexação MCP do Chrome não tem abas locais do Chrome abertas.
  • Remote CDP for profile "<name>" is not reachable → o endpoint CDP remoto configurado não é acessível a partir deste host.
  • Browser attachOnly is enabled ... not reachable ou Browser attachOnly is enabled and CDP websocket ... is not reachable → o perfil somente anexação não tem nenhum destino CDP ativo.
  • viewport obsoleto / substituições de 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 sem reiniciar o Gateway.

Páginas detalhadas:

Relacionados