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 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 de tiempo de ejecución

• Un proceso siempre activo para enrutamiento, plano de control y conexiones de canales.
• Un único puerto multiplexado para:
  • Control/RPC WebSocket
  • API HTTP, compatibles con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • IU 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 valor 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 de Open WebUI, LobeChat y LibreChat sondean primero /v1/models.
• Muchas canalizaciones de RAG y memoria esperan /v1/embeddings.
• Los clientes nativos de agentes prefieren cada vez más /v1/responses.

Nota de planificación:

• /v1/models está orientado primero a 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, el modelo normal del agente seleccionado y la configuración de embeddings siguen teniendo el control.

Todo esto se ejecuta en el puerto principal del Gateway y usa el mismo límite de autenticación de operador confiable 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 nuevo puerto.

El arranque del Gateway usa el mismo puerto y enlace efectivos cuando inicializa los orígenes locales de la IU 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 cualquier origen de navegador remoto, como URL de proxy HTTPS, a gateway.controlUi.allowedOrigins explícitamente.

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 del 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 intencionalmente aislamiento 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 existan instalaciones launchd/systemd/schtasks obsoletas.
• gateway probe puede advertir sobre multiple reachable gateways cuando responde más de un destino.
• Si eso es intencional, aísla puertos, configuración/estado y raíces de espacio de trabajo por gateway.

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 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 los 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 una fiabilidad 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 143KillMode=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 del 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)

• El primer frame de cliente debe ser connect.
• El 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 cada ruta auxiliar invocable.
• 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 de ciclo de vida de emparejamiento/aprobación y shutdown.

Las ejecuciones de agentes son de dos etapas:

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

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

Comprobaciones operativas

Actividad

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

Preparación

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

Para ver las escalas completas de diagnóstico, usa Solución de problemas del Gateway.

Garantías de seguridad

• Los clientes del protocolo Gateway fallan rápido cuando Gateway no está disponible (sin alternativa implícita directa al canal).
• Los primeros marcos 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
• Estado
• Diagnóstico
• Autenticación

Relacionado

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