Gateway

• De forma predeterminada, el Gateway se niega a iniciar a menos que gateway.mode=local esté definido 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 lo trata 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 (protección de seguridad).
• lan, tailnet y custom actualmente se resuelven mediante rutas BYOH solo IPv4.
• BYOH solo IPv6 no es compatible de forma nativa en esta ruta actualmente. Usa un sidecar o proxy IPv4 si el host en sí es solo IPv6.
• SIGUSR1 activa un reinicio en proceso cuando está autorizado (commands.restart está habilitado de forma predeterminada; define commands.restart: false para bloquear el reinicio manual, mientras que la aplicación/actualización de herramientas/configuración del gateway permanece 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 raw, 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, ids de aprobación, 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 solicitudes o respuestas, tokens, cookies, valores secretos, nombres de host ni ids de sesión sin procesar. Define diagnostics.enabled: false para deshabilitar el registrador por completo.
• En salidas fatales del Gateway, tiempos de espera de apagado y fallos de inicio tras reinicio, OpenClaw escribe la misma instantánea de diagnóstico 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 del paquete.

• gateway status sigue disponible para diagnósticos incluso cuando la configuración local de 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.
• Las comprobaciones de diagnóstico no mutan la autenticación de dispositivos por primera vez: reutilizan un token de dispositivo en caché existente cuando existe uno, pero no crean una nueva identidad de dispositivo de 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 de la comprobación 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 la conectividad/autenticación de la comprobación falla; pasa --token/--password explícitamente o resuelve primero la fuente del secreto.
• Si la comprobación tiene éxito, las advertencias de referencias de autenticación no resueltas se suprimen para evitar falsos positivos.
• Cuando la comprobación está habilitada, la salida JSON incluye gateway.version cuando el Gateway en ejecución la informa; --require-rpc puede recurrir a la carga RPC status.runtimeVersion si la comprobación de handshake de seguimiento no puede proporcionar metadatos de versión.
• Usa --require-rpc en scripts y automatización cuando un servicio en escucha no es suficiente y también necesitas que las llamadas RPC con alcance de lectura estén sanas.
• --deep añade un análisis 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 configuraciones deberían ejecutar un gateway por máquina.
• --deep también informa una delegación reciente de reinicio del supervisor de Gateway cuando el proceso del servicio salió limpiamente por un reinicio de supervisor externo.
• --deep ejecuta validación de configuración en modo consciente de plugins (pluginValidation: "full") y muestra advertencias de manifiestos de plugins configurados (por ejemplo, metadatos de configuración de canal faltantes) para que las comprobaciones de instalación y actualización las detecten. gateway status predeterminado conserva 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 más una instantánea de rutas/validez de configuración de CLI frente a servicio para ayudar a diagnosticar divergencias de perfil o directorio de estado.

• 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 entre comillas, múltiples archivos y archivos opcionales -).
• Las comprobaciones de deriva resuelven SecretRefs de gateway.auth.token usando el entorno de ejecución fusionado (primero el entorno del comando de servicio y luego el entorno del proceso como respaldo).
• 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 la comprobación pudo probar sobre la autenticación. Es independiente de la alcanzabilidad.
• 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 la RPC con alcance de lectura está limitada. Esto se informa como alcanzabilidad degradada, no como fallo completo.
• Read probe: failed después de Connect: ok significa que Gateway aceptó la conexión WebSocket, pero los diagnósticos de lectura de seguimiento agotaron el tiempo de espera o fallaron. Esto también es alcanzabilidad degradada, no un Gateway inalcanzable.
• Al igual que gateway status, la comprobación reutiliza la autenticación de dispositivo en caché existente, pero no crea identidad de dispositivo por primera vez ni estado de emparejamiento.
• El código de salida es distinto de cero solo cuando ningún destino comprobado es alcanzable.

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 detallados.
• capability: mejor capacidad observada entre los destinos alcanzables (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 local loopback/tailnet derivadas de la configuración actual y la red del host.
• discovery.timeoutMs y discovery.count: el presupuesto de descubrimiento y conteo de resultados reales usados para esta pasada de comprobación.

Por destino (targets[].connect):

• ok: alcanzabilidad después de la clasificación de conexión + degradación.
• rpcOk: éxito completo de RPC detallada.
• scopeLimited: la RPC detallada 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 de capacidad de autenticación expuesta para ese destino.

• ssh_tunnel_failed: falló la configuración del túnel SSH; el comando recurrió a comprobaciones directas.
• multiple_gateways: identidades de gateway distintas eran alcanzables, o OpenClaw no pudo probar 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 esta advertencia.
• auth_secretref_unresolved: no se pudo resolver una SecretRef de autenticación configurada para un destino fallido.
• probe_scope_limited: la conexión WebSocket tuvo éxito, pero la comprobación de lectura estuvo limitada 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, --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 deshabilitación: la recuperación automática de KeepAlive permanece activa para futuros bloqueos y gateway start vuelve a habilitarlo limpiamente sin un launchctl enable manual. Pasa --disable para suprimir KeepAlive y RunAtLoad de forma persistente, de modo que el Gateway no se vuelva a iniciar hasta el siguiente gateway start explícito; usa esto 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 y programe un único reinicio combinado después de que el trabajo activo se vacíe. El reinicio seguro predeterminado espera el trabajo activo hasta el gateway.reload.deferralTimeoutMs configurado (5 minutos de forma predeterminada); cuando ese presupuesto expira, el reinicio se fuerza. Establece gateway.reload.deferralTimeoutMs en 0 para una espera segura indefinida que nunca fuerza. --safe no se puede combinar con --force ni --wait.
• gateway restart --wait 30s anula el presupuesto configurado de vaciado 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 --safe --skip-deferral ejecuta el reinicio seguro compatible con OpenClaw, pero omite la puerta de aplazamiento para que el Gateway emita el reinicio de inmediato incluso cuando se informen bloqueadores. Es una vía de escape para operadores ante aplazamientos de ejecuciones de tareas atascadas; requiere --safe.
• gateway restart --force omite el vaciado del trabajo activo y reinicia de inmediato. Úsalo cuando un operador ya haya inspeccionado los bloqueadores de tareas listados y quiera que el Gateway vuelva ahora.
• Los comandos de ciclo de vida aceptan --json para scripts.

• Cuando la autenticación por 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 por token requiere un token y el SecretRef de token configurado no se resuelve, la instalación falla de forma cerrada en lugar de conservar texto sin formato de respaldo.
• Para autenticación por 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 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.