Gateway

• Por padrão, o Gateway se recusa a iniciar a menos que gateway.mode=local esteja definido em ~/.openclaw/openclaw.json. Use --allow-unconfigured para execuções ad hoc/de desenvolvimento.
• Espera-se que openclaw onboard --mode local e openclaw setup gravem gateway.mode=local. Se o arquivo existir, mas gateway.mode estiver ausente, trate isso como uma configuração quebrada ou sobrescrita e repare-a, em vez de presumir implicitamente o modo local.
• Se o arquivo existir e gateway.mode estiver ausente, o Gateway trata isso como dano suspeito à configuração e se recusa a "adivinhar local" por você.
• Vincular além de loopback sem autenticação é bloqueado (proteção de segurança).
• SIGUSR1 aciona uma reinicialização dentro do processo quando autorizada (commands.restart é habilitado por padrão; defina commands.restart: false para bloquear reinicialização manual, enquanto aplicação/atualização de ferramenta/configuração do gateway continuam permitidas).
• Os manipuladores de SIGINT/SIGTERM interrompem o processo do gateway, mas não restauram nenhum estado personalizado do terminal. Se você envolver a CLI com uma TUI ou entrada em modo bruto, restaure o terminal antes de sair.

• Os registros mantêm metadados operacionais: nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de fila/sessão, nomes de canais/plugins e resumos de sessão redigidos. Eles não mantêm texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies, valores secretos, nomes de host nem ids brutos de sessão. Defina diagnostics.enabled: false para desabilitar totalmente o gravador.
• Em saídas fatais do Gateway, timeouts de desligamento e falhas de inicialização de reinicialização, o OpenClaw grava o mesmo snapshot de diagnóstico em ~/.openclaw/logs/stability/openclaw-stability-*.json quando o gravador tem eventos. Inspecione o pacote mais recente com openclaw gateway stability --bundle latest; --limit, --type e --since-seq também se aplicam à saída do pacote.

• gateway status permanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou inválida.
• O gateway status padrão comprova o estado do serviço, a conexão WebSocket e a capacidade de autenticação visível no momento do handshake. Ele não comprova operações de leitura/escrita/administração.
• As sondagens de diagnóstico não fazem mutações para autenticação inicial de dispositivo: elas reutilizam um token de dispositivo em cache existente quando houver um, mas não criam uma nova identidade de dispositivo da CLI nem um registro de pareamento de dispositivo somente leitura apenas para verificar o status.
• gateway status resolve SecretRefs de autenticação configuradas para autenticação da sondagem quando possível.
• Se uma SecretRef de autenticação obrigatória não for resolvida neste caminho de comando, gateway status --json reportará rpc.authWarning quando a conectividade/autenticação da sondagem falhar; passe --token/--password explicitamente ou resolva a origem do segredo primeiro.
• Se a sondagem for bem-sucedida, avisos de auth-ref não resolvida serão suprimidos para evitar falsos positivos.
• Use --require-rpc em scripts e automação quando um serviço ouvindo não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam íntegras.
• --deep adiciona uma varredura de melhor esforço em busca de instalações extras de launchd/systemd/schtasks. Quando vários serviços semelhantes ao Gateway são detectados, a saída humana imprime dicas de limpeza e avisa que a maioria das configurações deve executar um Gateway por máquina.
• --deep também informa uma transferência recente de reinício do supervisor do Gateway quando o processo do serviço saiu corretamente para um reinício por supervisor externo.
• A saída humana inclui o caminho resolvido do arquivo de log mais o instantâneo de caminhos/validade da configuração da CLI versus serviço para ajudar a diagnosticar divergência de perfil ou diretório de estado.

• Em instalações Linux systemd, as verificações de divergência de autenticação do serviço leem valores de Environment= e EnvironmentFile= da unidade (incluindo %h, caminhos entre aspas, vários arquivos e arquivos opcionais com -).
• As verificações de divergência resolvem SecretRefs de gateway.auth.token usando o env de runtime mesclado (primeiro o env de comando do serviço, depois o fallback do env do processo).
• Se a autenticação por token não estiver efetivamente ativa (gateway.auth.mode explícito de password/none/trusted-proxy, ou modo não definido em que a senha pode vencer e nenhum candidato a token pode vencer), as verificações de divergência de token ignoram a resolução do token de configuração.

• Reachable: yes significa que pelo menos um alvo aceitou uma conexão WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only informa o que a sondagem conseguiu comprovar sobre autenticação. É separado da alcançabilidade.
• Read probe: ok significa que chamadas RPC de detalhe com escopo de leitura (health/status/system-presence/config.get) também foram bem-sucedidas.
• Read probe: limited - missing scope: operator.read significa que a conexão foi bem-sucedida, mas o RPC com escopo de leitura está limitado. Isso é relatado como alcançabilidade degradada, não falha completa.
• Read probe: failed depois de Connect: ok significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura posteriores atingiram tempo limite ou falharam. Isso também é alcançabilidade degradada, não um Gateway inalcançável.
• Assim como gateway status, a sondagem reutiliza a autenticação de dispositivo em cache existente, mas não cria identidade de dispositivo inicial nem estado de pareamento.
• O código de saída é diferente de zero apenas quando nenhum alvo sondado está alcançável.

Nível superior:

• ok: pelo menos um alvo está alcançável.
• degraded: pelo menos um alvo aceitou uma conexão, mas não concluiu os diagnósticos RPC de detalhe completos.
• capability: melhor capacidade vista entre alvos alcançáveis (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope ou unknown).
• primaryTargetId: melhor alvo para tratar como o vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e, por fim, local loopback.
• warnings[]: registros de aviso de melhor esforço com code, message e targetIds opcionais.
• network: dicas de URL de local loopback/tailnet derivadas da configuração atual e da rede do host.
• discovery.timeoutMs e discovery.count: o orçamento/contagem de resultados real de descoberta usado para esta passagem de sondagem.

Por alvo (targets[].connect):

• ok: alcançabilidade após conexão + classificação degradada.
• rpcOk: sucesso completo do RPC de detalhe.
• scopeLimited: RPC de detalhe falhou por falta de escopo de operador.

Por alvo (targets[].auth):

• role: função de autenticação reportada em hello-ok quando disponível.
• scopes: escopos concedidos reportados em hello-ok quando disponíveis.
• capability: a classificação de capacidade de autenticação exposta para esse alvo.

• ssh_tunnel_failed: a configuração do túnel SSH falhou; o comando voltou para sondagens diretas.
• multiple_gateways: mais de um alvo estava alcançável; isso é incomum, a menos que você execute intencionalmente perfis isolados, como um bot de resgate.
• auth_secretref_unresolved: uma SecretRef de autenticação configurada não pôde ser resolvida para um alvo com falha.
• probe_scope_limited: a conexão WebSocket foi bem-sucedida, mas a sondagem de leitura foi limitada pela ausência de operator.read.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Use gateway restart para reiniciar um serviço gerenciado. Não encadeie gateway stop e gateway start como substituto de reinício; no macOS, gateway stop desativa intencionalmente o LaunchAgent antes de pará-lo.
• gateway restart --safe solicita que o Gateway em execução faça uma pré-verificação do trabalho ativo do OpenClaw e adie o reinício até que a entrega de respostas, execuções embutidas e execuções de tarefas sejam drenadas. --safe não pode ser combinado com --force nem --wait.
• gateway restart --wait 30s substitui o orçamento configurado de drenagem de reinício para esse reinício. Números sem unidade são milissegundos; unidades como s, m e h são aceitas. --wait 0 espera indefinidamente.
• gateway restart --force ignora a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já tiver inspecionado os bloqueadores de tarefa listados e quiser o gateway de volta agora.
• Comandos de ciclo de vida aceitam --json para scripting.

• Quando a autenticação por token exige um token e gateway.auth.token é gerenciado por SecretRef, gateway install valida que o SecretRef pode ser resolvido, mas não persiste o token resolvido nos metadados do ambiente do serviço.
• Se a autenticação por token exige um token e o SecretRef de token configurado não pode ser resolvido, a instalação falha de forma fechada em vez de persistir texto simples de fallback.
• Para autenticação por senha em gateway run, prefira OPENCLAW_GATEWAY_PASSWORD, --password-file ou um gateway.auth.password apoiado por SecretRef em vez de --password inline.
• No modo de autenticação inferida, OPENCLAW_GATEWAY_PASSWORD apenas no shell não flexibiliza os requisitos de token de instalação; use configuração durável (gateway.auth.password ou env de configuração) ao instalar um serviço gerenciado.
• Se tanto gateway.auth.token quanto gateway.auth.password estiverem configurados e gateway.auth.mode não estiver definido, a instalação será bloqueada até que o modo seja definido explicitamente.