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/dev.
• 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 assumir 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" para 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 a reinicialização manual, enquanto aplicação/atualização da ferramenta/configuração do Gateway permanecem permitidas).
• Os manipuladores de SIGINT/SIGTERM interrompem o processo do Gateway, mas não restauram nenhum estado personalizado do terminal. Se você encapsular 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 filas/sessões, 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 ou ids brutos de sessão. Defina diagnostics.enabled: false para desabilitar totalmente o gravador.
• Em saídas fatais do Gateway, tempos limite de desligamento e falhas de inicialização após 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 novo com openclaw gateway stability --bundle latest; --limit, --type e --since-seq também se aplicam à saída de pacotes.

• gateway status permanece disponível para diagnóstico mesmo quando a configuração da CLI local 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/gravação/administração.
• Sondagens de diagnóstico não fazem mutações para autenticação de dispositivo pela primeira vez: elas reutilizam um token de dispositivo existente em cache quando há 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 configurados para autenticação da sondagem quando possível.
• Se uma SecretRef de autenticação obrigatória não for resolvida nesse caminho de comando, gateway status --json relata rpc.authWarning quando a conectividade/autenticação da sondagem falha; passe --token/--password explicitamente ou resolva primeiro a origem do segredo.
• Se a sondagem for bem-sucedida, avisos de referência de autenticação não resolvida são suprimidos para evitar falsos positivos.
• Use --require-rpc em scripts e automação quando um serviço em escuta não for suficiente e você também precisar que chamadas RPC de escopo de leitura estejam íntegras.
• --deep adiciona uma varredura de melhor esforço por 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 relata 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.
• --deep executa a validação de configuração em modo ciente de plugins (pluginValidation: "full") e expõe avisos de manifestos de plugins configurados (por exemplo, metadados ausentes de configuração de canal) para que verificações de fumaça de instalação e atualização os detectem. O gateway status padrão mantém o caminho rápido somente leitura que ignora a validação de plugins.
• A saída humana inclui o caminho resolvido do log em arquivo mais o instantâneo de caminhos/validade da configuração da CLI versus serviço para ajudar a diagnosticar desvios de perfil ou diretório de estado.

• Em instalações Linux systemd, as verificações de desvio de autenticação de serviço leem valores de Environment= e EnvironmentFile= da unit (incluindo %h, caminhos entre aspas, vários arquivos e arquivos opcionais com -).
• Verificações de desvio resolvem SecretRefs de gateway.auth.token usando o env de runtime mesclado (primeiro o env do 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 como password/none/trusted-proxy, ou modo não definido quando a senha pode vencer e nenhum candidato de token pode vencer), as verificações de desvio de token ignoram a resolução do token de configuração.

• Reachable: yes significa que pelo menos um destino aceitou uma conexão WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only relata o que a sondagem conseguiu comprovar sobre autenticação. É separado da acessibilidade.
• Read probe: ok significa que chamadas RPC detalhadas de 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 de escopo de leitura está limitado. Isso é relatado como acessibilidade degradada, não falha completa.
• Read probe: failed após Connect: ok significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura seguintes atingiram o tempo limite ou falharam. Isso também é acessibilidade degradada, não um Gateway inacessível.
• Como gateway status, a sondagem reutiliza a autenticação de dispositivo existente em cache, mas não cria identidade de dispositivo pela primeira vez nem estado de pareamento.
• O código de saída só é diferente de zero quando nenhum destino sondado está acessível.

Nível superior:

• ok: pelo menos um destino está acessível.
• degraded: pelo menos um destino aceitou uma conexão, mas não concluiu diagnósticos RPC detalhados completos.
• capability: melhor capacidade observada entre os destinos acessíveis (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope ou unknown).
• primaryTargetId: melhor destino a tratar como o vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e então local loopback.
• warnings[]: registros de aviso de melhor esforço com code, message e targetIds opcional.
• 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 de descoberta reais usados nesta passagem de sondagem.

Por destino (targets[].connect):

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

Por destino (targets[].auth):

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

• ssh_tunnel_failed: a configuração do túnel SSH falhou; o comando recorreu a sondagens diretas.
• multiple_gateways: mais de um destino estava acessí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 destino 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, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Use gateway restart para reiniciar um serviço gerenciado. Não encadeie gateway stop e gateway start como substituto de reinicialização.
• No macOS, gateway stop usa launchctl bootout por padrão, o que remove o LaunchAgent da sessão de inicialização atual sem persistir uma desativação — a recuperação automática do KeepAlive permanece ativa para falhas futuras, e gateway start reativa de forma limpa sem um launchctl enable manual. Passe --disable para suprimir persistentemente KeepAlive e RunAtLoad, de modo que o gateway não seja reiniciado até o próximo gateway start explícito; use isso quando uma parada manual deve sobreviver a reinicializações ou reinícios do sistema.
• gateway restart --safe solicita ao Gateway em execução que faça uma pré-verificação do trabalho ativo do OpenClaw e adie a reinicialização até que a entrega de respostas, execuções incorporadas e execuções de tarefas sejam drenadas. --safe não pode ser combinado com --force ou --wait.
• gateway restart --wait 30s substitui o orçamento configurado de drenagem de reinicialização para essa reinicialização. Números sem unidade são milissegundos; unidades como s, m e h são aceitas. --wait 0 aguarda indefinidamente.
• gateway restart --safe --skip-deferral executa a reinicialização segura ciente do OpenClaw, mas ignora a barreira de adiamento, para que o Gateway emita a reinicialização imediatamente mesmo quando bloqueadores forem relatados. Escape operacional para adiamentos de execuções de tarefas travadas; requer --safe.
• gateway restart --force ignora a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já tiver inspecionado os bloqueadores de tarefas 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 de ambiente do serviço.
• Se a autenticação por token exige um token e o SecretRef de token configurado não é 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 baseado em SecretRef em vez de --password inline.
• No modo de autenticação inferida, OPENCLAW_GATEWAY_PASSWORD disponível apenas no shell não relaxa 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 gateway.auth.token e gateway.auth.password estiverem configurados e gateway.auth.mode não estiver definido, a instalação é bloqueada até que o modo seja definido explicitamente.