Saltar al contenido principal

​
Runbook del gateway

Usa esta página para el arranque del día 1 y las operaciones del día 2 del servicio Gateway.

Solución de problemas avanzada

Diagnósticos orientados por síntomas con secuencias exactas de comandos y firmas de logs.

Configuración

Guía de configuración orientada a tareas + referencia completa de configuración.

Gestión de secretos

Contrato de SecretRef, comportamiento de instantáneas en tiempo de ejecución y operaciones de migración/recarga.

Contrato del plan de secretos

Reglas exactas de destino/ruta de secrets apply y comportamiento de perfiles de autenticación solo con refs.

​
Inicio local en 5 minutos

1

Iniciar el Gateway

openclaw gateway --port 18789
# debug/trace reflejado en stdio
openclaw gateway --port 18789 --verbose
# fuerza el cierre del listener en el puerto seleccionado y luego inicia
openclaw gateway --force
2

Verificar el estado del servicio

openclaw gateway status
openclaw status
openclaw logs --follow
Referencia saludable: Runtime: running y RPC probe: ok.
3

Validar la disponibilidad de canales

openclaw channels status --probe
Con un gateway accesible, esto ejecuta sondas live por cuenta y auditorías opcionales. Si el gateway no es accesible, la CLI usa como respaldo resúmenes de canales basados solo en configuración en lugar de salida de sondas live.
La recarga de configuración del Gateway observa la ruta del archivo de configuración activo (resuelta a partir de los valores predeterminados de profile/state, o OPENCLAW_CONFIG_PATH cuando está definido). El modo predeterminado es gateway.reload.mode="hybrid". Después de la primera carga correcta, el proceso en ejecución sirve la instantánea de configuración activa en memoria; una recarga correcta intercambia esa instantánea de forma atómica.

​
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, compatible con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Control UI 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é este conjunto es importante:
  • La mayoría de las integraciones de Open WebUI, LobeChat y LibreChat primero consultan /v1/models.
  • Muchos pipelines 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 a agentes: devuelve openclaw, openclaw/default y openclaw/<agentId>.
  • openclaw/default es el alias estable que siempre apunta al agente predeterminado configurado.
  • Usa x-openclaw-model cuando quieras una sobrescritura de proveedor/modelo del backend; en caso contrario, la configuración normal de modelo y embeddings del agente seleccionado sigue teniendo el control.
Todo esto se ejecuta en el puerto principal del Gateway y usa el mismo límite de autenticación confiable de operador que el resto de la API HTTP del Gateway.

​
Precedencia de puerto y enlace

AjusteOrden de resolución
Puerto del Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Modo de enlaceCLI/override → gateway.bind → loopback

​
Modos de hot reload

gateway.reload.modeComportamiento
offSin recarga de configuración
hotAplicar solo cambios seguros para hot reload
restartReiniciar en cambios que requieren recarga
hybrid (predeterminado)Aplicar en caliente cuando sea seguro, reiniciar cuando sea necesario

​
Conjunto de comandos de operador

openclaw gateway status
openclaw gateway status --deep   # agrega un escaneo del servicio a nivel de sistema
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep es para descubrimiento adicional de servicios (LaunchDaemons/unidades systemd del sistema /schtasks), no para una sonda RPC de estado más profunda.

​
Múltiples gateways (mismo host)

La mayoría de las instalaciones deberían ejecutar un gateway por máquina. Un único gateway puede alojar múltiples agentes y canales. Solo necesitas múltiples gateways cuando quieres aislamiento intencional o un bot de rescate. Comprobaciones útiles: 
openclaw gateway status --deep
openclaw gateway probe
Qué esperar:
  • gateway status --deep puede informar Other gateway-like services detected (best effort) e imprimir sugerencias de limpieza cuando aún existen instalaciones antiguas de launchd/systemd/schtasks.
  • gateway probe puede advertir sobre multiple reachable gateways cuando más de un destino responde.
  • Si eso es intencional, aísla puertos, config/state y raíces de workspace por gateway.
Configuración detallada: /gateway/multiple-gateways.

​
Acceso remoto

Preferido: Tailscale/VPN. Respaldo: túnel SSH. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Luego conecta los clientes a ws://127.0.0.1:18789 localmente.
Los túneles SSH no omiten la autenticación del gateway. Para autenticación con secreto compartido, los clientes aún deben enviar token/password incluso a través del túnel. Para modos con identidad, la solicitud sigue teniendo que satisfacer esa ruta de autenticación.
Consulta: Remote Gateway, Authentication, Tailscale.

​
Supervisión y ciclo de vida del servicio

Usa ejecuciones supervisadas para una fiabilidad tipo producción. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Las etiquetas de LaunchAgent son ai.openclaw.gateway (predeterminada) o ai.openclaw.<profile> (profile con nombre). openclaw doctor audita y repara la deriva de configuración del servicio.

​
Múltiples gateways en un mismo host

La mayoría de las configuraciones deberían ejecutar un Gateway. Usa varios solo para aislamiento/redundancia estrictos (por ejemplo, un profile de rescate). 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 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Consulta: Multiple gateways.

​
Ruta rápida del profile dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Los valores predeterminados incluyen state/config aislados y el puerto base del gateway 19001.

​
Referencia rápida del protocolo (vista de operador)

  • El primer frame del cliente debe ser connect.
  • El Gateway devuelve una instantánea hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • hello-ok.features.methods / events son una lista conservadora de descubrimiento, 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 del ciclo de vida de pairing/aprobación y shutdown.
Las ejecuciones del agente tienen dos etapas:
  1. Ack inmediato de aceptación (status:"accepted")
  2. Respuesta final de finalización (status:"ok"|"error"), con eventos agent transmitidos entre ambas.
Consulta la documentación completa del protocolo: Gateway Protocol.

​
Comprobaciones operativas

​
Disponibilidad

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

​
Preparación

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Recuperación ante huecos

Los eventos no se vuelven a reproducir. Cuando haya huecos de secuencia, actualiza el estado (health, system-presence) antes de continuar.

​
Firmas comunes de fallos

FirmaProblema probable
refusing to bind gateway ... without authEnlace no loopback sin una ruta válida de autenticación del gateway
another gateway instance is already listening / EADDRINUSEConflicto de puertos
Gateway start blocked: set gateway.mode=localLa configuración está en modo remoto, o falta la marca de modo local en una configuración dañada
unauthorized during connectIncompatibilidad de autenticación entre cliente y gateway
Para secuencias completas de diagnóstico, usa Gateway Troubleshooting.

​
Garantías de seguridad

  • Los clientes del protocolo Gateway fallan rápidamente cuando el Gateway no está disponible (sin fallback implícito a canales directos).
  • Los primeros frames inválidos/no connect se rechazan y la conexión se cierra.
  • El apagado ordenado emite un evento shutdown antes de cerrar el socket.
Relacionado: