> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 畫布

macOS 應用程式使用 `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`，應用程式會顯示內建的初始架構頁面。

## 面板行為

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

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

## 代理程式 API 介面

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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>
```

`eval` 和 `a2ui.*` 會更新內容，而不會開啟或顯示面板。只有
`present`、`navigate` 或使用者操作會顯示面板；隱藏後，內容更新
仍會繼續套用至隱藏的面板。`snapshot` 需要可見的面板，
否則會傳回 `CANVAS_HIDDEN`；請先執行 `present`。

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

位於 `/__openclaw__/canvas/` 和
`/__openclaw__/a2ui/` 下、由閘道託管的目標，會透過節點工作階段目前限定範圍的
Canvas URL 解析。應用程式會在導覽前重新整理該短效能力；
你不需要自行建構或複製能力 URL。

## Canvas 中的 A2UI

A2UI 由閘道 Canvas 主機託管，並在 Canvas
面板中呈現。當閘道公布 Canvas 主機時，macOS 應用程式會在第一次開啟時自動導覽
至 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）。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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>
```

快速冒煙測試：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes canvas a2ui push --node <id> --text "來自 A2UI 的問候"
```

## 從 Canvas 觸發代理程式執行

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

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
window.location.href = "openclaw://agent?message=Review%20this%20design";
```

支援的查詢參數：

| 參數                       | 含義                     |
| ------------------------ | ---------------------- |
| `message`                | 預先填入的代理程式提示詞。          |
| `sessionKey`             | 穩定的工作階段識別碼。            |
| `thinking`               | 選用的思考設定檔。              |
| `deliver`、`to`、`channel` | 傳遞目標。                  |
| `timeoutSeconds`         | 選用的執行逾時時間。             |
| `key`                    | 應用程式為受信任的本機呼叫端產生的安全權杖。 |

除非提供有效的金鑰，否則應用程式會提示確認。未附金鑰的
連結會在核准前顯示訊息和 URL，並忽略傳遞路由
欄位；附有金鑰的連結則使用一般的閘道執行路徑。

## 安全性注意事項

* Canvas 配置會封鎖目錄周遊；檔案必須位於工作階段根目錄下。
* 本機 Canvas 內容使用自訂配置（不需要回送伺服器）。
* 只有在明確導覽時才允許外部 `http(s)` URL。
* 一般網頁只能呈現內容。只有來自應用程式擁有的 Canvas 配置，或應用程式選取且具備確切能力範圍的閘道 A2UI 文件，才會接受代理程式操作；
  子框架、重新導向、過期的能力，以及已變更的
  查詢都無法分派操作。

## 相關內容

* [macOS 應用程式](/zh-TW/platforms/macos)
* [WebChat](/zh-TW/web/webchat)