Saltar al contenido principal
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 profunda

Diagnósticos orientados por síntomas con escaleras de comandos exactas y firmas de registro.

Configuración

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

Gestión de secretos

Contrato SecretRef, comportamiento de instantánea 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 por referencia.

​
Arranque local en 5 minutos

1

Inicia el Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Verifica el estado del servicio

openclaw gateway status
openclaw status
openclaw logs --follow
Línea base saludable: Runtime: running, Connectivity probe: ok y Capability: ... que coincida con lo esperado. Usa openclaw gateway status --require-rpc cuando necesites prueba RPC con alcance de lectura, no solo alcanzabilidad.
3

Valida la preparación del canal

openclaw channels status --probe
Con un Gateway alcanzable, esto ejecuta sondeos de canales en vivo por cuenta y auditorías opcionales. Si no se puede alcanzar el Gateway, la CLI recurre a resúmenes de canales solo de configuración en lugar de la salida del sondeo en vivo.
La recarga de configuración del Gateway observa la ruta del archivo de configuración activo (resuelta desde los valores predeterminados de perfil/estado, o OPENCLAW_CONFIG_PATH cuando está definida). 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 en 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
    • Interfaz 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 impacto 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 integraciones de Open WebUI, LobeChat y LibreChat sondean /v1/models primero.
  • Muchas canalizaciones RAG y de memoria esperan /v1/embeddings.
  • Los clientes nativos para agentes prefieren cada vez más /v1/responses.
Nota de planificación:
  • /v1/models prioriza 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, la configuración normal de modelo e incrustaciones del agente seleccionado mantiene el control.
Todo esto se ejecuta en el puerto principal del Gateway y usa el mismo límite de autenticación de operador de confianza que el resto de la API HTTP del Gateway. Admin HTTP RPC (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 Admin HTTP RPC.

​
Precedencia de puerto y enlace

ConfiguraciónOrden de resolución
Puerto del Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Modo de enlaceCLI/override → gateway.bind → loopback
Los servicios 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 interfaz 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 explícitamente cualquier origen de navegador remoto, como URL de proxy HTTPS, a gateway.controlUi.allowedOrigins.

​
Modos de recarga en caliente

gateway.reload.modeComportamiento
offSin recarga de configuración
hotAplica solo cambios seguros en caliente
restartReinicia ante cambios que requieren recarga
hybrid (predeterminado)Aplica en caliente cuando es seguro; reinicia cuando es necesario

​
Conjunto de comandos del operador

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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 de 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 aislamiento intencionalmente 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 todavía queden instalaciones launchd/systemd/schtasks obsoletas.
  • gateway probe puede advertir sobre multiple reachable gateway identities cuando responden gateways distintos, o cuando OpenClaw no puede demostrar que los destinos alcanzables 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 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 19001
OPENCLAW_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 clientes localmente a ws://127.0.0.1:18789.
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 que llevan identidad, la solicitud aún debe satisfacer esa ruta de autenticación.
Consulta: Gateway remoto, Autenticación, Tailscale.

​
Supervisión y ciclo de vida del servicio

Usa ejecuciones supervisadas para confiabilidad similar a producción. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Usa openclaw gateway restart para reinicios. No encadenes openclaw gateway stop y openclaw gateway start como sustituto de reinicio.En macOS, gateway stop usa launchctl bootout de forma predeterminada — esto elimina el LaunchAgent de la sesión de arranque actual sin persistir una desactivación, por lo que la recuperación automática de KeepAlive sigue funcionando después de bloqueos inesperados y gateway start lo vuelve a habilitar limpiamente. Para suprimir de forma persistente el reinicio automático entre reinicios del sistema, pasa --disable: openclaw gateway stop --disable.Las etiquetas LaunchAgent son ai.openclaw.gateway (predeterminada) o ai.openclaw.<profile> (perfil con nombre). openclaw doctor audita y repara desvíos de configuración del servicio.

​
Ruta rápida de perfil de desarrollo

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Los valores predeterminados incluyen estado/configuración aislados y puerto base del Gateway 19001.

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

  • La primera trama del cliente debe ser connect.
  • Gateway devuelve una 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.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos de ciclo de vida de emparejamiento/aprobación y shutdown.
Las ejecuciones de agente tienen dos etapas:
  1. Confirmación aceptada inmediata (status:"accepted")
  2. Respuesta final de finalización (status:"ok"|"error"), con eventos agent transmitidos entre medio.
Consulta la documentación completa del protocolo: Protocolo Gateway.

​
Comprobaciones operativas

​
Actividad

  • 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 de brechas

Los eventos no se reproducen. Ante brechas de secuencia, actualiza el estado (health, system-presence) antes de continuar.

​
Firmas de fallos comunes

FirmaProblema probable
refusing to bind gateway ... without authEnlace no loopback sin una ruta de autenticación de Gateway válida
another gateway instance is already listening / EADDRINUSEConflicto de puerto
Gateway start blocked: set gateway.mode=localConfiguración establecida en modo remoto, o falta el sello de modo local en una configuración dañada
unauthorized during connectDiscordancia de autenticación entre el cliente y Gateway
Para ver escalas 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 reserva implícita a canal directo).
  • Los primeros frames 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:

​
Relacionado