Canvas 技能

在已连接的 OpenClaw 节点（Mac 应用、iOS、Android）上显示 HTML 内容。

概述

Canvas 工具允许你在任意已连接节点的 Canvas 视图中呈现网页内容。适用于以下场景：

• 运行游戏、数据可视化、仪表盘
• 展示动态生成的 HTML 内容
• 交互式演示

工作原理

架构

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Canvas Host    │────▶│   Node Bridge    │────▶│  Node App   │
│  (HTTP Server)  │     │  (TCP Server)    │     │ (Mac/iOS/   │
│  Port 18793     │     │  Port 18790      │     │  Android)   │
└─────────────────┘     └──────────────────┘     └─────────────┘

1. Canvas Host 服务器：从 canvasHost.root 目录提供静态 HTML/CSS/JS 文件
2. Node Bridge：向已连接节点广播 Canvas URL
3. Node 应用：在 WebView 中渲染内容

Tailscale 集成

Canvas Host 服务器根据 gateway.bind 配置项决定绑定地址：

关键说明：canvasHostHostForBridge 的值由 bridgeHost 推导得出。当服务器绑定至 Tailscale 时，节点接收到的 URL 形如：

http://:18793/__openclaw__/canvas/.html

因此 localhost 类 URL 无法正常工作——因为节点从 Bridge 收到的是 Tailscale 主机名！

操作指令

配置

位于 ~/.openclaw/openclaw.json 中：

{
  "canvasHost": {
    "enabled": true,
    "port": 18793,
    "root": "/Users/you/clawd/canvas",
    "liveReload": true
  },
  "gateway": {
    "bind": "auto"
  }
}

实时重载（Live Reload）

当 liveReload: true（默认启用）时，Canvas Host 将：

• 通过 chokidar 监听根目录下的文件变更
• 向 HTML 文件注入 WebSocket 客户端脚本
• 在检测到文件变更时，自动刷新所有已连接的 Canvas

开发体验极佳！

使用流程

1. 创建 HTML 内容

将文件置于 Canvas 根目录（默认为 ~/clawd/canvas/）：

cat > ~/clawd/canvas/my-game.html << 'HTML'




  
Hello Canvas!


HTML

2. 获取 Canvas Host URL

检查 gateway 当前绑定模式：

cat ~/.openclaw/openclaw.json | jq '.gateway.bind'

据此构造 URL：

• loopback 模式：http://127.0.0.1:18793/__openclaw__/canvas/.html
• lan / tailnet / auto 模式：http://:18793/__openclaw__/canvas/.html

获取你的 Tailscale 主机名：

tailscale status --json | jq -r '.Self.DNSName' | sed 's/.$//'

3. 查找已连接节点

openclaw nodes list

查找具备 Canvas 能力的 Mac/iOS/Android 节点。

4. 呈现内容

canvas action:present node: target:

示例：

canvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__openclaw__/canvas/snake.html

5. 导航、截图或隐藏

canvas action:navigate node: url:
canvas action:snapshot node:
canvas action:hide node:

调试指南

白屏 / 内容未加载

原因：服务器实际绑定地址与节点预期的 URL 不匹配。

调试步骤：

1. 检查服务器绑定模式：cat ~/.openclaw/openclaw.json | jq '.gateway.bind'
2. 确认 Canvas 端口是否就绪：lsof -i :18793
3. 直接测试 URL 可达性：curl http://:18793/__openclaw__/canvas/.html

解决方案：务必使用与绑定模式完全匹配的完整主机名，而非 localhost。

“node required” 错误

必须始终显式指定 node: 参数。

“node not connected” 错误

节点当前离线。请使用 openclaw nodes list 查询在线节点。

内容未更新

若实时重载（Live Reload）未生效，请检查：

1. 配置中 liveReload: true 是否已启用
2. 文件是否位于 Canvas 根目录下
3. 日志中是否存在 watcher 相关错误

URL 路径结构

Canvas Host 服务路径以 /__openclaw__/canvas/ 为前缀：

http://:18793/__openclaw__/canvas/index.html  → ~/clawd/canvas/index.html
http://:18793/__openclaw__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html

该前缀由常量 CANVAS_HOST_PATH 定义。

使用提示

• 推荐 HTML 文件自包含（内联 CSS/JS），以获得最佳兼容性
• 可使用默认 index.html 作为测试页（内置 Bridge 诊断功能）
• Canvas 会持续显示，直至你主动执行 hide 或导航至其他页面
• 实时重载极大提升开发效率——保存即更新！
• A2UI JSON 推送功能仍在开发中，请暂用 HTML 文件