画布 - OpenClaw

macOS 应用使用 WKWebView 嵌入了一个由智能体控制的 Canvas 面板，这是一个用于 HTML/CSS/JS、A2UI 和小型交互式 UI 界面的轻量级可视化工作区。

Canvas 的位置

Canvas 状态存储在 Application Support 下：

~/Library/Application Support/OpenClaw/canvas/<session>/...

Canvas 面板通过自定义 URL scheme openclaw-canvas://<session>/<path> 提供这些文件：

openclaw-canvas://main/ -> <canvasRoot>/main/index.html
openclaw-canvas://main/assets/app.css -> <canvasRoot>/main/assets/app.css
openclaw-canvas://main/widgets/todo/ -> <canvasRoot>/main/widgets/todo/index.html

如果根目录中不存在 index.html，应用会显示内置的脚手架页面。

面板行为

无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。
显示 Canvas 不会切换应用或抢占键盘焦点。
按会话记住大小和位置。
本地 Canvas 文件发生变化时自动重新加载。
同一时间只显示一个 Canvas 面板（根据需要切换会话）。

可在 Settings -> Allow Canvas 中禁用 Canvas。禁用后，Canvas 节点命令会返回 CANVAS_DISABLED。

智能体 API 界面

Canvas 通过 Gateway 网关 WebSocket 公开，因此智能体可以显示或隐藏面板、导航到路径或 URL、执行 JavaScript，以及捕获快照图像：

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> "/"
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas snapshot --node <id>

eval 和 a2ui.* 会在不打开或显示面板的情况下更新内容。只有 present、navigate 或用户操作才会显示面板；隐藏后，内容更新仍会继续应用到隐藏的面板。snapshot 需要面板处于可见状态，否则会返回 CANVAS_HIDDEN；请先运行 present。 canvas.navigate 接受本地 Canvas 路径、http(s) URL 和 file:// URL。传入 "/" 会显示本地脚手架或 index.html。 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/ 下由 Gateway 网关托管的目标，会通过节点会话当前的作用域 Canvas URL 进行解析。应用会在导航前刷新这项短期有效的能力；你无需自行构造或复制能力 URL。

Canvas 中的 A2UI

A2UI 由 Gateway 网关 Canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway 网关公布 Canvas 主机时，macOS 应用会在首次打开时自动导航到 A2UI 主机页面。公布的 URL 受能力作用域限制，例如 http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos。应将其视为临时凭据，而不是稳定链接。

A2UI 命令（v0.8）

Canvas 接受 A2UI v0.8 服务器到客户端消息：beginRendering、surfaceUpdate、dataModelUpdate、deleteSurface。目前尚不支持 createSurface（v0.9）。

cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas（A2UI v0.8）"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"如果你能读到这段文字，则表示 A2UI 推送正常工作。"},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2

openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

快速冒烟测试：

openclaw nodes canvas a2ui push --node <id> --text "来自 A2UI 的问候"

从 Canvas 触发智能体运行

Canvas 可以通过 openclaw://agent?... 深层链接触发新的智能体运行：

window.location.href = "openclaw://agent?message=Review%20this%20design";

支持的查询参数：

参数	含义
`message`	预填充的智能体提示词。
`sessionKey`	稳定的会话标识符。
`thinking`	可选的思考配置。
`deliver`、`to`、`channel`	交付目标。
`timeoutSeconds`	可选的运行超时时间。
`key`	应用为受信任的本地调用方生成的安全令牌。

除非提供有效密钥，否则应用会提示确认。无密钥链接会在批准前显示消息和 URL，并忽略交付路由字段；有密钥链接使用正常的 Gateway 网关运行路径。

安全说明

Canvas scheme 会阻止目录遍历；文件必须位于会话根目录下。
本地 Canvas 内容使用自定义 scheme（无需 local loopback 服务器）。
仅在明确导航时才允许外部 http(s) URL。
普通网页仅用于渲染。仅应用所有的 Canvas scheme 或应用选定的、受能力作用域限制且完全匹配的 Gateway 网关 A2UI 文档可以接受智能体操作；子框架、重定向、过期能力和已更改的查询均无法分派操作。

平台概览

macOS 配套应用

画布

Canvas 的位置

面板行为

智能体 API 界面

Canvas 中的 A2UI

A2UI 命令（v0.8）

从 Canvas 触发智能体运行

安全说明

相关内容

​Canvas 的位置

​面板行为

​智能体 API 界面

​Canvas 中的 A2UI

​A2UI 命令（v0.8）

​从 Canvas 触发智能体运行

​安全说明

​相关内容

Canvas 的位置

面板行为

智能体 API 界面

Canvas 中的 A2UI

A2UI 命令（v0.8）

从 Canvas 触发智能体运行

安全说明

相关内容