Manual operativo del servicio Gateway

Utiliza esta página para el arranque del día 1 y las operaciones del día 2 del servicio Gateway.

Deep troubleshooting

Diagnósticos orientados a síntomas con secuencias de comandos exactas y firmas de registros.

Configuration

Guía de configuración orientada a tareas + referencia completa de configuración.

Inicio local en 5 minutos

Start the Gateway

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

Verify service health

openclaw --profile main gateway install
openclaw --profile rescue gateway install

Línea base saludable: Runtime: running y RPC probe: ok.

Validate channel readiness

openclaw channels status --probe

La recarga de configuración del Gateway supervisa la ruta activa del archivo de configuración (resuelta desde los valores predeterminados del perfil/estado, o OPENCLAW_CONFIG_PATH cuando está establecido). Modo predeterminado: gateway.reload.mode="hybrid" (aplica en caliente cambios seguros, reinicia en cambios críticos).

Modelo de ejecución

Un proceso siempre activo para el enrutamiento, el plano de control y las conexiones de canales.
Multiplexado de puerto único.
- Control/RPC por WebSocket
- OpenResponses (HTTP): /v1/responses.
- UI de control y hooks
Modo de enlace predeterminado: loopback.
La autenticación del Gateway es requerida por defecto: configure gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN) o gateway.auth.password.

Precedencia de puerto y enlace

Configuración	Orden de resolución
Puerto del Gateway	Precedencia de puertos: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > predeterminado `18789`.
Modo de enlace	CLI/override → `gateway.bind` → `loopback`

Modos de recarga en caliente

Deshabilite con `gateway.reload.mode="off"`.	Comportamiento de keepalive
`off`	Sin recarga de configuración
`hot`	Aplicar solo cambios seguros en caliente
`restart`	Reiniciar en cambios que requieren recarga
`hybrid` (predeterminado)	Aplicar en caliente cuando sea seguro, reiniciar cuando sea necesario

Conjunto de comandos del operador

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

Acceso remoto

Tailscale/VPN es preferido; de lo contrario, túnel SSH: Alternativa: túnel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@host

Luego los clientes se conectan a ws://127.0.0.1:18789 a través del túnel.

El uso remoto pasa por el mismo túnel SSH/Tailscale; si se configura un token del gateway, el cliente lo incluye durante connect.

Ver: Remote Gateway, Authentication, Tailscale.

Supervisión y ciclo de vida del servicio

Utiliza ejecuciones supervisadas para una fiabilidad similar a producción.

macOS (launchd)
Linux (systemd user)
Linux (system service)

Para reiniciar, use `openclaw gateway restart` (o `launchctl kickstart -k gui/$UID/bot.molt.gateway`).

Las etiquetas de LaunchAgent son ai.openclaw.gateway (predeterminado) o ai.openclaw.<profile> al ejecutar un perfil con nombre. openclaw doctor audita y repara la desviación de configuración del servicio.

systemctl --user enable --now openclaw-gateway[-<profile>].service

Habilite lingering (requerido para que el servicio de usuario sobreviva a cierre de sesión/inactividad):

sudo loginctl enable-linger youruser

Usa una unidad del sistema para hosts multiusuario/siempre activos.

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

Múltiples gateways (mismo host)

Por lo general es innecesario: un Gateway puede servir múltiples canales de mensajería y agentes. Use múltiples Gateways solo para redundancia o aislamiento estricto (ej.: bot de rescate). Lista de verificación por instancia:

gateway.port único
OPENCLAW_CONFIG_PATH único
OPENCLAW_STATE_DIR único
agents.defaults.workspace único

Ejemplo:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Vea Múltiples gateways.

Ruta rápida del perfil de desarrollo

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health

Los valores predeterminados incluyen estado/configuración aislados y el puerto base del gateway 19001.

Protocolo (vista del operador)

El primer frame del cliente debe ser connect.
El Gateway devuelve una instantánea hello-ok (presence, health, stateVersion, uptimeMs, límites/política).
Solicitudes: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
Eventos comunes: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Las ejecuciones del agente son de dos etapas:

Acuse de recibo inmediato de aceptación (status:"accepted")
Las respuestas agent son de dos etapas: primero un ack res {runId,status:"accepted"}, luego un res {runId,status:"ok"|"error",summary} final tras finalizar la ejecución; la salida en streaming llega como event:"agent".

Documentación completa: Protocolo del Gateway y Protocolo Bridge (heredado).

Verificaciones operativas

Vitalidad

Abre WS y envía connect.
Espera una respuesta hello-ok con la instantánea.

Preparación

`openclaw gateway health|status` — solicitar salud/estado sobre el WS del Gateway.

Recuperación de brechas

Los eventos no se reproducen. En brechas de secuencia, actualiza el estado (health, system-presence) antes de continuar.

Firmas de fallo comunes

Firma	Problema probable
`refusing to bind gateway ... without auth`	Vinculación no loopback sin token/contraseña
`another gateway instance is already listening` / `EADDRINUSE`	Conflicto de puerto
`Gateway start blocked: set gateway.mode=local`	Configuración establecida en modo remoto
`unauthorized` during connect	Desajuste de autenticación entre el cliente y el Gateway

Para escaleras de diagnóstico completas, usa Gateway Troubleshooting.

Garantías de seguridad

Los clientes del protocolo Gateway fallan rápidamente cuando el Gateway no está disponible (sin retroceso implícito a canal directo).
Los primeros frames no-connect o JSON malformado se rechazan y el socket se cierra.
Apagado ordenado: emite el evento shutdown antes de cerrar; los clientes deben manejar cierre + reconexión.

Relacionado:

Gateway

Acceso remoto

Interfaces web

Manual operativo del Gateway

Manual operativo del servicio Gateway

Deep troubleshooting

Configuration

Inicio local en 5 minutos

Modelo de ejecución

Precedencia de puerto y enlace

Modos de recarga en caliente

Conjunto de comandos del operador

Acceso remoto

Supervisión y ciclo de vida del servicio

Múltiples gateways (mismo host)

Ruta rápida del perfil de desarrollo

Protocolo (vista del operador)

Verificaciones operativas

Vitalidad

Preparación

Recuperación de brechas

Firmas de fallo comunes

Garantías de seguridad

​Manual operativo del servicio Gateway

Deep troubleshooting

Configuration

​Inicio local en 5 minutos

​Modelo de ejecución

​Precedencia de puerto y enlace

​Modos de recarga en caliente

​Conjunto de comandos del operador

​Acceso remoto

​Supervisión y ciclo de vida del servicio

​Múltiples gateways (mismo host)

​Ruta rápida del perfil de desarrollo

​Protocolo (vista del operador)

​Verificaciones operativas

​Vitalidad

​Preparación

​Recuperación de brechas

​Firmas de fallo comunes

​Garantías de seguridad

Manual operativo del servicio Gateway

Inicio local en 5 minutos

Modelo de ejecución

Precedencia de puerto y enlace

Modos de recarga en caliente

Conjunto de comandos del operador

Acceso remoto

Supervisión y ciclo de vida del servicio

Múltiples gateways (mismo host)

Ruta rápida del perfil de desarrollo

Protocolo (vista del operador)

Verificaciones operativas

Vitalidad

Preparación

Recuperación de brechas

Firmas de fallo comunes

Garantías de seguridad