openclaw gateway ….
Descoberta Bonjour
Configuração local de mDNS + DNS-SD de área ampla.
Visão geral de descoberta
Como o OpenClaw anuncia e encontra gateways.
Configuração
Chaves de configuração de gateway de nível superior.
Executar o Gateway
Execute um processo local do Gateway:Comportamento de inicialização
Comportamento de inicialização
- Por padrão, o Gateway se recusa a iniciar a menos que
gateway.mode=localesteja definido em~/.openclaw/openclaw.json. Use--allow-unconfiguredpara execuções ad hoc/dev. - Espera-se que
openclaw onboard --mode localeopenclaw setupgravemgateway.mode=local. Se o arquivo existir, masgateway.modeestiver 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.modeestiver 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,tailnetecustomatualmente 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.
SIGUSR1aciona uma reinicialização no processo quando autorizada (commands.restarté habilitado por padrão; definacommands.restart: falsepara bloquear reinicialização manual, enquanto aplicação/atualização de ferramenta/configuração do gateway continuam permitidas).- Manipuladores de
SIGINT/SIGTERMinterrompem 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.
Opções
Porta WebSocket (o padrão vem da configuração/env; geralmente
18789).Modo de vinculação do listener.
lan, tailnet e custom atualmente resolvem por caminhos somente IPv4.Substituição do modo de autenticação.
Substituição de token (também define
OPENCLAW_GATEWAY_TOKEN para o processo).Substituição de senha.
Lê a senha do gateway a partir de um arquivo.
Expõe o Gateway via Tailscale.
Redefine a configuração serve/funnel do Tailscale ao encerrar.
Espera um endereço IPv4 hoje. Para BYOH somente IPv6, coloque um sidecar IPv4 ou proxy na frente do Gateway e aponte o OpenClaw para esse endpoint IPv4.
Permite iniciar o gateway sem
gateway.mode=local na configuração. Ignora o guard de inicialização apenas para bootstrap ad hoc/dev; não grava nem repara o arquivo de configuração.Cria uma configuração dev + workspace se ausentes (ignora BOOTSTRAP.md).
Redefine configuração dev + credenciais + sessões + workspace (requer
--dev).Encerra qualquer listener existente na porta selecionada antes de iniciar.
Logs detalhados.
Mostra apenas logs do backend da CLI no console (e habilita stdout/stderr).
Estilo de log WebSocket.
Alias para
--ws-log compact.Registra eventos brutos de stream do modelo em jsonl.
Caminho do jsonl de stream bruto.
Reiniciar o Gateway
openclaw gateway restart --safe pede ao Gateway em execução para fazer uma pré-verificação do trabalho ativo e agendar uma reinicialização coalescida depois que o trabalho ativo for drenado. A reinicialização segura padrão aguarda 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. restart simples mantém o comportamento existente do gerenciador de serviço; --force continua sendo o caminho de substituição imediata.
openclaw gateway restart --safe --skip-deferral executa a mesma reinicialização coordenada ciente do OpenClaw que --safe, mas ignora o gate de adiamento por trabalho ativo, então o Gateway emite a reinicialização imediatamente mesmo quando bloqueadores são relatados. Use-o como a válvula de escape do operador quando um adiamento tiver sido preso por uma execução de tarefa travada e --safe sozinho puder ficar limitado por gateway.reload.deferralTimeoutMs. --skip-deferral requer --safe.
Profiling do Gateway
- Defina
OPENCLAW_GATEWAY_STARTUP_TRACE=1para registrar timings de fases durante a inicialização do Gateway, incluindo atrasoeventLoopMaxpor fase e timings de tabelas de consulta de plugins para índice instalado, registro de manifestos, planejamento de inicialização e trabalho de mapa de proprietários. - Defina
OPENCLAW_GATEWAY_RESTART_TRACE=1para registrar linhasrestart trace:no escopo da reinicialização para tratamento de sinal de reinicialização, drenagem de trabalho ativo, fases de desligamento, próxima inicialização, timing de pronto e métricas de memória. - Defina
OPENCLAW_DIAGNOSTICS=timelinecomOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>para gravar uma timeline de diagnósticos de inicialização JSONL best-effort para harnesses externos de QA. Você também pode habilitar a flag comdiagnostics.flags: ["timeline"]na configuração; o caminho ainda é fornecido por env. AdicioneOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1para incluir amostras de event-loop. - Execute
pnpm buildprimeiro, depoispnpm test:startup:gateway -- --runs 5 --warmup 1para medir a inicialização do Gateway em relação à entrada da CLI compilada. O benchmark registra a primeira saída do processo,/healthz,/readyz, timings de trace de inicialização, atraso de event-loop e detalhes de timing de tabelas de consulta de plugins. - Execute
pnpm buildprimeiro, depoispnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5para medir a reinicialização em processo do Gateway em relação à entrada da CLI compilada no macOS ou Linux. O benchmark de reinicialização usa SIGUSR1, habilita traces de inicialização e reinicialização no processo filho e registra o próximo/healthz, próximo/readyz, downtime, timing de pronto, CPU, RSS e métricas de trace de reinicialização. - Trate
/healthzcomo vivacidade e/readyzcomo prontidão utilizável. Linhas de trace e saída de benchmark servem para atribuição de proprietário; não trate um span de trace ou uma amostra como uma conclusão completa de desempenho.
Consultar um Gateway em execução
Todos os comandos de consulta usam RPC WebSocket.- Modos de saída
- Opções compartilhadas
- Padrão: legível por humanos (colorido em TTY).
--json: JSON legível por máquina (sem estilo/spinner).--no-color(ouNO_COLOR=1): desabilita ANSI mantendo o layout humano.
Quando você define
--url, a CLI não faz fallback para credenciais da configuração ou do ambiente. Passe --token ou --password explicitamente. Credenciais explícitas ausentes são um erro.gateway health
/healthz é uma probe de vivacidade: ele retorna quando o servidor consegue responder HTTP. O endpoint HTTP /readyz é mais rigoroso e permanece vermelho enquanto sidecars de plugins de inicialização, canais ou hooks configurados ainda estão se estabilizando. Respostas locais ou autenticadas de prontidão detalhada incluem um bloco de diagnóstico eventLoop com atraso de event-loop, utilização de event-loop, razão de núcleos de CPU e uma flag degraded.
Direciona a chamada de saúde para um Gateway local em local loopback nesta porta. Isso substitui
OPENCLAW_GATEWAY_URL e OPENCLAW_GATEWAY_PORT para a chamada de saúde.gateway usage-cost
Busca resumos de custo de uso nos logs de sessão.
Número de dias a incluir.
Limita o resumo de custo a um id de agente configurado.
Agrega o resumo de custo em todos os agentes configurados. Não pode ser combinado com
--agent.gateway stability
Busca o gravador de estabilidade diagnóstica recente de um Gateway em execução.
Número máximo de eventos recentes a incluir (máx.
1000).Filtra por tipo de evento de diagnóstico, como
payload.large ou diagnostic.memory.pressure.Inclui apenas eventos após um número de sequência de diagnóstico.
Lê um pacote de estabilidade persistido em vez de chamar o Gateway em execução. Use
--bundle latest (ou apenas --bundle) para o pacote mais novo no diretório de estado, ou passe um caminho JSON de pacote diretamente.Grava um zip compartilhável de diagnósticos de suporte em vez de imprimir detalhes de estabilidade.
Caminho de saída para
--export.Privacidade e comportamento de pacote
Privacidade e comportamento de pacote
- 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: falsepara 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-*.jsonquando o gravador tem eventos. Inspecione o pacote mais novo comopenclaw gateway stability --bundle latest;--limit,--typee--since-seqtambém se aplicam à saída do pacote.
gateway diagnostics export
Grava um zip local de diagnósticos projetado para anexar a relatórios de bugs. Para o modelo de privacidade e o conteúdo do pacote, consulte Exportação de diagnósticos.
Caminho do zip de saída. O padrão é uma exportação de suporte no diretório de estado.
Máximo de linhas de log sanitizadas a incluir.
Máximo de bytes de log a inspecionar.
URL WebSocket do Gateway para o instantâneo de integridade.
Token do Gateway para o instantâneo de integridade.
Senha do Gateway para o instantâneo de integridade.
Tempo limite do instantâneo de status/integridade.
Ignora a busca pelo pacote de estabilidade persistido.
Imprime o caminho gravado, o tamanho e o manifesto como JSON.
gateway status
gateway status mostra o serviço Gateway (launchd/systemd/schtasks), além de uma sondagem opcional de capacidade de conectividade/autenticação.
Adiciona um alvo de sondagem explícito. Remoto configurado + localhost ainda são sondados.
Autenticação por token para a sondagem.
Autenticação por senha para a sondagem.
Tempo limite da sondagem.
Ignora a sondagem de conectividade (visualização apenas do serviço).
Examina também serviços em nível de sistema.
Atualiza a sondagem de conectividade padrão para uma sondagem de leitura e sai com valor diferente de zero quando essa sondagem de leitura falha. Não pode ser combinado com
--no-probe.Semântica de status
Semântica de status
gateway statuspermanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou inválida.- O
gateway statuspadrã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 statusresolve 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 --jsonrelatarpc.authWarningquando a conectividade/autenticação da sondagem falha; passe--token/--passwordexplicitamente 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.versionquando o Gateway em execução a relata;--require-rpcpode recorrer ao payload RPCstatus.runtimeVersionse a sondagem de handshake subsequente não puder fornecer metadados de versão. - Use
--require-rpcem 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. --deepadiciona 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.--deeptambé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.--deepexecuta 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. Ogateway statuspadrã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.
Verificações de desvio de autenticação do systemd no Linux
Verificações de desvio de autenticação do systemd no Linux
- Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores
Environment=eEnvironmentFile=da unidade (incluindo%h, caminhos entre aspas, múltiplos arquivos e arquivos opcionais-). - As verificações de desvio resolvem SecretRefs
gateway.auth.tokenusando 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.modeexplícito comopassword/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.
gateway probe
gateway probe é o comando de “depurar tudo”. Ele sempre sonda:
- seu gateway remoto configurado (se definido), e
- localhost (loopback) mesmo se o remoto estiver configurado.
--url, esse alvo explícito é adicionado antes de ambos. A saída legível por humanos rotula os alvos como:
URL (explícita)Remoto (configurado)ouRemoto (configurado, inativo)Local loopback
Se vários alvos de sondagem estiverem acessíveis, ele imprime todos eles. Um túnel SSH, uma URL TLS/proxy e uma URL remota configurada podem apontar para o mesmo gateway mesmo quando suas portas de transporte diferirem;
multiple_gateways é reservado para gateways acessíveis distintos ou com identidade ambígua. Múltiplos gateways são compatíveis quando você usa perfis isolados (por exemplo, um bot de resgate), mas a maioria das instalações ainda executa um único gateway.Usa esta porta para o alvo de sondagem de local loopback e para a porta remota do túnel SSH. Sem
--url, isto seleciona o alvo de local loopback em vez da URL de ambiente do gateway configurado, porta de ambiente ou alvos remotos.Interpretação
Interpretação
Reachable: yessignifica que pelo menos um alvo aceitou uma conexão WebSocket.Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyrelata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da acessibilidade.Read probe: oksignifica 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.readsignifica 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: failedapósConnect: oksignifica 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.
Saída JSON
Saída JSON
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_scopeouunknown).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 comcode,messageetargetIdsopcionais.network: dicas de URL de local loopback/tailnet derivadas da configuração atual e da rede do host.discovery.timeoutMsediscovery.count: o orçamento/contagem de resultados de descoberta reais usados nesta passagem de sondagem.
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.
targets[].auth):role: função de autenticação relatada emhello-okquando disponível.scopes: escopos concedidos relatados emhello-okquando disponíveis.capability: a classificação de capacidade de autenticação exposta para esse alvo.
Códigos de aviso comuns
Códigos de aviso comuns
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 deoperator.read.
Remoto via SSH (paridade com o app para Mac)
O modo “Remoto via SSH” do app macOS usa um encaminhamento de porta local para que o gateway remoto (que pode estar vinculado apenas ao loopback) fique acessível emws://127.0.0.1:<port>.
Equivalente na CLI:
user@host ou user@host:port (a porta padrão é 22).Arquivo de identidade.
Escolhe o primeiro host de gateway descoberto como alvo SSH a partir do endpoint de descoberta resolvido (
local. mais o domínio de longa distância configurado, se houver). Dicas somente TXT são ignoradas.gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
Auxiliar RPC de baixo nível.
String de objeto JSON para params.
URL WebSocket do Gateway.
Token do Gateway.
Senha do Gateway.
Orçamento de tempo limite.
Principalmente para RPCs em estilo de agente que transmitem eventos intermediários antes de um payload final.
Saída JSON legível por máquina.
--params deve ser JSON válido.Gerenciar o serviço Gateway
Instalar com um encapsulador
Use--wrapper quando o serviço gerenciado precisar iniciar por meio de outro executável, por exemplo uma
camada intermediária de gerenciador de segredos ou um auxiliar de execução como outro usuário. O encapsulador recebe os argumentos normais do Gateway e é
responsável por eventualmente executar openclaw ou Node com esses argumentos.
gateway install valida que o caminho é
um arquivo executável, grava o encapsulador em ProgramArguments do serviço e persiste
OPENCLAW_WRAPPER no ambiente do serviço para reinstalações forçadas, atualizações e reparos do doctor
posteriores.
OPENCLAW_WRAPPER ao reinstalar:
Command options
Command options
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>,--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
Lifecycle behavior
Lifecycle behavior
- Use
gateway restartpara reiniciar um serviço gerenciado. Não encadeiegateway stopegateway startcomo substituto de reinicialização. - No macOS,
gateway stopusalaunchctl bootoutpor 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, egateway startreativa tudo de forma limpa sem umlaunchctl enablemanual. Passe--disablepara suprimir persistentemente KeepAlive e RunAtLoad, para que o Gateway não renasça até o próximogateway startexplícito; use isso quando uma parada manual deve sobreviver a reinicializações ou reinícios do sistema. gateway restart --safesolicita 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é ogateway.reload.deferralTimeoutMsconfigurado (padrão de 5 minutos); quando esse orçamento expira, a reinicialização é forçada. Definagateway.reload.deferralTimeoutMscomo0para uma espera segura indefinida que nunca força.--safenão pode ser combinado com--forceou--wait.gateway restart --wait 30ssubstitui o orçamento configurado de drenagem da reinicialização para essa reinicialização. Números sem unidade são milissegundos; unidades comos,mehsão aceitas.--wait 0espera indefinidamente.gateway restart --safe --skip-deferralexecuta 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 --forcepula 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
--jsonpara scripts.
Auth and SecretRefs at install time
Auth and SecretRefs at install time
- Quando a autenticação por token exige um token e
gateway.auth.tokené gerenciado por SecretRef,gateway installvalida 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, prefiraOPENCLAW_GATEWAY_PASSWORD,--password-fileou umgateway.auth.passwordapoiado por SecretRef em vez de--passwordembutido. - No modo de autenticação inferido,
OPENCLAW_GATEWAY_PASSWORDsomente no shell não relaxa os requisitos de token na instalação; use configuração durável (gateway.auth.passwordouenvde configuração) ao instalar um serviço gerenciado. - Se
gateway.auth.tokenegateway.auth.passwordestiverem configurados egateway.auth.modenão estiver definido, a instalação será bloqueada até que o modo seja definido explicitamente.
Descobrir gateways (Bonjour)
gateway discover procura beacons do Gateway (_openclaw-gw._tcp).
- Multicast DNS-SD:
local. - Unicast DNS-SD (Wide-Area Bonjour): escolha um domínio (exemplo:
openclaw.internal.) e configure DNS dividido + um servidor DNS; consulte Bonjour.
role(dica de função do gateway)transport(dica de transporte, por exemplo,gateway)gatewayPort(porta WebSocket, geralmente18789)sshPort(somente modo de descoberta completo; clientes usam22como alvo SSH padrão quando ele está ausente)tailnetDns(nome de host MagicDNS, quando disponível)gatewayTls/gatewayTlsSha256(TLS ativado + impressão digital do certificado)cliPath(somente modo de descoberta completo)
gateway discover
Tempo limite por comando (browse/resolve).
Saída legível por máquina (também desativa estilo/spinner).
- A CLI varre
local.mais o domínio de área ampla configurado quando um está ativado. wsUrlna saída JSON é derivado do endpoint de serviço resolvido, não de dicas somente TXT, comolanHostoutailnetDns.- Em mDNS
local.e DNS-SD de área ampla,sshPortecliPathsão publicados somente quandodiscovery.mdns.modeéfull.