Gateway

Runbook del Gateway

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

Solución de problemas profunda

Diagnósticos basados en síntomas con escaleras de comandos exactas y firmas de registro.

Configuración

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

Gestión de secretos

Contrato SecretRef, comportamiento de instantánea en tiempo de ejecución y operaciones de migración/recarga.

Contrato del plan de secretos

Reglas exactas de destino/ruta de aplicación de secretos y comportamiento de perfil de autenticación solo por referencia.

Inicio local en 5 minutos

Paso 1: Iniciar el Gateway

openclaw gateway --port 18789
# depuración/seguimiento reflejado en stdio
openclaw gateway --port 18789 --verbose
# forzar la terminación del listener en el puerto seleccionado, luego iniciar
openclaw gateway --force

Paso 2: Verificar la salud del servicio

openclaw gateway status
openclaw status
openclaw logs --follow

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

Paso 3: Validar la preparación de los canales

openclaw channels status --probe

ℹ️ La recarga de configuración del Gateway observa la ruta del archivo de configuración activo (resuelta a partir de los valores predeterminados de perfil/estado, o OPENCLAW_CONFIG_PATH cuando está establecida). El modo predeterminado es gateway.reload.mode="hybrid".

Modelo de tiempo de ejecución

  • Un proceso siempre activo para enrutamiento, plano de control y conexiones de canal.
  • Puerto único multiplexado para:
    • Control/RPC WebSocket
    • APIs HTTP (compatibles con OpenAI, Respuestas, invocación de herramientas)
    • UI de control y hooks
  • Modo de enlace predeterminado: loopback.
  • La autenticación es obligatoria por defecto (gateway.auth.token / gateway.auth.password, o OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

Precedencia de puerto y enlace

ConfiguraciónOrden de resolución
Puerto del Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Modo de enlaceCLI/sobrescritura → gateway.bind → loopback

Modos de recarga en caliente

gateway.reload.modeComportamiento
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 requerido

Conjunto de comandos del operador

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

Acceso remoto

Preferido: Tailscale/VPN. Alternativa: túnel SSH.

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

Luego conectar clientes a ws://127.0.0.1:18789 localmente.

⚠️ Si la autenticación del gateway está configurada, los clientes aún deben enviar autenticación (token/password) incluso a través de túneles SSH.

Ver: Gateway Remoto, Autenticación, Tailscale.

Supervisión y ciclo de vida del servicio

Usa ejecuciones supervisadas para una fiabilidad similar a la de producción.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

Múltiples gateways en un mismo host

La mayoría de las configuraciones deben ejecutar un Gateway. Usa múltiples solo para aislamiento/redundancia estricta (por ejemplo, un perfil de rescate). Lista de comprobació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

Ver: Múltiples gateways.

Ruta rápida de perfil de desarrollo

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

Referencia rápida del 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: req(method, params) → res(ok/payload|error).
  • Eventos comunes: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Las ejecuciones de agente son de dos etapas:

  1. Acuse de recibo inmediato aceptado (status:"accepted")
  2. Respuesta de finalización final (status:"ok"|"error"), con eventos agent transmitidos en el medio.

Ver documentación completa del protocolo: Protocolo del Gateway.

Comprobaciones operativas

Actividad

  • Abrir WS y enviar connect.
  • Esperar respuesta hello-ok con instantánea.

Preparación

openclaw gateway status
openclaw channels status --probe
openclaw health

Recuperación de brechas

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

Firmas de fallo comunes

FirmaProblema probable
refusing to bind gateway ... without authEnlace 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 durante la conexiónDesajuste de autenticación entre cliente y gateway

Para escaleras de diagnóstico completas, usa Solución de Problemas del Gateway.

Garantías de seguridad

  • Los clientes del protocolo Gateway fallan rápidamente cuando el Gateway no está disponible (sin fallback implícito a canal directo).
  • Los primeros frames inválidos/no connect son rechazados y cerrados.
  • El apagado elegante emite el evento shutdown antes de cerrar el socket.

Relacionado:

Configuración