Canvas 是 macOS 应用中由智能体控制的轻量级可视化工作区,用于展示 HTML/CSS/JS 和 A2UI 交互界面。
概述
Canvas 是一个无边框、可调整大小的面板,锚定在菜单栏附近,为智能体提供轻量级的视觉工作空间。它通过 WKWebView 嵌入,支持 HTML/CSS/JavaScript 和 A2UI 交互式 UI 界面。
核心特性
文件系统与自定义协议
- 存储位置: 状态存储在
~/Library/Application Support/OpenClaw/canvas/ - 自定义 URL Scheme: 使用
openclaw-canvas://协议提供本地文件服务 - 安全限制: 阻止目录遍历攻击,仅允许显式导航到外部 URL
- 自动重载: 文件变更时自动刷新内容
A2UI 支持
Canvas 支持 A2UI v0.8 消息协议,包括:
surfaceUpdate- 更新界面内容beginRendering- 开始渲染流程- 其他 A2UI 标准消息类型
智能体控制
智能体可以通过 Gateway WebSocket 控制 Canvas,例如:
# 显示 Canvas 面板
openclaw nodes canvas present
# 更新 Canvas 内容
openclaw nodes canvas update --content "..."
# 隐藏 Canvas
openclaw nodes canvas dismiss使用场景
- 展示交互式数据可视化
- 渲染动态 HTML/CSS/JS 内容
- 显示 A2UI 消息生成的界面
- 创建临时性的可视化工作区
安全机制
安全提示
- Canvas 会阻止目录遍历 (
../) 攻击 - 只能访问指定的 canvas 目录内的文件
- 外部 URL 需要显式用户导航才能访问
开发建议
- 将 HTML 文件放置在
~/Library/Application Support/OpenClaw/canvas/目录 - 使用
openclaw-canvas://协议引用本地资源 - 利用自动重载功能快速迭代开发
- 遵循 A2UI v0.8 消息规范实现交互