小组件面板

macOS 应用包含一个原生面板，用于呈现托管 widget 文档。 Canvas 插件负责这一呈现路径。它既不是独立可视化工作区，也不是 A2UI 推送目标。

推荐的代理路径是使用 show_widget 并设置 presentation.target: "node_panel"。OpenClaw 将 widget 存储为托管文档， 选择一台已连接的 macOS 节点，打开面板，并将面板导航到该文档。如果没有可用的 Mac 连接或呈现失败， widget 仍会以内联形式出现在聊天中，工具结果会说明如何重试。

原生面板中的 widget 仅用于渲染。与宿主集成的 widget 操作仍可在 Control UI 聊天和 会话仪表板 界面中使用，而不能在面板中使用。

面板行为¶

• 面板无边框、可调整大小，并锚定在菜单栏或鼠标光标附近。
• 呈现 widget 不会切换应用或夺取键盘焦点。
• 同一时间只显示一个 widget 面板。
• 应用会按会话记住面板的大小和位置。

可以通过 Dashboard → Settings → This Mac → Capabilities 禁用 Canvas。禁用后， 面板命令返回 CANVAS_DISABLED。

代理路径¶

让代理使用 show_widget 并将目标设为节点面板。该工具仅在 widget 呈现插件处于活动状态时暴露 node_panel。

{
  "title": "Build status",
  "widget_code": "<main><h1>Build passed</h1></main>",
  "presentation": { "target": "node_panel" }
}

呈现成功时，结果会标识所选的 Mac。OpenClaw 目前只会选择声明了 canvas.present 的已连接 macOS 节点。

节点命令¶

配对节点的命令面包含三个命令：

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> "/__openclaw__/canvas/documents/<document-id>/index.html"
openclaw nodes canvas hide --node <id>

• canvas.present 显示面板。它也接受现有的可选 target 和 placement 参数。
• canvas.navigate 加载托管 widget 文档路径或应用本地的 Canvas URL。
• canvas.hide 隐藏面板，但不改变其当前文档。

/__openclaw__/canvas/ 下的托管路径通过节点会话当前作用域内的 pluginSurfaceUrls.canvas URL 解析。应用会在导航前刷新该短时能力。调用方应传入文档 路径，而不是构造或复制能力 URL。

应用本地 scheme 仍然可用于应用自有内容：

openclaw-canvas://<session>/<path>

通过该 scheme 寻址的文件必须保持在 Application Support 中该会话的 Canvas 根目录内。 目录遍历会被阻止。

A2UI 属于会话仪表板¶

A2UI widget 在 会话仪表板 上渲染，并与其他仪表板 widget 共享相同的固定、布局、审批和交互模型。其渲染器 bundle 继续从 Gateway 的 /__openclaw__/a2ui/ 资源路由加载。

macOS 面板不接受 A2UI push/reset 命令，也不会自动导航到 A2UI 页面。

从自定义根目录迁移文档¶

运行 openclaw doctor --fix 可将文档从已退役的 plugins.entries.canvas.config.host.root（或更早的 canvasHost.root）移动到 状态目录的 canvas/documents 文件夹。显式插件根目录优先于更早的设置。Doctor 仅在没有任何旧版文档存留后才会移除根设置。如果目录访问或文档复制失败，doctor 会发出警告并保留源定位符以便重试。它可能会将更早的设置移入插件配置，同时保留路径。已经指向规范存储（包括通过符号链接）的根目录无需复制。

修复报告中的权限或目标冲突，然后重新运行该命令。不要自行移除根设置。托管路由仅服务规范文件夹， 因此在迁移完成之前，其余旧版文档不可用。

相关链接¶

• 显示 widget
• 会话仪表板
• macOS 应用
• 节点