Saltar al contenido principal

​
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

1

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
2

Verify service health

openclaw --profile main gateway install
openclaw --profile rescue gateway install
Línea base saludable: Runtime: running y RPC probe: ok.
3

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ónOrden de resolución
Puerto del GatewayPrecedencia de puertos: --port > OPENCLAW_GATEWAY_PORT > gateway.port > predeterminado 18789.
Modo de enlaceCLI/override → gateway.bind → loopback

​
Modos de recarga en caliente

Deshabilite con gateway.reload.mode="off".Comportamiento de keepalive
offSin recarga de configuración
hotAplicar solo cambios seguros en caliente
restartReiniciar 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. 
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.

​
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:
  1. Acuse de recibo inmediato de aceptación (status:"accepted")
  2. 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

FirmaProblema probable
refusing to bind gateway ... without authVinculación no loopback sin token/contraseña
another gateway instance is already listening / EADDRINUSEConflicto de puerto
Gateway start blocked: set gateway.mode=localConfiguración establecida en modo remoto
unauthorized during connectDesajuste 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: