Manual de operaciones del 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 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
  • Control UI y hooks
• Modo de enlace predeterminado: loopback. Dentro de un entorno de contenedor detectado, el valor predeterminado efectivo es auto (se resuelve a 0.0.0.0 para reenvío de puertos), salvo que Tailscale serve/funnel esté activo, lo que siempre 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 con proxy inverso que no sean 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é 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.

/v1/models está orientado a 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ía x-openclaw-model cuando quieras anular el proveedor/modelo de backend; de lo contrario, la configuración normal de modelo y embeddings 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.

El RPC HTTP de administración (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 RPC HTTP de administración.

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 siembra orígenes locales de Control UI para enlaces que no son loopback. Por ejemplo, --bind lan --port 3000 siembra 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 de 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 sirve para descubrimiento adicional de servicios (LaunchDaemons/unidades systemd del sistema/schtasks), no para un sondeo de salud 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 intencionadamente 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 pistas de limpieza cuando aún quedan instalaciones obsoletas de launchd/systemd/schtasks.
• gateway probe puede advertir sobre multiple reachable gateway identities cuando responden gateways distintos, 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 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 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@gateway-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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=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 salen con el código 78. Las unidades systemd de Linux usan RestartPreventExitStatus=78 para dejar de reiniciar hasta que se corrija la configuración. launchd y el Programador de tareas de Windows no tienen una regla equivalente de detención por código de salida, por lo que el Gateway también persiste el historial de arranques rápidos no limpios y suprime el inicio automático de cuentas de canal/proveedor después de fallos de arranque repetidos. En ese modo seguro, el plano de control sigue arrancando para inspección y reparación, las recargas en caliente de configuración y secrets.reload rechazan reinicios automáticos de canales, y una solicitud explícita de operador channels.start puede anular la supresión.

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 el puerto base de gateway 19001.

Referencia rápida del protocolo (vista de operador)

• El primer frame del cliente debe ser connect.
• Gateway devuelve un frame hello-ok con un snapshot (presence, health, stateVersion, uptimeMs) más límites de policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• 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.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos del ciclo de vida de emparejamiento/aprobación, y shutdown.

Las ejecuciones de agente tienen dos etapas:

1. Acuse inmediato aceptado (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 de Gateway.

Comprobaciones operativas

Actividad

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

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 escaleras 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 fallback implícito a canal directo).
• Los primeros frames no válidos o que no sean de conexión se rechazan y se cierran.
• El apagado ordenado emite el evento shutdown antes de cerrar el socket.

Relacionado

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