Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Solución avanzada de problemas

Diagnósticos a partir de síntomas con secuencias exactas de comandos y firmas de registro.

Configuración

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

Gestión de secretos

Contrato 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 por referencia.

​
Arranque local en 5 minutos

1

Iniciar 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

Verificar el estado del servicio

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

Validar la preparación del canal

openclaw channels status --probe
Con un gateway accesible, esto ejecuta sondeos de canal en vivo por cuenta y auditorías opcionales. Si el gateway no es accesible, la CLI recurre a resúmenes de canales solo de configuración en lugar de la salida de sondeos en vivo.
La recarga de configuración del Gateway observa la ruta activa del archivo de configuración (resuelta a partir de 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 activa de configuración en memoria; una recarga correcta cambia 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, compatibles con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • IU 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 valor 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 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.
Nota de planificación:
  • /v1/models está orientado primero a 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, el modelo normal del agente seleccionado y la configuración de embeddings siguen teniendo el control.
Todo esto se ejecuta en el puerto principal del Gateway y usa el mismo límite de autenticación de operador confiable 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/sobrescritura → gateway.bind → loopback
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 nuevo puerto. El arranque del Gateway usa el mismo puerto y enlace efectivos cuando inicializa los orígenes locales de la IU 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 cualquier origen de navegador remoto, como URL de proxy HTTPS, a gateway.controlUi.allowedOrigins explícitamente.

​
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 del 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 intencionalmente aislamiento 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 existan instalaciones launchd/systemd/schtasks obsoletas.
  • gateway probe puede advertir sobre multiple reachable gateways cuando responde más de un destino.
  • Si eso es intencional, aísla puertos, configuración/estado y raíces de espacio 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 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 los clientes localmente a ws://127.0.0.1:18789.
Los túneles SSH no eluden la autenticación del gateway. Para la 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 aún tiene que satisfacer esa ruta de autenticación.
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 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 deshabilitación, por lo que la recuperación automática de KeepAlive sigue funcionando tras bloqueos inesperados y gateway start vuelve a habilitarlo limpiamente. Para suprimir de forma persistente la reaparición automática entre reinicios, pasa --disable: openclaw gateway stop --disable.Las etiquetas de LaunchAgent son ai.openclaw.gateway (predeterminada) o ai.openclaw.<profile> (perfil con nombre). openclaw doctor audita y repara desviaciones de configuración del servicio.

​
Ruta rápida del 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)

  • El primer frame de cliente debe ser connect.
  • El Gateway devuelve la 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.tool, sessions.changed, presence, tick, health, heartbeat, eventos de ciclo de vida de emparejamiento/aprobación y shutdown.
Las ejecuciones de agentes son de dos etapas:
  1. Acuse de aceptación inmediato (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 del Gateway.

​
Comprobaciones operativas

​
Actividad

  • Abre WS y envía connect.
  • Espera la 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. En brechas de secuencia, actualiza el estado (health, system-presence) antes de continuar.

​
Firmas de fallo comunes

FirmaProblema probable
refusing to bind gateway ... without authEnlace no local 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 la marca de modo local en una configuración dañada
unauthorized during connectIncompatibilidad de autenticación entre el cliente y el Gateway
Para ver las escalas completas de diagnóstico, usa Solución de problemas del Gateway.

​
Garantías de seguridad

  • Los clientes del protocolo Gateway fallan rápido cuando Gateway no está disponible (sin alternativa implícita directa al canal).
  • Los primeros marcos 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