跳转至

仪表盘架构

会话仪表盘(Session dashboards)是附加到会话上的持久化组件面板。本参考涵盖其所有权、沙箱与能力边界、存储以及 Gateway 协议。操作员工作流程请参阅会话仪表盘。组件编写 API 请参阅Show widget。

愿景

仪表盘将会话变成工作台:代理渲染交互式组件,用户将它们固定到持久化面板上,面板可以占据主区域或聊天旁的侧面板。聚焦主视图可为其提供完整的任务区域。面板和对话仍然属于同一会话。

原则:

  • 面板属于会话,而不是新的工作空间。 没有固定组件的会话就是普通聊天。固定一个组件后,面板便存在于该会话的 Dashboard 视图中。面板继承会话的身份、代理所有权、命名、固定状态和生命周期。没有 dashboard_create,没有面板注册表,也没有独立的 ACL 模型。
  • 代理对等性。 用户在面板上能做的一切,代理都可以通过工具完成:添加/更新/移除组件、排列组件、管理标签页、切换可见标签页,以及请求分屏或展开呈现。
  • 原生外壳。 面板由 Control UI 外壳中的 Lit 组件构成(与应用其余部分相同的设计系统)。数据报告直接渲染。自定义可执行组件使用沙箱化的 iframe;Browser 仪表盘复用 Browser 面板及其导航控件。
  • 极简的代理接口。 组件通过稳定名称寻址并原地更新。布局是流式的自动压缩网格。代理只描述尺寸和锚点,绝不涉及像素或坐标。
  • 能力胜于信任。 组件代码是代理编写的任意 HTML/JS,运行在强沙箱中。可达范围(gateway 数据、操作、网络)仅通过声明的、由操作员授予的能力清单(capability manifest)存在。

概念

概念 定义
Session (thread) 现有的网关会话,以稳定的 sessionKey 为键,由代理拥有。
Board 一个会话的组件面板。仅当会话具有组件/标签页时才存在。在 /new//reset 后仍然保留(绑定到 sessionKey,而非会话记录)。
Tab 面板的呈现页面:包含哪些组件及其排列方式。面板初始只有一个隐式标签页。
Widget 会话拥有的命名内容单元:原生报告、HTML/JS、MCP App 或插件组件。以 sessionKey + name 寻址。
Capability manifest 每个组件对可达范围的声明:data(读取绑定)、actions(已允许的动词)、prompt(发送到会话)、net(允许的来源)。
Pin (widget) 将会话记录中的组件移到会话面板上(用户操作入口或代理工具参数)。取消固定会将其从面板移除。
Pin (session) 根会话和普通的 Home 关联仪表盘会话可以固定;派生(spawned)、子代理(subagent)和嵌套子会话会拒绝固定请求。子代理运行会出现在会话记录中,但在侧边栏导航之外。打开已固定的会话会恢复该浏览器已保存的任务布局。

用户体验流程

  • 升级流程(Graduation): 代理在支持内联的聊天中调用 show_widget → 组件渲染在会话记录中 → 悬停显示 Pin to dashboard → 组件出现在会话面板上。代理也可以传入 pin: true 达到同样效果。频道演示者也可以让同一核心文档在当前传输通道上可见。
  • 面板视图(Board view): 侧面板中的 Dashboard 打开当前任务的面板,包括其空状态,并且不会编辑聊天草稿。除非已保存任务布局,否则第一个固定的组件会在聊天旁边打开一个可调整大小的仪表盘。任务工具栏的 Swap 按钮交换主视图与活动侧面板内容,包括 Chat、Dashboard、Browser、Terminal、Files 和 Review。其工具提示会指明这两个视图。同一工具栏的 Layout 菜单可将侧面板定位到左侧、右侧或下方。同一工具栏中的 Focus 让主视图获得完整任务区域。Restore split 恢复侧面板。后续面板更新会保留用户当前布局。关闭 Dashboard 标签页仅移除其视图。关闭整个侧面板只是隐藏它,不会改变主视图。
  • 布局所有权(Layout ownership): 浏览器按会话存储布局,包括主视图、活动侧边标签页、泊靠位置、尺寸和聚焦状态。普通的重新访问和画廊(gallery)打开会先应用个人呈现覆盖,再使用共享的会话默认值。带 ?dashboard=expanded 的显式链接会让 Dashboard 成为主视图并在本次访问中聚焦它,且不会创建个人覆盖。布局位置变更会复用已挂载的内容,因此组件框架、浏览器视图、终端和聊天草稿在交换后仍然保留。在左/右布局中,任务工具栏和侧面板标签页标题分别对齐到各自窗格上方;堆叠布局则让每个标题保持在其窗格上方。
  • 导航保留(Navigation retention): 一个已连接的会话页面所有者会在任务导航和访问其他路由期间,为每个窗格保留最多三个最近会话。隐藏页面会让出前台活动、查看者存在状态、焦点和命令。Chat 和 dashboard 的路由加载器与已挂载视图共享相同的 Gateway/认证作用域。连接所有者变更会使两者同时失效,而普通的重新连接会保留它们。后台刷新期间,已缓存的成功路由会继续渲染。
  • 拖拽: 用户拖拽组件。网格自动压缩(组件上浮,相邻组件重新排列)。通过手柄调整大小,并按尺寸档位吸附。任何人都不能进行像素级定位。
  • 重置警告: 对带面板的会话执行 /new / /reset 时,Web UI 会要求确认(“上下文会重置,但仪表盘会保留”),并保留面板。
  • 侧边栏: 打开已固定的会话会恢复其已保存的任务布局。Home 会话的面板是默认的“代理仪表盘(agent dashboard)”。
  • 交互(Interactions)(三个层级,见下文):静默状态事件、可见的提示发送,以及自动化触发。

交互层级

  1. 状态事件(默认)。 Widget UI 交互中,模型应当知晓但无需响应的部分。bridge.emitState({...}) 会追加一条结构化的会话通知(与群组活动通知使用相同机制)。不会启动 agent 回合。模型在下次运行时才会看到累积的通知。
  2. 提示(显式对话)。 bridge.sendPrompt(text) — 需要用户激活,并向所属会话发送一条可见的用户消息。有速率限制。除非 widget 持有 prompt 能力授权,否则每次发送都需要用户确认。
  3. 自动化。 bridge.runAction(name, args) — 触发一个在 manifest 中声明的动作。初始动词集合:cron.trigger(立即运行一个已有的 cron 任务)和 binding.refresh。Cron 任务已经在可见、隔离的运行会话中执行,可以使用更便宜的模型:这就是“小模型驱动 widget”的路径。任何地方都不存在隐藏会话。

Widget 模型与托管

HTML/JS widget 内容由 agent 编写(通常通过 show_widget),封装在标准文档外壳(CSP meta、尺寸上报器、bridge 引导)中,并在不透明源(opaque-origin)的 content iframe 中渲染。在 Control UI 默认的 scripts 嵌入模式中,内联 widget 和看板 widget 均使用下文所述的专用源沙箱代理。

  • 内联(转录)widget 使用 <stateDir>/canvas/documents 下受管理的 Canvas 文档构件,通过经过认证的 canvas.document.view RPC 读取,并按作用域修剪。这些构件与 SQLite 看板存储分离,无需能力审批(它们在构造上就是无能力的——发送提示需要用户手势)。打开内联预览不会创建任何看板状态,也绝不会继承已固定副本的授权。
  • 看板 widget 属于会话状态:字节数据存放在所属 agent 的 SQLite 数据库(board_widgets)中,由读取该数据库的核心网关路由(/__openclaw__/board/<agentId>/<sessionKey>/<name>/)提供。固定一个转录 widget 会复制其字节。上限:每个文档(含外壳)10 MiB 的 UTF-8 HTML,每个已注册 widget 的源代码 256 KiB,每个原生 widget 的 JSON 属性 8 KiB,每个看板 48 个 widget。
  • 原地更新: 以相同的 name 和内容所有者重新发出一个 widget,会替换其内容、递增 revision 并广播 board.changed。实时视图会更新该单元格。文档型 widget 仅重新加载该 iframe。更改内容所有者需要先移除该 widget,然后才能创建替代者。
  • 字节冻结: HTML 和已注册源代码的授权与已审批内容的 SHA-256 摘要绑定。保留授权需要相同的内容作用域、匹配的已审批摘要,以及不会扩大的声明。即使声明保持不变或缩小,字节一旦变化,也需要根据会话的审批策略做出新的决定。

Widgets 承载内容;MCP 应用是其中一种内容类型

widget 是 OpenClaw 的基元:一个具名、可固定、可调整大小、归会话所有且带有授权记录的看板单元格。其内部渲染的内容属于一种内容类型:

  • session:report — 核心拥有的原生数据报告,通过 dashboard 或 show_widget 的结构化 report 字段编写。看板存储保存其有界的 JSON 属性。
  • html — 由 agent 通过 show_widget 编写,字节数据存放在看板存储中。
  • mcp-app — 托管在 widget 单元格内的第三方 MCP 应用视图(来自已配置服务器的 ui:// 资源)。
  • 已注册的插件类型 — 经过插件验证的源代码,通过同一个沙箱化文档框架渲染。Canvas 插件注册了 a2ui。核心会动态发现活动注册表,绝不硬编码插件类型的名称。

MCP 应用并不定义 widget 模型。widget 只是获得了承载它们的能力。身份、位置、固定、授权以及面向作者的 API 仍然属于 OpenClaw——因此 show_widget 代码依然和现在一样简短,也永远不需要知道 MCP Apps 规范的存在。

已注册的类型使用一个小的运行时 Plugin SDK 接缝。一次注册拥有面向 agent 的类型名称、源代码验证、按能力划分作用域的渲染器资源以及文档正文的组装。Gateway 在 board.widget.put 时再次验证源代码,将其存放到现有的通用 plugin 描述符信封中,并且只有在票据化(ticketed)看板读取之后才组装框架文档。这样可以将存储的源代码排除在看板快照之外,并避免数据库 CHECK 约束或 schema 版本变更。被禁用的插件不会出现在注册表中,因此新的 put 会以“启用后重试”的错误失败,而现有单元格则渲染为已禁用状态。

A2UI 实现会组装一个引用其渲染器 bundle 的小型文档。票据化看板文档使用按能力划分作用域的 Gateway 资产路由。内联文档从沙箱源加载同一个公开的静态渲染器。核心会添加与 HTML widget 相同的 CSP、主题桥、尺寸上报器和私有端口主机桥。v0.8 和 v0.9 使用不同的渲染器 bundle,因为它们的 Lit 自定义元素共享标签名,但处理器和动作合约不同。

已注册的类型可以通过 resources.readPublicResource(path) 公开静态渲染器字节。隔离的监听器仅提供精确注册的 resources.paths,仅响应 GET 或 HEAD,并且在读取后会重新检查活动插件注册表。它不会代理 Gateway 路由、凭据或数据。Canvas 为其两个 A2UI bundle 选择加入该机制。这不会授予 widget 任何网络或主机工具能力。

共享托管基础设施:

  • 单一沙箱主机。 html widget 通过 MCP 应用随附的同一加固管道渲染(在专用沙箱源上使用双重 iframe、声明按 widget 的 CSP,并以 fail-closed(失败即关闭)方式解码),而不是第二个定制的 iframe 主机。代理按值接收 HTML,因此本地内容就是天然场景。
  • 经过认证的加载。 受信任的 Control UI 通过现有的 Gateway 连接读取内联 Canvas HTML,并通过其票据化 HTTP 路由读取看板 HTML,然后将字节传递给代理。内容 iframe 绝不会导航到经过认证的文档路由。这样就避免了 iframe 单独登录重定向到拒绝嵌入的页面。
  • 可执行内容的统一授权模型。 widget 的能力范围是一个已授权的白名单。对于 html widget,白名单包含主机工具。对于 mcp-app widget,白名单包含服务器的应用可见工具和同服务器资源(通过现有的实时 App 交互权限,按 widget 持久化,而不是按每次铸造(minting)运行持久化)。
  • 面向 html widget 的主机工具(通过 widget 桥暴露,并根据授权进行检查):
  • openclaw.prompt.send — 第 2 层,经由可见的输入框路由,除非已授权否则需用户确认
  • openclaw.state.emit — 第 1 层会话通知(合并、大小受限)
  • openclaw.data.read — 参数化的只读绑定(现有的白名单只读 RPC 集合),在网关侧解析
  • openclaw.action.run — 第 3 层插件拥有的自动化
  • openclaw.cron.trigger — 第 3 层自动化
  • net = CSP。 网络访问范围使用已随附的按 widget CSP 声明(connect-src 源)——自更新的天气 widget 直接从沙箱请求其 API,无需网关参与。
  • 静态资产。 共享的 widget CDN 白名单允许在文档、代理和直接响应策略中使用公共脚本、样式表和字体。这与 connect-src 和主机工具授权无关。第三方代码以 widget 的内容和已授予的能力运行;资产 URL 不得包含私有数据。参见库和字体。
  • 授权。 未声明任何内容的 HTML 和已注册 widget 会立即渲染(沙箱化、default-src 'none'、提示发送需逐一确认)。声明的能力和交互式 MCP App 遵循明确的会话权限模式。完全访问予以授权。工作区使用 AI 审查者,拒绝任何其不允许的内容。受保护显示允许/拒绝。只读予以拒绝。如果没有显式的会话模式,则应用等效的已配置执行审批策略。授权按 widget 名称和内容作用域划分。HTML 和已注册源代码的更新仅在已审批摘要匹配且声明不扩大的情况下保留授权。由外壳编写的看板 widget 会将用户点击的 http/https 新标签页链接转发给 Control UI 主机。这种普通导航不需要授权,也绝不会授予 iframe 弹窗权限。
  • 编写垫片(Authoring shim)。 文档外壳会注入 window.openclaw.prompt、window.openclaw.state、window.openclaw.data、window.openclaw.action、window.openclaw.cron 以及主机提供的 window.openclaw.host.controlUiBaseUrl,作为稳定的作者 API。Dashboard 调用和受信任的新标签页链接点击共享同一个绑定视图票据的请求通道。主机使用 noopener,noreferrer 打开链接。尺寸上报和主题令牌仍然是独立的主机通知。

外部代理运行在与 Control UI 和 Gateway 都不同的源上。其 iframe 允许 allow-same-origin,因此宿主可以针对该专用源对代理消息进行身份验证。代理将小部件字节放入内部 srcdoc iframe,启用 allow-scripts allow-forms,但不启用 allow-same-origin。因此,小部件代码既没有应用源的访问权限,也没有代理源的访问权限。内联视图仅采用包装器的私有提示通道。仪表板视图初始化各自独立的、绑定票据的桥接。

公共代理外壳使用其 HTML 和安全头的 URL 指纹。浏览器可以缓存该精确版本,以便重复挂载小部件时使用;更改外壳或其策略会更改 URL。未版本化或不匹配的请求不会被缓存。此缓存不包含小部件文档、凭据或视图票据。

共享加载器在沙箱代理启动时获取板 HTML,并仅在该精确代理报告就绪后才交付它。仪表板小部件会保留主题化的加载占位符,直到代理确认当前内部文档已加载。此渲染信号与 HTML 交付和桥接初始化分开,因此空小部件可以完成加载而不报告正的内容高度。聚焦的仪表板路由会重用已解析的会话密钥和代理所有者,以避免第二次会话查找。

已挂载的小部件在演示更改和票据续期期间保留其已加载的文档。内联视图仅在一个客户端和连接代次内共享对同一文档的并发读取。每个视图仍然拥有自己的沙箱和提示通道。

受管理的 [embed ref="..."] 预览在其有效沙箱策略允许脚本时使用该已认证路径,包括没有显式沙箱字段的默认情况。显式严格预览保持无脚本。

没有已完成文档的缓存:Canvas 允许替换命名文档 ID,因此重新挂载会再次读取当前源。瞬时断开连接会保留已挂载的内联 iframe 及其本地交互状态,但会废弃来自先前连接的待处理结果和服务器操作权限。重新连接会重新验证文档:未更改的字节保留框架,而更改的内容或身份会替换该框架。这是内存中的演示保留,而不是持久化的文档缓存或重放小部件操作的权限。

网站小部件

session:website 使用带有经过验证的 props: { url } 的现有原生小部件描述符。板存储负责持久化、修订、同名更新和删除;无需更改模式、协议方法或配置。较旧的渲染器对此未知类型显示普通的不可用小部件状态。

Control UI 在其自己的沙箱框架中渲染 HTTPS 网站,启用脚本、同源网站存储、表单和弹出窗口。它拒绝包含用户信息的 URL,并拒绝 Control UI 和已连接 Gateway 的主机名跨端口使用,因为浏览器 cookie 共享主机名边界。OpenClaw 不注入 Gateway 令牌、能力票据、消息桥接或父级导航权限。其自身的 HTTP 头和浏览器 cookie 规则仍然适用。Gateway 从不获取或中继其内容。被动图库预览从不挂载该框架。

网站小部件不使用 HTML 文档沙箱或其能力授权。该所有者继续阻止后代框架。全宽网站可以填满现有的展开仪表板;共享网格保持其常规尺寸。参见 全屏显示网站。

Browser 仪表板

Browser 插件向具有 Browser 访问权限的操作者通告 browser:dashboard。其保存的 props 包含 HTTP(S) URL 和可选的本地托管配置文件。原生渲染器重用 Browser 面板的流式视口和输入路径,并固定到仪表板的精确浏览器目标。普通的 Browser 预览结果不会替换此仪表板演示。

板拥有定义和插入标识。原生插件小部件在现有清单元数据中存储内部生成的 pluginInstanceId,并将其作为可选的 instanceId 字段公开。同一所有者的更新会保留它;删除/重新创建会轮换它。较旧的原生行在下次 put 时接收标识,且没有读取时回填。文档小部件保留其现有的每次 put 视图和授权代次;这些是不同的生命周期。

Browser 在其现有的 browser.session-tabs SQLite 命名空间中拥有选项卡关联和停止状态,包括用于安全清理的浏览器/配置文件指纹。并发视图和代理调用共享同一板实例的物化。在首次打开之前停止会在同一存储中持久化已键入的意图,没有浏览器目标或指纹;它在重新加载后仍然存在,并在成功 Resume 或定义移除后退役。调用在行动前解析当前定义,并通过现有的浏览器路由/配置文件准入重新验证关联。仅保存的目标 ID 本身不构成权限。

现有的 browser.request 传输为 Control UI 请求携带仪表板标识。面向模型的 browser 工具接受小部件名称作为 dashboard;dashboard 仍然是板的创作/布局工具。Stop 和 Resume 更新 Browser 的生命周期状态,而不重写板 props 或覆盖并发的定义编辑。UI 卸载仅释放流。Browser 通过其现有的插件事件服务发布生命周期失效通知,因此代理的 Stop/Resume 会更新可见的仪表板。板更改和会话删除通知请求协调;当普通空闲清理被禁用时,现有的清理周期也会协调已移除/替换的定义。对话重置保留板及其有效的选项卡关联。

原生数据报告

session:report 是一种已通告的核心小部件类型。其经过验证的 props 包含文本、指标、表格、条形图或折线图以及 HTTP(S) 链接。Control UI 直接从板快照渲染这些块,无需文档获取、iframe、能力票据或小部件桥接。此纯渲染器也可以出现在被动仪表板图库预览中。该例外不会在预览中启用任意的原生插件小部件。

两种创作路径都使用 src/boards/board-report.ts 中的同一个验证器:

  • dashboard: action: "widget_put", pluginKind: "session:report", props: report.
  • show_widget: report: { blocks: [...] }, pin: true. 省略 kind 和 widget_code。

该报告使用现有的通用 plugin 描述符和 JSON props 存储。没有新的存储模式或协议方法。其完整 JSON 上限为 8KB 和 24 个块。报告不接受任何能力、可执行操作、HTML、CSS、媒体、网络读取或 RPC。show_widget 报告模式仅限仪表盘,不支持内联、设备面板或频道展示。其结构化的 report 字段不能与 kind、widget_code、capabilities 或设备展示混用。现有的 source-kind 枚举和插件注册保持不变。

同名报告更新保留 session:report 内容所有者。转换 HTML widget 需要先显式移除再创建,没有自动迁移。对于固定的数据摘要,优先使用报告。将 HTML 用于任意交互或内联内容。请参阅 报告模式与示例。

插件能力声明

已启用的插件可以通过 openclaw.plugin.json 中的 dashboard.dataBindings 和 dashboard.actionVerbs 扩展 widget 宿主。插件本地 id 会成为以插件 id 为前缀的授权名称,例如 workboard.cards.list 和 workboard.dispatch。插件 id 段中的 % 和 . 会被转义,因此不同的插件/本地 id 拆分无法继承相同的持久化授权。在插件注册期间,OpenClaw 会验证每个绑定是否指向由同一插件以 operator.read 注册的 RPC,以及每个操作是否指向以 operator.write 注册的 RPC。无效的声明会导致插件加载失败。验证后的注册表仅在插件生命周期变化时重建,而 widget 授权仍然是每个 widget 独立的,并受字节和修订版本约束。

show_widget 使用这个经过验证的活动注册表进行有界作者发现,包括可用的完整描述和操作参数模式。它绝不会仅仅为了描述插件的仪表盘能力而加载插件。

认证的 GitHub 读取

Core 现有的 GitHub 身份和 HTTP 所有者通过 board.data.read 提供 github.actions.runs。封闭的参数契约只会构造 api.github.com 上的仓库或工作流运行列表操作。即使项目发现使用配置的 Enterprise 主机,凭据选择和传输仍然绑定到 github.com。Enterprise 凭据绝不会用于此公共主机能力。授权需要精确的规范化 github.actions.runs:<owner>/<repo> 工具授权。网络来源的授权绝不提供 GitHub 身份权限。批准会披露:Actions 元数据(包括 agent 可访问的私有仓库数据)将与 widget/会话受众共享。

作者指导以可用的已连接 agent 身份为条件,而非工具构建时的检查。board.widget.put 在保存 HTML(包括物化的 Canvas 文档)或声明此宿主能力的已注册 widget 之前,会验证并重新验证该身份。同一个准备所有者同时服务于固定(pinning)和读取,包括源配置预览凭据清理和 OAuth 刷新。在持久化之前,会重新检查调用方取消和会话变更授权。失败时,现有内容和授权保持完好。MCP App 工具名称使用各自的契约,不会触发此预检。

该 board 能力所有者在内部持有规范的 agent/会话,并会在数据和操作路径的跨异步等待(await)过程中重新检查实时 Gateway、票据生成、widget 修订版和授权。GitHub 使用现有的凭据所有者和 OAuth 刷新服务来选择 agent 覆盖、System 或本机身份。读取权限在获取之前和返回数据之前还会重新验证选择和凭据轮换。本机 gh auth token 读取可以在最多 60 秒内重用成功的查找结果,因此主机登录、注销和账户切换可能需要这么长时间才能生效。环境令牌、托管凭据和调用方权限保持实时检查。这不会改变个人发布代理(broker)或其已接受的凭据快照语义。

认证读取绝不使用预览认证或匿名重试。拒绝重定向。只有此 Actions 读取允许最多 1 MiB 的上游主体。其他 GitHub JSON 调用者保持其 256 KiB 默认值。所有者验证并将最多 30 个运行投影到一个小型响应中,不包含原始仓库对象或机密。Gateway 本地缓存最多保存 32 个成功结果,持续 30 秒。最多 32 个并发调用者可以准备或等待读取。共享传输层仅在其捕获的凭据范围内缓存已验证的投影。此内部缓存写入并非向 widget 的投递。每个调用者,包括发起者、后续调用者以及缓存命中者,都会在投递前重新验证自己的实时权限。移除一个调用者不会使另一个授权调用者的结果失效,失败的传输读取也不会被缓存为成功。请参阅 作者契约与示例。

建模残留:WebRTC 数据通道

沙箱 CSP 会输出提议的 webrtc 'block' 指令,但 Chromium 当前的 CSP 指令集 并未实现该指令。因此,可脚本化 widget 可以使用 WebRTC 数据通道进行出口通信,而 CSP 不会强制执行该指令。此残留也适用于内联聊天 widget 和 MCP Apps 宿主。

已接受的权衡: OpenClaw 不会因这一残留而限制可脚本化 widget。Widget 内容只能通过策略授予的、字节冻结的数据绑定来访问敏感的 OpenClaw 数据,并且沙箱 Permissions Policy 会阻止摄像头和麦克风访问。

内联组件和看板组件在组件代码运行之前启用 DOM API 防护。该防护移除同一 realm 的 WebRTC 构造函数,并阻止了创建带有新构造函数的后代浏览上下文的常见方式。这降低了暴露面,但仍属于尽力而为的纵深防御,而非隔离或授权边界。它并未消除已接受的残余风险。该防护在 src/agents/sandbox-host.ts 中实现,并由 Canvas 和看板视图所有者启用。

对话记录展示:单个组件卡片

内联 HTML 和 MCP App 预览共享一个组件卡片渲染器,该渲染器根据内容类型进行分发。符合条件的预览暴露相同的固定到仪表盘操作。生成的组件名称让卡片能够识别已有的固定项,避免重复提供。渲染器和固定路径位于 ui/src/pages/chat/components/widget-card.ts。

组件通过网格邻接进行组合:代理编写的组件和 MCP App 可以占据同一个标签页上的相邻单元格。每个组件保持自己的沙箱和桥接身份。MCP App 不得在代理编写的 iframe 内渲染,因为嵌套会破坏桥接身份,并允许覆盖层叠加在已授权的应用 UI 之上。

服务器来源组件(固定的 MCP 应用){#server-sourced-widgets-pinned-mcp-apps}

通过统一的主机,固定第三方 MCP 应用只是一个组件,其内容从服务器获取而非存储:board_widgets 保存描述符(serverName、toolName、uiResourceUri、来源 toolCallId + sessionKey)而非 HTML 字节,并且看板会在聊天轮次的 10 分钟 TTL 之后重新铸造视图租约(在过期时重新获取 ui:// 资源)。聊天内联 MCP 应用视图与代理组件具有相同的固定到仪表盘操作。按设计,重新打开的视图目前是只读的。

需要保持交互性的固定应用会获得对服务器上应用可见工具的持久授权(固定时向操作员显示明确的允许列表),与铸造运行解耦。未获授权的固定项可以渲染其获取到的 App HTML,但无法调用工具或访问同服务器资源桥接。固定项属于来源会话的看板。不支持跨会话固定。

WorkBoard 集成

WorkBoard 集成方案保持卡片和看板由插件拥有。它通过现有的 sessionKey 和 runId 将分发的卡片拼接回其会话看板。它通过插件声明的绑定和操作暴露 WorkBoard 数据流和分发。它将这些结果与现有的 html 和 mcp-app 组件种类组合,而不是引入 WorkBoard 特定的组件类型。

布局:流式网格

12 列,固定行高,自动压缩(拖动时向上聚集、向旁推开——gridstack 语义,原生实现)。网格计算保持纯粹且与 DOM 无关。每个标签页的组件布局状态:{ name, w (1-12), h (rows) } 以及顺序。

代理词汇表:

  • size:sm(3×3)· md(6×4)· lg(8×6)· xl(12×8)· full(单组件标签页)
  • after: <widgetName> 可选的排序锚点。省略 = 追加到末尾
  • 用户可自由拖拽/调整大小。相同的顺序+大小模型可往返传输。

数据模型(每代理数据库){#data-model-per-agent-db}

看板状态位于 agents/<agentId>/agent/openclaw-agent.sqlite:

  • board_tabs 存储标签页身份、排序、聊天停靠区和看板修订版本。
  • board_widgets 存储组件身份、放置位置、内容或描述符、能力声明、已批准的摘要以及授权状态。

权威表定义、约束和索引位于 src/state/openclaw-agent-schema.sql。看板模式的确保/修复路径是 src/state/openclaw-agent-board-schema.ts。运行时读写由 src/boards/sqlite-board-store.ts 拥有。参见 数据库模式 了解模式版本、迁移和降级规则,以及重大存储变更的审查检查点。不要使用复制的 SQL 草稿作为模式契约。

普通磁盘快照和组件文档读取使用现有的会话历史读取工作器。变更操作借用权威的每代理 SQLite 写入者连接,看板后端在事务入口和提交时检查当前调用者权限。已提交的变更会在变更返回之前使主机的精确会话投影失效;清理失败不会将已完成的写入变成可重试的失败。现有会话写入预检、源句柄获取、模式/引导/迁移以及看板存在性投影保留其现有的所有者。读取在等待之前捕获其物理存储,并加入与写入相同的每代理 FIFO。读取工作器保留其已接纳的只读连接,并读取一个一致的快照,而不会创建缺失的看板表或打开写入者发布。主机在开始消费和释放队列之前检查捕获的物理身份、原生变更见证和当前权限。外部消费者 Promise 的运行不持有该队列,因此排队的撤销不会被后续受保护的发布超越。网关关闭会拒绝新请求,并在工作器拆除之前加入已接受的读取和发布清理。隐身读取和写入在其进程持有的连接上继续。工作器从不拥有第二个代理数据库参与者,这一调整不改变任何看板模式、保留策略、更新行为或协议负载。

看板存在 = 该 sessionKey 有任意行。删除会话会删除其看板行。/new//reset 不会触及它们。

协议面

RPC(核心方法表,gateway-protocol 中的 typebox 模式):

  • canvas.document.preview { html } → 返回未更改的调用者拥有的 HTML,以及与 canvas.document.view 相同的隔离沙箱连接元数据 — operator.read。它最多接受 2 MiB 的 UTF-8 数据(包括空 HTML),拒绝多余字段,并且从不读取或创建已存储的文档。它遵循 Canvas 主机禁用设置,不返回能力票据或提示/工具/主机访问权限。文件标签页客户端使用默认的 SandboxHost 策略并阻止后代框架,而非应用源活动 srcdoc 或 Canvas 组件提示/API 桥接。
  • canvas.document.view { docId } → HTML 和沙箱连接元数据 — operator.read。它接受最大 2 MiB 的受管理、启用脚本的 Canvas 文档,不创建任何看板状态,不返回能力票据。
  • board.get { sessionKey } → 标签页 + 组件元数据和原生属性(无文档字节)— operator.read
  • board.update { sessionKey, ops[] } — 标签页增删改查/重排、组件移动/调整大小/移除/取消固定、停靠状态、聚焦标签页 — operator.write
  • board.widget.put { sessionKey, name, content, declared?, placement? } — operator.write(代理工具路径和固定路径)
  • board.widget.grant { sessionKey, name, decision } — operator.approvals
  • board.event { ticket, payload } — 绑定票据的一级状态事件接收。旧版受信任主机的 { sessionKey, widget, payload } 格式保留 — operator.write
  • board.prompt.authorize { ticket } — 返回可见的提示发送是否仍需要逐次点击确认 — operator.read
  • board.data.read { ticket, bindingId, params? } — 网关侧允许列表内的核心或活动插件读取绑定解析 — operator.read
  • board.action { ticket, action, ... } — 通过现有 cron 立即运行路径或活动插件的已验证动作动词进行精确授权自动化分发 — operator.write

事件(在 EVENT_SCOPE_GUARDS 中,读取范围):

  • board.changed { sessionKey, revision, widget? } — 持久化状态已更改。 UI 会重新获取数据(当存在 widget 时还会重新加载一个 iframe)。
  • board.command { sessionKey, command } — 瞬态 UI 驱动(代理切换 可见标签页或仪表盘面板展示)— 即 ui.command 模式。

看板 widget 字节使用已认证的 HTTP 表面。内联 Canvas widget 字节使用 canvas.document.view。原生客户端和直接打开文档继续使用 现有的 Canvas HTTP 路由。

代理工具

核心共有三个工具。show_widget 面向以下场景暴露:inline-widgets 客户端、与当前频道唯一匹配的呈现器,或持久会话自动化 (其服务器编写的工具策略明确允许仅固定式创建):

  • show_widget { title, widget_code?, report?, kind?, name?, pin?, size?, tab?, after?, presentation?, capabilities? } — 按名称创建/更新。kind 默认为 html,其枚举 包含已注册的活动种类。HTML 和已注册源使用 widget_code。 原生报告使用 report,不提供 kind 或 widget_code,要求 pin: true, 并且仅在看板上渲染。对于 HTML 和已注册种类,pin 也会将 widget 放置到看板。 如果未提供 name/pin,其行为与现在完全一致(内联、临时)。 无头定时创建要求 pin: true,不能选择展示目标, 并且对分离的 cron-run 会话不可用。
  • dashboard { action, ... } — 看板管理操作:read、tab_create、 tab_update、tab_delete、tabs_reorder、widget_put、widget_move、 widget_resize、widget_remove、focus_tab、set_presentation、 set_default_presentation。共享的 boardPresentation 默认值属于 会话元数据(session_nodes.entry_json),而非看板布局状态。UI 和 代理写入使用 sessions.patch;现有的会话读取/更改投影、 权限、重置保留和删除机制负责其生命周期。浏览器布局 会单独缓存展示设置,与明确的个人覆盖区分开。共享更改 在下一次打开仪表盘时生效,不会影响当前正在查看的用户。 展示方式为 split 或 expanded。expanded 使仪表盘成为主视图并聚焦; 而 split 使用当前布局显示仪表盘,并在仪表盘为主视图时将聊天并排显示。 Control UI 拥有侧面板的停靠位置。该工具将展示方式映射到现有的 set_chat_dock 线协议命令,而不更改 Gateway 协议。
  • 现有的 automations 工具覆盖自动化层。无需新工具。

工具描述会说明尺寸/锚点词汇和分层模型。代理通过会话通知获知用户的 tier-1 事件,例如 [dashboard] user clicked "Refresh" on widget weather (tab main)。

此更改取代的内容

  • extensions/workspaces 已删除。 实验性功能,enabledByDefault: false,从未进入稳定版(首次出现在 2026.7.2 beta 版本)。无需 迁移。doctor 规则会清除残留的 <stateDir>/workspaces/(如果存在)。 从中提取的想法:纯网格数学、桥接安全模型(端口引导、 绑定门控、速率限制)、字节冻结审批。
  • 核心负责承载 widget。 Canvas 文档存储、文档包装器、HTTP 服务以及 show_widget 工具位于核心(src/canvas/)。Canvas 插件拥有 macOS 节点面板呈现器和 A2UI 仪表盘内容种类。pluginSurfaceUrls["canvas"] 广告和 /__openclaw__/canvas 路径是已发布的原生客户端契约,并保持 稳定。Discord Activities 在核心的规范 show_widget 工具背后注册上下文呈现器。

当前边界

  • 看板不引入单独的共享或 ACL 模型。会话可见性和成员资格 使用现有的会话共享表面。Widget 能力授权仍然与成员资格分开。
  • 原生 macOS/iOS 看板渲染通过嵌入式 Control UI 完成。内联 widget 路径保持不变。
  • 已启用的插件通过现有注册表扩展内容种类、数据绑定和操作动词。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw