Gateway

• De forma predeterminada, el Gateway se niega a iniciar a menos que gateway.mode=local esté configurado en ~/.openclaw/openclaw.json. Usa --allow-unconfigured para ejecuciones ad hoc/de desarrollo.
• Se espera que openclaw onboard --mode local y openclaw setup escriban gateway.mode=local. Si el archivo existe pero falta gateway.mode, trátalo como una configuración rota o sobrescrita y repárala en lugar de asumir implícitamente el modo local.
• Si el archivo existe y falta gateway.mode, el Gateway trata eso como daño sospechoso en la configuración y se niega a "adivinar local" por ti.
• Se bloquea el enlace más allá de loopback sin autenticación (barrera de seguridad).
• SIGUSR1 activa un reinicio dentro del proceso cuando está autorizado (commands.restart está habilitado de forma predeterminada; establece commands.restart: false para bloquear el reinicio manual, mientras que la aplicación/actualización de herramientas/configuración del gateway sigue permitida).
• Los manejadores de SIGINT/SIGTERM detienen el proceso del gateway, pero no restauran ningún estado personalizado de la terminal. Si envuelves la CLI con una TUI o entrada en modo sin procesar, restaura la terminal antes de salir.

• Los registros conservan metadatos operativos: nombres de eventos, conteos, tamaños en bytes, lecturas de memoria, estado de colas/sesiones, nombres de canales/plugins y resúmenes de sesiones redactados. No conservan texto de chat, cuerpos de webhook, salidas de herramientas, cuerpos sin procesar de solicitud o respuesta, tokens, cookies, valores secretos, nombres de host ni ids de sesión sin procesar. Establece diagnostics.enabled: false para deshabilitar por completo el registrador.
• En salidas fatales del Gateway, tiempos de espera de apagado y fallos de inicio durante reinicio, OpenClaw escribe la misma instantánea diagnóstica en ~/.openclaw/logs/stability/openclaw-stability-*.json cuando el registrador tiene eventos. Inspecciona el paquete más nuevo con openclaw gateway stability --bundle latest; --limit, --type y --since-seq también se aplican a la salida de paquetes.

• gateway status permanece disponible para diagnósticos incluso cuando la configuración local de la CLI falta o no es válida.
• gateway status predeterminado prueba el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible en el momento del handshake. No prueba operaciones de lectura/escritura/administración.
• Los sondeos de diagnóstico no mutan nada para la autenticación inicial de dispositivos: reutilizan un token de dispositivo existente en caché cuando existe, pero no crean una nueva identidad de dispositivo de la CLI ni un registro de emparejamiento de dispositivo de solo lectura solo para comprobar el estado.
• gateway status resuelve SecretRefs de autenticación configuradas para la autenticación del sondeo cuando es posible.
• Si una SecretRef de autenticación requerida no se resuelve en esta ruta de comando, gateway status --json informa rpc.authWarning cuando falla la conectividad/autenticación del sondeo; pasa --token/--password explícitamente o resuelve primero la fuente del secreto.
• Si el sondeo se realiza correctamente, las advertencias de auth-ref no resueltas se suprimen para evitar falsos positivos.
• Usa --require-rpc en scripts y automatización cuando un servicio en escucha no sea suficiente y también necesites que las llamadas RPC con alcance de lectura estén sanas.
• --deep añade un escaneo de mejor esfuerzo para instalaciones adicionales de launchd/systemd/schtasks. Cuando se detectan varios servicios similares al gateway, la salida para personas imprime sugerencias de limpieza y advierte que la mayoría de las configuraciones deberían ejecutar un Gateway por máquina.
• --deep también informa una transferencia reciente de reinicio del supervisor del Gateway cuando el proceso del servicio salió limpiamente para un reinicio de supervisor externo.
• La salida para personas incluye la ruta resuelta del registro de archivo más una instantánea de rutas/validez de configuración CLI frente a servicio para ayudar a diagnosticar derivas de perfil o state-dir.

• En instalaciones systemd de Linux, las comprobaciones de deriva de autenticación del servicio leen valores Environment= y EnvironmentFile= de la unidad (incluidos %h, rutas entrecomilladas, varios archivos y archivos opcionales con -).
• Las comprobaciones de deriva resuelven SecretRefs de gateway.auth.token usando el entorno de runtime combinado (primero el entorno del comando de servicio y luego el entorno del proceso como reserva).
• Si la autenticación con token no está efectivamente activa (gateway.auth.mode explícito de password/none/trusted-proxy, o modo no definido donde la contraseña puede prevalecer y ningún candidato de token puede prevalecer), las comprobaciones de deriva de token omiten la resolución del token de configuración.

• Reachable: yes significa que al menos un destino aceptó una conexión WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only informa lo que el sondeo pudo probar sobre la autenticación. Es independiente de la accesibilidad.
• Read probe: ok significa que las llamadas RPC de detalle con alcance de lectura (health/status/system-presence/config.get) también se completaron correctamente.
• Read probe: limited - missing scope: operator.read significa que la conexión se completó, pero el RPC con alcance de lectura está limitado. Esto se informa como accesibilidad degradada, no como fallo completo.
• Read probe: failed después de Connect: ok significa 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 inaccesible.
• Igual que gateway status, el sondeo reutiliza la autenticación de dispositivo existente en caché, pero no crea una identidad de dispositivo inicial ni estado de emparejamiento.
• El código de salida es distinto de cero solo cuando ningún destino sondeado es accesible.

Nivel superior:

• ok: al menos un destino es accesible.
• 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 accesibles (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope o unknown).
• primaryTargetId: mejor destino para tratar como ganador activo en este orden: URL explícita, túnel SSH, remoto configurado y luego local loopback.
• warnings[]: registros de advertencia de mejor esfuerzo con code, message y targetIds opcionales.
• network: sugerencias de URL de local loopback/tailnet derivadas de la configuración actual y la red del host.
• discovery.timeoutMs y discovery.count: el presupuesto de descubrimiento/recuento de resultados real usado para esta pasada de sondeo.

Por destino (targets[].connect):

• ok: accesibilidad después de la clasificación de conexión + degradación.
• rpcOk: éxito completo de RPC de detalle.
• scopeLimited: el RPC de detalle falló porque faltaba el alcance de operador.

Por destino (targets[].auth):

• role: rol de autenticación informado en hello-ok cuando está disponible.
• scopes: alcances concedidos informados en hello-ok cuando están disponibles.
• capability: clasificación de capacidad de autenticación expuesta para ese destino.

• ssh_tunnel_failed: falló la configuración del túnel SSH; el comando recurrió a sondeos directos.
• multiple_gateways: más de un destino fue accesible; esto es inusual salvo que ejecutes perfiles aislados intencionalmente, como un bot de rescate.
• auth_secretref_unresolved: no se pudo resolver una SecretRef de autenticación configurada para un destino fallido.
• probe_scope_limited: la conexión WebSocket se completó, pero el sondeo de lectura quedó limitado por la falta 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Usa gateway restart para reiniciar un servicio gestionado. No encadenes gateway stop y gateway start como sustituto de reinicio; en macOS, gateway stop deshabilita intencionalmente el LaunchAgent antes de detenerlo.
• gateway restart --safe pide al Gateway en ejecución que haga una comprobación previa del trabajo activo de OpenClaw y difiera el reinicio hasta que se vacíen la entrega de respuestas, las ejecuciones integradas y las ejecuciones de tareas. --safe no se puede combinar con --force ni --wait.
• gateway restart --wait 30s sustituye el presupuesto configurado de drenaje de reinicio para ese reinicio. Los números sin unidad son milisegundos; se aceptan unidades como s, m y h. --wait 0 espera indefinidamente.
• gateway restart --force omite el drenaje de trabajo activo y reinicia inmediatamente. Úsalo cuando un operador ya haya inspeccionado los bloqueadores de tareas enumerados y quiera recuperar el gateway ahora.
• Los comandos de ciclo de vida aceptan --json para scripting.

• Cuando la autenticación por token requiere un token y gateway.auth.token está gestionado por SecretRef, gateway install valida que el SecretRef pueda resolverse, pero no conserva 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 cerrada en lugar de conservar texto sin formato alternativo.
• Para la autenticación por contraseña en gateway run, prefiere OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password respaldado por SecretRef en lugar de --password en línea.
• En el modo de autenticación inferido, OPENCLAW_GATEWAY_PASSWORD solo de shell no relaja los requisitos de token de instalación; usa configuración duradera (gateway.auth.password o env de configuración) al instalar un servicio administrado.
• Si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está definido, la instalación se bloquea hasta que el modo se establezca explícitamente.