让 AI 看得见

🎯 核心概念

Canvas 是 macOS 应用内置的AI 控制的可视化面板，基于 WKWebView 实现：

• 轻量级视觉工作空间
• 支持 HTML/CSS/JS 渲染
• 支持 A2UI（AI-to-UI）界面
• 小型交互式 UI 表面

📂 Canvas 存储位置

Canvas 状态存储在应用支持目录下：

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

Canvas 通过自定义 URL scheme 提供文件：

# URL scheme 格式
openclaw-canvas://<session>/<path>

# 示例
openclaw-canvas://main/              → main/index.html
openclaw-canvas://main/assets/app.css → main/assets/app.css
openclaw-canvas://main/widgets/todo/  → main/widgets/todo/index.html

🖥️ 面板行为

• 无边框可调整面板 - 靠近菜单栏或鼠标光标定位
• 记住大小位置 - 每个会话独立记忆
• 自动重载 - 本地 Canvas 文件变化时自动刷新
• 单面板显示 - 一次只能显示一个 Canvas，会话切换时切换

可以在设置中禁用 Canvas：Settings → Allow Canvas

🤖 Agent API

Canvas 通过 Gateway WebSocket 暴露给 Agent：

CLI 命令

# 显示 Canvas 面板
openclaw nodes canvas present --node <id>

# 导航到路径或 URL
openclaw nodes canvas navigate --node <id> --url "/"

# 执行 JavaScript
openclaw nodes canvas eval --node <id> --js "document.title"

# 捕获快照图片
openclaw nodes canvas snapshot --node <id>

注意：

• canvas.navigate 接受本地 Canvas 路径、http(s) URL、file:// URL
• 如果传入 "/"，Canvas 显示本地脚手架或 index.html

🎭 A2UI 在 Canvas 中

A2UI 由 Gateway Canvas 主机托管，在 Canvas 面板中渲染。Gateway 宣示 Canvas 主机后，macOS 应用首次打开时会自动导航到 A2UI 主机页面。

默认 A2UI 主机 URL

http://<gateway-host>:18789/__openclaw__/a2ui/

A2UI 命令 (v0.8)

Canvas 当前支持以下 A2UI v0.8 服务→客户端消息：

• beginRendering - 开始渲染
• surfaceUpdate - 表面更新
• dataModelUpdate - 数据模型更新
• deleteSurface - 删除表面

注意：createSurface (v0.9) 暂不支持

A2UI 推送示例

# 推送 A2UI v0.8 内容
cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
{"surfaceUpdate":{"surfaceId":"main","components":[...]}}
{"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 "Hello from A2UI"

🔗 深度链接触发 Agent

Canvas 可以通过深度链接触发新的 Agent 运行：

# 深度链接格式
openclaw://agent?message=Review%20this%20design

# 在 JavaScript 中使用
window.location.href = "openclaw://agent?message=Review%20this%20design";

应用会提示确认，除非提供了有效的密钥。

💡 使用场景

🔒 安全说明

• Canvas scheme 阻止目录遍历 - 文件必须位于会话根目录下
• 本地 Canvas 内容使用自定义 scheme（无需回环服务器）
• 外部 http(s) URL 仅在明确导航时才允许

🎉 接下来做什么？

继续探索其他有趣的玩法