Runbook 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 stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Modelo en tiempo de ejecución

• Un proceso siempre activo para enrutamiento, plano de control y conexiones de canales.
• Un único puerto multiplexado para:
  • Control/RPC por WebSocket
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Rutas HTTP de Plugin, como la opcional /api/v1/admin/rpc
  • Interfaz de control 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 no 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 integraciones de Open WebUI, LobeChat y LibreChat sondean /v1/models primero.
• Muchas canalizaciones RAG y de 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 sobrescribir el proveedor/modelo de backend; de lo contrario, la configuración normal de modelo e incrustaciones del agente seleccionado mantiene el control.

Todo esto se ejecuta en el puerto principal del Gateway y usa el mismo límite de autenticación de operador de confianza que el resto de la API HTTP del Gateway.

Admin HTTP RPC (POST /api/v1/admin/rpc) es una ruta de Plugin separada, desactivada de forma predeterminada, para herramientas del host que no pueden usar RPC por WebSocket. Consulta Admin HTTP RPC.

Precedencia de puerto y enlace

Los servicios 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 nuevo puerto.

El arranque del Gateway usa el mismo puerto y enlace efectivos cuando inicializa los orígenes locales de la interfaz de control para enlaces no 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. Agrega 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 statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

Múltiples gateways (mismo host)

La mayoría de las instalaciones deberían ejecutar un Gateway por máquina. Un único Gateway puede alojar varios agentes y canales.

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

Comprobaciones útiles:

openclaw gateway status --deepopenclaw gateway probe

Qué esperar:

• gateway status --deep puede informar Other gateway-like services detected (best effort) e imprimir sugerencias de limpieza cuando todavía queden instalaciones launchd/systemd/schtasks obsoletas.
• gateway probe puede advertir sobre multiple reachable gateway identities cuando responden gateways distintos, o cuando OpenClaw no puede demostrar que los destinos alcanzables son el mismo Gateway. Un túnel SSH, una URL de proxy o una URL remota configurada hacia el mismo Gateway es un Gateway con varios transportes, incluso cuando los puertos de transporte difieren.
• Si eso es intencional, aísla puertos, configuración/estado y raíces de espacios 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 19001OPENCLAW_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 clientes localmente a ws://127.0.0.1:18789.

Consulta: Gateway remoto, Autenticación, Tailscale.

Supervisión y ciclo de vida del servicio

Usa ejecuciones supervisadas para confiabilidad similar a producción.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

Ruta rápida de perfil de desarrollo

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

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

Referencia rápida del protocolo (vista del operador)

• La primera trama del cliente debe ser connect.
• Gateway devuelve una 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 cada ruta auxiliar invocable.
• Solicitudes: req(method, params) → res(ok/payload|error).
• Los eventos comunes incluyen connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos de ciclo de vida de emparejamiento/aprobación y shutdown.

Las ejecuciones de agente tienen dos etapas:

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

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

Comprobaciones operativas

Actividad

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

Preparación

openclaw gateway statusopenclaw channels status --probeopenclaw 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 ver escalas completas de diagnóstico, usa Solución de problemas de Gateway.

Garantías de seguridad

• Los clientes del protocolo Gateway fallan rápido cuando Gateway no está disponible (sin reserva implícita a canal directo).
• Los primeros frames inválidos o que no son de conexión se rechazan y se cierran.
• El apagado ordenado emite el evento shutdown antes de cerrar el socket.

Relacionado:

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

Relacionado

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