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

Solución de problemas avanzada

Diagnósticos basados en síntomas con secuencias exactas de comandos y firmas de registro.

Configuración

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

Gestión de secretos

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

Contrato del plan de secretos

Reglas exactas de destino/ruta de secrets apply y comportamiento de perfiles de autenticación que solo admiten referencias.

​
Puesta en marcha local en 5 minutos

1

Iniciar el Gateway

2

Verificar el estado del servicio

Referencia de estado correcto: Runtime: running, Connectivity probe: ok y una línea Capability que coincida con lo esperado. Use openclaw gateway status --require-rpc para demostrar el RPC con alcance de lectura, no solo la accesibilidad.
3

Validar la disponibilidad de los canales

Con un gateway accesible, esto ejecuta sondeos en vivo de los canales de cada cuenta y auditorías opcionales. Si el gateway no está accesible, la CLI recurre a resúmenes de canales basados únicamente en la configuración.
La recarga de la configuración del Gateway supervisa la ruta del archivo de configuración activo (resuelta a partir de los valores predeterminados del perfil/estado, o OPENCLAW_CONFIG_PATH cuando se establece). El modo predeterminado es gateway.reload.mode="hybrid". Después de la primera carga correcta, el proceso en ejecución utiliza la instantánea activa de la configuración en memoria; una recarga correcta sustituye esa instantánea de forma atómica.

​
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

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:
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:
Configuración detallada: /gateway/multiple-gateways.

​
Acceso remoto

Opción preferida: Tailscale/VPN. Alternativa: túnel SSH.
Después, conecte localmente los clientes a ws://127.0.0.1:18789.
Los túneles SSH no eluden la autenticación del gateway. Para la autenticación mediante secreto compartido, los clientes deben seguir enviando token/password incluso a través del túnel. Para los modos que incluyen identidad, la solicitud también debe satisfacer esa ruta de autenticación.
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.
Use openclaw gateway restart para los reinicios. No encadene openclaw gateway stop y openclaw gateway start como sustituto de un reinicio.En macOS, gateway stop usa launchctl bootout de forma predeterminada. Esto elimina el LaunchAgent de la sesión de arranque actual sin conservar una desactivación, por lo que la recuperación automática de KeepAlive sigue funcionando después de fallos inesperados y gateway start lo vuelve a activar correctamente. Para impedir de forma persistente la reaparición automática tras los reinicios del sistema, pase --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 corrige las desviaciones en la configuración del servicio.
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

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

​
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