Canal WebChat de OpenClaw

WebChat se comunica con OpenClaw Gateway a través de una conexión WebSocket usando tres operaciones principales: • chat.history — Recuperar el historial de conversación del Gateway • chat.send — Transmitir mensajes del usuario al asistente de IA • chat.inject — Agregar notas del asistente directamente a las transcripciones y transmitirlas a la interfaz sin activar una ejecución del agente A diferencia de otros canales que dependen de servicios externos y webhooks, WebChat es completamente nativo del Gateway. Los mensajes nunca salen de tu infraestructura — la conexión WebSocket es directa entre el cliente de la interfaz y el proceso del Gateway. El enrutamiento es determinista: las respuestas de la IA siempre regresan a la sesión de WebChat que inició la conversación.

La autenticación es obligatoria para todas las conexiones de WebChat, incluso en loopback (localhost). Esto previene el acceso no autorizado a tu asistente de IA. OpenClaw soporta dos modos de autenticación: • token — Un token secreto compartido que se envía en el handshake de WebSocket. Ideal para acceso programático y configuraciones de un solo usuario. • password — Autenticación basada en contraseña. Adecuada para entornos multiusuario donde cada usuario tiene sus propias credenciales. Al menos uno de los modos, token o password, debe estar configurado para que WebChat acepte conexiones. Configúralos en los ajustes de gateway.auth de tu openclaw.json.

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "a-strong-random-token-here"
    }
  }
}

WebChat soporta conectividad remota sin necesidad de ejecutar un servidor web separado. Se recomiendan dos enfoques: • Túnel SSH — Redirige el puerto del Gateway a través de SSH: ssh -L 3000:localhost:3000 user@remote-host. Esto te permite acceder a WebChat localmente mientras el Gateway se ejecuta en una máquina remota. • Tailscale — Conecta tus dispositivos a través de la VPN mesh de Tailscale. El Gateway será accesible en su dirección IP de Tailscale sin necesidad de redirección de puertos ni configuración de firewall. Para conexiones remotas, configura los ajustes de gateway.remote con la URL de WebSocket de destino y las credenciales de autenticación. El cliente nativo gestiona la reconexión automáticamente cuando cambian las condiciones de red.

{
  "gateway": {
    "remote": {
      "url": "wss://your-remote-host:3000",
      "token": "YOUR_REMOTE_TOKEN"
    }
  }
}

WebChat utiliza sesiones gestionadas por el Gateway para mantener el contexto de la conversación. Cada conexión de WebChat está asociada a una sesión que almacena el historial de conversación y el contexto de la IA. Las sesiones persisten entre reconexiones — si el WebSocket se desconecta y reconecta, la conversación continúa donde se quedó. La operación chat.history recupera la conversación completa del Gateway al reconectar. La configuración de sesiones se gestiona a través de los ajustes session.* en openclaw.json, incluyendo el backend de almacenamiento y las claves de sesión por defecto.

Cuando el Gateway deja de estar accesible, WebChat entra automáticamente en modo de solo lectura. En este estado: • El historial de conversación previo permanece visible • No se pueden enviar nuevos mensajes • La interfaz indica el estado de desconexión • Se realizan intentos de reconexión automática en segundo plano Una vez que el Gateway vuelve a estar en línea, WebChat se reconecta automáticamente y restaura la funcionalidad completa. No se pierden mensajes del historial de conversación ya que todo el historial proviene del Gateway.

WebChat está implementado como una aplicación nativa de SwiftUI en plataformas Apple: • macOS — Experiencia de escritorio completa con atajos de teclado, notificaciones del sistema e integración con la barra de menú • iOS — Interfaz optimizada para móvil con notificaciones push y actualización en segundo plano La implementación nativa proporciona una experiencia responsiva y nativa de la plataforma sin la sobrecarga de un navegador embebido o un wrapper de Electron. El renderizado de texto, el desplazamiento y el manejo de entrada utilizan componentes nativos de la plataforma. Para otras plataformas (Windows, Linux, Android), accede a WebChat a través de la pestaña de chat de Control UI en cualquier navegador web moderno.

WebChat gestiona la entrega de mensajes a través de la conexión WebSocket con fragmentación configurable para respuestas largas de la IA: • textChunkLimit — Máximo de caracteres por fragmento de mensaje (por defecto: 2000). Las respuestas largas se dividen automáticamente. • blockStreaming — Cuando está habilitado, las respuestas se envían en fragmentos basados en bloques a medida que se generan, proporcionando retroalimentación en tiempo real. Los mensajes se entregan instantáneamente a través del WebSocket — no hay polling ni demora de webhooks. La conexión bidireccional de WebSocket significa que tanto el envío como la recepción ocurren en tiempo real.

{
  "channels": {
    "webchat": {
      "textChunkLimit": 2000,
      "blockStreaming": true
    }
  }
}

La seguridad de WebChat se basa en la capa de autenticación del Gateway. Sigue estas mejores prácticas para despliegues seguros: • Siempre configura la autenticación — No se permite acceso anónimo • Usa cifrado TLS — Conéctate a través de wss:// (WebSocket Secure) para todas las conexiones remotas • Restringe la dirección de enlace — Usa gateway.bind: "127.0.0.1" para acceso solo local; evita vincular a 0.0.0.0 a menos que estés detrás de un proxy inverso • Usa credenciales seguras — Genera tokens aleatorios o contraseñas fuertes • Proxy inverso — Para despliegues en producción, coloca el Gateway detrás de un proxy inverso (nginx, Caddy) con terminación TLS Si usas un proxy inverso en la misma máquina, configura gateway.trustedProxies para asegurar la detección correcta de la IP del cliente.