畫布

macOS App 使用 WKWebView 內嵌由代理程式控制的 Canvas 面板，這是一個適用於 HTML/CSS/JS、A2UI 與小型互動式 UI 介面的輕量視覺工作區。

Canvas 的位置

Canvas 狀態儲存在 Application Support 下：

• ~/Library/Application Support/OpenClaw/canvas/<session>/...

Canvas 面板透過自訂 URL 配置 openclaw-canvas://<session>/<path> 提供這些檔案：

• openclaw-canvas://main/ -> <canvasRoot>/main/index.html
• openclaw-canvas://main/assets/app.css -> <canvasRoot>/main/assets/app.css
• openclaw-canvas://main/widgets/todo/ -> <canvasRoot>/main/widgets/todo/index.html

如果根目錄中沒有 index.html，App 會顯示內建的初始框架頁面。

面板行為

• 無邊框、可調整大小的面板，固定在選單列（或滑鼠游標）附近。
• 記住各工作階段的大小與位置。
• 本機 Canvas 檔案變更時自動重新載入。
• 一次只會顯示一個 Canvas 面板（視需要切換工作階段）。

你可以從 Settings -> Allow Canvas 停用 Canvas。停用後，Canvas 節點命令會傳回 CANVAS_DISABLED。

代理程式 API 介面

Canvas 透過閘道 WebSocket 公開，因此代理程式可以顯示或隱藏面板、導覽至路徑或 URL、執行 JavaScript，以及擷取快照影像：

openclaw nodes canvas present --node <id>openclaw nodes canvas navigate --node <id> "/"openclaw nodes canvas eval --node <id> --js "document.title"openclaw nodes canvas snapshot --node <id>

canvas.navigate 接受本機 Canvas 路徑、http(s) URL 與 file:// URL。傳入 "/" 會顯示本機初始框架或 index.html。

閘道託管且位於 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/ 下的目標，會透過節點工作階段目前具範圍限制的 Canvas URL 解析。App 會在導覽前重新整理這項短效能力；你不需要自行建構或複製能力 URL。

Canvas 中的 A2UI

A2UI 由閘道 Canvas 主機託管，並在 Canvas 面板中算繪。當閘道公告 Canvas 主機時，macOS App 會在首次開啟時自動導覽至 A2UI 主機頁面。

公告的 URL 具有能力範圍限制，例如 http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos。請將其視為暫時性認證資訊，而非穩定連結。

A2UI 命令（v0.8）

Canvas 接受 A2UI v0.8 伺服器對用戶端訊息：beginRendering、surfaceUpdate、dataModelUpdate、deleteSurface。目前尚不支援 createSurface（v0.9）。

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":"如果你能讀到這段文字，表示 A2UI 推送運作正常。"},"usageHint":"body"}}}]}}{"beginRendering":{"surfaceId":"main","root":"root"}}EOFA2 openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

快速冒煙測試：

openclaw nodes canvas a2ui push --node <id> --text "來自 A2UI 的問候"

從 Canvas 觸發代理程式執行

Canvas 可以透過 openclaw://agent?... 深層連結觸發新的代理程式執行：

window.location.href = "openclaw://agent?message=Review%20this%20design";

支援的查詢參數：

除非提供有效的金鑰，否則 App 會提示使用者確認。未含金鑰的連結會在核准前顯示訊息和 URL，並忽略傳送路由欄位；含金鑰的連結則使用正常的閘道執行路徑。

安全性注意事項

• Canvas 配置會封鎖目錄遍歷；檔案必須位於工作階段根目錄下。
• 本機 Canvas 內容使用自訂配置（不需要回送伺服器）。
• 只有在明確導覽時才允許外部 http(s) URL。
• 一般網頁僅供算繪。只有 App 擁有的 Canvas 配置，或 App 選取且能力範圍完全相符的閘道 A2UI 文件，才能接受代理程式動作；子框架、重新導向、過期能力及變更過的查詢都無法分派動作。

相關內容

• macOS App
• WebChat