探索 Canvas：在 macOS App 中打造 Agent 專屬的互動介面

寫 Agent 的時候，最煩人的往往是受限於終端機的純文字輸出。當你需要呈現複雜的資料圖表、互動式按鈕，或是即時的網頁預覽時，純文字就顯得力不從心。你可能想過自己刻一個前端介面，但處理視窗管理和通訊協議又是另一件苦差事。

Canvas 就是為了填補這個空缺而設計的。它在 macOS App 裡內嵌了一個由 Agent 控制的 WKWebView 面板，讓你可以直接用熟悉的 HTML/CSS/JS 或是 A2UI 來構建輕量級的視覺工作區。

需要準備的東西

macOS 版 OpenClaw App
已連線的 Gateway WebSocket
源文檔提到的 CLI 工具 openclaw

快速開始

想在 5 分鐘內看到 Canvas 動起來？按照這幾個步驟做：

確認設定：進入 Settings → Allow Canvas，確保功能已開啟。
喚起面板：在終端機輸入以下指令來顯示 Canvas：
Terminal window
```
openclaw nodes canvas present --node <id>
```
導航至首頁：讓 Canvas 顯示預設的 scaffold 頁面：
Terminal window
```
openclaw nodes canvas navigate --node <id> --url "/"
```
快速測試 A2UI：發送一個簡單的文字訊息到 Canvas：
Terminal window
```
openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
```

Canvas 的運作機制

Canvas 的檔案儲存在你的電腦本地路徑： ~/Library/Application Support/OpenClaw/canvas/<session>/...

面板透過自定義的 URL scheme 來讀取這些檔案：

openclaw-canvas://<session>/ 對應到該 session 根目錄的 index.html
openclaw-canvas://main/assets/app.css 則對應到資源路徑

如果你的根目錄沒有 index.html，App 會自動顯示一個內建的 scaffold 頁面。Canvas 面板會記住你在每個 session 中的視窗大小與位置，並且當本地檔案變動時，它會自動重新整理頁面。

Agent API 操作

Agent 可以透過 Gateway WebSocket 完全掌控 Canvas 的行為。除了基本的顯示與隱藏，你還可以執行以下操作：

# 導航至特定路徑或 URL
openclaw nodes canvas navigate --node <id> --url "/"

# 在頁面中執行 JavaScript
openclaw nodes canvas eval --node <id> --js "document.title"

# 擷取當前畫面截圖
openclaw nodes canvas snapshot --node <id>

注意：canvas.navigate 支援本地路徑、http(s) 協定以及 file:// 協定。

在 Canvas 中使用 A2UI

Canvas 支援 A2UI v0.8，這讓你不需要寫複雜的 HTML 就能推播 UI 元件。當 Gateway 偵測到 Canvas 環境時，App 會自動導航至 A2UI 的代管頁面。

目前支援的 A2UI v0.8 指令包括：

beginRendering
surfaceUpdate
dataModelUpdate
deleteSurface

注意： 目前不支援 A2UI v0.9 的 createSurface 指令。

你可以透過 CLI 推播一個 JSONL 檔案來更新 UI：

cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2

openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

從 Canvas 觸發 Agent 任務

你可以利用 Deep Links 從 Canvas 內部發起新的 Agent 任務。這在建立互動式按鈕時非常有用：

// 在 Canvas 的 JavaScript 中執行
window.location.href = "openclaw://agent?message=Review%20this%20design";

除非你提供了有效的金鑰，否則 App 會彈出視窗要求你確認操作。

疑難排解

收到 CANVAS_DISABLED 錯誤：代表你在 Settings 中關閉了 Canvas 功能，請重新開啟。
檔案讀取不到：確保檔案位於正確的 session 根目錄下。為了安全起見，Canvas 禁止目錄遍歷（directory traversal），檔案必須嚴格存放在 session 路徑內。
A2UI 沒反應：檢查你的指令是否使用了 v0.9 的 createSurface，請確保只使用 v0.8 支援的指令。

如果你在設定過程中遇到任何困難，可以詢問 AI Setup Assistant 獲取即時協助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。