Manual operativo de Gateway

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

# Arranque local en 5 minutos

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Modelo en tiempo de ejecución

• Un proceso siempre activo para enrutamiento, plano de control y conexiones de canal.
• Puerto multiplexado único para:
  • Control/RPC de WebSocket
  • API HTTP, compatibles con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI y hooks
• Modo de enlace predeterminado: loopback.
• La autenticación es obligatoria de forma predeterminada. Las configuraciones con secreto compartido usan gateway.auth.token / gateway.auth.password (o OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), y las configuraciones de proxy inverso sin loopback pueden usar gateway.auth.mode: "trusted-proxy".

# Endpoints compatibles con OpenAI

La superficie de compatibilidad de mayor impacto de OpenClaw ahora es:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Por qué importa este conjunto:

• La mayoría de las integraciones con Open WebUI, LobeChat y LibreChat prueban primero /v1/models.
• Muchas canalizaciones de RAG y memoria esperan /v1/embeddings.
• Los clientes nativos para agentes prefieren cada vez más /v1/responses.

Nota de planificación:

• /v1/models prioriza agentes: devuelve openclaw, openclaw/default y openclaw/<agentId>.
• openclaw/default es el alias estable que siempre se asigna al agente predeterminado configurado.
• Usa x-openclaw-model cuando quieras anular el proveedor/modelo de backend; de lo contrario, la configuración normal de modelo e incrustaciones del agente seleccionado mantiene el control.

Todos estos se ejecutan en el puerto principal del Gateway y usan el mismo límite de autenticación de operador de confianza que el resto de la API HTTP del Gateway.

# Precedencia de puerto y enlace

Los servicios de gateway instalados registran el --port resuelto en los metadatos del supervisor. Después de cambiar gateway.port, ejecuta openclaw doctor --fix o openclaw gateway install --force para que launchd/systemd/schtasks inicie el proceso en el puerto nuevo.

El arranque del Gateway usa el mismo puerto y enlace efectivos cuando inicializa orígenes locales de Control UI para enlaces sin loopback. Por ejemplo, --bind lan --port 3000 inicializa http://localhost:3000 y http://127.0.0.1:3000 antes de que se ejecute la validación en tiempo de ejecución. Añade explícitamente cualquier origen de navegador remoto, como URL de proxy HTTPS, a gateway.controlUi.allowedOrigins.

# Modos de recarga en caliente

# Conjunto de comandos del operador

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep es para descubrimiento adicional de servicios (LaunchDaemons/unidades de sistema systemd/schtasks), no una prueba de estado RPC más profunda.

# Varios gateways (mismo host)

La mayoría de las instalaciones deberían ejecutar un gateway por máquina. Un solo gateway puede alojar múltiples agentes y canales.

Solo necesitas varios gateways cuando quieres aislamiento intencionalmente o un bot de rescate.

Comprobaciones útiles:

openclaw gateway status --deep
openclaw gateway probe

Qué esperar:

• gateway status --deep puede informar Other gateway-like services detected (best effort) e imprimir sugerencias de limpieza cuando todavía quedan instalaciones antiguas de launchd/systemd/schtasks.
• gateway probe puede advertir sobre multiple reachable gateways cuando responde más de un destino.
• Si eso es intencional, aísla los puertos, la configuración/estado y las raíces de espacio de trabajo por gateway.

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

Configuración detallada: /gateway/multiple-gateways.

# Acceso remoto

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

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

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

Consulta: Remote Gateway, Authentication, Tailscale.

# Supervisión y ciclo de vida del servicio

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

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

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

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# Ruta rápida del 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 de gateway 19001.

# Referencia rápida del protocolo (vista del operador)

• La primera trama del cliente debe ser connect.
• Gateway devuelve la instantánea hello-ok (presence, health, stateVersion, uptimeMs, límites/política).
• hello-ok.features.methods / events son una lista de descubrimiento conservadora, no un volcado generado de todas las rutas auxiliares invocables.
• Solicitudes: req(method, params) → res(ok/payload|error).
• Los eventos comunes incluyen connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos del ciclo de vida de emparejamiento/aprobación y shutdown.

Las ejecuciones de agentes tienen dos etapas:

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

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

# Comprobaciones operativas

# Vivacidad

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

# Firmas de fallos comunes

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

# Garantías de seguridad

• Los clientes del protocolo Gateway fallan de inmediato cuando Gateway no está disponible (sin alternativa implícita de canal directo).
• Las primeras tramas no válidas o que no son de conexión se rechazan y se cierran.
• El cierre ordenado emite el evento shutdown antes del cierre del socket.

Relacionado:

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

# Relacionado

• Configuración
• Solución de problemas de Gateway
• Acceso remoto
• Gestión de secretos