Configura OpenClaw Gateway: Guía de comandos y CLI

Descripción general de Gateway CLI

El Gateway es el servidor WebSocket de OpenClaw, diseñado para gestionar canales, nodos, sesiones y hooks de manera eficiente. Esta herramienta es fundamental para que puedas mantener una comunicación fluida en tu infraestructura utilizando OpenClaw para la gestión de Gateway.

Los subcomandos que verás a continuación se ejecutan bajo el comando principal openclaw gateway.

Documentación relacionada:

• /gateway/bonjour
• /gateway/discovery
• /gateway/configuration

Instalación de Gateway CLI

Para comenzar a utilizar las funciones de Gateway, primero debes asegurarte de tener instalado el entorno de Node.js en tu sistema. Puedes instalar la herramienta globalmente mediante npm o pnpm para acceder a ella desde cualquier lugar de tu terminal.

1. Ejecuta el siguiente comando en tu terminal para instalar el paquete:

npm install -g @openclaw/gateway

2. Si prefieres utilizar pnpm, puedes ejecutar este comando:

pnpm add -g @openclaw/gateway

Verificación de la versión de Gateway

Es importante que siempre compruebes que estás ejecutando la versión más reciente de la CLI para evitar problemas de compatibilidad. Esto te asegura que todas las funciones de Gateway operen según lo esperado en tu entorno de Docker o local.

1. Verifica la instalación ejecutando el comando de versión:

openclaw gateway --version

2. Si necesitas obtener más detalles sobre el estado actual de tu Gateway, puedes usar el comando de ayuda:

openclaw gateway --help

Ejecución del servidor Gateway

Una vez que hayas configurado tu entorno, puedes iniciar el servidor para procesar tus conexiones y webhook de forma inmediata. Asegúrate de que tu archivo de configuración en formato JSON esté correctamente ubicado antes de lanzar el proceso.

1. Inicia el servidor de Gateway con el siguiente comando:

openclaw gateway start --config config.json

2. Si deseas ejecutarlo en modo de depuración para ver los logs en tiempo real, utiliza el flag correspondiente:

openclaw gateway start --debug

Configuración de hooks en Gateway

Los hooks te permiten extender la funcionalidad de OpenClaw al reaccionar ante eventos específicos dentro de tus canales. Configurar estos puntos de entrada es sencillo y te permite integrar servicios externos a través de GitHub o cualquier otro proveedor de servicios.

1. Define tus hooks en el archivo de configuración para que el Gateway pueda reconocerlos:

{
  "hooks": {
    "onConnect": "http://localhost:3000/webhook",
    "onDisconnect": "http://localhost:3000/webhook"
  }
}

2. Reinicia el servicio para aplicar los cambios en la configuración de tus hooks:

openclaw gateway restart

AI Setup Assistant

Ejecutar el Gateway

Para poner en marcha un proceso local de Gateway, simplemente ejecuta el siguiente comando en tu terminal:

openclaw gateway

Si prefieres utilizar el alias para ejecutarlo en primer plano, usa este comando:

openclaw gateway run

Ten en cuenta los siguientes puntos importantes sobre el comportamiento del proceso:

1. Por defecto, el Gateway se niega a iniciar a menos que gateway.mode=local esté configurado en ~/.openclaw/openclaw.json. Puedes usar --allow-unconfigured para ejecuciones rápidas o de desarrollo.
2. Se espera que openclaw onboard --mode local y openclaw setup escriban gateway.mode=local. Si el archivo existe pero falta gateway.mode, el sistema lo trata como una configuración dañada o alterada y la repara en lugar de asumir el modo local implícitamente.
3. Si el archivo existe y gateway.mode no está presente, el Gateway considera que la configuración es sospechosa y se niega a “adivinar” el modo local por ti.
4. La vinculación fuera del loopback sin autenticación está bloqueada como medida de seguridad.
5. SIGUSR1 activa un reinicio dentro del proceso cuando está autorizado (commands.restart está habilitado por defecto; puedes establecer commands.restart: false para bloquear el reinicio manual, aunque las herramientas del gateway, la aplicación de configuración y las actualizaciones seguirán permitidas).
6. Los manejadores 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, asegúrate de restaurar la terminal antes de salir.

Opciones

Puedes personalizar el comportamiento del proceso utilizando las siguientes banderas y parámetros al ejecutar el comando:

1. --port <port>: Puerto WebSocket (el valor por defecto proviene de la configuración o variables de entorno; usualmente 18789).
2. --bind <loopback|lan|tailnet|auto|custom>: Modo de enlace del listener.
3. --auth <token|password>: Sobrescribe el modo de autenticación.
4. --token <token>: Sobrescribe el token (también establece OPENCLAW_GATEWAY_TOKEN para el proceso).
5. --password <password>: Sobrescribe la contraseña. Advertencia: las contraseñas en línea pueden quedar expuestas en los listados de procesos locales.
6. --password-file <path>: Lee la contraseña del Gateway desde un archivo.
7. --tailscale <off|serve|funnel>: Expone el Gateway a través de Tailscale.
8. --tailscale-reset-on-exit: Restablece la configuración de serve/funnel de Tailscale al apagar.
9. --allow-unconfigured: Permite iniciar el Gateway sin gateway.mode=local en la configuración. Esto omite la protección de inicio solo para arranques rápidos o de desarrollo; no escribe ni repara el archivo de configuración.
10. --dev: Crea una configuración de desarrollo y un espacio de trabajo si faltan (omite BOOTSTRAP.md).
11. --reset: Restablece la configuración de desarrollo, credenciales, sesiones y espacio de trabajo (requiere --dev).
12. --force: Elimina cualquier listener existente en el puerto seleccionado antes de iniciar.
13. --verbose: Muestra registros detallados.
14. --cli-backend-logs: Muestra solo los registros del backend de la CLI en la consola (y habilita stdout/stderr).
15. --ws-log <auto|full|compact>: Estilo de registro de WebSocket (por defecto auto).
16. --compact: Alias para --ws-log compact.
17. --raw-stream: Registra eventos de flujo del modelo sin procesar en formato JSONL.
18. --raw-stream-path <path>: Ruta para el archivo JSONL de flujo sin procesar.

Para realizar el perfilado durante el inicio, puedes seguir estas instrucciones:

1. Establece OPENCLAW_GATEWAY_STARTUP_TRACE=1 para registrar los tiempos de fase durante el inicio del Gateway.
2. Ejecuta pnpm test:startup:gateway -- --runs 5 --warmup 1 para realizar un benchmark del inicio del Gateway. El benchmark registra la salida del primer proceso, /healthz, /readyz y los tiempos de traza de inicio.

Consultar un Gateway en ejecución

Todos los comandos de consulta utilizan WebSocket RPC para comunicarse con el servicio.

Modos de salida:

• Predeterminado: legible para humanos (con colores en la TTY).
• --json: JSON legible por máquina (sin estilos ni animaciones).
• --no-color (o NO_COLOR=1): deshabilita ANSI manteniendo el diseño legible.

Opciones compartidas (donde sean compatibles):

• --url <url>: URL de WebSocket del Gateway.
• --token <token>: Token del Gateway.
• --password <password>: Contraseña del Gateway.
• --timeout <ms>: tiempo de espera o presupuesto (varía según el comando).
• --expect-final: espera una respuesta “final” (llamadas de agente).

Nota: cuando configuras --url, la CLI no recurre a las credenciales de configuración o del entorno. Debes pasar --token o --password explícitamente. La falta de credenciales explícitas resultará en un error.

gateway health

El comando gateway health verifica el estado de salud del servicio.

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

El endpoint HTTP /healthz es una prueba de vivacidad: responde una vez que el servidor puede contestar peticiones HTTP. El endpoint HTTP /readyz es más estricto y permanece en estado rojo mientras los sidecars de inicio, canales o webhook configurados aún se están estableciendo.

gateway usage-cost

Este comando permite obtener resúmenes de los costos de uso a partir de los registros de sesión.

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

Opciones:

• --days <days>: número de días a incluir (predeterminado 30).

gateway status

gateway status muestra el estado del servicio Gateway (launchd/systemd/schtasks) junto con una prueba opcional de conectividad y capacidad de autenticación.

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

Opciones:

• --url <url>: añade un objetivo de prueba explícito. El remoto configurado + localhost también se prueban.
• --token <token>: autenticación mediante token para la prueba.
• --password <password>: autenticación mediante contraseña para la prueba.
• --timeout <ms>: tiempo de espera de la prueba (predeterminado 10000).
• --no-probe: omite la prueba de conectividad (vista solo de servicio).
• --deep: escanea también los servicios a nivel de sistema.
• --require-rpc: actualiza la prueba de conectividad predeterminada a una prueba de lectura y sale con un código distinto de cero si falla. No se puede combinar con --no-probe.

Notas:

• gateway status permanece disponible para diagnósticos incluso cuando la configuración local de la CLI falta o es inválida.
• El 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.
• gateway status resuelve los SecretRefs de autenticación configurados para la prueba 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 falla la conectividad o la autenticación; pasa --token/--password explícitamente o resuelve primero la fuente del secreto.
• Si la prueba tiene éxito, 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 necesites que las llamadas RPC de alcance de lectura también estén saludables.
• --deep añade un escaneo de mejor esfuerzo para instalaciones adicionales de launchd/systemd/schtasks. Cuando se detectan múltiples servicios tipo gateway, la salida humana imprime sugerencias de limpieza y advierte que la mayoría de las configuraciones deben ejecutar un solo gateway por máquina.
• La salida humana incluye la ruta del archivo de registro resuelta más las rutas de configuración de la CLI frente al servicio para ayudar a diagnosticar desviaciones en el perfil o directorio de estado.
• En instalaciones de Linux con systemd, las comprobaciones de desviación de autenticación del servicio leen tanto los valores Environment= como EnvironmentFile= de la unidad (incluyendo %h, rutas entre comillas, múltiples 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 respaldo del entorno del proceso).
• Si la autenticación por token no está efectivamente activa (modo gateway.auth.mode explícito de password/none/trusted-proxy, o modo no establecido donde la contraseña puede ganar y no hay candidato a token), las comprobaciones de desviación de token omiten la resolución del token de configuración.

gateway probe

gateway probe es el comando para “depurar todo”. Siempre prueba:

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

Si pasas --url, ese objetivo explícito se añade antes que ambos. La salida humana etiqueta los objetivos como:

• URL (explicit)
• Remote (configured) o Remote (configured, inactive)
• Local loopback

Si hay múltiples gateways alcanzables, los imprime todos. Se admiten múltiples gateways cuando usas perfiles/puertos aislados (por ejemplo, un bot de rescate), pero la mayoría de las instalaciones ejecutan un solo gateway.

openclaw gateway probe
openclaw gateway probe --json

Interpretación:

• Reachable: yes significa que al menos un objetivo aceptó una conexión WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only informa lo que la prueba pudo verificar sobre la autenticación. Es independiente de la alcanzabilidad.
• Read probe: ok significa que las llamadas RPC de detalle de 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 de alcance de lectura es limitado. Esto se reporta como alcanzabilidad degradada, no como fallo total.
• El código de salida es distinto de cero solo cuando ningún objetivo probado es alcanzable.

Notas sobre JSON (--json):

• Nivel superior:
  • ok: al menos un objetivo es alcanzable.
  • degraded: al menos un objetivo tuvo un RPC de detalle con alcance limitado.
  • capability: mejor capacidad vista entre los objetivos alcanzables (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, o unknown).
  • primaryTargetId: mejor objetivo a tratar como el ganador activo en este orden: URL explícita, túnel SSH, remoto configurado, luego loopback local.
  • warnings[]: registros de advertencia de mejor esfuerzo con code, message, y targetIds opcionales.
  • network: sugerencias de URL de loopback local/tailnet derivadas de la configuración actual y la red del host.
  • discovery.timeoutMs y discovery.count: el presupuesto de descubrimiento/conteo de resultados usado para esta pasada de prueba.
• Por objetivo (targets[].connect):
  • ok: alcanzabilidad después de conectar + clasificación degradada.
  • rpcOk: éxito total del RPC de detalle.
  • scopeLimited: el RPC de detalle falló debido a la falta de alcance de operador.
• Por objetivo (targets[].auth):
  • role: rol de autenticación reportado en hello-ok cuando está disponible.
  • scopes: alcances concedidos reportados en hello-ok cuando están disponibles.
  • capability: la clasificación de capacidad de autenticación mostrada para ese objetivo.

Códigos de advertencia comunes:

• ssh_tunnel_failed: la configuración del túnel SSH falló; el comando recurrió a pruebas directas.
• multiple_gateways: más de un objetivo fue alcanzable; esto es inusual a menos que ejecutes intencionalmente perfiles aislados, como un bot de rescate.
• auth_secretref_unresolved: un SecretRef de autenticación configurado no pudo resolverse para un objetivo fallido.
• probe_scope_limited: la conexión WebSocket tuvo éxito, pero la prueba de lectura fue limitada por la falta de operator.read.

Remoto sobre SSH (paridad de la aplicación Mac)

El modo “Remote over SSH” de la aplicación de macOS utiliza un reenvío de puerto local para que el gateway remoto (que puede estar vinculado solo a loopback) sea alcanzable 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 (el puerto predeterminado es 22).
• --ssh-identity <path>: archivo de identidad.
• --ssh-auto: elige el primer gateway descubierto como objetivo SSH desde el endpoint de descubrimiento resuelto (local. más el dominio de área amplia configurado, si existe). Las sugerencias solo de TXT se ignoran.

Configuración (opcional, usada como valores predeterminados):

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

gateway call <method>

Ayudante de RPC de bajo nivel.

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

Opciones:

• --params <json>: cadena de objeto JSON para parámetros (predeterminado {})
• --url <url>
• --token <token>
• --password <password>
• --timeout <ms>
• --expect-final
• --json

Notas:

• --params debe ser un JSON válido.
• --expect-final es principalmente para RPCs estilo agente que transmiten eventos intermedios antes de una carga útil final.

AI Setup Assistant

Gestionar el servicio Gateway

Para mantener tu infraestructura funcionando correctamente, puedes usar los comandos de la CLI de OpenClaw para controlar el ciclo de vida del servicio. Aquí tienes las operaciones básicas que necesitas para administrar tu Gateway:

1. Ejecuta openclaw gateway install para configurar el servicio.
2. Usa openclaw gateway start para poner en marcha el Gateway.
3. Utiliza openclaw gateway stop para detener el servicio de forma segura.
4. Aplica openclaw gateway restart cuando necesites reiniciar el proceso.
5. Ejecuta openclaw gateway uninstall para eliminar el servicio de tu sistema.

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

Opciones de comandos

Cada comando de la CLI admite parámetros específicos que te permiten ajustar el comportamiento de tu Gateway según tus necesidades. Puedes consultar las opciones disponibles para cada acción a continuación:

1. Para gateway status, cuentas con: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json.
2. Para gateway install, puedes usar: --port, --runtime <node|bun>, --token, --force, --json.
3. Para gateway uninstall|start|stop|restart, el único parámetro disponible es --json.

Notas técnicas

Es importante tener en cuenta cómo se gestionan las configuraciones y la seguridad durante la instalación y ejecución del servicio. Sigue estas recomendaciones para asegurar una configuración correcta de tu OpenClaw Gateway:

1. El comando gateway install es compatible con las opciones --port, --runtime, --token, --force y --json.
2. Cuando la autenticación mediante token requiere un valor y gateway.auth.token es gestionado por SecretRef, gateway install valida que el SecretRef sea resoluble, pero no guarda el token resuelto en los metadatos del entorno del servicio.
3. Si la autenticación por token requiere uno y el SecretRef configurado no se puede resolver, la instalación fallará en lugar de guardar un texto plano como respaldo.
4. Para la autenticación con contraseña en gateway run, es preferible usar OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password respaldado por SecretRef en lugar de incluir --password directamente en la línea de comandos.
5. En el modo de autenticación inferida, la variable OPENCLAW_GATEWAY_PASSWORD solo de shell no elimina los requisitos de token de instalación; utiliza una configuración duradera (gateway.auth.password o configuración env) al instalar un servicio gestionado.
6. Si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está definido, la instalación se bloqueará hasta que el modo se establezca explícitamente.
7. Los comandos de ciclo de vida aceptan --json para facilitar la integración en scripts.

AI Setup Assistant

Descubrir Gateways (Bonjour)

El comando gateway discover analiza la red en busca de balizas de Gateway (_openclaw-gw._tcp) para que puedas conectar tus servicios de forma sencilla. OpenClaw utiliza este mecanismo para facilitar la detección automática de dispositivos en tu red local o mediante configuraciones de red más avanzadas.

1. Multicast DNS-SD: local.
2. Unicast DNS-SD (Wide-Area Bonjour): elige un dominio (por ejemplo, openclaw.internal.) y configura un DNS dividido junto con un servidor DNS; consulta /gateway/bonjour.

Solo los Gateway que tienen habilitada la detección Bonjour (activada por defecto) anuncian su baliza.

Los registros de detección de área amplia (Wide-Area) incluyen (TXT):

1. role (sugerencia de rol del Gateway)
2. transport (sugerencia de transporte, por ejemplo, gateway)
3. gatewayPort (puerto WebSocket, generalmente 18789)
4. sshPort (opcional; los clientes usan 22 por defecto si no está presente)
5. tailnetDns (nombre de host de MagicDNS, cuando está disponible)
6. gatewayTls / gatewayTlsSha256 (TLS habilitado + huella digital del certificado)
7. cliPath (sugerencia de instalación remota escrita en la zona de área amplia)

gateway discover

Puedes ejecutar este comando directamente desde tu terminal para listar los dispositivos disponibles en tu entorno. Asegúrate de tener el CLI instalado para interactuar con tu OpenClaw Gateway.

openclaw gateway discover

Opciones:

1. --timeout <ms>: tiempo de espera por comando (exploración/resolución); el valor predeterminado es 2000.
2. --json: salida legible por máquina (también deshabilita el estilo y el indicador de carga).

Ejemplos:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'

Notas:

1. El CLI escanea local. además del dominio de área amplia configurado cuando hay uno habilitado.
2. La wsUrl en la salida JSON se deriva del punto final del servicio resuelto, no de sugerencias basadas solo en TXT como lanHost o tailnetDns.
3. En mDNS local., sshPort y cliPath solo se transmiten cuando discovery.mdns.mode es full. El DNS-SD de área amplia sigue escribiendo cliPath; sshPort también permanece opcional allí.