Manual del Gateway

Usa esta página para la puesta en marcha del día 1 y las operaciones del día 2 del servicio Gateway.

• Solución de problemas avanzada — Diagnósticos basados en síntomas con secuencias exactas de comandos y firmas de logs.
• Configuración — Guía de configuración orientada a tareas + referencia completa de configuración.
• Gestión de secretos — Contrato SecretRef, comportamiento de instantánea en runtime y operaciones de migración/recarga.
• Contrato del plan de secretos — Reglas exactas de objetivo/ruta de secrets apply y comportamiento de perfil de autenticación solo-ref.

Inicio local en 5 minutos

Paso 1: Iniciar el Gateway

openclaw gateway --port 18789
# debug/trace reflejado a stdio
openclaw gateway --port 18789 --verbose
# forzar cierre 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 canales

openclaw channels status --probe

Nota: La recarga de configuración del Gateway vigila la ruta activa del archivo de configuración (resuelta desde los valores por defecto de perfil/estado, o OPENCLAW_CONFIG_PATH cuando está configurado). El modo por defecto es gateway.reload.mode="hybrid".

Modelo de runtime

• Un proceso siempre activo para enrutamiento, plano de control y conexiones de canales.
• Puerto único multiplexado para:
  • WebSocket de control/RPC
  • APIs HTTP (compatible con OpenAI, Responses, invocación de herramientas)
  • Control UI y hooks
• Modo de enlace por defecto: 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

Modos de recarga en caliente

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. Respaldo: túnel SSH.

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

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

Advertencia: Si la autenticación del gateway está configurada, los clientes aún deben enviar autenticación (token/password) incluso por túneles SSH.

Consulta: Gateway remoto, Autenticación, Tailscale.

Supervisión y ciclo de vida del servicio

Usa ejecuciones supervisadas para confiabilidad tipo producción.

macOS (launchd)

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

Las etiquetas del LaunchAgent son ai.openclaw.gateway (por defecto) o ai.openclaw.<perfil> (perfil nombrado). openclaw doctor audita y repara la deriva de configuración del servicio.

Linux (systemd usuario)

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

Para persistencia después de cerrar sesión, habilita lingering:

sudo loginctl enable-linger <user>

Linux (servicio del sistema)

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 en un host

La mayoría de las configuraciones deberían ejecutar un Gateway. Usa múltiples solo para aislamiento/redundancia estricta (por ejemplo un perfil 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

Consulta: Múltiples gateways.

Ruta rápida de perfil dev

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

Los valores por defecto incluyen estado/configuración aislada 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 del agente son de dos etapas:

1. Confirmación inmediata de aceptación (status:"accepted")
2. Respuesta final de finalización (status:"ok"|"error"), con eventos agent transmitidos entre ambas.

Consulta la documentación completa del protocolo: Protocolo Gateway.

Verificaciones operativas

Vivacidad

• Abre WS y envía connect.
• Espera 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. Ante brechas de secuencia, refresca el estado (health, system-presence) antes de continuar.

Firmas de fallo comunes

Para secuencias 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 respaldo implícito a canal directo).
• Los primeros frames inválidos/no connect se rechazan y se cierran.
• El apagado graceful emite un evento shutdown antes de cerrar el socket.

Relacionado:

• Solución de problemas
• Proceso en segundo plano
• Configuración
• Salud
• Doctor
• Autenticación