CLI del Gateway

El Gateway es el servidor WebSocket de OpenClaw (canales, nodos, sesiones, hooks).

Los subcomandos en esta página se encuentran bajo openclaw gateway ....

Documentación relacionada:

Ejecutar el Gateway

Ejecuta un proceso local del Gateway:

openclaw gateway

Alias en primer plano:

openclaw gateway run

Notas:

  • Por defecto, el Gateway se niega a iniciar a menos que gateway.mode=local esté establecido en ~/.openclaw/openclaw.json. Usa --allow-unconfigured para ejecuciones ad-hoc/dev.
  • Vincular más allá del loopback sin autenticación está bloqueado (guardabarrera de seguridad).
  • SIGUSR1 activa un reinicio en proceso cuando está autorizado (commands.restart está habilitado por defecto; establece commands.restart: false para bloquear el reinicio manual, mientras que la herramienta de gateway/config apply/update siguen permitidos).
  • Los manejadores de SIGINT/SIGTERM detienen el proceso del gateway, pero no restauran ningún estado personalizado del terminal. Si envuelves el CLI con una TUI o entrada en modo raw, restaura el terminal antes de salir.

Opciones

  • --port <port>: puerto WebSocket (el valor por defecto viene de config/env; normalmente 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: modo de vinculación del listener.
  • --auth <token|password>: sobrescritura del modo de autenticación.
  • --token <token>: sobrescritura de token (también establece OPENCLAW_GATEWAY_TOKEN para el proceso).
  • --password <password>: sobrescritura de contraseña. Advertencia: las contraseñas en línea pueden exponerse en listados de procesos locales.
  • --password-file <path>: lee la contraseña del gateway desde un archivo.
  • --tailscale <off|serve|funnel>: exponer el Gateway vía Tailscale.
  • --tailscale-reset-on-exit: restablecer la configuración de Tailscale serve/funnel al apagar.
  • --allow-unconfigured: permitir inicio del gateway sin gateway.mode=local en la configuración.
  • --dev: crear una configuración + workspace de dev si no existen (omite BOOTSTRAP.md).
  • --reset: restablecer configuración + credenciales + sesiones + workspace de dev (requiere --dev).
  • --force: matar cualquier listener existente en el puerto seleccionado antes de iniciar.
  • --verbose: logs detallados.
  • --claude-cli-logs: solo mostrar logs de claude-cli en la consola (y habilitar su stdout/stderr).
  • --ws-log <auto|full|compact>: estilo de log de websocket (por defecto auto).
  • --compact: alias de --ws-log compact.
  • --raw-stream: registrar eventos de stream de modelo sin procesar en jsonl.
  • --raw-stream-path <path>: ruta del jsonl de stream sin procesar.

Consultar un Gateway en ejecución

Todos los comandos de consulta usan RPC por WebSocket.

Modos de salida:

  • Por defecto: legible por humanos (coloreado en TTY).
  • --json: JSON legible por máquinas (sin estilo/spinner).
  • --no-color (o NO_COLOR=1): deshabilitar ANSI manteniendo el diseño humano.

Opciones compartidas (donde estén soportadas):

  • --url <url>: URL WebSocket del Gateway.
  • --token <token>: token del Gateway.
  • --password <password>: contraseña del Gateway.
  • --timeout <ms>: timeout/presupuesto (varía por comando).
  • --expect-final: esperar una respuesta “final” (llamadas de agente).

Nota: cuando estableces --url, el CLI no recurre a credenciales de configuración o entorno. Pasa --token o --password explícitamente. La falta de credenciales explícitas es un error.

gateway health

openclaw gateway health --url ws://127.0.0.1:18789

gateway status

gateway status muestra el servicio del Gateway (launchd/systemd/schtasks) más un sondeo RPC opcional.

openclaw gateway status
openclaw gateway status --json

Opciones:

  • --url <url>: sobrescribir la URL del sondeo.
  • --token <token>: autenticación por token para el sondeo.
  • --password <password>: autenticación por contraseña para el sondeo.
  • --timeout <ms>: timeout del sondeo (por defecto 10000).
  • --no-probe: omitir el sondeo RPC (vista solo del servicio).
  • --deep: escanear servicios a nivel del sistema también.

Notas:

  • gateway status resuelve SecretRefs de autenticación configurados para la autenticación del sondeo cuando es posible.
  • Si un SecretRef de autenticación requerido no está resuelto en esta ruta de comando, la autenticación del sondeo puede fallar; pasa --token/--password explícitamente o resuelve la fuente del secreto primero.
  • En instalaciones Linux con systemd, las verificaciones de deriva de autenticación del servicio leen tanto valores Environment= como EnvironmentFile= de la unidad (incluyendo %h, rutas entre comillas, múltiples archivos y archivos opcionales con -).

gateway probe

gateway probe es el comando de “depurar todo”. Siempre sondea:

  • tu gateway remoto configurado (si está establecido), y
  • localhost (loopback) incluso si el remoto está configurado.

Si múltiples gateways son accesibles, los imprime todos. Se soportan múltiples gateways cuando usas perfiles/puertos aislados (ej., un bot de rescate), pero la mayoría de las instalaciones siguen ejecutando un solo gateway.

openclaw gateway probe
openclaw gateway probe --json

Remoto por SSH (paridad con la app Mac)

El modo “Remote over SSH” de la app macOS usa un port-forward local para que el gateway remoto (que puede estar vinculado solo al loopback) sea accesible en ws://127.0.0.1:<port>.

Equivalente en CLI:

openclaw gateway probe --ssh user@gateway-host

Opciones:

  • --ssh <target>: user@host o user@host:port (puerto por defecto 22).
  • --ssh-identity <path>: archivo de identidad.
  • --ssh-auto: elegir el primer host de gateway descubierto como destino SSH (solo LAN/WAB).

Configuración (opcional, usada como valores por defecto):

  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>

Helper RPC de bajo nivel.

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

Gestionar el servicio del Gateway

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

Notas:

  • gateway install soporta --port, --runtime, --token, --force, --json.
  • Cuando la autenticación por token requiere un token y gateway.auth.token está gestionado por SecretRef, gateway install valida 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 de token configurado no está resuelto, install falla de forma cerrada en lugar de persistir texto plano de fallback.
  • Para autenticación por contraseña en gateway run, prefiere OPENCLAW_GATEWAY_PASSWORD, --password-file, o un gateway.auth.password respaldado por SecretRef sobre --password en línea.
  • En modo de autenticación inferido, OPENCLAW_GATEWAY_PASSWORD/CLAWDBOT_GATEWAY_PASSWORD solo del shell no relaja los requisitos de token de install; usa configuración duradera (gateway.auth.password o config 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, install se bloquea hasta que el modo se establezca explícitamente.
  • Los comandos de ciclo de vida aceptan --json para scripting.

Descubrir gateways (Bonjour)

gateway discover escanea en busca de beacons del Gateway (_openclaw-gw._tcp).

  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): elige un dominio (ejemplo: openclaw.internal.) y configura split DNS + un servidor DNS; ver /gateway/bonjour

Solo los gateways con descubrimiento Bonjour habilitado (por defecto) anuncian el beacon.

Los registros de descubrimiento de área amplia incluyen (TXT):

  • role (indicación de rol del gateway)
  • transport (indicación de transporte, ej. gateway)
  • gatewayPort (puerto WebSocket, normalmente 18789)
  • sshPort (puerto SSH; por defecto 22 si no está presente)
  • tailnetDns (hostname MagicDNS, cuando está disponible)
  • gatewayTls / gatewayTlsSha256 (TLS habilitado + huella digital del certificado)
  • cliPath (indicación opcional para instalaciones remotas)

gateway discover

openclaw gateway discover

Opciones:

  • --timeout <ms>: timeout por comando (browse/resolve); por defecto 2000.
  • --json: salida legible por máquinas (también deshabilita estilo/spinner).

Ejemplos:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
arrow_back
Anterior
Doctor
Siguiente
Health
arrow_forward