Canvas OS

Canvas 作为一个应用平台：在 OpenClaw Canvas 上构建、存储并运行富交互可视化应用。

设计理念

你即操作系统（OS）。Canvas 是你的窗口。应用在本地构建，并在 Canvas 上运行。

富交互 HTML/CSS/JS 界面 —— 不仅限于纯文本，支持完整交互、动画与实时数据。

快捷命令

工作原理

核心原则：应用运行于 Canvas，而非浏览器标签页。Canvas 即你的 UI 窗口。

Canvas 加载方式

Canvas 具有安全限制，禁止访问本地文件路径。以下三种方式可行：

❌ 不可用方式： file:///path/to/file.html（被 Canvas 安全策略拦截）

📖 参考文档： CANVAS-LOADING.md（含详细指南与排障说明）

辅助脚本： canvas-inject.py —— 格式化 HTML 以适配直接注入

1. 应用即 HTML/CSS/JS 文件

~/.openclaw/workspace/apps/[app-name]/
├── index.html    # UI 页面（推荐采用自包含形式）
├── data.json     # 持久化状态数据
└── manifest.json # 应用元数据

2. 通过 localhost 启动服务

cd ~/.openclaw/workspace/apps/[app-name]
python3 -m http.server [PORT] > /dev/null 2>&1 &

3. 导航 Canvas 至 localhost 地址

NODE="Your Node Name"  # 通过命令获取：openclaw nodes status
openclaw nodes canvas navigate --node "$NODE" "http://localhost:[PORT]/"

重要提示： 此操作将应用打开在 Canvas（可视化面板）中，而非浏览器标签页。

4. Agent 通过 JS eval 注入数据

openclaw nodes canvas eval --node "$NODE" --js "app.setData({...})"

注意： 当前 OpenClaw 版本中 openclaw-canvas:// URL Scheme 存在兼容性问题，请改用 http://localhost:。

启动一个应用

该操作的作用： 在 Canvas（可视化面板）中显示应用，而非在浏览器标签页中打开。

方法 1：本地服务器（推荐用于复杂应用）

完整执行流程：

NODE="Your Node Name"
PORT=9876
APP="my-app"

# 1. 终止该端口上已存在的服务进程
lsof -ti:$PORT | xargs kill -9 2>/dev/null

# 2. 启动服务端
cd ~/.openclaw/workspace/apps/$APP
python3 -m http.server $PORT > /dev/null 2>&1 &

# 3. 等待服务就绪
sleep 1

# 4. 导航 Canvas 至应用地址
openclaw nodes canvas navigate --node "$NODE" "http://localhost:$PORT/"

# 5. 注入初始数据
openclaw nodes canvas eval --node "$NODE" --js "app.loadData({...})"

方法 2：直接 HTML 注入（适用于快速展示）

适用场景： Canvas 因安全沙箱机制禁止使用文件路径（file://）；Data URLs 在部分环境下不稳定。此方式无需启动本地服务，可实现即时渲染。

# 示例：使用 canvas 工具
canvas.present(url="about:blank", target=node_name)

html_content = """


    


    

        
Your Content Here
    

"""

# 转义反引号后注入
js_code = f"""document.open();
document.write(`{html_content}`);
document.close();"""

canvas.eval(javaScript=js_code, target=node_name)

关键限制： 文件路径（file:///path/to/file.html）因安全策略在 Canvas 中被明确禁止。请始终使用 localhost 或直接注入方式。

构建应用

应用 API 规范

每个应用应暴露 window.app 或 window.[appname] 对象：

window.app = {
  // 更新单个字段值
  setValue: (key, val) => {
    document.getElementById(key).textContent = val;
  },
  
  // 批量更新数据
  loadData: (data) => { /* 渲染全部内容 */ },
  
  // 显示通知
  notify: (msg) => { /* 弹出 toast 提示 */ }
};

双向通信

应用可通过深度链接（deep links）向 Agent 发送指令：

function sendToAgent(message) {
  window.location.href = `openclaw://agent?message=${encodeURIComponent(message)}`;
}

// 按钮点击 → 触发 Agent 命令
document.getElementById('btn').onclick = () => {
  sendToAgent('Refresh my dashboard');
};

模板

Dashboard

含统计卡片、进度条、列表等内容的自包含 HTML 应用。

• 默认端口：9876
• API 接口：dashboard.setRevenue()、dashboard.setProgress()、dashboard.notify()

Tracker

支持习惯/任务勾选与连续打卡功能的自包含 HTML 应用。

• 默认端口：9877
• API 接口：tracker.setItems()、tracker.addItem()、tracker.toggleItem()

快速展示（A2UI）

适用于无需完整应用结构的临时信息展示：

openclaw nodes canvas a2ui push --node "$NODE" --text "
📊 QUICK STATUS

Revenue: $500
Users: 100

Done!
"

端口分配

设计系统

:root {
  --bg-primary: #0a0a0a;
  --bg-card: #1a1a2e;
  --accent-green: #00d4aa;
  --accent-blue: #4a9eff;
  --accent-orange: #f59e0b;
  --text-primary: #fff;
  --text-muted: #888;
  --border: #333;
}

最佳实践

1. 自包含 HTML —— 内联 CSS/JS，提升可移植性
2. 深色主题 —— 与 OpenClaw 整体视觉风格保持一致
3. 暴露应用 API —— 便于 Agent 通过 window.app.* 动态更新
4. 合理使用 ID —— 为 Agent 需更新的 DOM 元素设置唯一 ID
5. 实时时间显示 —— 表明应用处于活跃运行状态
6. 深度链接（Deep Links） —— 支持双向通信能力

故障排查

应用在浏览器中打开而非 Canvas？

• 确认使用的是 openclaw nodes canvas navigate，而非普通 open 命令
• canvas navigate 明确作用于 Canvas 面板

Canvas 显示 “Not Found”？

• 文件路径不可用： Canvas 出于安全沙箱限制，屏蔽所有 file:/// 协议 URL
• Data URLs 可能失败： 推荐改用 canvas eval + document.write() 进行直接 HTML 注入
• 若使用 localhost：请验证服务是否正常运行 —— curl http://localhost:[PORT]/
• 检查端口号是否正确
• 请使用 http://localhost:，避免使用存在兼容问题的 openclaw-canvas://

URL 正确但 Canvas 仍显示 “Not Found”？

• 这是由 Canvas 的安全边界导致：其无法访问本地文件系统
• 解决方案： 使用 “启动一个应用” 小节中的方法 2（直接 HTML 注入）
• 或采用方法 1（通过 localhost 提供服务）

应用未响应更新？

• 检查 window.app API 是否已正确定义：openclaw nodes canvas eval --js "typeof window.app"
• 确认 JS eval 语法正确：双引号内嵌套单引号

端口已被占用？

• 终止已有进程：lsof -ti:[PORT] | xargs kill -9

辅助脚本

canvas-inject.py

用于直接 HTML 注入（方法 2）的 Python 辅助工具。

# Python 中调用示例
from canvas_inject import inject_html_to_canvas

html = open("my-dashboard.html").read()
commands = inject_html_to_canvas(html, node_name="Your Node")

# 后续使用 canvas 工具执行返回的指令
canvas.present(**commands["step1_present"])
canvas.eval(**commands["step2_inject"])

或手动遵循 “启动一个应用” 小节中方法 2 的操作模式。

运行要求

• 支持 Canvas 功能的 OpenClaw（macOS 应用）
• Python 3（用于运行 http.server）
• 已配对且具备 Canvas 能力的节点