Gateway
El Gateway es el servidor WebSocket de OpenClaw (canales, nodos, sesiones, hooks). Los subcomandos en esta página se encuentran en openclaw gateway ….
Configuración de mDNS local + DNS-SD de área amplia.
Cómo OpenClaw anuncia y encuentra gateways.
Claves de configuración de nivel superior del gateway.
Ejecutar el Gateway
Sección titulada «Ejecutar el Gateway»Ejecutar un proceso de Gateway local:
openclaw gatewayAlias en primer plano:
openclaw gateway runComportamiento de inicio
- De forma predeterminada, el Gateway se niega a iniciarse a menos que se establezca
gateway.mode=localen~/.openclaw/openclaw.json. Use--allow-unconfiguredpara ejecuciones ad-hoc/desarrollo. - Se espera que
openclaw onboard --mode localyopenclaw setupescribangateway.mode=local. Si el archivo existe pero faltagateway.mode, trátelo como una configuración rota o alterada y repárela en lugar de asumir implícitamente el modo local. - Si el archivo existe y falta
gateway.mode, el Gateway lo trata como un daño sospechoso en la configuración y se niega a “asumir local” por usted. - El enlace más allá del loopback sin autenticación está bloqueado (guardavía de seguridad).
SIGUSR1desencadena un reinicio en proceso cuando está autorizado (commands.restartestá habilitado de forma predeterminada; establezcacommands.restart: falsepara bloquear el reinicio manual, mientras que gateway tool/config apply/update permanecen permitidos).- Los controladores
SIGINT/SIGTERMdetienen el proceso del gateway, pero no restauran ningún estado personalizado de la terminal. Si envuelve la CLI con una interfaz de usuario de terminal (TUI) o entrada en modo raw, restaure la terminal antes de salir.
Opciones
Sección titulada «Opciones»Reiniciar el Gateway
Sección titulada «Reiniciar el Gateway»openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --safe le pide al Gateway en ejecución que realice una comprobación previa del trabajo activo de OpenClaw antes de reiniciar. Si hay operaciones en cola, entrega de respuestas, ejecuciones integradas o ejecuciones de tareas activas, el Gateway informa de los bloqueos, combina las solicitudes de reinicio seguro duplicadas y se reinicia una vez que se completa el trabajo activo. restart normal mantiene el comportamiento del gestor de servicios existente para la compatibilidad. Use --force solo cuando desee explícitamente la ruta de anulación inmediata.
openclaw gateway restart --safe --skip-deferral ejecuta el mismo reinicio coordinado con conocimiento de OpenClaw que --safe, pero omite la puerta de aplazamiento de trabajo activo para que el Gateway emita el reinicio inmediatamente incluso cuando se informan bloqueos. Úselo como la escotilla de escape del operador cuando un aplazamiento ha sido fijado por una ejecución de tarea atascada y --safe solo esperaría indefinidamente. --skip-deferral requiere --safe.
Perfilado del Gateway
Sección titulada «Perfilado del Gateway»- Establezca
OPENCLAW_GATEWAY_STARTUP_TRACE=1para registrar los tiempos de las fases durante el inicio del Gateway, incluyendo el retrasoeventLoopMaxpor fase y los tiempos de la tabla de búsqueda de complementos para el trabajo de índice instalado, registro de manifiestos, planificación de inicio y mapa de propietarios. - Establezca
OPENCLAW_GATEWAY_RESTART_TRACE=1para registrar líneasrestart trace:con alcance de reinicio para el manejo de señales de reinicio, drenaje de trabajo activo, fases de apagado, próximo inicio, sincronización de listos y métricas de memoria. - Establezca
OPENCLAW_DIAGNOSTICS=timelineconOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>para escribir una línea de tiempo de diagnóstico de inicio JSONL de mejor esfuerzo para arneses de QA externos. También puede habilitar la opción condiagnostics.flags: ["timeline"]en la configuración; la ruta aún se proporciona a través del entorno. AgregueOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1para incluir muestras del bucle de eventos. - Ejecute
pnpm buildprimero, luegopnpm test:startup:gateway -- --runs 5 --warmup 1para comparar el inicio de Gateway con la entrada CLI construida. El punto de referencia registra la primera salida del proceso,/healthz,/readyz, tiempos de rastro de inicio, retraso del bucle de eventos y detalles de tiempo de la tabla de búsqueda de complementos. - Ejecute
pnpm buildprimero, luegopnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5para comparar el reinicio en proceso de Gateway con la entrada CLI construida en macOS o Linux. El punto de referencia de reinicio usa SIGUSR1, habilita rastros de inicio y de reinicio en el proceso secundario y registra el siguiente/healthz, el siguiente/readyz, tiempo de inactividad, tiempo de disponibilidad, CPU, RSS y métricas de rastro de reinicio. - Trate
/healthzcomo actividad (liveness) y/readyzcomo disponibilidad utilizable. Las líneas de rastro y la salida del punto de referencia son para la atribución del propietario; no trate un intervalo de rastro o una muestra como una conclusión de rendimiento completa.
Consultar un Gateway en ejecución
Sección titulada «Consultar un Gateway en ejecución»Todos los comandos de consulta usan WebSocket RPC.
- Predeterminado: legible por humanos (coloreado en TTY).
--json: JSON legible por máquina (sin estilo/indicador de carga).--no-color(oNO_COLOR=1): desactivar ANSI manteniendo el diseño humano.
- `—url
: URL WebSocket de Gateway. - —token
: token de Gateway. - —password
: contraseña de Gateway. - —timeout
: tiempo de espera/presupuesto (varía según el comando). - —expect-final`: esperar una respuesta “final” (llamadas de agente).
gateway health
Sección titulada «gateway health»openclaw gateway health --url ws://127.0.0.1:18789El endpoint HTTP /healthz es un sondeo de actividad (liveness probe): devuelve una respuesta una vez que el servidor puede responder a HTTP. El endpoint HTTP /readyz es más estricto y permanece en rojo mientras los sidecars de complementos de inicio, los canales o los enlaces configurados aún se estén estabilizando. Las respuestas detalladas de preparación locales o autenticadas incluyen un bloque de diagnóstico eventLoop con el retraso del bucle de eventos, la utilización del bucle de eventos, la relación de núcleos de CPU y una bandera degraded.
gateway usage-cost
Sección titulada «gateway usage-cost»Obtener resúmenes de costos de uso de los registros de sesiones.
openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --jsongateway stability
Sección titulada «gateway stability»Obtener el grabador de estabilidad de diagnóstico reciente de un Gateway en ejecución.
openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw gateway stability --jsonPrivacidad y comportamiento del paquete
- Los registros mantienen metadatos operativos: nombres de eventos, recuentos, tamaños de bytes, lecturas de memoria, estado de cola/sesión, nombres de canal/complemento y resúmenes de sesión redactados. No mantienen texto de chat, cuerpos de webhook, salidas de herramientas, cuerpos de solicitudes o respuestas sin procesar, tokens, cookies, valores secretos, nombres de host o IDs de sesión sin procesar. Configure
diagnostics.enabled: falsepara deshabilitar el grabador por completo. - En salidas fatales del Gateway, tiempos de espera de apagado y fallos de inicio al reiniciar, OpenClaw escribe la misma instantánea de diagnóstico en
~/.openclaw/logs/stability/openclaw-stability-*.jsoncuando el grabador tiene eventos. Inspeccione el paquete más reciente conopenclaw gateway stability --bundle latest;--limit,--typey--since-seqtambién se aplican a la salida del paquete.
gateway diagnostics export
Sección titulada «gateway diagnostics export»Escriba un archivo zip de diagnóstico local diseñado para adjuntar a los informes de errores. Para conocer el modelo de privacidad y el contenido del paquete, consulte Exportación de diagnósticos.
openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --jsonLa exportación contiene un manifiesto, un resumen en Markdown, la forma de la configuración, detalles saneados de la configuración, resúmenes de registros saneados, instantáneas saneadas de estado/salud del Gateway, y el paquete de estabilidad más reciente cuando existe uno.
Está pensado para ser compartido. Mantiene detalles operativos que ayudan a la depuración, como campos de registro seguros de OpenClaw, nombres de subsistemas, códigos de estado, duraciones, modos configurados, puertos, IDs de complementos, IDs de proveedores, configuraciones de características no secretas, y mensajes de registro operativos redactados. Omite o redacta el texto del chat, los cuerpos de los webhooks, las salidas de las herramientas, las credenciales, las cookies, los identificadores de cuenta/mensaje, el texto de indicaciones/instrucciones, los nombres de host y los valores secretos. Cuando un mensaje estilo LogTape parece ser texto de carga útil de usuario/chat/herramienta, la exportación mantiene solo que un mensaje fue omitido más su conteo de bytes.
gateway status
Sección titulada «gateway status»gateway status muestra el servicio del Gateway (launchd/systemd/schtasks) más una sonda opcional de la capacidad de conectabilidad/autenticación.
openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpcSemántica de estado
gateway statuspermanece disponible para diagnósticos incluso cuando la configuración local de la CLI falta o no es válida.- El
gateway statuspredeterminado prueba el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible en el momento del handshake. No prueba las operaciones de lectura/escritura/administración. - Las sondas de diagnóstico no son mutantes para la autenticación de dispositivos por primera vez: reutilizan un token de dispositivo almacenado en caché existente cuando hay uno, pero no crean una nueva identidad de dispositivo CLI ni un registro de emparejamiento de dispositivo de solo lectura solo para verificar el estado.
gateway statusresuelve los SecretRefs de autenticación configurados para la autenticación de la sonda cuando es posible.- Si un SecretRef de autenticación requerido no se resuelve en esta ruta de comando,
gateway status --jsoninformarpc.authWarningcuando falla la conectividad/autenticación de la sonda; pase--token/--passwordexplícitamente o resuelva primero la fuente del secreto. - Si la sonda tiene éxito, las advertencias de auth-ref no resueltas se suprimen para evitar falsos positivos.
- Use
--require-rpcen scripts y automatización cuando un servicio de escucha no es suficiente y necesita que las llamadas RPC con alcance de lectura también estén sanas. --deepagrega un escaneo de mejor esfuerzo para instalaciones adicionales de launchd/systemd/schtasks. Cuando se detectan múltiples servicios similares a un gateway, la salida humana imprime sugerencias de limpieza y advierte que la mayoría de las configuraciones deberían ejecutar un gateway por máquina.--deeptambién informa un traspaso de reinicio reciente del supervisor del Gateway cuando el proceso del servicio salió limpiamente para un reinicio del supervisor externo.--deepejecuta la validación de configuración en modo compatible con complementos (pluginValidation: "full") y expone las advertencias del manifiesto del complemento configurado (por ejemplo, metadatos de configuración de canal faltantes) para que las pruebas de humo de instalación y actualización las detecten. Elgateway statuspredeterminado mantiene la ruta rápida de solo lectura que omite la validación de complementos.- La salida humana incluye la ruta del registro de archivos resuelta más la instantánea de las rutas/validez de la configuración de CLI frente al servicio para ayudar a diagnosticar el desvío del perfil o del directorio de estado.
Linux systemd auth-drift checks
- En instalaciones de Linux systemd, las comprobaciones de deriva de autenticación del servicio leen tanto los valores de
Environment=como los deEnvironmentFile=de la unidad (incluyendo%h, rutas entre comillas, múltiples archivos y archivos opcionales-). - Las comprobaciones de deriva resuelven los SecretRefs
gateway.auth.tokenutilizando el entorno de tiempo de ejecución combinado (primero el entorno del comando del servicio, luego el respaldo del entorno del proceso). - Si la autenticación por token no está efectivamente activa (
gateway.auth.modeexplícito depassword/none/trusted-proxy, o modo no establecido donde la contraseña puede ganar y ningún candidato de token puede ganar), las comprobaciones de deriva de tokens omiten la resolución del token de configuración.
gateway probe
Sección titulada «gateway probe»gateway probe es el comando “depurar todo”. Siempre sondea:
- su puerta de enlace remota configurada (si está configurada), y
- localhost (bucle de retorno) incluso si se configura el remoto.
Si pasa --url, ese objetivo explícito se añade antes que ambos. La salida humana etiqueta los objetivos como:
URL (explicit)Remote (configured)oRemote (configured, inactive)Local loopback
openclaw gateway probeopenclaw gateway probe --jsonInterpretación
Reachable: yessignifica que al menos un objetivo aceptó una conexión WebSocket.Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyinforma lo que la sonda pudo probar sobre la autenticación. Está separado de la accesibilidad.Read probe: oksignifica que las llamadas RPC de detalle de 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 la RPC de alcance de lectura está limitada. Esto se informa como accesibilidad degradada, no como fallo total.Read probe: faileddespués deConnect: oksignifica que el Gateway aceptó la conexión WebSocket, pero los diagnósticos de lectura posteriores agotaron el tiempo de espera o fallaron. Esto también es accesibilidad degradada, no un Gateway inalcanzable.- Al igual que
gateway status, la sonda reutiliza la autenticación de dispositivo almacenada en caché existente, pero no crea la identidad del dispositivo por primera vez ni el estado de emparejamiento. - El código de salida es distinto de cero solo cuando ningún objetivo sondeado es accesible.
Salida JSON
Nivel superior:
ok: al menos un objetivo es alcanzable.degraded: al menos un objetivo aceptó una conexión pero no completó el diagnóstico completo de RPC de detalles.capability: la mejor capacidad vista entre los objetivos alcanzables (read_only,write_capable,admin_capable,pairing_pending,connected_no_operator_scopeounknown).primaryTargetId: el mejor objetivo para tratar como el ganador activo en este orden: URL explícita, túnel SSH, remoto configurado y luego bucle local.warnings[]: registros de advertencia de mejor esfuerzo concode,messageytargetIdsopcional.network: sugerencias de URL de bucle local/tailnet derivadas de la configuración actual y la red del host.discovery.timeoutMsydiscovery.count: el recuento de presupuesto/resultado de descubrimiento real utilizado para este pase de sondeo.
Por objetivo (targets[].connect):
ok: alcanzabilidad después de conectar + clasificación degradada.rpcOk: éxito de RPC de detalles completos.scopeLimited: la RPC de detalles falló debido a que falta el ámbito de operador.
Por objetivo (targets[].auth):
role: rol de autenticación reportado enhello-okcuando esté disponible.scopes: ámbitos concedidos reportados enhello-okcuando estén disponibles.capability: la clasificación de capacidad de autenticación expuesta para ese objetivo.
Códigos de advertencia comunes
ssh_tunnel_failed: error en la configuración del túnel SSH; el comando recurrió a sondas directas.multiple_gateways: se alcanzó más de un objetivo; esto es inusual a menos que ejecute intencionalmente perfiles aislados, como un bot de rescate.auth_secretref_unresolved: no se pudo resolver un SecretRef de autenticación configurado para un objetivo fallido.probe_scope_limited: la conexión WebSocket se realizó correctamente, pero la sonda de lectura se limitó por la falta deoperator.read.
Remoto a través de SSH (paridad de la aplicación Mac)
Sección titulada «Remoto a través de SSH (paridad de la aplicación Mac)»El modo “Remote over SSH” de la aplicación macOS utiliza un redireccionamiento de puerto local para que la puerta de enlace remota (que podría estar vinculada solo al loopback) sea accesible en ws://127.0.0.1:<port>.
Equivalente en CLI:
openclaw gateway probe --ssh user@gateway-hostConfiguración (opcional, se usa como valores predeterminados):
gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
Sección titulada «gateway call <method>»Auxiliar RPC de bajo nivel.
openclaw gateway call statusopenclaw gateway call logs.tail --params '{"sinceMs": 60000}'Administrar el servicio Gateway
Sección titulada «Administrar el servicio Gateway»openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstallInstalar con un contenedor (wrapper)
Sección titulada «Instalar con un contenedor (wrapper)»Use --wrapper cuando el servicio administrado debe iniciarse a través de otro ejecutable, por ejemplo un
shim de administrador de secretos o un asistente de ejecución (run-as). El contenedor recibe los argumentos normales de Gateway y es
responsable de ejecutar finalmente openclaw o Node con esos argumentos.
cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler
openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restartTambién puede establecer el contenedor a través del entorno. gateway install valida que la ruta sea
un archivo ejecutable, escribe el contenedor en el servicio ProgramArguments y persiste
OPENCLAW_WRAPPER en el entorno del servicio para reinstalaciones forzadas, actualizaciones y reparaciones
de doctor posteriores.
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctorPara eliminar un contenedor persistente, borre OPENCLAW_WRAPPER al reinstalar:
OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restartOpciones del comando
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port, `—runtime
, —token, —wrapper
, —force, —json -gateway restart: —safe, —skip-deferral, —force, —wait
, —json -gateway uninstall|start: —json -gateway stop: —disable, —json`
Comportamiento del ciclo de vida
- Use
gateway restartpara reiniciar un servicio administrado. No encadenegateway 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 desactivación; la recuperación automática de KeepAlive permanece activa para futuros bloqueos ygateway startse vuelve a activar limpiamente sin unlaunchctl enablemanual. Pase--disablepara suprimir persistentemente KeepAlive y RunAtLoad para que el puerta de enlace no se regenere hasta el próximogateway startexplícito; use esto cuando una parada manual debe sobrevivir a los reinicios o reinicios del sistema. gateway restart --safesolicita al Gateway en ejecución que realice un verificación previa del trabajo activo de OpenClaw y difiera el reinicio hasta que se complete la entrega de respuestas, las ejecuciones integradas y las ejecuciones de tareas.--safeno se puede combinar con--forceo--wait.gateway restart --wait 30sanula el presupuesto de drenaje de reinicio configurado para ese reinicio. Los números simples son milisegundos; se aceptan unidades comos,myh.--wait 0espera indefinidamente.gateway restart --safe --skip-deferralejecuta el reinicio seguro compatible con OpenClaw pero omite el puerta de aplazamiento para que el Gateway emita el reinicio inmediatamente incluso cuando se reportan bloqueadores. Escapatoria del operador para aplazamientos de ejecución de tareas atascadas; requiere--safe.gateway restart --forceomite el drenaje de trabajo activo y se reinicia inmediatamente. Úselo cuando un operador ya haya inspeccionado los bloqueadores de tareas listados y quiera el puerta de enlace ahora mismo.- Los comandos del ciclo de vida aceptan
--jsonpara secuencias de comandos.
Auth y SecretRefs en el momento de la instalación
- Cuando la autenticación por token requiere un token y
gateway.auth.tokenestá gestionado por SecretRef,gateway installvalida que el SecretRef sea resoluble 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 del token configurado no está resuelto, la instalación falla de forma segura (fails closed) en lugar de persistir el texto sin formato de reserva.
- Para la autenticación por contraseña en
gateway run, se prefiereOPENCLAW_GATEWAY_PASSWORD,--password-file, o ungateway.auth.passwordrespaldado por SecretRef en lugar de--passworden línea. - En el modo de autenticación inferido,
OPENCLAW_GATEWAY_PASSWORDsolo de shell no relaja los requisitos del token de instalación; use una configuración duradera (gateway.auth.passwordo configuraciónenv) al instalar un servicio gestionado. - Si tanto
gateway.auth.tokencomogateway.auth.passwordestán configurados ygateway.auth.modeno está establecido, la instalación se bloquea hasta que el modo se establezca explícitamente.
Descubrir gateways (Bonjour)
Sección titulada «Descubrir gateways (Bonjour)»gateway discover escanea balizas de Gateway (_openclaw-gw._tcp).
- DNS-SD multidifusión:
local. - DNS-SD unidifusión (Bonjour de área amplia): elija un dominio (ejemplo:
openclaw.internal.) y configure DNS dividido + un servidor DNS; consulte Bonjour.
Solo los gateways con el descubrimiento de Bonjour habilitado (predeterminado) anuncian la baliza.
Los registros de descubrimiento de área amplia pueden incluir estas sugerencias TXT:
role(sugerencia de rol de gateway)transport(sugerencia de transporte, p. ej.gateway)gatewayPort(puerto WebSocket, generalmente18789)sshPort(solo modo de descubrimiento completo; los clientes establecen por defecto los destinos SSH a22cuando está ausente)tailnetDns(nombre de host MagicDNS, cuando está disponible)gatewayTls/gatewayTlsSha256(TLS habilitado + huella digital del certificado)cliPath(solo modo de descubrimiento completo)
gateway discover
Sección titulada «gateway discover»openclaw gateway discoverEjemplos:
openclaw gateway discover --timeout 4000openclaw gateway discover --json | jq '.beacons[].wsUrl'