Configuración de la Web y el Gateway

Configurar un panel de control y que funcione a la primera fuera de tu máquina local suele ser frustrante. Entre túneles, certificados y permisos de red, es fácil perder tiempo en detalles técnicos que te alejan de lo que realmente quieres construir.

Gestionar el acceso remoto a una UI de control sin comprometer la seguridad es un reto común. Esta guía te ayuda a exponer tu Gateway de forma directa y segura.

Requisitos previos

• Archivos de la interfaz en la carpeta dist/control-ui.
• Tailscale instalado (si planeas usar los modos de acceso remoto).

Inicio rápido

El Gateway ofrece una Control UI para el navegador (basada en Vite + Lit) en el mismo puerto que el WebSocket del Gateway. Por defecto, puedes acceder en http://<host>:18789/.

Para activarla, usa esta configuración mínima en tu archivo:

{
  gateway: {
    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath es opcional
  },
}

Después, inicia el Gateway desde tu terminal:

openclaw gateway

Acceso con Tailscale

Integrated Serve (Recomendado)

Esta es la mejor opción. Mantienes el Gateway en loopback y dejas que Tailscale Serve actúe como proxy:

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

Al iniciar el Gateway con openclaw gateway, podrás entrar desde:

• https://<magicdns>/ (o el basePath que hayas configurado).

Tailnet bind + token

Si prefieres vincularlo directamente a la IP de tu Tailnet:

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "tu-token-aqui" },
  },
}

Accede a través de:

• http://<tailscale-ip>:18789/

Seguridad y Webhooks

Cuando activas hooks.enabled=true, el Gateway expone un endpoint para webhooks en el mismo servidor HTTP. Puedes revisar los detalles de autenticación y payloads en la configuración de hooks.

En cuanto a la seguridad, ten en cuenta estos puntos:

• El Gateway requiere autenticación por defecto (token, password o headers de identidad de Tailscale). Los binds que no son loopback siempre obligan a usar un token o password compartido.
• La UI incluye headers anti-clickjacking y solo acepta conexiones WebSocket del mismo origen, a menos que definas gateway.controlUi.allowedOrigins.
• Si usas el modo funnel, es obligatorio configurar gateway.auth.mode: "password".
• Con el modo serve, los headers de identidad de Tailscale pueden validar la auth si gateway.auth.allowTailscale es true.

Building the UI

Si necesitas compilar los archivos estáticos de la Control UI manualmente, ejecuta este comando:

pnpm ui:build

Este comando instalará las dependencias de la UI automáticamente la primera vez que lo lances.

Solución de problemas

• Error de autenticación en conexiones remotas: Si no estás en loopback, el sistema exige un token o password. Revisa que gateway.auth tenga las credenciales correctas.
• WebSocket rechazado por origen: Si intentas conectar desde un dominio distinto, la conexión fallará. Asegúrate de añadir ese dominio en gateway.controlUi.allowedOrigins.

¿Necesitas ayuda con la configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Control UI
• Gateway configuration
• Tailscale Integration
• Security Guide