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 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ê.
• Vinculação além de loopback sem autenticação é bloqueada (guardrail de segurança).
• lan, tailnet e custom atualmente resolvem por caminhos BYOH somente IPv4.
• BYOH somente IPv6 não tem suporte nativo neste caminho hoje. Use um sidecar IPv4 ou proxy se o próprio host for somente IPv6.
• SIGUSR1 aciona uma reinicialização no 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).
• 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 raw, 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, ids de aprovação, nomes de canal/plugin 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 o gravador completamente.
• 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 novo 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/gravação/administração.
• As sondagens diagnósticas não fazem mutações para autenticação inicial de dispositivo: elas reutilizam um token de dispositivo existente em cache 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 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 auth-ref não resolvida são suprimidos para evitar falsos positivos.
• Quando a sondagem está habilitada, a saída JSON inclui gateway.version quando o Gateway em execução a relata; --require-rpc pode recorrer ao payload RPC status.runtimeVersion se a sondagem de handshake subsequente não puder fornecer metadados de versão.
• Use --require-rpc em scripts e automações quando um serviço escutando não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam saudáveis.
• --deep adiciona uma varredura de melhor esforço por instalações extras de launchd/systemd/schtasks. Quando vários serviços semelhantes a gateway são detectados, a saída legível por humanos 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 reinicialização do supervisor do Gateway quando o processo do serviço saiu de forma limpa para uma reinicialização por supervisor externo.
• --deep executa validação de configuração em modo ciente de plugins (pluginValidation: "full") e expõe avisos de manifesto de Plugin configurado (por exemplo, metadados ausentes de configuração de canal) para que verificações rápidas de instalação e atualização os capturem. O gateway status padrão mantém o caminho rápido somente leitura que ignora a validação de plugins.
• A saída legível por humanos inclui o caminho resolvido do arquivo de log, além do instantâneo de caminhos/validade da configuração CLI versus serviço, para ajudar a diagnosticar desvios de perfil ou de diretório de estado.

• Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores Environment= e EnvironmentFile= da unidade (incluindo %h, caminhos entre aspas, múltiplos arquivos e arquivos opcionais -).
• As verificações de desvio resolvem SecretRefs gateway.auth.token usando o ambiente de runtime mesclado (ambiente de comando do serviço primeiro, depois fallback para o ambiente 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 em que a senha pode vencer e nenhum candidato a token pode vencer), as verificações de desvio de token ignoram a resolução de token da 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 relata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da acessibilidade.
• 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 teve sucesso, mas a RPC com escopo de leitura está limitada. 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 subsequentes expiraram ou falharam. Isso também é acessibilidade degradada, não um Gateway inacessível.
• Assim como gateway status, a sondagem reutiliza autenticação de dispositivo existente em cache, 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á acessível.

Nível superior:

• ok: pelo menos um alvo está acessível.
• degraded: pelo menos um alvo aceitou uma conexão, mas não concluiu os diagnósticos RPC detalhados completos.
• capability: melhor capacidade vista entre alvos acessíveis (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope ou unknown).
• primaryTargetId: melhor alvo para tratar como 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 de descoberta reais usados nesta passagem de sondagem.

Por alvo (targets[].connect):

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

Por alvo (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 alvo.

• ssh_tunnel_failed: falha na configuração do túnel SSH; o comando recorreu a sondagens diretas.
• multiple_gateways: identidades distintas de gateway estavam acessíveis, ou o OpenClaw não conseguiu comprovar que os alvos acessíveis são o mesmo gateway. Um túnel SSH, URL de proxy ou URL remota configurada para o mesmo gateway não aciona este aviso.
• auth_secretref_unresolved: uma SecretRef de autenticação configurada não pôde ser resolvida para um alvo com falha.
• probe_scope_limited: conexão WebSocket 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 tudo de forma limpa sem um launchctl enable manual. Passe --disable para suprimir persistentemente KeepAlive e RunAtLoad, para que o Gateway não renasça 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 que o Gateway em execução faça uma verificação prévia do trabalho ativo e agende uma reinicialização coalescida depois que o trabalho ativo drenar. A reinicialização segura padrão aguarda o trabalho ativo até o gateway.reload.deferralTimeoutMs configurado (padrão de 5 minutos); quando esse orçamento expira, a reinicialização é forçada. Defina gateway.reload.deferralTimeoutMs como 0 para uma espera segura indefinida que nunca força. --safe não pode ser combinado com --force ou --wait.
• gateway restart --wait 30s substitui o orçamento configurado de drenagem da reinicialização para essa reinicialização. Números sem unidade são milissegundos; unidades como s, m e h são aceitas. --wait 0 espera indefinidamente.
• gateway restart --safe --skip-deferral executa a reinicialização segura ciente do OpenClaw, mas ignora o bloqueio de adiamento para que o Gateway emita a reinicialização imediatamente, mesmo quando bloqueadores forem relatados. É uma saída de emergência para operadores em adiamentos de execuções de tarefas travadas; requer --safe.
• gateway restart --force pula 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 scripts.

• 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 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 embutido.
• No modo de autenticação inferido, OPENCLAW_GATEWAY_PASSWORD somente no shell não relaxa os requisitos de token na 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 será bloqueada até que o modo seja definido explicitamente.