Solução de problemas

• model_not_found com um servidor local no estilo MLX/vLLM → verifique se baseUrl inclui /v1, se api é "openai-completions" para backends /v1/chat/completions e se models.providers.<provider>.models[].id é o id simples local do provedor. Selecione-o uma vez com o prefixo do provedor, por exemplo mlx/mlx-community/Qwen3-30B-A3B-6bit; mantenha a entrada do catálogo como mlx-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: defina models.providers.<provider>.models[].compat.requiresStringContent: true.
• validation.keys ou chaves de mensagem permitidas como ["role","content"] → o backend rejeita metadados de replay no estilo OpenAI em mensagens do Chat Completions. Correção: defina models.providers.<provider>.models[].compat.strictMessageKeys: true.
• incomplete turn detected ... stopReason=stop payloads=0 → o backend concluiu a solicitação do Chat Completions, mas não retornou texto de assistente visível ao usuário para esse turno. O OpenClaw tenta novamente uma vez turnos vazios compatíveis com OpenAI seguros para replay; falhas persistentes geralmente significam que o backend está emitindo conteúdo vazio/não textual ou suprimindo texto de resposta final.
• solicitações diretas pequenas têm sucesso, mas execuções de agente do OpenClaw falham com travamentos do backend/modelo (por exemplo, Gemma em algumas builds inferrs) → o transporte do OpenClaw provavelmente já está correto; o backend está falhando no formato maior de prompt do runtime do agente.
• as falhas diminuem após desabilitar ferramentas, mas não desaparecem → esquemas de ferramentas faziam parte da pressão, mas o problema restante ainda é capacidade do modelo/servidor upstream ou um bug do backend.

1. Defina compat.requiresStringContent: true para backends Chat Completions que aceitam apenas strings.
2. Defina compat.strictMessageKeys: true para backends Chat Completions estritos que aceitam apenas role e content em cada mensagem.
3. Defina compat.supportsTools: false para modelos/backends que não conseguem lidar de forma confiável com a superfície de esquema de ferramentas do OpenClaw.
4. Reduza a pressão do 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.
5. Se solicitações diretas pequenas continuarem passando enquanto turnos de agente do OpenClaw ainda travarem dentro do backend, trate isso como uma limitação upstream do servidor/modelo e registre uma reprodução lá com o formato de payload aceito.

• device identity required → contexto não seguro ou autenticação de dispositivo ausente.
• origin not allowed → o Origin do navegador não está em gateway.controlUi.allowedOrigins (ou você está conectando a partir 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 timestamp obsoleto) para o handshake atual.
• AUTH_TOKEN_MISMATCH com canRetryWithDeviceToken=true → o cliente pode fazer uma nova tentativa confiável com o 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 deviceToken explícito / scopes explí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; refaça o pareamento ou aprove o contrato de escopo solicitado em vez de rotacionar um token Gateway compartilhado.
• Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é token/senha compartilhado explícito primeiro, depois deviceToken explícito, depois token de dispositivo armazenado, depois token de bootstrap.
• No caminho assíncrono da interface de controle do Tailscale Serve, tentativas malsucedidas para o mesmo {scope, ip} são serializadas antes que o limitador registre a falha. Portanto, duas novas tentativas concorrentes inválidas do mesmo cliente podem expor retry later na segunda tentativa em vez de duas divergências simples.
• too many failed authentication attempts (retry later) de um cliente loopback com origem de navegador → falhas repetidas dessa mesma Origin normalizada são bloqueadas temporariamente; outra origem localhost usa um bucket separado.
• unauthorized repetido após essa nova tentativa → divergência de token compartilhado/token de dispositivo; atualize a configuração do token e aprove novamente/rotacione o token de dispositivo se necessário.
• gateway connect failed: → alvo de host/porta/url errado.

• Gateway start blocked: set gateway.mode=local ou existing config is missing gateway.mode → o modo de Gateway local não está habilitado, ou o arquivo de configuração foi sobrescrito e perdeu gateway.mode. Correção: defina gateway.mode="local" na sua configuração ou execute novamente openclaw onboard --mode local / openclaw setup para remarcar a configuração de modo local esperada. Se você estiver executando o OpenClaw via Podman, o caminho de configuração padrão é ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → bind fora de loopback sem um caminho de autenticação do Gateway válido (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) → unidades launchd/systemd/schtasks obsoletas ou paralelas existem. A maioria das configurações deve manter um Gateway por máquina; se você realmente precisar de mais de um, isole portas + configuração/estado/workspace. Consulte /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected do doctor → existe uma unidade de sistema systemd enquanto o serviço em nível de usuário está ausente. Remova ou desabilite a duplicata antes de permitir que o doctor instale um serviço de usuário, ou defina OPENCLAW_SERVICE_REPAIR_POLICY=external se a unidade de sistema for o supervisor pretendido.
• Gateway service port does not match current gateway config → o supervisor instalado ainda fixa o --port antigo. Execute openclaw doctor --fix ou openclaw gateway install --force, então reinicie o serviço do Gateway.

• A configuração não foi validada durante a inicialização, o recarregamento dinâmico ou uma gravação pertencente ao OpenClaw.
• A inicialização do Gateway falha fechada em vez de reescrever openclaw.json.
• O recarregamento dinâmico ignora edições externas inválidas e mantém a configuração de runtime atual ativa.
• Gravações 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 válida conhecida preservando o payload rejeitado como .clobbered.*.

• .clobbered.* existe → o doctor preservou uma edição externa quebrada enquanto reparava a configuração ativa.
• .rejected.* existe → uma gravação de configuração pertencente ao OpenClaw falhou em verificações de esquema ou sobrescrita antes do commit.
• Config write rejected: → a gravação tentou remover a forma obrigatória, reduzir o arquivo drasticamente 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 dos serviços do Gateway iniciarem.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good ou size-drop-vs-last-good:* → uma gravação pertencente ao OpenClaw foi rejeitada porque perdeu campos ou tamanho em comparação com o último backup válido conhecido.
• Config last-known-good promotion skipped → o candidato continha placeholders de segredos redigidos, como ***.

1. Execute openclaw doctor --fix para deixar o doctor reparar configuração prefixada/sobrescrita ou restaurar a última versão válida conhecida.
2. Copie apenas as chaves pretendidas de .clobbered.* ou .rejected.*, então aplique-as com openclaw config set ou config.patch.
3. Execute openclaw config validate antes de reiniciar.
4. Se você editar manualmente, mantenha a configuração JSON5 completa, não apenas o objeto parcial que queria alterar.

• 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 skipped with reason=quiet-hours → fora da janela de horas ativas.
• heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md existe, mas contém apenas linhas em branco / cabeçalhos markdown, então o OpenClaw pula a chamada ao modelo.
• heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md contém um bloco tasks:, mas nenhuma das tarefas vence neste tick.
• heartbeat: unknown accountId → ID de conta inválido para o destino de entrega do Heartbeat.
• heartbeat skipped with reason=dm-blocked → o destino do Heartbeat foi resolvido para um destino estilo DM enquanto agents.defaults.heartbeat.directPolicy (ou substituição por agente) está definido como block.

• unknown command "browser" or unknown command 'browser' → o Plugin de navegador incluído foi excluído por plugins.allow.
• browser tool missing / unavailable while browser.enabled=true → plugins.allow exclui browser, então o Plugin nunca foi carregado.
• Failed to start Chrome CDP on port → o processo do navegador falhou ao iniciar.
• 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, como file: ou ftp:.
• 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 principal de runtime do navegador; reinstale ou atualize o OpenClaw e reinicie o Gateway. Snapshots ARIA e capturas de tela básicas de página ainda podem funcionar, mas navegação, snapshots de IA, capturas de tela de elementos por seletor CSS e exportação de PDF permanecem indisponíveis.

• Could not find DevToolsActivePort for chrome → a sessão existente do Chrome MCP ainda não conseguiu se 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 com login não for necessário, prefira o perfil gerenciado openclaw.
• 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 reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → o perfil somente de anexação não tem um alvo acessível, ou o endpoint HTTP respondeu, mas o WebSocket CDP ainda não pôde ser aberto.

• fullPage is not supported for element screenshots → a solicitação de captura de tela misturou --full-page com --ref ou --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → chamadas de captura de tela do Chrome MCP / existing-session devem usar captura de página ou um --ref de snapshot, não CSS --element.
• 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 oferecem suporte a substituições de timeout.
• existing-session type does not support timeoutMs overrides. → omita timeoutMs para act:type em perfis profile="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. → omita timeoutMs para act:evaluate em perfis profile="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. → responsebody ainda exige um navegador gerenciado ou perfil CDP bruto.
• substituições antigas de viewport / modo escuro / localidade / offline em perfis somente de 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.

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

O que verificar:

• Se gateway.mode=remote, chamadas da CLI podem estar direcionando para o remoto enquanto seu serviço local está funcionando.
• Chamadas explícitas com --url não recorrem a credenciais armazenadas.

Assinaturas comuns:

• gateway connect failed: → destino de URL incorreto.
• unauthorized → endpoint acessível, mas autenticação incorreta.

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

O que verificar:

• Binds não loopback (lan, tailnet, custom) precisam de um caminho válido de autenticação do Gateway: autenticação por token/senha compartilhados ou uma implantação trusted-proxy não loopback configurada corretamente.
• Chaves antigas como gateway.token não substituem gateway.auth.token.

Assinaturas comuns:

• refusing to bind gateway ... without auth → bind não loopback sem um caminho válido de autenticação do Gateway.
• Connectivity probe: failed enquanto o runtime está em execução → Gateway ativo, mas inacessível com a autenticação/URL atual.

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

O que verificar:

• Aprovações de dispositivo pendentes para dashboard/nodes.
• Aprovações de pareamento por DM pendentes após mudanças de política ou identidade.

Assinaturas comuns:

• device identity required → autenticação do dispositivo não satisfeita.
• pairing required → remetente/dispositivo deve ser aprovado.