Gateway

• De forma predeterminada, el Gateway se niega a iniciarse a menos que gateway.mode=local esté establecido 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, trata eso 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 lo trata como un daño sospechoso de 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 aplicar/actualizar la herramienta/configuración del gateway sigue permitido).
• Los manejadores SIGINT/SIGTERM detienen el proceso del gateway, pero no restauran ningún estado personalizado del terminal. Si envuelves la CLI con una TUI o entrada en modo raw, restaura el 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 sesión redactados. No conservan texto de chat, cuerpos de webhook, salidas de herramientas, cuerpos sin procesar de solicitudes o respuestas, tokens, cookies, valores secretos, hostnames ni ids de sesión sin procesar. Establece diagnostics.enabled: false para deshabilitar por completo el registrador.
• En salidas fatales del Gateway, timeouts de apagado y fallos de inicio tras reinicio, OpenClaw escribe la misma instantánea diagnóstica en ~/.openclaw/logs/stability/openclaw-stability-*.json cuando el registrador tiene eventos. Inspecciona el bundle más nuevo con openclaw gateway stability --bundle latest; --limit, --type y --since-seq también se aplican a la salida de bundle.

• gateway status sigue disponible para diagnósticos incluso cuando la configuración local de la CLI falta o no es válida.
• gateway status predeterminado comprueba el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible durante el handshake. No comprueba operaciones de lectura/escritura/administración.
• Los sondeos de diagnóstico no mutan la autenticación de dispositivos por primera vez: reutilizan un token de dispositivo en caché existente 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 los SecretRefs de autenticación configurados para la autenticación del sondeo cuando es posible.
• Si un SecretRef de autenticación requerido no se resuelve en esta ruta de comando, gateway status --json informa rpc.authWarning cuando la conectividad/autenticación del sondeo falla; pasa --token/--password explícitamente o resuelve primero el origen del secreto.
• Si el sondeo tiene éxito, las advertencias de referencia de autenticación sin resolver 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 de alcance de lectura estén sanas.
• --deep agrega un escaneo de mejor esfuerzo para instalaciones adicionales de launchd/systemd/schtasks. Cuando se detectan varios servicios similares a 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.
• --deep también informa una transferencia reciente de reinicio del supervisor de Gateway cuando el proceso del servicio salió limpiamente para un reinicio de supervisor externo.
• --deep ejecuta la validación de configuración en modo compatible con plugins (pluginValidation: "full") y muestra advertencias de manifiestos de plugins configurados (por ejemplo, metadatos faltantes de configuración de canal) para que las comprobaciones smoke de instalación y actualización las detecten. gateway status predeterminado mantiene la ruta rápida de solo lectura que omite la validación de plugins.
• La salida humana incluye la ruta resuelta del log en archivo más la instantánea de rutas/validez de configuración CLI-vs-servicio para ayudar a diagnosticar desviaciones de perfil o de directorio de estado.

• En instalaciones Linux systemd, las comprobaciones de desviación de autenticación del servicio leen tanto los valores Environment= como EnvironmentFile= de la unidad (incluidos %h, rutas entre comillas, varios archivos y archivos - opcionales).
• Las comprobaciones de desviación resuelven los SecretRefs de gateway.auth.token usando el entorno de ejecución combinado (primero el entorno del comando de servicio, luego el entorno del proceso como alternativa).
• Si la autenticación por token no está activa efectivamente (gateway.auth.mode explícito de password/none/trusted-proxy, o modo sin definir donde la contraseña puede ganar y ningún candidato de token puede ganar), las comprobaciones de desviación 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 comprobar 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 tuvieron éxito.
• Read probe: limited - missing scope: operator.read significa que la conexión tuvo éxito, 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 o fallaron. Esto también es accesibilidad degradada, no un Gateway inaccesible.
• Al igual que gateway status, el sondeo reutiliza la autenticación de dispositivo en caché existente, pero no crea una identidad de dispositivo por primera vez ni estado de emparejamiento.
• El código de salida es distinto de cero solo cuando no se puede acceder a ningún destino sondeado.

Nivel superior:

• ok: se puede acceder al menos a un destino.
• degraded: al menos un destino aceptó una conexión pero no completó todos los diagnósticos RPC de detalle.
• capability: mejor capacidad vista 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 opcional.
• 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 connect + clasificación degradada.
• rpcOk: éxito completo del RPC de detalle.
• scopeLimited: el RPC de detalle falló por falta de 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: la clasificación expuesta de capacidad de autenticación para ese destino.

• ssh_tunnel_failed: falló la configuración del túnel SSH; el comando recurrió a sondeos directos.
• multiple_gateways: se pudo acceder a más de un destino; esto es inusual salvo que ejecutes perfiles aislados intencionalmente, como un bot de rescate.
• 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 el sondeo de lectura estuvo limitado por 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, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Usa gateway restart para reiniciar un servicio administrado. No encadenes gateway stop y gateway start como sustituto de reinicio.
• En macOS, gateway stop usa launchctl bootout de forma predeterminada, lo que elimina el LaunchAgent de la sesión de arranque actual sin conservar una desactivación persistente: la recuperación automática de KeepAlive sigue activa para bloqueos futuros y gateway start vuelve a habilitarlo limpiamente sin un launchctl enable manual. Pasa --disable para suprimir de forma persistente KeepAlive y RunAtLoad, de modo que el gateway no reaparezca hasta el siguiente gateway start explícito; úsalo cuando una detención manual deba sobrevivir a reinicios del equipo o del sistema.
• gateway restart --safe pide al Gateway en ejecución que compruebe previamente el trabajo activo de OpenClaw y aplace el reinicio hasta que se vacíen la entrega de respuestas, las ejecuciones incrustadas y las ejecuciones de tareas. --safe no se puede combinar con --force ni --wait.
• gateway restart --wait 30s anula el presupuesto de vaciado de reinicio configurado para ese reinicio. Los números sin unidad son milisegundos; se aceptan unidades como s, m y h. --wait 0 espera indefinidamente.
• gateway restart --safe --skip-deferral ejecuta el reinicio seguro con conocimiento de OpenClaw, pero omite la compuerta de aplazamiento para que el Gateway emita el reinicio inmediatamente incluso cuando se informen bloqueadores. Vía de escape para operadores ante aplazamientos de ejecuciones de tareas atascadas; requiere --safe.
• gateway restart --force omite el vaciado 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 con token requiere un token y gateway.auth.token está administrado por SecretRef, gateway install valida que el SecretRef se pueda resolver, pero no conserva el token resuelto en los metadatos de entorno del servicio.
• Si la autenticación con token requiere un token y el SecretRef de token configurado no se puede resolver, la instalación falla de forma cerrada en lugar de conservar texto sin formato alternativo.
• Para autenticación con contraseña en gateway run, prefiere OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password respaldado por SecretRef antes que --password en línea.
• En modo de autenticación inferida, OPENCLAW_GATEWAY_PASSWORD solo de shell no relaja los requisitos de token de instalación; usa configuración duradera (gateway.auth.password o config env) 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.