Configura la UI de OpenClaw: Acceso y Emparejamiento Rápido

¿Alguna vez has sentido que configurar una interfaz para tu Gateway es más difícil que el propio modelo de IA? Gestionar tokens, lidiar con permisos y querer una UI que simplemente funcione desde cualquier dispositivo puede ser frustrante cuando solo quieres empezar a construir.

La Control UI es una pequeña aplicación de página única (SPA) creada con Vite + Lit que sirve el Gateway. Es la forma más directa de interactuar con tu configuración sin complicaciones innecesarias.

• Por defecto: http://<host>:18789/
• Prefijo opcional: configura gateway.controlUi.basePath (ej. /openclaw)

Esta interfaz se comunica directamente con el WebSocket del Gateway en el mismo puerto.

Apertura rápida (local)

Si el Gateway se está ejecutando en la misma computadora, abre:

• http://127.0.0.1:18789/ (o http://localhost:18789/)

Si la página no carga, inicia el Gateway primero: openclaw gateway.

La autenticación se envía durante el apretón de manos (handshake) del WebSocket mediante:

• connect.params.auth.token
• connect.params.auth.password

El panel de configuración del dashboard guarda un token para la sesión actual de la pestaña del navegador y la URL del gateway seleccionada; las contraseñas no se guardan. El proceso de onboarding genera un token de gateway por defecto, así que pégalo aquí en tu primera conexión.

Emparejamiento de dispositivos (primera conexión)

Cuando te conectas a la Control UI desde un nuevo navegador o dispositivo, el Gateway requiere una aprobación de emparejamiento única, incluso si estás en la misma Tailnet con gateway.auth.allowTailscale: true. Esta es una medida de seguridad para evitar accesos no autorizados.

Lo que verás: “disconnected (1008): pairing required”

Para aprobar el dispositivo:

# List pending requests
openclaw devices list

# Approve by request ID
openclaw devices approve <requestId>

Si el navegador reintenta el emparejamiento con detalles de autenticación distintos (roles, alcances o clave pública), la solicitud pendiente anterior se descarta y se crea un nuevo requestId. Ejecuta openclaw devices list antes de aprobar.

Una vez aprobado, el dispositivo se recuerda y no necesitará otra aprobación a menos que lo revoques con openclaw devices revoke --device <id> --role <role>. Consulta Devices CLI para la rotación y revocación de tokens.

Notas:

• Las conexiones locales (127.0.0.1) se aprueban automáticamente.
• Las conexiones remotas (LAN, Tailnet, etc.) requieren aprobación explícita.
• Cada perfil de navegador genera un ID de dispositivo único, por lo que cambiar de navegador o borrar los datos del mismo requerirá un nuevo emparejamiento.

Soporte de idiomas

La Control UI puede localizarse automáticamente en la primera carga según el idioma de tu navegador, y puedes cambiarlo después desde el selector de idiomas en la tarjeta de Acceso.

• Idiomas soportados: en, zh-CN, zh-TW, pt-BR, de, es
• Las traducciones que no son en inglés se cargan de forma diferida (lazy-load) en el navegador.
• El idioma seleccionado se guarda en el almacenamiento del navegador para futuras visitas.
• Si faltan claves de traducción, se usará el inglés por defecto.

Qué puede hacer (hoy)

• Chatear con el modelo vía Gateway WS (chat.history, chat.send, chat.abort, chat.inject)
• Ver flujos de llamadas a herramientas y tarjetas de salida en vivo en el Chat (eventos del agente)
• Canales: Estado de WhatsApp/Telegram/Discord/Slack + canales de plugins (Mattermost, etc.) + login por QR + configuración por canal (channels.status, web.login.*, config.patch)
• Instancias: Lista de presencia y actualización (system-presence)
• Sesiones: Lista y ajustes de thinking/fast/verbose/reasoning por sesión (sessions.list, sessions.patch)
• Tareas Cron: Listar, añadir, editar, ejecutar, activar/desactivar e historial de ejecución (cron.*)
• Skills: Estado, activar/desactivar, instalar y actualizar claves de API (skills.*)
• Nodos: Lista y capacidades (node.list)
• Aprobaciones de ejecución: Editar listas de permitidos del gateway o nodos y políticas para exec host=gateway/node (exec.approvals.*)
• Configuración: Ver y editar ~/.openclaw/openclaw.json (config.get, config.set)
• Configuración: Aplicar y reiniciar con validación (config.apply) y reactivar la última sesión activa
• Las escrituras de configuración incluyen una protección de hash base para evitar sobrescribir ediciones simultáneas
• Las escrituras (config.set/config.apply/config.patch) también verifican la resolución de SecretRef activos antes de guardar; si hay referencias sin resolver, se rechaza la escritura
• Esquema de configuración y renderizado de formularios (config.schema, incluyendo esquemas de plugins y canales); el editor de JSON puro solo está disponible si el snapshot permite un ciclo de ida y vuelta seguro
• Si un snapshot no es seguro para texto plano, la Control UI fuerza el modo Formulario y desactiva el modo Raw
• Los valores de objetos SecretRef estructurados se muestran como solo lectura en los inputs de texto para evitar que se corrompan accidentalmente al convertirlos a string
• Depuración: Snapshots de estado, salud y modelos + log de eventos + llamadas RPC manuales (status, health, models.list)
• Logs: Seguimiento en vivo de los archivos de log del gateway con filtros y exportación (logs.tail)
• Actualización: Ejecutar actualización de paquete o git y reiniciar (update.run) con reporte de reinicio

Notas del panel de tareas Cron:

• Para tareas aisladas, la entrega por defecto es el resumen de anuncio. Puedes cambiarlo a “none” si quieres ejecuciones solo internas.
• Los campos de canal y objetivo aparecen cuando se selecciona “announce”.
• El modo Webhook usa delivery.mode = "webhook" con delivery.to apuntando a una URL HTTP(S) válida.
• Para tareas de la sesión principal, están disponibles los modos webhook y none.
• Los controles avanzados incluyen borrar tras ejecutar, anular agente, opciones de cron exacto o escalonado, ajustes de modelo del agente y opciones de entrega de mejor esfuerzo.
• La validación del formulario es instantánea con errores por campo; los valores inválidos desactivan el botón de guardar.
• Configura cron.webhookToken para enviar un token bearer dedicado; si se omite, el webhook se envía sin cabecera de autenticación.
• Compatibilidad heredada: las tareas antiguas con notify: true pueden seguir usando cron.webhook hasta que se migren.

Comportamiento del Chat

• chat.send es no bloqueante: responde inmediatamente con { runId, status: "started" } y la respuesta fluye vía eventos de chat.
• Reenviar con la misma idempotencyKey devuelve { status: "in_flight" } si está en ejecución, y { status: "ok" } al terminar.
• Las respuestas de chat.history tienen un límite de tamaño por seguridad. Si las entradas son muy grandes, el Gateway puede truncar textos largos, omitir bloques de metadatos pesados y reemplazar mensajes excesivos con un marcador ([chat.history omitted: message too large]).
• chat.inject añade una nota del asistente a la sesión y emite un evento de chat solo para la UI (sin ejecución del agente ni entrega por canal).
• Detener:
  • Haz clic en Stop (llama a chat.abort)
  • Escribe /stop (o frases como stop, stop action, stop run, stop openclaw, please stop) para abortar fuera de banda
  • chat.abort soporta { sessionKey } (sin runId) para detener todas las ejecuciones activas de esa sesión
• Retención parcial al abortar:
  • Cuando se aborta una ejecución, el texto parcial del asistente puede mostrarse en la UI.
  • El Gateway guarda ese texto parcial en el historial cuando existe salida en el búfer.
  • Las entradas guardadas incluyen metadatos de aborto para que se pueda distinguir entre fragmentos abortados y respuestas completas.

Acceso vía Tailnet (recomendado)

Tailscale Serve integrado (preferido)

Mantén el Gateway en loopback y deja que Tailscale Serve actúe como proxy con HTTPS:

openclaw gateway --tailscale serve

Abre:

• https://<magicdns>/ (o tu gateway.controlUi.basePath configurado)

Por defecto, las peticiones de Control UI/WebSocket vía Serve pueden autenticarse mediante cabeceras de identidad de Tailscale (tailscale-user-login) cuando gateway.auth.allowTailscale es true. OpenClaw verifica la identidad resolviendo la dirección x-forwarded-for con tailscale whois. Solo acepta esto cuando la petición llega a loopback con las cabeceras x-forwarded-* de Tailscale. Configura gateway.auth.allowTailscale: false si quieres exigir token o contraseña incluso en tráfico de Serve. La autenticación sin token en Serve asume que el host del gateway es confiable.

Vincular a tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

Luego abre:

• http://<tailscale-ip>:18789/ (o tu gateway.controlUi.basePath configurado)

Pega el token en la configuración de la UI (se envía como connect.params.auth.token).

HTTP no seguro

Si abres el dashboard sobre HTTP plano (http://<lan-ip> o http://<tailscale-ip>), el navegador se ejecuta en un contexto no seguro y bloquea WebCrypto. Por defecto, OpenClaw bloquea las conexiones de la Control UI sin identidad de dispositivo.

Solución recomendada: usa HTTPS (Tailscale Serve) o abre la UI localmente:

• https://<magicdns>/ (Serve)
• http://127.0.0.1:18789/ (en el host del gateway)

Comportamiento del interruptor de autenticación insegura:

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth es solo un ajuste de compatibilidad local:

• Permite que las sesiones de la Control UI en localhost funcionen sin identidad de dispositivo en contextos HTTP no seguros.
• No salta las verificaciones de emparejamiento.
• No relaja los requisitos de identidad para dispositivos remotos (que no sean localhost).

Solo para emergencias:

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

dangerouslyDisableDeviceAuth desactiva las comprobaciones de identidad de la Control UI y supone un riesgo de seguridad grave. Revierte este cambio rápido tras su uso.

Consulta Tailscale para guías de configuración HTTPS.

Construir la UI

El Gateway sirve archivos estáticos desde dist/control-ui. Puedes construirlos con:

pnpm ui:build # auto-installs UI deps on first run

Base absoluta opcional (si quieres URLs de assets fijas):

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

Para desarrollo local (servidor de desarrollo independiente):

pnpm ui:dev # auto-installs UI deps on first run

Luego apunta la UI a la URL de tu Gateway WS (ej. ws://127.0.0.1:18789).

Depuración/pruebas: servidor de desarrollo + Gateway remoto

La Control UI son archivos estáticos; el objetivo del WebSocket es configurable y puede ser distinto al origen HTTP. Esto es útil si quieres el servidor de desarrollo de Vite localmente pero el Gateway corre en otro lugar.

1. Inicia el servidor de desarrollo de la UI: pnpm ui:dev
2. Abre una URL como:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

Autenticación única opcional (si es necesaria):

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

Notas:

• gatewayUrl se guarda en localStorage tras la carga y se elimina de la URL.
• El token debe pasarse mediante el fragmento de la URL (#token=...) siempre que sea posible. Los fragmentos no se envían al servidor, evitando fugas en logs o Referer.
• La password solo se mantiene en memoria.
• Cuando se define gatewayUrl, la UI no usa credenciales de configuración o entorno. Debes proporcionar el token (o password) explícitamente.
• Usa wss:// cuando el Gateway esté tras TLS (Tailscale Serve, proxy HTTPS, etc.).
• gatewayUrl solo se acepta en ventanas de nivel superior (no embebidas) para evitar clickjacking.
• Los despliegues de Control UI que no sean loopback deben configurar gateway.controlUi.allowedOrigins explícitamente.
• No uses gateway.controlUi.allowedOrigins: ["*"] salvo para pruebas locales muy controladas.
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true permite el modo de respaldo de cabecera Host, pero es un modo de seguridad peligroso.

Ejemplo:

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

Detalles de configuración de acceso remoto: Remote access.

Relacionado

• Dashboard — panel de control del gateway
• WebChat — interfaz de chat basada en navegador
• TUI — interfaz de usuario de terminal
• Health Checks — monitoreo de salud del gateway

Siguientes pasos

• Configura tu primer canal en la sección de Canales.
• Revisa la CLI de dispositivos para gestionar accesos.

AI Setup Assistant