Cómo funciona el cliente web OCTO para la colaboración entre humanos y agentes de IA

La mayoría de los intentos de integrar LLMs en chats de trabajo terminan como simples bots de Telegram. El usuario escribe un comando con barra, espera unos segundos y recibe una respuesta estándar en un solo bloque. Los creadores del proyecto OCTO decidieron abordarlo desde un ángulo diferente. Están construyendo un entorno de trabajo abierto donde los agentes de IA participan en chats junto a las personas como empleados digitales de pleno derecho.

Hoy analizaremos el repositorio octo-web. Esta es la parte frontend del sistema, escrita en TypeScript y React.

Base de código unificada para web y escritorio

La principal decisión arquitectónica del proyecto es abandonar la separación entre la versión web y el cliente de escritorio. Los desarrolladores no crearon dos proyectos React separados. Toda la aplicación reside en el directorio src/.

Si ejecutas el cliente en un navegador, funciona la compilación estándar. Si estás construyendo una versión de escritorio para macOS, Windows o Linux, se conecta una capa ligera de Electron desde la carpeta electron/. Esta capa maneja la integración con el sistema operativo: bandeja del sistema, notificaciones, arrastrar y soltar archivos y actualizaciones en segundo plano.

Este enfoque elimina la necesidad de duplicar componentes de interfaz o mantener dos ramas diferentes de la interfaz.

Interfaz para trabajar con agentes de IA

Los chats regulares no se adaptan bien a las particularidades del trabajo de las redes neuronales. Cuando un modelo selecciona una herramienta o ejecuta una cadena de razonamiento, un mensajero convencional solo muestra un indicador de escritura.

En octo-web, la interfaz fue diseñada desde cero para la autonomía de los agentes (en la terminología del proyecto, se les llama Lobsters, y funcionan basados en OpenClaw).

Esto es lo que está implementado en el diseño y los componentes:

• Renderizado de respuestas en streaming con soporte de Markdown en tiempo real
• Visualización de funciones y herramientas invocadas directamente dentro del mensaje (llamada a herramientas en línea)
• Separación de estados de escritura y lectura para humanos y agentes autónomos
• Insignias visuales que ayudan a distinguir instantáneamente un bot de un colega en vivo
• Soporte de interfaz bilingüe (inglés y chino) con verificación de configuración regional en la etapa de CI

Cómo se organiza la estructura del proyecto

Dentro del repositorio, todo está organizado en carpetas claras sin complejidad innecesaria:

• src/pages/ contiene las pantallas principales: chats, listas de canales, configuración y estructura organizacional
• src/components/ almacena el conjunto de componentes: burbujas de mensajes, campos de entrada, insignias de agentes y renderizados en streaming
• src/store/ maneja el estado del cliente: autorización, borradores, canales y estado de interacción con agentes
• src/api/ contiene clientes REST y WebSocket para la comunicación con el backend
• electron/ contiene los puntos de entrada para Electron

El cliente se comunica con el backend octo-server, escrito en Go. El motor WuKongIM se utiliza para la transmisión de mensajes en tiempo real. Los autores no ocultan el fork: tomaron la estructura básica del frontend del proyecto de código abierto TangSengDaoDaoWeb y la adaptaron para tareas de IA.

Inicio rápido para desarrollo

Para ejecutar el cliente web localmente, necesitas Node.js y el gestor de paquetes pnpm.

git clone https://github.com/Mininglamp-OSS/octo-web.git
cd octo-web
pnpm install
pnpm dev

Por defecto, el cliente espera que el backend octo-server esté ejecutándose en localhost:8080. Para apuntarlo a una dirección diferente, crea un archivo .env.local basándote en .env.example y especifica los valores actuales para VITE_API_*.

La compilación de la aplicación de escritorio se activa con comandos separados:

pnpm build        # обычная веб-сборка
pnpm pc:dev       # запуск Electron-клиента
pnpm pc:package   # упаковка приложения под нужную ОС

Principios y autonomía

Los desarrolladores del proyecto siguen la idea de local-first. Todo lo que pueda ejecutarse en el hardware del usuario o dentro del perímetro de red de la empresa debería ejecutarse allí. Los chats, las bases de datos vectoriales y los agentes de IA se ejecutan localmente sin vinculación obligatoria a nubes de terceros.

Su enfoque de división de roles es simple: la IA maneja el razonamiento y la ejecución rutinaria, mientras que los humanos establecen la dirección y evalúan la calidad.

A quién le interesa explorar el repositorio

El proyecto actualmente tiene alrededor de 600 estrellas en GitHub, pero es interesante como ejemplo de organización limpia de monorepo con React y Electron. Si estás construyendo un chat de trabajo, una herramienta interna de empresa o experimentando con interfaces para LLMs, puedes encontrar soluciones útiles aquí para llamadas a herramientas y streaming de mensajes.

El proyecto se distribuye bajo la licencia Apache 2.0, por lo que puedes examinar el código en detalle libremente o usarlo en tus propios proyectos.