Manual de operaciones del Gateway

Use esta página para la puesta en marcha inicial y las operaciones posteriores del servicio Gateway.

Puesta en marcha local en 5 minutos

openclaw gateway --port 18789# depuración/rastreo reflejados en stdioopenclaw gateway --port 18789 --verbose# finalizar por la fuerza el proceso que escucha en el puerto seleccionado y, después, 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 Plugin, como la ruta opcional /api/v1/admin/rpc
  • Interfaz de control y enlaces
• 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 la publicación o el túnel de Tailscale estén activos, 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 de proxy inverso que no usan bucle invertido pueden utilizar 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é este conjunto es importante:

• 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 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 desee sustituir el proveedor/modelo del backend; de lo contrario, el modelo normal y la configuración de incrustaciones del agente seleccionado mantienen el control.

Todos estos se ejecutan en el puerto principal del Gateway y usan el mismo límite de autenticación del 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 independiente y 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 del gateway instalados registran el valor resuelto de --port en los metadatos del supervisor. Después de cambiar gateway.port, ejecute openclaw doctor --fix o openclaw gateway install --force para que launchd/systemd/schtasks inicie el proceso en el puerto nuevo.

El inicio del Gateway usa el mismo puerto y enlace efectivos cuando genera los orígenes locales de la interfaz de control para enlaces que no son de bucle invertido. Por ejemplo, --bind lan --port 3000 genera http://localhost:3000 y http://127.0.0.1:3000 antes de que se ejecute la validación en tiempo de ejecución. Añada explícitamente a gateway.controlUi.allowedOrigins cualquier origen de navegador remoto, como las URL de proxy HTTPS.

Modos de recarga en caliente

Conjunto de comandos del operador

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 solo gateway puede alojar varios agentes y canales. Solo se necesitan varios gateways cuando se busca intencionadamente el aislamiento o un bot de recuperación.

Comprobaciones útiles:

openclaw gateway status --deepopenclaw gateway probe

Qué cabe esperar:

• gateway status --deep puede informar de Other gateway-like services detected (best effort) y mostrar indicaciones de limpieza cuando aún existen 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 sean el mismo gateway. Un túnel SSH, una URL de proxy o una URL remota configurada que apunten al mismo gateway constituyen un único gateway con varios transportes, aunque los puertos de transporte sean diferentes.
• Si esto es intencionado, 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:

• 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

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

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

Después, conecte localmente los clientes 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 nuevos intentos de inicio hasta que se corrija la configuración. launchd y el Programador de tareas de Windows no disponen de una regla equivalente para detenerse según el código de salida, por lo que el Gateway también conserva el historial de inicios rápidos fallidos e impide el inicio automático de las cuentas de canales/proveedores después de varios fallos de inicio. En ese modo seguro, el plano de control sigue iniciándose para permitir su inspección y reparación, las recargas en caliente de la configuración y secrets.reload rechazan los reinicios automáticos de los 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 estado/configuración aislados y el puerto base del gateway 19001.

Referencia rápida del protocolo (perspectiva del operador)

• La primera trama del cliente debe ser connect.
• El Gateway devuelve una trama hello-ok con un 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 descubrimiento conservadora, no un volcado generado de todas las rutas auxiliares invocables.
• Solicitudes: req(method, params) → res(ok/payload|error).
• Entre los eventos habituales se 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 de vinculación/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 del Gateway.

Comprobaciones operativas

Disponibilidad

• Abra una conexión WS y envíe connect.
• Se espera una respuesta hello-ok con una instantánea.

Preparación

openclaw gateway statusopenclaw channels status --probeopenclaw health

Recuperación tras interrupciones

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

Indicadores habituales de error

Para consultar los procedimientos completos de diagnóstico, use 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 respaldo implícito al canal directo).
• Las primeras tramas no válidas o que no sean de conexión se rechazan y se cierra la conexión.
• El apagado ordenado emite el evento shutdown antes de cerrar el socket.

Contenido relacionado

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