Canvas OS
Canvas as an app platform. Build, store, and run rich visual apps on the OpenClaw Canvas.
Philosophy
You are an OS. Canvas is the window. Apps are built locally and run on Canvas.
Rich HTML/CSS/JS UIs — not just text. Full interactivity, animations, live data.
Quick Commands
| Command | What Jarvis Does |
|---|
| "Open [app]" | Start server, navigate Canvas, inject data |
| "Build me a [type]" |
Create app from template, open it |
| "Update [element]" | Inject JS to modify live |
| "Show [data] on canvas" | Quick A2UI display |
| "Close canvas" | Stop server, hide Canvas |
How It Works
Key principle: Apps run on Canvas, not in a browser tab. Canvas is your UI window.
Canvas Loading Methods
Canvas has security restrictions that block file path access. Three methods work:
| Method | When to Use | Pros | Cons |
|---|
| Localhost Server | Complex apps, external assets | Full browser features | Requires port management |
| Direct HTML Injection |
Quick displays, demos | Instant, no server needed | No external assets, size limit |
|
Data URLs | Small content | Self-contained | Unreliable on some systems |
❌ Does NOT work: file:///path/to/file.html (blocked by Canvas security)
📖 See: CANVAS-LOADING.md for detailed guide + troubleshooting
Helper script: canvas-inject.py — Formats HTML for direct injection
1. Apps are HTML/CSS/JS files
CODEBLOCK0
2. Serve via localhost
CODEBLOCK1
3. Navigate Canvas to localhost
CODEBLOCK2
Important: This opens the app on Canvas (the visual panel), NOT in a browser.
4. Agent injects data via JS eval
CODEBLOCK3
Note: The openclaw-canvas:// URL scheme has issues in current OpenClaw versions. Use http://localhost: instead.
Opening an App
What this does: Displays the app on Canvas (the visual panel), not in a browser tab.
Method 1: Localhost Server (Recommended for Complex Apps)
Full sequence:
CODEBLOCK4
Method 2: Direct HTML Injection (For Quick Displays)
When to use: File paths don't work in Canvas (security sandboxing). Data URLs can be unreliable. Use this for instant displays without localhost.
CODEBLOCK5
Key limitation: File paths (file:///path/to/file.html) are blocked in Canvas for security. Always use localhost or direct injection.
Building Apps
App API Convention
Every app should expose a window.app or window.[appname] object:
CODEBLOCK6
Two-Way Communication
Apps send commands back via deep links:
CODEBLOCK7
Templates
Dashboard
Stats cards, progress bars, lists. Self-contained HTML.
- - Default port: 9876
- API:
dashboard.setRevenue(), dashboard.setProgress(), INLINECODE10
Tracker
Habits/tasks with checkboxes and streaks. Self-contained HTML.
- - Default port: 9877
- API:
tracker.setItems(), tracker.addItem(), INLINECODE13
Quick Display (A2UI)
For temporary displays without a full app:
CODEBLOCK8
Port Assignments
| App Type | Default Port |
|---|
| Dashboard | 9876 |
| Tracker |
9877 |
| Timer | 9878 |
| Display | 9879 |
| Custom | 9880+ |
Design System
CODEBLOCK9
Best Practices
- 1. Self-contained HTML — Inline CSS/JS for portability
- Dark theme — Match OpenClaw aesthetic
- Expose app API — Let agent update via INLINECODE14
- Use IDs — On elements the agent will update
- Live clock — Shows the app is alive
- Deep links — For two-way communication
Troubleshooting
App opens in browser instead of Canvas?
- - Make sure you're using
openclaw nodes canvas navigate, not just INLINECODE16 - Canvas navigate targets the Canvas panel specifically
"Not Found" on Canvas?
- - File paths don't work: Canvas blocks
file:/// URLs for security (sandboxing) - Data URLs may fail: Use direct HTML injection via
canvas eval + document.write() instead - For localhost: Verify server is running: INLINECODE20
- Check port is correct
- Use
http://localhost: not openclaw-canvas:// (URL scheme has issues)
Canvas shows "Not Found" even with correct URL?
- - This is a security boundary: Canvas can't access local filesystem
- Solution: Use Method 2 (Direct HTML Injection) from "Opening an App" section
- Or serve via localhost (Method 1)
App not updating?
- - Check window.app API is defined: INLINECODE23
- Verify JS eval syntax: single quotes inside double quotes
Server port already in use?
- - Kill existing: INLINECODE24
Helper Scripts
canvas-inject.py
Python helper for direct HTML injection (Method 2).
CODEBLOCK10
Or just follow the pattern manually (see Method 2 in "Opening an App").
Requirements
- - OpenClaw with Canvas support (macOS app)
- Python 3 (for http.server)
- A paired node with canvas capability
Canvas OS
Canvas 作为一个应用平台。在 OpenClaw Canvas 上构建、存储和运行丰富的可视化应用。
理念
你是一个操作系统。Canvas 是窗口。应用在本地构建，在 Canvas 上运行。
丰富的 HTML/CSS/JS 用户界面 — 不仅仅是文本。完整的交互性、动画、实时数据。
快速命令
| 命令 | Jarvis 执行的操作 |
|---|
| 打开 [应用] | 启动服务器，导航 Canvas，注入数据 |
| 为我构建一个 [类型] |
从模板创建应用，打开它 |
| 更新 [元素] | 注入 JS 以实时修改 |
| 在 canvas 上显示 [数据] | 快速 A2UI 显示 |
| 关闭 canvas | 停止服务器，隐藏 Canvas |
工作原理
关键原则： 应用在 Canvas 上运行，而不是在浏览器标签页中。Canvas 是你的 UI 窗口。
Canvas 加载方法
Canvas 存在安全限制，会阻止文件路径访问。有三种方法可行：
| 方法 | 何时使用 | 优点 | 缺点 |
|---|
| 本地服务器 | 复杂应用、外部资源 | 完整的浏览器功能 | 需要端口管理 |
| 直接 HTML 注入 |
快速显示、演示 | 即时，无需服务器 | 无外部资源，大小限制 |
|
数据 URL | 小内容 | 自包含 | 在某些系统上不可靠 |
❌ 不适用： file:///path/to/file.html（被 Canvas 安全机制阻止）
📖 参见： CANVAS-LOADING.md 获取详细指南 + 故障排除
辅助脚本： canvas-inject.py — 格式化 HTML 用于直接注入
1. 应用是 HTML/CSS/JS 文件
~/.openclaw/workspace/apps/[应用名称]/
├── index.html # 用户界面（建议自包含）
├── data.json # 持久化状态
└── manifest.json # 应用元数据
2. 通过本地服务器提供服务
bash
cd ~/.openclaw/workspace/apps/[应用名称]
python3 -m http.server [端口] > /dev/null 2>&1 &
3. 将 Canvas 导航到本地服务器
bash
NODE=你的节点名称 # 从以下命令获取：openclaw nodes status
openclaw nodes canvas navigate --node $NODE http://localhost:[端口]/
重要： 这会在 Canvas（可视化面板）上打开应用，而不是在浏览器中。
4. 代理通过 JS eval 注入数据
bash
openclaw nodes canvas eval --node $NODE --js app.setData({...})
注意： openclaw-canvas:// URL 方案在当前 OpenClaw 版本中存在一些问题。请使用 http://localhost: 替代。
打开应用
功能说明： 在 Canvas（可视化面板）上显示应用，而不是在浏览器标签页中。
方法 1：本地服务器（推荐用于复杂应用）
完整流程：
bash
NODE=你的节点名称
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 中文件路径无法使用（安全沙箱）。数据 URL 可能不可靠。使用此方法无需本地服务器即可即时显示。
python
使用 canvas 工具的示例
canvas.present(url=about:blank, target=node_name)
html_content =
你的内容在这里
转义反引号并注入
js_code = fdocument.open();
document.write({html_content});
document.close();
canvas.eval(javaScript=jscode, target=nodename)
关键限制： Canvas 出于安全原因阻止文件路径（file:///path/to/file.html）。始终使用本地服务器或直接注入。
构建应用
应用 API 约定
每个应用都应暴露一个 window.app 或 window.[应用名称] 对象：
javascript
window.app = {
// 更新值
setValue: (key, val) => {
document.getElementById(key).textContent = val;
},
// 批量更新
loadData: (data) => { / 渲染所有 / },
// 通知
notify: (msg) => { / 显示提示 / }
};
双向通信
应用通过深度链接发送命令返回：
javascript
function sendToAgent(message) {
window.location.href = openclaw://agent?message=${encodeURIComponent(message)};
}
// 按钮点击 → 代理命令
document.getElementById(btn).onclick = () => {
sendToAgent(刷新我的仪表盘);
};
模板
仪表盘
统计卡片、进度条、列表。自包含 HTML。
- - 默认端口：9876
- API：dashboard.setRevenue()、dashboard.setProgress()、dashboard.notify()
追踪器
带复选框和连续打卡记录的习惯/任务。自包含 HTML。
- - 默认端口：9877
- API：tracker.setItems()、tracker.addItem()、tracker.toggleItem()
快速显示（A2UI）
用于无需完整应用的临时显示：
bash
openclaw nodes canvas a2ui push --node $NODE --text
📊 快速状态
收入：\$500
用户：100
完成！
端口分配
9877 |
| 计时器 | 9878 |
| 显示器 | 9879 |
| 自定义 | 9880+ |
设计系统
css
: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 以便移植
- 深色主题 — 匹配 OpenClaw 美学风格
- 暴露应用 API — 让代理通过 window.app.* 更新
- 使用 ID — 在代理将要更新的元素上
- 实时时钟 — 显示应用正在运行
- 深度链接 — 用于双向通信
故障排除
应用在浏览器中打开而不是在 Canvas 中？
- - 确保你使用的是 openclaw nodes canvas navigate，而不仅仅是 open
- Canvas 导航专门针对 Canvas 面板
Canvas 上显示未找到？
- - 文件路径不起作用： Canvas 出于安全原因阻止 file:/// URL（沙箱）
- 数据 URL 可能失败： 改用通过 canvas eval + document.write() 的直接 HTML 注入
- 对于本地服务器：验证服务器是否正在运行：curl http://localhost:[端口]/
- 检查端口是否正确
- 使用 http://localhost: 而不是 openclaw-canvas://（URL 方案存在问题）
即使 URL 正确，Canvas 仍显示未找到？
- - 这是安全边界：Canvas 无法访问本地文件系统
- 解决方案： 使用打开应用部分中的方法 2（直接 HTML 注入）
- 或通过本地服务器提供服务（方法 1）
应用不更新？
- - 检查 window.app API 是否已定义：openclaw nodes canvas eval --js typeof window
