openclaw gateway ....
Detección Bonjour
Configuración de mDNS local + DNS-SD de área amplia.
Resumen de detección
Cómo OpenClaw anuncia y encuentra gateways.
Configuración
Claves de configuración de gateway de nivel superior.
Ejecutar el Gateway
Comportamiento de inicio
Comportamiento de inicio
- Se niega a iniciarse a menos que
gateway.mode=localesté definido en~/.openclaw/openclaw.json. Usa--allow-unconfiguredpara ejecuciones ad hoc/de desarrollo; omite la protección sin escribir ni reparar la configuración. openclaw onboard --mode localyopenclaw setupescribengateway.mode=local. Si el archivo de configuración existe pero faltagateway.mode, se trata como configuración dañada/sobrescrita y el Gateway se niega a adivinarlocalpor ti: vuelve a ejecutar el onboarding, define la clave manualmente o pasa--allow-unconfigured.- Se bloquea el enlace más allá de loopback sin autenticación.
- Los valores de
--bindlan,tailnetycustomse resuelven hoy mediante rutas solo IPv4; las configuraciones solo IPv6 con host propio necesitan un sidecar IPv4 o un proxy delante del Gateway. SIGUSR1activa un reinicio dentro del proceso cuando está autorizado.commands.restart(predeterminado: habilitado) controlaSIGUSR1enviado externamente; defínelo enfalsepara bloquear reinicios manuales por señal del SO sin dejar de permitir el reinicio mediante el comandogateway restart, la herramienta gateway y config-apply/update.SIGINT/SIGTERMdetienen el proceso, pero no restauran el estado personalizado del terminal; si envuelves la CLI en una TUI o entrada en modo raw, restaura el terminal tú mismo antes de salir.
Opciones
Puerto WebSocket (valor predeterminado de config/env; normalmente
18789).Modo de enlace:
loopback (predeterminado), lan, tailnet, auto, custom.Token compartido para
connect.params.auth.token. Usa OPENCLAW_GATEWAY_TOKEN de forma predeterminada cuando está definido.Modo de autenticación:
none, token, password, trusted-proxy.Contraseña para
--auth password.Lee la contraseña del Gateway desde un archivo.
Exposición de Tailscale:
off, serve, funnel.Restablece la configuración serve/funnel de Tailscale al cerrar.
Inicia sin exigir
gateway.mode=local. Solo arranque ad hoc/de desarrollo; no persiste ni repara la configuración.Crea una configuración de desarrollo + espacio de trabajo si faltan (omite
BOOTSTRAP.md).Restablece la configuración de desarrollo, credenciales, sesiones y espacio de trabajo. Requiere
--dev.Mata cualquier listener existente en el puerto de destino antes de iniciar.
Registro detallado en stdout/stderr.
Muestra solo los logs del backend de la CLI en la consola (también habilita stdout/stderr).
Estilo de log WebSocket:
auto, full, compact.Alias de
--ws-log compact.Registra eventos raw del stream del modelo en JSONL.
Ruta JSONL del stream raw.
--claude-cli-logs es un alias obsoleto de --cli-backend-logs.
Para --bind custom, define gateway.customBindHost con una dirección IPv4; el Gateway recurre a 0.0.0.0 si esa dirección no está disponible. Las configuraciones solo IPv6 con host propio necesitan un sidecar IPv4 o un proxy delante del Gateway.
Reiniciar el Gateway
--safe pide al Gateway en ejecución que haga un preflight del trabajo activo y programe un reinicio combinado después de que ese trabajo se vacíe. La espera está limitada por gateway.reload.deferralTimeoutMs (predeterminado: 5 minutos / 300000); cuando se agota el presupuesto, se fuerza el reinicio. Define deferralTimeoutMs: 0 para esperar indefinidamente (con advertencias periódicas de pendientes) en lugar de forzar. --safe no se puede combinar con --force ni --wait.
--skip-deferral omite la compuerta de aplazamiento por trabajo activo en un reinicio seguro, por lo que el Gateway se reinicia de inmediato incluso con bloqueadores reportados. Requiere --safe; úsalo cuando un aplazamiento esté atascado en una tarea descontrolada.
--wait <duration> anula el presupuesto de vaciado para un reinicio simple (no seguro). Acepta milisegundos sin unidad o sufijos de unidad ms, s, m, h, d (por ejemplo, 30s, 5m, 1h30m); --wait 0 espera indefinidamente. No es compatible con --force ni --safe.
--force omite el vaciado de trabajo activo y reinicia inmediatamente. restart simple (sin flags) conserva el comportamiento de reinicio existente del gestor de servicios.
Perfilado del Gateway
OPENCLAW_GATEWAY_STARTUP_TRACE=1registra tiempos de fases durante el inicio, incluido el retrasoeventLoopMaxpor fase y tiempos de tablas de búsqueda de plugins (índice instalado, registro de manifiestos, planificación de inicio, trabajo de owner-map).OPENCLAW_GATEWAY_RESTART_TRACE=1registra líneasrestart trace:con alcance de reinicio: manejo de señales, vaciado de trabajo activo, fases de cierre, siguiente inicio, tiempo hasta estar listo y métricas de memoria.OPENCLAW_DIAGNOSTICS=timelineconOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>escribe una línea de tiempo de diagnósticos de inicio JSONL de mejor esfuerzo para arneses externos de QA (equivalente a la configuracióndiagnostics.flags: ["timeline"]; la ruta sigue siendo solo env). AñadeOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1para incluir muestras del event loop.pnpm buildy luegopnpm test:startup:gateway -- --runs 5 --warmup 1hacen benchmark del inicio del Gateway contra la entrada CLI compilada: salida del primer proceso,/healthz,/readyz, tiempos de trazas de inicio, retraso del event loop y tiempos de tablas de búsqueda de plugins.pnpm buildy luegopnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5hacen benchmark del reinicio dentro del proceso en macOS o Linux (no compatible con Windows; el reinicio requiereSIGUSR1). UsaSIGUSR1, habilita ambas trazas en el proceso hijo y registra el siguiente/healthz, el siguiente/readyz, tiempo de inactividad, tiempo hasta estar listo, CPU, RSS y métricas de trazas de reinicio./healthzes liveness;/readyzes preparación utilizable. Trata las líneas de traza y la salida del benchmark como señal de atribución de propietario, no como una conclusión completa de rendimiento a partir de un tramo o muestra.
Consultar un Gateway en ejecución
Todos los comandos de consulta usan RPC WebSocket.- Modos de salida
- Opciones compartidas
- Predeterminado: legible para humanos (con color en TTY).
--json: JSON legible por máquinas (sin estilos/spinner).--no-color(oNO_COLOR=1): deshabilita ANSI mientras mantiene el diseño humano.
Cuando defines
--url, la CLI no recurre a credenciales de configuración ni de entorno. Pasa --token o --password explícitamente. La falta de credenciales explícitas es un error.gateway health
/healthz es una sonda de liveness: devuelve respuesta en cuanto el servidor puede responder HTTP. /readyz es más estricta y permanece en rojo mientras los sidecars de plugins de inicio, canales o hooks configurados todavía se están estabilizando. Las respuestas detalladas locales o autenticadas de /readyz incluyen un bloque de diagnóstico eventLoop (retraso, utilización, relación de núcleos de CPU, flag degraded).
Apunta a un Gateway local loopback en este puerto. Anula
OPENCLAW_GATEWAY_URL y OPENCLAW_GATEWAY_PORT para esta llamada.gateway usage-cost
Obtén resúmenes de coste de uso desde logs de sesión.
Número de días que se incluirán.
Limita el resumen a un id de agente configurado.
Agrega entre todos los agentes configurados. No se puede combinar con
--agent.gateway stability
Obtén el grabador reciente de estabilidad de diagnóstico desde un Gateway en ejecución.
Máximo de eventos recientes que se incluirán (máximo
1000).Filtra por tipo de evento de diagnóstico, por ejemplo
payload.large o diagnostic.memory.pressure.Incluye solo eventos posteriores a un número de secuencia de diagnóstico.
Lee un paquete de estabilidad persistido en lugar de llamar al Gateway en ejecución.
--bundle latest (o --bundle sin valor) elige el paquete más reciente bajo el directorio de estado; también puedes pasar directamente una ruta JSON de paquete.Escribe un zip de diagnósticos de soporte compartible en lugar de imprimir detalles de estabilidad.
Ruta de salida para
--export.Privacidad y comportamiento de paquetes
Privacidad y comportamiento de paquetes
- Los registros conservan metadatos operativos: nombres de eventos, recuentos, tamaños en bytes, lecturas de memoria, estado de cola/sesión, ids de aprobación, nombres de canal/plugin y resúmenes de sesión redactados. Excluyen texto de chat, cuerpos de Webhook, salidas de herramientas, cuerpos raw de solicitud/respuesta, tokens, cookies, valores secretos, nombres de host e ids raw de sesión. Define
diagnostics.enabled: falsepara deshabilitar el grabador por completo. - Las salidas fatales del Gateway, timeouts de cierre y fallos de inicio tras reinicio escriben la misma instantánea de diagnóstico en
~/.openclaw/logs/stability/openclaw-stability-*.jsoncuando el grabador tiene eventos. Inspecciona el paquete más reciente conopenclaw gateway stability --bundle latest;--limit,--typey--since-seqtambién se aplican a la salida de paquete.
gateway diagnostics export
Escribe un zip local de diagnósticos diseñado para informes de bugs. Para el modelo de privacidad y el contenido del paquete, consulta Exportación de diagnósticos.
Ruta del zip de salida. De forma predeterminada, usa una exportación de soporte bajo el directorio de estado.
Cantidad máxima de líneas de registro saneadas que se incluirán.
Cantidad máxima de bytes de registro que se inspeccionarán.
URL WebSocket del Gateway para la instantánea de estado.
Token del Gateway para la instantánea de estado.
Contraseña del Gateway para la instantánea de estado.
Tiempo de espera de la instantánea de estado/salud.
Omite la búsqueda del paquete de estabilidad persistido.
Imprime la ruta escrita, el tamaño y el manifiesto como JSON.
manifest.json (inventario de archivos), summary.md (resumen Markdown), diagnostics.json (resumen de configuración/registros/detección/estabilidad/estado/salud de nivel superior), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl y stability/latest.json cuando existe un paquete.
Está diseñada para compartirse. Conserva detalles operativos útiles para depurar —campos de registro seguros, nombres de subsistemas, códigos de estado, duraciones, modos configurados, puertos, ids de plugins/proveedores, ajustes de funciones que no son secretos y mensajes de registro operativos redactados— y omite o redacta texto de chat, cuerpos de webhook, salidas de herramientas, credenciales, cookies, identificadores de cuenta/mensaje, texto de prompts/instrucciones, nombres de host y valores secretos. Cuando un mensaje de registro parece texto de carga útil de usuario/chat/herramienta (por ejemplo, “user said”, “chat text”, “tool output”, “webhook body”), la exportación conserva solo el hecho de que se omitió un mensaje y su recuento de bytes.
gateway status
Muestra el servicio Gateway (launchd/systemd/schtasks) junto con una prueba opcional de conectividad/autenticación.
Agrega un destino de prueba explícito. La conexión remota configurada + localhost se siguen probando.
Autenticación con token para la prueba.
Autenticación con contraseña para la prueba.
Tiempo de espera de la prueba.
Omite la prueba de conectividad (vista solo del servicio).
También analiza los servicios de nivel de sistema.
Eleva la prueba de conectividad a una prueba de lectura y sale con código distinto de cero si falla. No se puede combinar con
--no-probe.Status semantics
Status semantics
- Sigue disponible para diagnósticos incluso cuando falta la configuración local de la CLI o no es válida.
- La salida predeterminada prueba el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible durante el handshake, no las operaciones de lectura/escritura/administración.
- Las pruebas no realizan mutaciones para la autenticación inicial de dispositivos: reutilizan un token de dispositivo en caché existente cuando hay uno, pero nunca crean una nueva identidad de dispositivo de la CLI ni un registro de emparejamiento de solo lectura solo para comprobar el estado.
- Resuelve los SecretRefs de autenticación configurados para la autenticación de la prueba cuando es posible. Si un SecretRef requerido no se resuelve,
--jsoninformarpc.authWarningcuando falla la conectividad/autenticación de la prueba; pasa--token/--passwordexplícitamente o corrige la fuente del secreto. Las advertencias de autenticación no resuelta se suprimen cuando la prueba tiene éxito. - La salida JSON incluye
gateway.versioncuando el Gateway en ejecución la informa;--require-rpcpuede recurrir a la carga útil RPCstatus.runtimeVersionsi la prueba de handshake no puede proporcionar metadatos de versión. - Usa
--require-rpcen scripts/automatización cuando un servicio en escucha no sea suficiente y también necesites que el RPC con alcance de lectura esté sano. --deepbusca instalaciones launchd/systemd/schtasks adicionales; cuando se encuentran varios servicios similares a gateway, la salida humana imprime sugerencias de limpieza (normalmente ejecutar un gateway por máquina) e informa una transferencia reciente de reinicio del supervisor cuando corresponde.--deeptambién ejecuta validación de configuración en modo consciente de plugins (pluginValidation: "full") y muestra advertencias del manifiesto del plugin (por ejemplo, metadatos de configuración de canal faltantes). Elgateway statuspredeterminado mantiene la ruta rápida de solo lectura que omite la validación de plugins.- La salida humana incluye la ruta resuelta del archivo de registro, además de rutas/validez de configuración CLI frente a servicio para ayudar a diagnosticar desviaciones de perfil o directorio de estado.
Linux systemd auth-drift checks
Linux systemd auth-drift checks
- Las comprobaciones de desviación de autenticación del servicio leen tanto
Environment=comoEnvironmentFile=desde la unidad (incluidos%h, rutas entre comillas, múltiples archivos y archivos-opcionales). - Resuelve SecretRefs de
gateway.auth.tokenusando el entorno de ejecución combinado (primero el entorno del comando del servicio y luego el entorno del proceso como fallback). - Las comprobaciones de desviación de token omiten la resolución del token de configuración cuando la autenticación con token no está efectivamente activa (
gateway.auth.modeexplícitamentepassword/none/trusted-proxy, o modo sin definir donde la contraseña puede ganar y ningún candidato de token puede ganar).
gateway probe
El comando para “depurarlo todo”. Siempre prueba:
- tu gateway remoto configurado (si está definido), y
- localhost (loopback), incluso si hay un remoto configurado.
--url agrega ese destino explícito antes de ambos. La salida humana etiqueta los destinos como URL (explicit), Remote (configured) / Remote (configured, inactive) y Local loopback.
Si se puede alcanzar más de un destino de prueba, se imprimen todos. Un túnel SSH, una URL TLS/proxy y una URL remota configurada pueden apuntar al mismo gateway incluso con puertos de transporte distintos;
multiple_gateways se reserva para gateways alcanzables distintos o con identidad ambigua. Ejecutar varios gateways está permitido para perfiles aislados (por ejemplo, un bot de rescate), pero la mayoría de las instalaciones ejecutan un solo gateway.Usa este puerto para el destino de prueba local loopback y el puerto remoto del túnel SSH. Sin
--url, esto selecciona solo el destino local loopback en lugar de la URL de entorno del gateway configurado, el puerto de entorno o los destinos remotos.Interpretation
Interpretation
Reachable: yessignifica que al menos un destino aceptó una conexión WebSocket.Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyinforma lo que la prueba pudo demostrar sobre la autenticación, separado de la alcanzabilidad.Read probe: oksignifica que las llamadas RPC de detalle con alcance de lectura (health/status/system-presence/config.get) también tuvieron éxito.Read probe: limited - missing scope: operator.readsignifica que la conexión tuvo éxito, pero el RPC con alcance de lectura está limitado. Se informa como alcanzabilidad degradada, no como fallo total.Read probe: faileddespués deConnect: oksignifica que el WebSocket se conectó, pero los diagnósticos de lectura posteriores agotaron el tiempo de espera o fallaron; también es degradado, no inalcanzable.- Como
gateway status, la prueba reutiliza la autenticación de dispositivo en caché existente, pero no crea identidad de dispositivo inicial ni estado de emparejamiento. - El código de salida solo es distinto de cero cuando ningún destino probado es alcanzable.
JSON output
JSON output
Nivel superior:
ok: al menos un destino es alcanzable.degraded: al menos un destino aceptó una conexión, pero no completó todos los diagnósticos RPC de detalle.capability: mejor capacidad observada entre los destinos alcanzables (read_only,write_capable,admin_capable,pairing_pending,connected_no_operator_scopeounknown).primaryTargetId: mejor destino para tratar como ganador activo, en orden: URL explícita, túnel SSH, remoto configurado, local loopback.warnings[]: registros de advertencia de mejor esfuerzo concode,messageytargetIdsopcional.network: sugerencias de URL local loopback/tailnet derivadas de la configuración actual y la red del host.discovery.timeoutMs/discovery.count: el presupuesto de detección real/recuento de resultados usado para esta pasada de prueba.
targets[].connect): ok (alcanzabilidad + clasificación degradada), rpcOk (éxito completo de RPC de detalle), scopeLimited (RPC de detalle fallido por falta de alcance de operador).Por destino (targets[].auth): role y scopes informados en hello-ok cuando están disponibles, además de la clasificación capability mostrada.Common warning codes
Common warning codes
ssh_tunnel_failed: falló la configuración del túnel SSH; el comando recurrió a pruebas directas.multiple_gateways: se alcanzaron identidades de gateway distintas, o OpenClaw no pudo demostrar que los destinos alcanzables son el mismo gateway. Un túnel SSH, una URL de proxy o una URL remota configurada hacia el mismo gateway no activa esto.auth_secretref_unresolved: no se pudo resolver un SecretRef de autenticación configurado para un destino fallido.probe_scope_limited: la conexión WebSocket tuvo éxito, pero la prueba de lectura estuvo limitada por la falta deoperator.read.local_tls_runtime_unavailable: TLS del Gateway local está habilitado, pero OpenClaw no pudo cargar la huella digital del certificado local.
Remoto por SSH (paridad con la app de Mac)
El modo “Remoto por SSH” de la app de macOS usa un reenvío de puerto local para que un gateway remoto solo de loopback sea alcanzable enws://127.0.0.1:<port>.
Equivalente en la CLI:
user@host o user@host:port (el puerto predeterminado es 22).Archivo de identidad.
Elige el primer host de gateway detectado como destino SSH desde el endpoint de detección resuelto (
local. más el dominio de área amplia configurado, si existe). Las sugerencias solo TXT se ignoran.gateway.remote.sshTarget, gateway.remote.sshIdentity.
gateway call <method>
Ayudante RPC de bajo nivel.
Cadena de objeto JSON para params.
URL WebSocket del Gateway.
Token del Gateway.
Contraseña del Gateway.
Presupuesto de tiempo de espera.
Principalmente para RPCs de estilo agente que transmiten eventos intermedios antes de una carga útil final.
Salida JSON legible por máquina.
--params debe ser JSON válido, y cada método valida su propia forma de params (los campos adicionales o con nombre incorrecto se rechazan).Gestionar el servicio Gateway
Instalar con un wrapper
Usa--wrapper cuando el servicio gestionado deba iniciarse a través de otro ejecutable, por ejemplo un shim de gestor de secretos o un ayudante de ejecución como otro usuario. El wrapper recibe los argumentos normales del Gateway y es responsable de terminar ejecutando con exec openclaw o Node con esos argumentos.
gateway install valida que la ruta sea un archivo ejecutable, escribe el contenedor en los ProgramArguments del servicio y conserva OPENCLAW_WRAPPER en el entorno del servicio para reinstalaciones forzadas, actualizaciones y reparaciones de doctor posteriores.
OPENCLAW_WRAPPER durante la reinstalación:
Opciones de comando
Opciones de comando
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>(predeterminado:node),--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
Comportamiento del ciclo de vida
Comportamiento del ciclo de vida
- Usa
gateway restartpara reiniciar un servicio administrado. No encadenesgateway stopygateway startcomo sustituto de reinicio. - En macOS,
gateway stopusalaunchctl bootoutde forma predeterminada, lo que elimina el LaunchAgent de la sesión de arranque actual sin persistir una deshabilitación; la recuperación automática de KeepAlive permanece activa para futuros fallos ygateway startvuelve a habilitarlo limpiamente sin unlaunchctl enablemanual. Pasa--disablepara suprimir KeepAlive y RunAtLoad de forma persistente, de modo que el gateway no reaparezca hasta el siguientegateway startexplícito; usa esto cuando una detención manual deba sobrevivir a reinicios. - Los comandos de ciclo de vida aceptan
--jsonpara scripts.
Auth y SecretRefs en el momento de la instalación
Auth y SecretRefs en el momento de la instalación
- Cuando la autenticación por token requiere un token y
gateway.auth.tokenestá administrado por SecretRef,gateway installvalida que SecretRef pueda resolverse, pero no persiste el token resuelto en los metadatos del entorno del servicio. - Si la autenticación por token requiere un token y el SecretRef de token configurado no se resuelve, la instalación falla cerrada en lugar de persistir texto sin formato alternativo.
- Para la autenticación por contraseña en
gateway run, prefiereOPENCLAW_GATEWAY_PASSWORD,--password-fileo ungateway.auth.passwordrespaldado por SecretRef en lugar de--passworden línea. - En modo de autenticación inferido,
OPENCLAW_GATEWAY_PASSWORDdefinido solo en la shell no relaja los requisitos de token de instalación; usa una configuración duradera (gateway.auth.passwordo configenv) al instalar un servicio administrado. - Si
gateway.auth.tokenygateway.auth.passwordestán configurados ygateway.auth.modeno está definido, la instalación se bloquea hasta que el modo se configure explícitamente.
Descubrir gateways (Bonjour)
gateway discover busca balizas de Gateway (_openclaw-gw._tcp).
- DNS-SD multicast:
local. - DNS-SD unicast (Bonjour de área amplia): elige un dominio (ejemplo:
openclaw.internal.) y configura DNS dividido + un servidor DNS; consulta Bonjour.
role (pista de rol del gateway), transport (pista de transporte, por ejemplo, gateway), gatewayPort (puerto WebSocket, normalmente 18789), tailnetDns (nombre de host MagicDNS, cuando está disponible), gatewayTls / gatewayTlsSha256 (TLS habilitado + huella digital del certificado). sshPort y cliPath se publican solo en modo de descubrimiento completo (discovery.mdns.mode: "full"; el predeterminado es "minimal", que los omite; los clientes entonces usan por defecto el puerto 22 para destinos SSH).
gateway discover
Tiempo de espera por comando (explorar/resolver).
Salida legible por máquina (también deshabilita el estilo y el indicador de actividad).
- Busca en
local.más el dominio de área amplia configurado cuando hay uno habilitado. wsUrlen la salida JSON se deriva del endpoint de servicio resuelto, no de pistas solo TXT comolanHostotailnetDns.discovery.mdns.modecontrola la publicación desshPort/cliPathtanto en mDNSlocal.como en DNS-SD de área amplia (consulta lo anterior).