Skip to main content

​
Canvas (画布)

Canvas 是一个 节点托管的 WebView,代理可以用来渲染交互式 HTML/CSS/JS 界面。 画布用于:
  • 可视化数据(图表、图形、仪表板)
  • 向用户展示工作流进度
  • 构建自定义 UI 组件
  • 测试和演示 Web 界面

​
要求

  • 已配对的节点(iOS、Android 或 macOS)
  • 网关画布主机已配置(默认情况下由网关 HTTP 服务器提供)

​
快速开始

​
1) 导航到画布 URL

openclaw nodes invoke --node "<节点名称>" --command canvas.navigate \
  --params '{"url":"http://<网关主机>:18789/__openclaw__/canvas/"}'
说明:
  • <网关主机> 可以是网关的 IP、主机名或 MagicDNS 名称。
  • 画布页面由网关在 /__openclaw__/canvas/ 路径提供。
  • 源文件位于 ~/.openclaw/workspace/canvas/index.html(可编辑)。

​
2) 执行 JavaScript

openclaw nodes invoke --node "<节点名称>" --command canvas.eval \
  --params '{"javaScript":"document.body.style.background = \"#ff2d55\""}'

​
3) 拍摄快照

openclaw nodes invoke --node "<节点名称>" --command canvas.snapshot \
  --params '{"maxWidth":900,"format":"jpeg"}'

​
Canvas 命令

所有画布命令通过 node.invoke 执行,并需要节点在前台运行。

​
canvas.navigate

导航到 URL。 参数:
  • url(字符串,必需): 目标 URL。
    • 使用 "" 或 "/" 返回默认脚手架。
    • 使用 http://<网关主机>:<端口>/__openclaw__/canvas/ 加载网关托管的画布。
示例: 
openclaw nodes invoke --node "iOS 节点" --command canvas.navigate \
  --params '{"url":"http://192.168.1.100:18789/__openclaw__/canvas/"}'

​
canvas.eval

在画布上下文中执行 JavaScript。 参数:
  • javaScript(字符串,必需): 要执行的 JS 代码。
返回: 表达式的返回值(字符串形式)。 示例: 
openclaw nodes invoke --node "iOS 节点" --command canvas.eval \
  --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.fillStyle=\"#007aff\"; ctx.fillRect(50,50,200,100); return \"ok\"; })()" }'

​
canvas.snapshot

捕获画布的屏幕截图。 参数:
  • format(可选): "jpeg"(默认) 或 "png"
  • maxWidth(可选): 最大宽度(像素)
  • quality(可选): JPEG 质量 (0.0-1.0)
返回: { format, base64 } 示例: 
openclaw nodes invoke --node "iOS 节点" --command canvas.snapshot \
  --params '{"maxWidth":1200,"format":"png"}'

​
Canvas 主机 (网关)

网关在以下路径提供画布页面:
  • /__openclaw__/canvas/ — 主画布页面 (index.html)
  • /__openclaw__/a2ui/ — A2UI 主机(用于代理到界面)
源文件:
  • 主画布: ~/.openclaw/workspace/canvas/index.html
  • A2UI: 内置,由网关提供

​
编辑画布 HTML

  1. 编辑 ~/.openclaw/workspace/canvas/index.html:
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Canvas</title>
  <style>
    body { margin: 0; background: #000; color: #fff; font-family: sans-serif; }
    canvas { display: block; }
  </style>
</head>
<body>
  <canvas id="canvas"></canvas>
  <script>
    const canvas = document.getElementById('canvas');
    const ctx = canvas.getContext('2d');
    canvas.width = window.innerWidth;
    canvas.height = window.innerHeight;
    window.__openclaw = { ctx };
  </script>
</body>
</html>
  1. 保存后,画布会通过实时重载自动刷新(如果已连接)。

​
A2UI (代理到界面)

A2UI 是一种声明式 UI 协议,用于从代理构建交互式界面。

​
A2UI 命令

  • canvas.a2ui.push — 推送 A2UI 元素或操作
  • canvas.a2ui.reset — 清除画布并重置 A2UI 状态
参数:
  • items(数组,必需): A2UI 元素或操作的数组
示例: 
openclaw nodes invoke --node "iOS 节点" --command canvas.a2ui.push \
  --params '{"items":[{"type":"text","content":"你好,世界!"}]}'
A2UI 元素类型:
  • text — 文本块
  • button — 可点击按钮
  • input — 文本输入字段
  • image — 图像(Base64 或 URL)
  • card — 容器卡片
完整的 A2UI 规范请参见 A2UI 文档。

​
故障排查

​
”NODE_BACKGROUND_UNAVAILABLE”

画布命令需要节点应用在前台运行。将应用切换到前台并重试。

​
“A2UI_HOST_NOT_CONFIGURED”

网关未广播画布主机 URL。检查网关配置中的 gateway.canvasHost。

​
画布未加载

  • 确认网关 HTTP 服务正在运行(与 WebSocket 端口相同,默认 18789)。
  • 检查网络连接性(节点能否访问网关主机?)。
  • 使用节点的 IP 地址而非 localhost 或 127.0.0.1。

​
JavaScript 执行失败

  • 确保 JavaScript 是有效的。
  • 检查 window.__openclaw 上下文是否可用。
  • 使用 console.log 调试(输出显示在节点控制台中)。

​
相关文档