Manual de operaciones del Gateway

Use esta página para el arranque inicial y las operaciones posteriores del servicio Gateway.

Arranque local en 5 minutos

openclaw gateway --port 18789# depuración/rastreo reflejados en stdioopenclaw gateway --port 18789 --verbose# finalizar de forma forzada el proceso que escucha en el puerto seleccionado y, a continuación, iniciaropenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Modelo de tiempo de ejecución

• Un proceso siempre activo para el enrutamiento, el plano de control y las conexiones de canales.
• Un único puerto multiplexado para:
  • Control/RPC mediante WebSocket
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Rutas HTTP de Plugins, como la ruta opcional /api/v1/admin/rpc
  • Interfaz de control y hooks
• Modo de enlace predeterminado: loopback. Dentro de un entorno de contenedor detectado, el valor predeterminado efectivo es auto (se resuelve como 0.0.0.0 para el reenvío de puertos), salvo que Tailscale serve/funnel esté activo, en cuyo caso siempre se fuerza 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:

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

Por qué es importante este conjunto:

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

/v1/models prioriza los agentes: devuelve openclaw, openclaw/default y openclaw/<agentId> para cada agente configurado. openclaw/default es el alias estable que siempre se asigna al agente predeterminado configurado. Envíe x-openclaw-model cuando quiera sustituir el proveedor/modelo de backend; de lo contrario, se mantiene el control mediante la configuración habitual del modelo y de las incrustaciones del agente seleccionado.

Todos estos endpoints 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.

El RPC HTTP de administración (POST /api/v1/admin/rpc) es una ruta independiente de Plugin, desactivada de forma predeterminada, para herramientas del host que no pueden usar RPC mediante WebSocket. Consulte RPC HTTP de administración.

Precedencia del puerto y el enlace

Los servicios de Gateway instalados registran el valor de --port resuelto en los metadatos del supervisor. Después de cambiar gateway.port, ejecute openclaw doctor --fix u 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 que no sean loopback. Por ejemplo, --bind lan --port 3000 inicializa http://localhost:3000 y http://127.0.0.1:3000 antes de ejecutar la validación en tiempo de ejecución. Añada explícitamente cualquier origen de navegador remoto, como las URL de proxy HTTPS, a gateway.controlUi.allowedOrigins.

Modos de recarga en caliente

Conjunto de comandos para operadores

openclaw gateway statusopenclaw gateway status --deep   # añade un análisis del servicio a nivel del sistemaopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep sirve para detectar servicios adicionales (LaunchDaemons/unidades de sistema de systemd/schtasks), no para realizar un sondeo más profundo del estado de RPC.

Varios Gateways (mismo host)

La mayoría de las instalaciones deben ejecutar un Gateway por máquina. Un único Gateway puede alojar varios agentes y canales. Solo se necesitan varios Gateways cuando se busca deliberadamente el aislamiento o un bot de rescate.

Comprobaciones útiles:

openclaw gateway status --deepopenclaw gateway probe

Qué puede esperar:

• gateway status --deep puede informar Other gateway-like services detected (best effort) e imprimir indicaciones de limpieza cuando aún existen instalaciones obsoletas de launchd/systemd/schtasks.
• gateway probe puede advertir sobre multiple reachable gateway identities cuando responden distintos Gateways o cuando OpenClaw no puede demostrar que los destinos accesibles son el mismo Gateway. Un túnel SSH, una URL de proxy o una URL remota configurada hacia el mismo Gateway representan un solo Gateway con varios transportes, aunque los puertos de transporte sean distintos.
• Si esto es intencional, aísle los puertos, la configuración/estado y las raíces de los espacios de trabajo de cada Gateway.

Lista de comprobación por instancia:

• Un valor de gateway.port único
• Un valor de OPENCLAW_CONFIG_PATH único
• Un valor de OPENCLAW_STATE_DIR único
• Un valor de 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

Opción preferida: Tailscale/VPN. Alternativa: túnel SSH.

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

Después, conecte los clientes localmente a ws://127.0.0.1:18789.

Consulte: Gateway remoto, Autenticación, Tailscale.

Supervisión y ciclo de vida del servicio

Use ejecuciones supervisadas para obtener una fiabilidad similar a la de 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 $(whoami)

[Unit]Description=Gateway de OpenClawAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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

Los errores de configuración no válida terminan con el código 78. Las unidades de systemd de Linux usan RestartPreventExitStatus=78 para detener los reinicios hasta que se corrija la configuración. launchd y el Programador de tareas de Windows no tienen una regla equivalente para detenerse según el código de salida, por lo que el Gateway también conserva el historial de arranques rápidos no limpios e impide el inicio automático de las cuentas de canales/proveedores después de fallos de arranque repetidos. En ese modo seguro, el plano de control sigue iniciándose para permitir la inspección y la reparación, las recargas en caliente de la configuración y secrets.reload rechazan los reinicios automáticos de canales, y una solicitud explícita del operador mediante channels.start puede anular la restricción.

Ruta rápida del perfil de desarrollo

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

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

Referencia rápida del protocolo (perspectiva del operador)

• El primer frame del cliente debe ser connect.
• Gateway devuelve un frame hello-ok con una snapshot (presence, health, stateVersion, uptimeMs), además de los límites de policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events son una lista de detección conservadora, no un volcado generado de todas las rutas auxiliares invocables.
• Solicitudes: req(method, params) → res(ok/payload|error).
• Los eventos habituales incluyen connect.challenge, agent, chat, session.message, session.operation, session.tool, el evento opcional session.approval, sessions.changed, presence, tick, health, heartbeat, eventos del ciclo de vida del emparejamiento y la aprobación, y shutdown.

Las ejecuciones del agente constan 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.

Consulte la documentación completa del protocolo: Protocolo de Gateway.

Comprobaciones operativas

Actividad

• Abra WS y envíe connect.
• Espere una respuesta hello-ok con la instantánea.

Disponibilidad

openclaw gateway statusopenclaw channels status --probeopenclaw health

Recuperación tras interrupciones

Los eventos no se reproducen. Si hay interrupciones en la secuencia, actualice el estado (health, system-presence) antes de continuar.

Indicadores comunes de fallos

Para consultar los procedimientos completos de diagnóstico, consulte Solución de problemas del Gateway.

Garantías de seguridad

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

Temas relacionados

• Configuración
• Solución de problemas del Gateway
• Proceso en segundo plano
• Estado
• Doctor
• Autenticación
• Acceso remoto
• Gestión de secretos