Gateway

• Se niega a iniciarse a menos que gateway.mode=local esté establecido en ~/.openclaw/openclaw.json. Use --allow-unconfigured para ejecuciones ad hoc o de desarrollo; omite la protección sin escribir ni reparar la configuración.
• Cuando al iniciarse encuentra una configuración no válida que se puede reparar, un terminal interactivo ofrece ejecutar openclaw doctor --fix y, tras obtener el consentimiento, vuelve a intentar el inicio una vez. Las ejecuciones no interactivas nunca realizan reparaciones automáticamente; en su lugar, muestran el comando. Si la configuración reparada sigue sin ser válida, el inicio permanece detenido.
• openclaw onboard --mode local y openclaw setup escriben gateway.mode=local. Si el archivo de configuración existe pero falta gateway.mode, se considera que la configuración está dañada o sobrescrita, y el Gateway se niega a deducir local — vuelva a ejecutar la incorporación, establezca la clave manualmente o pase --allow-unconfigured.
• Se bloquea la vinculación más allá de la interfaz de bucle invertido sin autenticación.
• Actualmente, los valores lan, tailnet y custom de --bind se resuelven mediante rutas que solo usan IPv4; las configuraciones con host propio que solo admiten IPv6 necesitan un proceso auxiliar IPv4 o un proxy delante del Gateway.
• SIGUSR1 activa un reinicio dentro del proceso cuando está autorizado. commands.restart (valor predeterminado: habilitado) controla los SIGUSR1 enviados externamente; establézcalo en false para bloquear los reinicios manuales mediante señales del sistema operativo. La herramienta gateway orientada a agentes es de solo lectura; los agentes solicitan el reinicio mediante la herramienta de delegación openclaw aprobada por una persona.
• SIGINT/SIGTERM detienen el proceso, pero no restauran el estado personalizado del terminal; si encapsula la CLI en una TUI o una entrada en modo sin procesar, restaure el terminal antes de salir.

• Los registros conservan metadatos operativos: nombres de eventos, recuentos, tamaños en bytes, lecturas de memoria, estado de colas y sesiones, ids de aprobación, nombres de canales y plugins, y resúmenes de sesión censurados. Excluyen texto de chat, cuerpos de webhooks, salidas de herramientas, cuerpos de solicitudes y respuestas sin procesar, tokens, cookies, valores secretos, nombres de host e ids de sesión sin procesar. Establezca diagnostics.enabled: false para desactivar por completo el registro.
• Las salidas fatales del Gateway, los tiempos de espera de apagado y los fallos de inicio tras un reinicio escriben la misma instantánea de diagnóstico en ~/.openclaw/logs/stability/openclaw-stability-*.json cuando el registro contiene eventos. Inspeccione el paquete más reciente con openclaw gateway stability --bundle latest; --limit, --type y --since-seq también se aplican a la salida de los paquetes.

• Permanece disponible para realizar diagnósticos aunque falte la configuración local de la CLI o esta no sea válida.
• La salida predeterminada demuestra el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible durante el protocolo de enlace, pero no las operaciones de lectura, escritura o administración.
• Las sondas no realizan cambios para la autenticación inicial de dispositivos: reutilizan un token de dispositivo almacenado en caché cuando existe, pero nunca crean una nueva identidad de dispositivo de la CLI ni un registro de emparejamiento de solo lectura únicamente para comprobar el estado.
• Resuelve las SecretRefs de autenticación configuradas para autenticar la sonda cuando es posible. Si una SecretRef obligatoria no se puede resolver, --json informa de rpc.authWarning cuando falla la conectividad o autenticación de la sonda; proporcione --token/--password explícitamente o corrija el origen del secreto. Las advertencias sobre autenticación sin resolver se suprimen cuando la sonda funciona correctamente.
• La salida JSON incluye gateway.version cuando el Gateway en ejecución lo proporciona; --require-rpc puede recurrir a la carga útil RPC de status.runtimeVersion si la sonda del protocolo de enlace no puede proporcionar metadatos de versión.
• Utilice --require-rpc en scripts y automatizaciones cuando no baste con que el servicio esté escuchando y también sea necesario que RPC con ámbito de lectura funcione correctamente.
• --deep busca instalaciones adicionales de launchd/systemd/schtasks; cuando se encuentran varios servicios similares a un gateway, la salida para personas muestra sugerencias de limpieza (normalmente, ejecutar un gateway por máquina) e informa de una transferencia de reinicio reciente del supervisor cuando corresponde.
• --deep también ejecuta la validación de la configuración en modo compatible con plugins (pluginValidation: "full") y muestra advertencias del manifiesto de plugins (por ejemplo, la ausencia de metadatos de configuración del canal). El valor predeterminado gateway status conserva la ruta rápida de solo lectura que omite la validación de plugins.
• La salida para personas incluye la ruta resuelta del archivo de registro, además de las rutas y la validez de la configuración de la CLI y del servicio, para ayudar a diagnosticar divergencias del perfil o del directorio de estado.
• La salida para personas incluye Gateway heap: con el límite aplicado y su cálculo adaptativo. La salida JSON presenta el mismo informe como service.gatewayHeap.

• Las comprobaciones de divergencia de autenticación del servicio leen tanto Environment= como EnvironmentFile= de la unidad (incluidos %h, rutas entre comillas, varios archivos y archivos - opcionales).
• Resuelve las SecretRefs de gateway.auth.token mediante el entorno de ejecución combinado (primero el entorno del comando del servicio y después el entorno del proceso como alternativa).
• Las comprobaciones de divergencia de tokens omiten la resolución del token de configuración cuando la autenticación mediante token no está activa de forma efectiva (gateway.auth.mode establecido explícitamente en password/none/trusted-proxy, o modo sin establecer cuando la contraseña puede prevalecer y ningún token candidato puede hacerlo).

• 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 de lo que la sonda pudo demostrar sobre la autenticación, por separado de la accesibilidad.
• Read probe: ok significa que las llamadas RPC detalladas con ámbito 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 realizó correctamente, pero RPC con ámbito de lectura está limitado. Se informa como accesibilidad degradada, no como fallo total.
• Read probe: failed después de Connect: ok significa que se estableció la conexión WebSocket, pero los diagnósticos de lectura posteriores agotaron el tiempo de espera o fallaron; también se considera un estado degradado, no inaccesible.
• Al igual que gateway status, la sonda reutiliza la autenticación de dispositivo existente en caché, pero no crea una identidad de dispositivo ni un estado de emparejamiento iniciales.
• El código de salida solo es distinto de cero cuando no se puede acceder a ninguno de los destinos sondeados.

Nivel superior:

• ok: al menos un destino es accesible.
• degraded: al menos un destino aceptó una conexión, pero no completó los diagnósticos RPC detallados completos.
• 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 tratarlo como el ganador activo, en este orden: URL explícita, túnel SSH, remoto configurado, bucle local.
• warnings[]: registros de advertencia de mejor esfuerzo con code, message y targetIds opcional.
• network: sugerencias de URL de bucle local/tailnet derivadas de la configuración actual y la red del host.
• discovery.timeoutMs / discovery.count: el presupuesto de descubrimiento y el recuento de resultados reales utilizados para esta pasada de sondeo.

Por destino (targets[].connect): ok (accesibilidad + clasificación degradada), rpcOk (éxito del RPC detallado completo), scopeLimited (el RPC detallado falló por falta del ámbito de operador).

Por destino (targets[].auth): role y scopes se indican en hello-ok cuando están disponibles, junto con la clasificación capability mostrada.

• ssh_tunnel_failed: falló la configuración del túnel SSH; el comando recurrió a sondeos directos.
• multiple_gateways: se pudo acceder a identidades de Gateway distintas, o OpenClaw no pudo demostrar que los destinos accesibles correspondieran al 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 con errores.
• probe_scope_limited: la conexión WebSocket se realizó correctamente, pero el sondeo de lectura estuvo limitado por la falta de operator.read.
• local_tls_runtime_unavailable: TLS está habilitado en el Gateway local, pero OpenClaw no pudo cargar la huella digital del certificado local.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node> (valor predeterminado: node), --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --force, --json

• gateway start es idempotente: cuando el servicio gestionado ya está en ejecución, informa del proceso en ejecución y no lo modifica. Un servicio cargado pero detenido se inicia como antes.
• Utilice gateway restart para reiniciar un servicio gestionado. No encadene gateway stop y gateway start como sustituto del reinicio.
• En un shell no interactivo, gateway stop requiere --force. Los terminales interactivos mantienen el comportamiento existente sin solicitudes. Para automatización y pruebas, es preferible utilizar gateway run --dev o un --profile aislado con un puerto libre.
• En macOS, gateway stop utiliza launchctl bootout de forma predeterminada, lo que elimina el LaunchAgent de la sesión de arranque actual sin conservar una desactivación: la recuperación automática de KeepAlive permanece activa para futuros fallos y gateway start lo vuelve a habilitar correctamente sin necesidad de ejecutar manualmente launchctl enable. Pase --disable para suprimir de forma persistente KeepAlive y RunAtLoad, de modo que el Gateway no vuelva a generarse hasta el siguiente gateway start explícito; utilice esta opción cuando una detención manual deba persistir tras los reinicios.
• Las modificaciones del ciclo de vida del Gateway añaden registros de auditoría de clave-valor de mejor esfuerzo a <state-dir>/logs/gateway-restart.log, incluidas las operaciones de inicio, detención y reinicio de la CLI, las solicitudes de reinicio seguro, los reinicios del supervisor y las transferencias desvinculadas.
• Los comandos del ciclo de vida aceptan --json para la creación de scripts.

• gateway install escribe un valor NODE_OPTIONS exclusivo para el montón del servicio Gateway gestionado. Su objetivo es el 50 % de la memoria restringida cuando Node informa de un límite de contenedor o servicio; en caso contrario, el 50 % de la memoria física.
• El intervalo objetivo nominal es de 2048–8192 MiB, con un límite adicional del 75 % para reservar espacio para la memoria nativa. En hosts pequeños, ese límite de espacio reservado puede situar el límite aplicado por debajo del mínimo nominal de 2048 MiB.
• Un valor --max-old-space-size explícito y válido ya almacenado en el servicio instalado se conserva durante las reinstalaciones forzadas y las reparaciones del doctor. Otros indicadores de NODE_OPTIONS no se transfieren al servicio gestionado.
• El valor NODE_OPTIONS del shell del entorno no anula esta política. Utilice gateway status o doctor para inspeccionar el valor instalado; ejecute openclaw gateway install --force para regenerar metadatos de servicios antiguos que no tengan una configuración de montón gestionado.
• La política solo se aplica al servicio Gateway gestionado. gateway run en primer plano, los servicios de Node y las unidades del supervisor escritas manualmente conservan su propia configuración de tiempo de ejecución.

• Cuando la autenticación mediante token requiere un token y gateway.auth.token se gestiona mediante SecretRef, gateway install valida que la SecretRef se pueda resolver, pero no conserva el token resuelto en los metadatos del entorno del servicio.
• Si la autenticación mediante token requiere un token y la SecretRef del token configurada no se puede resolver, la instalación se cierra de forma segura en lugar de conservar texto sin formato de respaldo.
• Para la autenticación mediante contraseña en gateway run, es preferible utilizar OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password respaldado por SecretRef en lugar de --password insertado.
• En el modo de autenticación inferido, OPENCLAW_GATEWAY_PASSWORD exclusivo del shell no relaja los requisitos de token de la instalación; utilice una configuración duradera (gateway.auth.password o la configuración env) al instalar un servicio gestionado.
• Si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está establecido, la instalación queda bloqueada hasta que se establezca explícitamente el modo.