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 local simples do provedor. Selecione-o com o prefixo do provedor uma vez, 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.
• incomplete turn detected ... stopReason=stop payloads=0 → o backend concluiu a solicitação de Chat Completions, mas não retornou texto de assistente visível ao usuário para esse turno. OpenClaw tenta novamente uma vez turnos vazios compatíveis com OpenAI que são seguros para replay; 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 travamentos de backend/modelo (por exemplo, Gemma em alguns builds inferrs) → o transporte do OpenClaw provavelmente já está correto; o backend está falhando no formato de prompt maior do runtime do agente.
• as falhas diminuem após desativar ferramentas, mas não desaparecem → os esquemas de ferramentas eram 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 string.
2. Defina compat.supportsTools: false para modelos/backends que não conseguem lidar de forma confiável com a superfície de esquemas de ferramentas do OpenClaw.
3. 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 robusto a contexto longo.
4. Se solicitações diretas pequenas continuarem passando enquanto turnos de agente do OpenClaw ainda travarem dentro do backend, trate 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 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.
• Fora desse caminho de nova tentativa, a precedência da autenticação de conexão é primeiro token/senha compartilhado explícito, depois deviceToken explícito, depois token de dispositivo armazenado e depois token de bootstrap.
• No caminho assíncrono da interface de controle via Tailscale Serve, tentativas com falha para o mesmo {scope, ip} são serializadas antes de o limitador registrar a falha. Portanto, duas novas tentativas ruins concorrentes do mesmo cliente podem expor retry later na segunda tentativa em vez de duas incompatibilidades simples.
• too many failed authentication attempts (retry later) de um cliente de navegador com origem loopback → 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 reaprove/gire o token de dispositivo se necessário.
• gateway connect failed: → destino de host/porta/url incorreto.

• 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 recarimbar 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 → vinculação sem loopback sem um caminho de autenticação de 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) → 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. Consulte /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected do doctor → existe uma unidade systemd de sistema 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 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 e depois reinicie o serviço do gateway.

• A configuração não foi validada durante a inicialização, o recarregamento a quente ou uma gravação de propriedade do OpenClaw.
• A inicialização do Gateway falha fechada em vez de reescrever openclaw.json.
• O recarregamento a quente ignora edições externas inválidas e mantém a configuração de runtime atual ativa.
• Gravações de propriedade do OpenClaw rejeitam cargas úteis inválidas/destrutivas 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 enquanto preserva a carga útil rejeitada como .clobbered.*.

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

• .clobbered.* existe → o doctor preservou uma edição externa quebrada ao reparar a configuração ativa.
• .rejected.* existe → uma gravação de configuração de propriedade do 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 drasticamente o arquivo ou persistir 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 de os 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 de propriedade do OpenClaw foi rejeitada porque perdeu campos ou tamanho em comparação com o backup da última versão válida conhecida.
• Config last-known-good promotion skipped → o candidato continha placeholders de segredos redigidos, como ***.

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

• cron: scheduler disabled; jobs will not run automatically → cron desabilitado.
• cron: timer tick failed → tique do agendador falhou; verifique erros de arquivo/log/runtime.
• heartbeat skipped com reason=quiet-hours → fora da janela de horas ativas.
• heartbeat skipped com 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 com reason=no-tasks-due → HEARTBEAT.md contém um bloco tasks:, mas nenhuma das tarefas vence neste tique.
• heartbeat: unknown accountId → ID de conta inválido para o destino de entrega do Heartbeat.
• heartbeat skipped com reason=dm-blocked → o destino do Heartbeat foi resolvido para um destino do tipo DM enquanto agents.defaults.heartbeat.directPolicy (ou a substituição por agente) está definido como block.

• unknown command "browser" ou unknown command 'browser' → o plugin de navegador incluído está excluído por plugins.allow.
• ferramenta de navegador ausente / indisponível enquanto 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 de navegador; reinstale ou atualize o OpenClaw e reinicie o Gateway. Snapshots ARIA e capturas de tela básicas da 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 existing-session 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 autenticado 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 ou Browser attachOnly is enabled and CDP websocket ... is not reachable → o perfil somente anexação não tem destino 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 --element CSS.
• 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 dão 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 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.

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

O que verificar:

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

Assinaturas comuns:

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

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

O que verificar:

• Binds que não sã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 list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

O que verificar:

• Aprovações de dispositivo pendentes para painel/Nodes.
• Aprovações de pareamento de 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.