Arquitectura del panel de control

​

Visión

• Un tablero es una vista de una sesión, no un objeto nuevo. Cada sesión (hilo) tiene dos vistas: la transcripción y el tablero. Una sesión sin widgets fijados es un chat normal. Al fijar un widget, el tablero pasa a existir. Los tableros heredan la identidad, la propiedad del agente, el nombre, la fijación y el ciclo de vida de la sesión. No hay ningún dashboard_create, ningún registro de tableros ni ningún modelo de ACL independiente.
• Paridad del agente. Todo lo que el usuario puede hacer en un tablero, el agente puede hacerlo mediante herramientas: añadir, actualizar y eliminar widgets, organizarlos, gestionar pestañas, cambiar la pestaña visible y acoplar u ocultar el chat.
• Nativo, no incrustado. El tablero se compone de componentes Lit en el shell de la interfaz de control (el mismo sistema de diseño que el resto de la aplicación). Solo el contenido de los widgets está aislado en iframes. No hay barra de URL ni elementos de interfaz del navegador.
• Superficie reducida para el agente. Los widgets se identifican mediante un nombre estable y se actualizan sin sustituirlos. El diseño es una cuadrícula fluida con compactación automática; el agente especifica tamaños y anclajes, nunca píxeles ni coordenadas.
• Capacidades en lugar de confianza. El código de los widgets es HTML/JS arbitrario creado por el agente dentro de un entorno aislado estricto. El acceso (datos del Gateway, acciones y red) solo existe mediante un manifiesto de capacidades declarado y concedido por el operador.

​

Conceptos

​

Flujos de UX

• Promoción: el agente llama a show_widget en cualquier chat → el widget se renderiza en línea en la transcripción exactamente igual que ahora → al pasar el cursor se muestra Fijar en el panel → el widget aparece en el tablero de la sesión. El agente puede pasar pin: true para hacer lo mismo.
• Vista del tablero: una sesión con tablero obtiene un selector de vista (Chat / Panel). Vista del tablero = barra de pestañas (solo cuando hay más de 1 pestaña) + cuadrícula fluida + panel de chat acoplado. El acoplamiento del chat puede cambiar de tamaño y posición (izquierda/derecha/abajo), y se puede contraer exactamente como la barra lateral. El estado de acoplamiento se recuerda para cada pestaña.
• Arrastre: el usuario arrastra los widgets; la cuadrícula se compacta automáticamente (los widgets suben y los elementos vecinos se redistribuyen). El cambio de tamaño mediante el controlador se ajusta a incrementos predefinidos. No se permite la colocación por píxeles, para nadie.
• Advertencia de restablecimiento: /new / /reset en una sesión que contiene un tablero solicita confirmación en la interfaz web («el contexto se restablece, el panel permanece») y conserva el tablero.
• Barra lateral: las sesiones fijadas muestran la vista de su tablero cuando tienen uno. El tablero de la sesión de inicio es el «panel del agente» predeterminado.
• Interacciones (tres niveles, consulte más adelante): eventos de estado silenciosos, envíos visibles de instrucciones y activadores de automatización.

​

Niveles de interacción

1. Eventos de estado (predeterminados). Interacciones con la interfaz del widget que el modelo debe conocer, pero a las que no debe responder. bridge.emitState({...}) añade un aviso estructurado a la sesión (el mismo mecanismo que los avisos de actividad de grupo). No se inicia ningún turno del agente; el modelo ve los avisos acumulados en su siguiente ejecución.
2. Instrucciones (conversación explícita). bridge.sendPrompt(text) — requiere una acción del usuario; envía un mensaje visible del usuario a la sesión (el chat acoplado lo muestra). Tiene limitación de frecuencia; cada envío requiere la confirmación del usuario, salvo que el widget disponga de la concesión de capacidad prompt.
3. Automatización. bridge.runAction(name, args) — ejecuta una acción declarada en el manifiesto. Conjunto inicial de verbos: cron.trigger (ejecutar ahora un trabajo Cron existente) y binding.refresh. Los trabajos Cron ya se ejecutan en sesiones de ejecución visibles y aisladas, y pueden usar un modelo más económico: esa es la vía por la que «un modelo pequeño controla el widget». No hay sesiones ocultas en ningún lugar.

​

Modelo y alojamiento de widgets

• Los widgets en línea (de la transcripción) mantienen el pipeline actual de documentos del lienzo: se escriben en el directorio de estado, los sirve el Gateway, se depuran por ámbito y no requieren aprobación (por diseño, no tienen capacidades; los envíos de instrucciones requieren confirmación del usuario).
• Los widgets del tablero forman parte del estado de la sesión: los bytes se almacenan en la base de datos SQLite del agente propietario (board_widgets) y los sirve una ruta principal del Gateway (/__openclaw__/board/<agentId>/<sessionKey>/<name>/) que lee la base de datos. Al fijar un widget de la transcripción, se copian los bytes. Límites: 256 KB por widget, 48 widgets por tablero.
• Actualización sin sustitución: volver a emitir un widget con el mismo name sustituye los bytes, incrementa revision, difunde board.changed y hace que las vistas activas recarguen únicamente ese iframe.
• Inmovilización de bytes: las capacidades concedidas se vinculan al sha256 de los bytes del widget. Al cambiar los bytes, se conservan las concesiones data/net/actions solo si la nueva revisión declara un subconjunto del manifiesto concedido; un manifiesto ampliado vuelve a solicitar la autorización del operador.

​

Los widgets alojan contenido; las aplicaciones MCP son un tipo de contenido

• html — creado por el agente mediante show_widget, con los bytes almacenados en el tablero.
• mcp-app — una vista de una aplicación MCP de terceros (recurso ui:// de un servidor configurado) alojada dentro de la celda del widget.

• Un único host aislado. Los widgets html se renderizan mediante el mismo pipeline reforzado con el que se publicaron las aplicaciones MCP (doble iframe en el origen aislado dedicado, con CSP declarada por widget, decodificada con cierre en caso de error) en lugar de usar un segundo host de iframe específico. El proxy recibe HTML por valor, por lo que el contenido local es el caso natural.
• Un único modelo de autorización. El acceso de un widget es una lista de permitidos concedida, sea cual sea su tipo: para los widgets html, las herramientas del host; para los widgets mcp-app, las herramientas del servidor visibles para la aplicación (mediante el mecanismo existente allowedAppToolNames, que se hace persistente por widget en lugar de por ejecución de creación).
• Herramientas del host para widgets html (expuestas mediante el puente del widget y verificadas respecto a la concesión):
  • openclaw.prompt.send — nivel 2; se enruta mediante el compositor visible, requiere confirmación del usuario salvo que se haya concedido
  • openclaw.state.emit — avisos de sesión de nivel 1 (agrupados y con límite de tamaño)
  • openclaw.data.read — enlaces parametrizados de solo lectura (conjunto existente de RPC de lectura incluidos en la lista de permitidos), resueltos en el Gateway
  • openclaw.cron.trigger — automatización de nivel 3
• net = CSP. El acceso a la red usa la declaración de CSP por widget ya publicada (orígenes connect-src): el widget meteorológico con actualización automática obtiene su API directamente desde el entorno aislado, sin intervención del Gateway.
• Concesiones. Un widget que no declara nada se renderiza inmediatamente (aislado, default-src 'none', con cada envío de instrucciones confirmado individualmente), con la misma confianza que los widgets en línea de los chats actuales. Las herramientas y los orígenes declarados sitúan el widget en pending en el tablero: una tarjeta de marcador de posición los enumera de forma comprensible y permite Permitir/Rechazar con un solo toque. Las concesiones se asignan por nombre de widget; en los widgets html se inmovilizan según los bytes (sha256), y al cambiar estos se conserva la concesión solo si la declaración se ha reducido.
• Capa de compatibilidad para autores. El contenedor del documento inyecta window.openclaw.sendPrompt/emitState/read/call como API estable para autores; si el transporte subyacente es nuestro canal o AppBridge es un detalle interno que el autor del widget nunca ve. Los informes de tamaño y los tokens de tema se transmiten por el mismo puente.

​

Visualización de transcripciones: una única tarjeta de widget

​

Widgets procedentes del servidor (aplicaciones MCP fijadas)

​

Diseño: cuadrícula fluida

• size: sm (3×3) · md (6×4) · lg (8×6) · xl (12×8) · full (pestaña de un solo widget)
• after: <widgetName> ancla de ordenación opcional; si se omite = añadir al final
• El usuario arrastra y cambia el tamaño libremente; el mismo modelo de orden+tamaño permite una conversión de ida y vuelta.

​

Modelo de datos (base de datos por agente)

CREATE TABLE board_tabs (
  session_key TEXT NOT NULL,
  tab_id      TEXT NOT NULL,           -- slug
  title       TEXT NOT NULL,
  position    INTEGER NOT NULL,
  chat_dock   TEXT NOT NULL DEFAULT 'right',  -- left|right|bottom|hidden
  created_by  TEXT NOT NULL,           -- 'user' | 'agent'
  PRIMARY KEY (session_key, tab_id)
) STRICT;

CREATE TABLE board_widgets (
  session_key  TEXT NOT NULL,
  name         TEXT NOT NULL,          -- stable widget name
  tab_id       TEXT NOT NULL,
  title        TEXT,
  html         BLOB NOT NULL,          -- wrapped document source
  sha256       TEXT NOT NULL,
  revision     INTEGER NOT NULL,
  size_w       INTEGER NOT NULL,
  size_h       INTEGER NOT NULL,
  position     INTEGER NOT NULL,       -- order within tab (auto-compact input)
  manifest     TEXT NOT NULL DEFAULT '{}',  -- capability manifest JSON
  grant_state  TEXT NOT NULL DEFAULT 'none', -- none|pending|granted|rejected
  granted_sha  TEXT,                   -- byte-frozen grant
  created_by   TEXT NOT NULL,
  created_at   INTEGER NOT NULL,
  updated_at   INTEGER NOT NULL,
  PRIMARY KEY (session_key, name)
) STRICT;

​

Superficie del protocolo

• board.get { sessionKey } → pestañas + metadatos de widgets (sin bytes) — operator.read
• board.update { sessionKey, ops[] } — CRUD/reordenación de pestañas, mover/cambiar el tamaño/ eliminar/desfijar widgets, estado del acoplamiento, enfocar pestaña — operator.write
• board.widget.put { sessionKey, name, html, manifest, placement } — operator.write (ruta de la herramienta del agente y ruta de fijación)
• board.widget.grant { sessionKey, name, decision } — operator.approvals
• board.event { sessionKey, widget, payload } — ingesta de eventos de estado de nivel 1 — operator.write

• board.changed { sessionKey, revision, widget? } — cambió el estado persistente; la interfaz vuelve a obtenerlo (y recarga un iframe cuando está presente widget).
• board.command { sessionKey, command } — control transitorio de la interfaz (el agente cambia la pestaña visible, alterna el acoplamiento del chat) — el patrón ui.command.

​

Herramientas del agente

• show_widget { title, widget_code, name?, pin?, size?, tab?, after?, capabilities? } — crear/actualizar por nombre; pin lo coloca en el tablero. Sin name/pin, se comporta exactamente como ahora (insertado, efímero).
• dashboard { action, ... } — verbos de administración del tablero: read, tab_create, tab_update, tab_delete, tabs_reorder, widget_move, widget_remove, unpin, focus_tab, set_chat_dock.
• Las herramientas cron existentes cubren el nivel de automatización; no se necesita una herramienta nueva.

​

Qué reemplaza esto

• Se elimina extensions/workspaces. Experimental, enabledByDefault: false, nunca incluido en una versión estable (apareció por primera vez en las versiones beta 2026.7.2). Sin migración; una regla de doctor elimina <stateDir>/workspaces/ obsoleto si está presente. Ideas aprovechadas: cálculos puros de cuadrícula, modelo de seguridad del puente (inicio del puerto, control de vinculación, límites de frecuencia), aprobación con bytes inmutables.
• El alojamiento de widgets pasa de extensions/canvas al núcleo. El almacén de documentos del lienzo, el contenedor de documentos, el servicio HTTP y la herramienta show_widget pasan al núcleo (src/canvas/); el plugin conserva la herramienta de control node-canvas (canvas) y A2UI. El anuncio pluginSurfaceUrls["canvas"] y las rutas /__openclaw__/canvas son contratos distribuidos de clientes nativos y permanecen estables. Las sesiones de Discord conservan la variante show_widget propiedad de Discord.
• WorkBoard no se modifica (la integración es un programa de seguimiento).

​

Fuera del alcance (este programa)

• Uso compartido del tablero entre varios usuarios/ACL (futuro; llegará mediante el uso compartido de sesiones).
• Renderizado nativo del tablero en macOS/iOS (lo obtienen donde integren la interfaz de control; la ruta de widgets insertados no cambia).
• Widgets de datos integrados (tarjetas de sesiones/uso/cron): el puente de capacidades y los widgets creados por el agente cubren la v1; más adelante puede incorporarse un registro de tipos integrados.
• WorkBoard en el panel.

​

Plan de implementación