標籤

OpenClaw Node App Canvas A2UI 指令完全攻略｜AI Agent 互動式畫面渲染

OpenClaw Node App Canvas A2UI 指令完全攻略

這篇文章會介紹 OpenClaw Node App 的「Canvas A2UI」功能，讓你能夠與 AI Agent 進行互動式畫面渲染。

>

實驗日期：2026-04-19
實驗設備：Vivo V2514（Android 16）
OpenClaw 版本：2026.4.19.14ver

一、什麼是 A2UI？

A2UI 是什麼？

A2UI（Agent-to-UI）是一種特殊的通訊協議，允許 AI Agent 將訊息推送到手機上的 WebView，進行互動式的畫面渲染。

簡單來說：

  • AI Agent 可以主動推送訊息到手機螢幕
  • 手機可以即時顯示 AI 生成的內容
  • 支援互動式操作（如按鈕點擊、表單輸入等）

與一般 Canvas 的差別

功能CanvasCanvas A2UI
控制方式被動（等待指令）主動（AI 推送）
互動性有限完整互動
使用場景顯示網頁、截圖AI Agent UI 渲染

二、Canvas A2UI 指令家族

根據官方文件和原始碼分析，Canvas A2UI 有 3 個指令：

指令功能
canvas.a2ui.push推送訊息到 A2UI
canvas.a2ui.pushJSONL推送 JSONL 格式訊息
canvas.a2ui.reset重置 A2UI

三、指令詳細說明

1. canvas.a2ui.push - 推送訊息

用途： 將 A2UI 訊息推送到 WebView 進行渲染

指令格式：

openclaw nodes invoke --node "V2514" --command canvas.a2ui.push --params '{
  "messages": [
    {
      "beginRendering": {
        "surfaceId": "my-surface"
      }
    }
  ]
}'

參數說明：

參數類型必填說明
messagesJsonArray✅A2UI 訊息陣列

支援的訊息類型：

訊息類型說明
beginRendering開始渲染指定表面
surfaceUpdate更新現有表面
dataModelUpdate更新資料模型
deleteSurface刪除表面

回傳格式：

{
  "ok": true,
  "surfaces": ["my-surface"]
}

2. canvas.a2ui.pushJSONL - 推送 JSONL 格式訊息

用途： 以 JSONL（JSON Lines）格式推送多筆訊息

指令格式：

openclaw nodes invoke --node "V2514" --command canvas.a2ui.pushJSONL --params '{
  "jsonl": "{\"beginRendering\": {\"surfaceId\": \"surface-1\"}}\n{\"surfaceUpdate\": {\"surfaceId\": \"surface-1\"}}"
}'

參數說明：

參數類型必填說明
jsonlstring❌JSONL 格式字串（多行）
messagesJsonArray❌JSON 陣列格式

注意： 至少需要提供 jsonl 或 messages 其中之一

回傳格式：

{
  "ok": true,
  "surfaces": ["surface-1"]
}

3. canvas.a2ui.reset - 重置 A2UI

用途： 重置 A2UI 狀態，清除所有表面

指令格式：

openclaw nodes invoke --node "V2514" --command canvas.a2ui.reset --params '{}'

參數： 無

回傳格式：

{
  "ok": true
}

四、實際測試結果

測試環境

  • 設備：Vivo V2514（Android 16）
  • 版本：2026.4.19.14ver

測試結果

測試指令結果
初始化canvas.present✅ 成功
重置canvas.a2ui.reset✅ 成功
推送訊息canvas.a2ui.push✅ 成功
JSONL 推送canvas.a2ui.pushJSONL✅ 成功

測試過程

# 1. 初始化 WebView
$ openclaw nodes invoke --node "V2514" --command canvas.present --params '{"url": "https://example.com"}'
{"ok": true, ...}

# 2. 重置 A2UI
$ openclaw nodes invoke --node "V2514" --command canvas.a2ui.reset --params '{}'
{"ok": true, "payload": {"ok": true}}

# 3. 推送訊息
$ openclaw nodes invoke --node "V2514" --command canvas.a2ui.push --params '{"messages": [{"beginRendering": {"surfaceId": "test"}}]}'
{"ok": true, "payload": {"ok": true, "surfaces": ["test"]}}

# 4. JSONL 格式推送
$ openclaw nodes invoke --node "V2514" --command canvas.a2ui.pushJSONL --params '{"jsonl": "{\"beginRendering\": {\"surfaceId\": \"jsonl-test\"}}"}'
{"ok": true, "payload": {"ok": true, "surfaces": ["test", "jsonl-test"]}}

五、功能可用性總結

指令成功率需要 Screen 分頁說明
canvas.a2ui.push✅ 100%是推送訊息到 A2UI
canvas.a2ui.pushJSONL✅ 100%是JSONL 格式推送
canvas.a2ui.reset✅ 100%是重置 A2UI

六、A2UI 訊息格式

v0.8 支援的訊息

A2UI 目前支援 v0.8 格式，包含以下訊息：

1. beginRendering

開始渲染一個新的表面（Surface）。

{
  "beginRendering": {
    "surfaceId": "my-surface-id"
  }
}

2. surfaceUpdate

更新現有表面的內容。

{
  "surfaceUpdate": {
    "surfaceId": "my-surface-id",
    "content": {
      "title": "標題",
      "body": "內容"
    }
  }
}

3. dataModelUpdate

更新資料模型。

{
  "dataModelUpdate": {
    "key": "data-key",
    "value": "data-value"
  }
}

4. deleteSurface

刪除指定的表面。

{
  "deleteSurface": {
    "surfaceId": "my-surface-id"
  }
}

⚠️ 不支援的格式

A2UI v0.9 格式不支援，例如：

{
  "createSurface": { ... }  // 不支援！
}

如果使用 v0.9 格式，會收到錯誤：

A2UI JSONL line 1: looks like A2UI v0.9 (`createSurface`). Canvas supports v0.8 messages only.

七、使用範例

範例 1：基本渲染流程

# 初始化 WebView
openclaw nodes invoke --node "V2514" --command canvas.present --params '{"url": "https://example.com"}'

# 重置 A2UI 狀態
openclaw nodes invoke --node "V2514" --command canvas.a2ui.reset --params '{}'

# 開始渲染表面
openclaw nodes invoke --node "V2514" --command canvas.a2ui.push --params '{"messages": [{"beginRendering": {"surfaceId": "main"}}]}'

範例 2：批量更新多個表面

openclaw nodes invoke --node "V2514" --command canvas.a2ui.push --params '{
  "messages": [
    {"beginRendering": {"surfaceId": "header"}},
    {"beginRendering": {"surfaceId": "content"}},
    {"beginRendering": {"surfaceId": "footer"}}
  ]
}'

範例 3：使用 JSONL 格式

openclaw nodes invoke --node "V2514" --command canvas.a2ui.pushJSONL --params '{
  "jsonl": "{\"beginRendering\": {\"surfaceId\": \"surface-1\"}}\n{\"surfaceUpdate\": {\"surfaceId\": \"surface-1\", \"content\": {\"title\": \"Hello\"}}}"
}'

八、重要提示

⚠️ 必須切換到 Screen 分頁

與一般 Canvas 指令相同，A2UI 指令需要在 Screen 分頁上才能看到效果。

正確步驟：
1. 執行 canvas.a2ui.push 或其他 A2UI 指令
2. 在手機上點擊「Screen」分頁
3. 看到 A2UI 渲染的內容

九、常見問題

Q1：為什麼訊息推送沒有效果？

A：請確認：

  1. 執行了 canvas.present 初始化 WebView
  2. 切換到 Screen 分頁（底部導航）
  3. 檢查訊息格式是否正確（確認是 v0.8 格式）

Q2：支援哪些訊息類型？

A：A2UI v0.8 支援：

  • beginRendering - 開始渲染
  • surfaceUpdate - 更新表面
  • dataModelUpdate - 更新資料模型
  • deleteSurface - 刪除表面

不支援 createSurface（這是 v0.9 格式）

Q3：JSONL 和 messages 有什麼差別？

A：

  • messages：標準 JSON 陣列格式
  • jsonl：JSON Lines 格式，每行一個 JSON 物件，適合大量資料

Q4：可以同時推送多個訊息嗎？

A：可以！messages 陣列可以包含多個訊息，會依序處理。

openclaw nodes invoke --node "V2514" --command canvas.a2ui.push --params '{
  "messages": [
    {"beginRendering": {"surfaceId": "a"}},
    {"beginRendering": {"surfaceId": "b"}},
    {"beginRendering": {"surfaceId": "c"}}
  ]
}'

十、與一般 Canvas 指令的比較

功能CanvasCanvas A2UI
用途網頁顯示、截圖AI Agent UI 渲染
訊息格式任意 URL/JavaScriptA2UI v0.8 格式
互動性有限完整互動
典型使用顯示網頁、取得頁面內容Agent 推送 UI 更新

十一、技術備註

A2UI 工作原理

  1. 初始化：執行 canvas.present 創建 WebView
  2. 導航：WebView 載入 A2UI 主機頁面
  3. 推送：透過 canvas.a2ui.push 推送訊息
  4. 渲染：WebView 中的 JavaScript (openclawA2UI) 處理訊息並渲染

底層 JavaScript

A2UI 依賴 WebView 中的 globalThis.openclawA2UI 物件：

// 檢查是否就緒
globalThis.openclawA2UI.applyMessages(messages)

// 重置狀態
globalThis.openclawA2UI.reset()

十二、結論

Canvas A2UI 是 OpenClaw Node App 中強大的功能，允許 AI Agent 將訊息主動推送到手機螢幕，進行互動式渲染。

在 Android 上使用時，請記得：

  1. 執行指令後切換到 Screen 分頁
  2. 所有 A2UI 指令都完全可用
  3. 確認訊息格式為 v0.8（不支援 v0.9）

文章更新：2026-04-19

感謝微風提供測試設備和建議！

電子郵件發布
標籤：

留言

張貼留言

歡迎留下您的心靈足跡👍