Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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:
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:
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:
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:
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:
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:
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:
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