仪表盘架构

​

远景

• 画板是会话的一种视图，而不是一个新对象。 每个会话（线程）都有两个视图：对话记录和画板。没有固定小部件的会话就是普通聊天。固定一个小部件后，画板就存在了。画板继承会话的身份、智能体所有权、命名、固定状态和生命周期。没有 dashboard_create，没有画板注册表，也没有单独的 ACL 模型。
• 智能体对等。 用户在画板上能做的一切，智能体都可以通过工具做到：添加/更新/移除小部件、排列它们、管理标签页、切换可见标签页、停靠或隐藏聊天。
• 原生，而非嵌入式。 画板是 Control UI 外壳中的 Lit 组件（与应用其余部分使用相同的设计系统）。只有小部件的_内容_被隔离在 iframe 中。没有地址栏，没有浏览器外壳。
• 小型智能体表面。 小部件通过稳定名称寻址并就地更新。布局是一个流式自动紧凑网格；智能体只描述尺寸和锚点，从不使用像素或坐标。
• 以能力而非信任为基础。 小部件代码是任意的、由智能体编写的 HTML/JS，运行在强沙箱中。访问范围（网关数据、动作、网络）仅通过声明式、由操作者授予的能力清单存在。

​

概念

​

UX 流程

• 完成流程： agent 在任意聊天中调用 show_widget → widget 以内联方式渲染在 transcript 中，与现在完全一致 → 悬停时显示 固定到仪表板 → widget 出现在该会话的面板中。agent 也可以传入 pin: true 来执行相同操作。
• **面板视图：**拥有面板的会话会获得视图切换选项（聊天 / 分栏 / 仪表板）。分栏视图 = 标签页栏（仅在标签页数 >1 时显示）+ 流式网格 + 停靠的聊天 窗格；仪表板视图则相同，但不包含聊天。聊天停靠窗格可调整大小，也可通过切换器的停靠位置选择器移动到（左侧 / 右侧 / 底部）。 每个标签页的停靠状态都会被记住。
• **拖拽：**用户拖拽 widget；网格会自动紧凑排列（widget 向上浮动，邻近元素重新布局）。通过控制柄调整大小时会吸附到尺寸步长。不允许任何人进行像素级定位。
• **重置警告：**在拥有面板的会话中执行 /new / /reset 时，Web UI 会请求确认（“上下文将被重置，仪表板会保留”），并保留面板。
• **侧边栏：**已固定的会话在拥有面板时显示其面板缩略视图。 Home 会话的面板是默认的“agent 仪表板”。
• 交互（分为三个层级，见下文）：静默状态事件、可见的提示发送，以及自动化触发器。

​

交互层级

1. 状态事件（默认）。 模型应该知道但不需要回应的小部件 UI 交互。bridge.emitState({...}) 会追加一条结构化的会话通知（与群组活动通知使用相同机制）。不会启动新的 agent 回合；模型会在下一次运行时看到累积的通知。
2. 提示（显式对话）。 bridge.sendPrompt(text) — 需要用户激活；向会话发送一条可见的用户消息（停靠的聊天窗口会显示它）。有速率限制；每次发送都需要用户确认，除非小部件持有 prompt 能力授权。
3. 自动化。 bridge.runAction(name, args) — 触发一个在清单中声明的动作。初始动词集合：cron.trigger（立即运行现有的 cron 作业）和 binding.refresh。Cron 作业已经在可见、隔离的运行会话中执行，并且可以使用更便宜的模型：这就是“小模型驱动小部件”的路径。任何地方都没有隐藏会话。

​

Widget 模型与托管

• 内联（transcript）widget 保持当前的 canvas-document 管线： 写入状态目录，由 gateway 提供服务，按作用域清理，无需审批（它们从构造上就是无能力的——prompt 发送由用户确认）。
• Board widget 是会话状态：字节内容保存在所属 agent 的 SQLite DB（board_widgets）中，由一个核心 gateway 路由提供服务 （/__openclaw__/board/<agentId>/<sessionKey>/<name>/），该路由读取 DB。 将 transcript widget 固定会复制这些字节。容量上限：每个 widget 256 KB， 每个 board 48 个 widget。
• 原地更新： 以相同 name 重新发出一个 widget 会替换这些字节， 提升 revision，广播 board.changed，并且只会让活动视图重新加载那个 iframe。
• 字节冻结： 授予的能力绑定到 widget 字节的 sha256。变更字节后，只有在新 revision 声明的 manifest 是已授予 manifest 的子集时，才保留 data/net/actions 授权；一旦 manifest 扩大，则会重新提示操作者。

​

Widget 承载内容；MCP 应用只是内容的一种

• html — 由 agent 通过 show_widget 编写，字节存放在 board 存储中。
• mcp-app — 第三方 MCP 应用视图（来自已配置服务器的 ui:// 资源），托管在 widget 单元内部。

• 一个沙箱主机。 html widget 通过 MCP 应用已经发布的同一套加固管线渲染 （在专用沙箱 origin 上的双 iframe、每个 widget 声明的 CSP、以及失败即关闭的解码）， 而不是再造一套专门的 iframe 主机。代理按值接收 HTML，因此本地内容是自然场景。
• 一个授权模型。 无论 widget 类型如何，它的可达范围都是一份已授予的 allowlist： 对于 html widget，是主机工具；对于 mcp-app widget，是服务器对应用可见的工具 （通过现有的 allowedAppToolNames 机制实现，并改为按 widget 持久化，而不是按一次 mint 运行持久化）。
• html widget 的主机工具（通过 widget bridge 暴露，并按授权校验）：
  • openclaw.prompt.send — tier 2；通过可见的 composer 转发，除非已授权否则需要用户确认
  • openclaw.state.emit — tier 1 会话通知（合并、限制大小）
  • openclaw.data.read — 参数化只读绑定（现有的允许列表 read RPC 集），在 gateway 侧解析
  • openclaw.cron.trigger — tier 3 自动化
• net = CSP。 网络可达性使用已经发布的每个 widget 的 CSP 声明 （connect-src origins）——这个会自动更新的天气 widget 直接从沙箱中获取其 API， 不需要 gateway 介入。
• 授权。 未声明任何内容的 widget 会立即渲染（已沙箱化， default-src 'none'，逐条确认 prompt 发送）——与今天的内联聊天 widget 的信任等级相同。 声明了工具/origin 的 widget 会在 board 上进入 pending：一个占位卡片会以人类可读的方式列出这些内容，并提供一键 允许/拒绝。 授权按 widget 名称生效；对于 html widget，它们是字节冻结的（sha256），而变更后的字节只有在声明缩小的情况下才保留授权。
• 作者包装层。 文档外壳注入 window.openclaw.prompt、window.openclaw.state、 window.openclaw.data 和 window.openclaw.cron，作为稳定的作者 API。Dashboard 调用共享一条以 view-ticket 绑定的请求通道；尺寸上报和主题 token 仍然作为单独的主机通知存在。

​

插件能力声明

​

建模残留：WebRTC 数据通道

​

Transcript 展示：一个 widget 卡片

​

服务端来源的 widget（固定的 MCP 应用）

​

WorkBoard 集成

​

布局：流式网格

• size: sm（3×3）· md（6×4）· lg（8×6）· xl（12×8）· full （单组件标签页）
• after: <widgetName> 可选的排序锚点；省略 = 追加
• 用户可自由拖拽/调整大小；相同的顺序+尺寸模型可往返保持一致。

​

数据模型（每个代理的数据库）

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',  -- 左侧|右侧|底部|隐藏
  created_by  TEXT NOT NULL,           -- '用户' | '代理'
  PRIMARY KEY (session_key, tab_id)
) STRICT;

CREATE TABLE board_widgets (
  session_key  TEXT NOT NULL,
  name         TEXT NOT NULL,          -- 稳定的组件名称
  tab_id       TEXT NOT NULL,
  title        TEXT,
  html         BLOB NOT NULL,          -- 包装后的文档源代码
  sha256       TEXT NOT NULL,
  revision     INTEGER NOT NULL,
  size_w       INTEGER NOT NULL,
  size_h       INTEGER NOT NULL,
  position     INTEGER NOT NULL,       -- 标签页内的顺序（自动压缩输入）
  manifest     TEXT NOT NULL DEFAULT '{}',  -- 能力清单 JSON
  grant_state  TEXT NOT NULL DEFAULT 'none', -- 无|待处理|已授予|已拒绝
  granted_sha  TEXT,                   -- 字节冻结的授权
  created_by   TEXT NOT NULL,
  created_at   INTEGER NOT NULL,
  updated_at   INTEGER NOT NULL,
  PRIMARY KEY (session_key, name)
) STRICT;

​

协议表面

• board.get { sessionKey } → 标签页 + 小部件元数据（不含字节）— operator.read
• board.update { sessionKey, ops[] } — 标签页 CRUD/重排、小部件移动/调整大小/ 移除/取消固定、停靠状态、聚焦标签页 — operator.write
• board.widget.put { sessionKey, name, html, manifest, placement } — operator.write（代理工具路径和固定路径）
• board.widget.grant { sessionKey, name, decision } — operator.approvals
• board.event { ticket, payload } — 绑定 ticket 的一级状态事件接收； 旧的受信任主机 { sessionKey, widget, payload } 形状仍然保留 — operator.write
• board.prompt.authorize { ticket } — 返回可见提示发送是否 仍需要每次点击确认 — operator.read
• board.data.read { ticket, bindingId, params? } — 网关侧白名单化的 核心或活动插件读取绑定解析 — operator.read
• board.action { ticket, action, ... } — 通过现有的 cron 立即运行路径或活动插件已验证的 action 动词进行精确授权自动化分发 — operator.write

• board.changed { sessionKey, revision, widget? } — 持久化状态已更改； UI 重新拉取（当存在 widget 时也会重载一个 iframe）。
• board.command { sessionKey, command } — 临时 UI 驱动（代理切换 可见标签页，切换聊天停靠栏）— ui.command 模式。

​

代理工具

• show_widget { title, widget_code, name?, pin?, size?, tab?, after?, capabilities? } — 按名称创建/更新；pin 将其放置到面板上。 不使用 name/pin 时，其行为与当前完全一致（内嵌、临时）。
• dashboard { action, ... } — 面板管理操作：read、tab_create、 tab_update、tab_delete、tabs_reorder、widget_move、widget_remove、 unpin、focus_tab、set_chat_dock。
• 现有的 automations 工具负责自动化层；无需新增工具。

​

这替代了什么

• extensions/workspaces 已删除。 该功能具有实验性，enabledByDefault: false，从未进入稳定版本（最早出现在 2026.7.2 beta 版中）。无需迁移；如果存在，doctor 规则会移除过时的 <stateDir>/workspaces/。 吸收的想法：纯网格数学、桥接安全模型（端口引导、绑定门控、速率限制）、字节冻结审批。
• 小部件托管从 extensions/canvas 迁移到核心。 canvas 文档存储、文档包装器、HTTP 提供，以及 show_widget 工具都成为核心（src/canvas/）；插件保留 node-canvas 控制工具（canvas）和 A2UI。pluginSurfaceUrls["canvas"] 公告和 /__openclaw__/canvas 路径是原生客户端合同的一部分并保持稳定。Discord 会话继续保留 Discord 自有的 show_widget 变体。

​

非目标（本项目）

• 多用户看板共享/ACL（未来；将通过会话共享实现）。
• 原生 macOS/iOS 看板渲染（它们在嵌入 Control UI 的任何地方都会获得该能力；内联组件路径保持不变）。
• 内置数据组件（会话/用量/cron 卡片）——能力桥接加上代理编写的组件已覆盖 v1；内置类型注册表可以后续再加入。

​

实施计划