> ## 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.

# Peekaboo 橋接器

OpenClaw 可將 **PeekabooBridge** 作為本機且具權限感知能力的 UI 自動化代理程式（`PeekabooBridgeHostCoordinator`，由 `steipete/Peekaboo` Swift 套件支援）。如此一來，`peekaboo` 命令列介面便能利用 macOS 應用程式的 TCC 權限來驅動 UI 自動化。

## 這是什麼（以及不是什麼）

* **主機**：OpenClaw\.app 可作為 PeekabooBridge 主機。
* **用戶端**：`peekaboo` 命令列介面（沒有獨立的 `openclaw ui ...` 介面）。
* **UI**：視覺疊加層保留在 Peekaboo.app 中；OpenClaw 是精簡的代理主機。

## 與其他桌面控制路徑的關係

OpenClaw 有四條刻意保持獨立的桌面控制路徑：

* **PeekabooBridge 主機**：OpenClaw\.app 代管本機 PeekabooBridge 通訊端。`peekaboo` 命令列介面是用戶端，並使用 OpenClaw\.app 的 macOS 權限來執行螢幕截圖、點按、選單、對話框、Dock 操作及視窗管理。
* **由代理程式驅動的電腦操作（`computer.act`）**：閘道代理程式的內建 `computer` 工具會透過 `screen.snapshot` 擷取螢幕截圖，並使用危險的 `computer.act` 節點命令操控指標和鍵盤。macOS 節點會使用此橋接所公開的內嵌 Peekaboo 自動化服務及有限的 CoreGraphics 基本功能，在處理程序內完成 `computer.act`，而不經過 PeekabooBridge 通訊端或 `peekaboo` 命令列介面。請參閱[電腦操作](/zh-TW/nodes/computer-use)。
* **Codex 電腦操作**：內建的 `codex` 外掛會檢查並可安裝 Codex 的 `computer-use` MCP 外掛（`extensions/codex/src/app-server/computer-use.ts`），接著讓 Codex 在 Codex 模式的回合中負責原生桌面控制工具呼叫。OpenClaw 不會透過 PeekabooBridge 代理這些操作。
* **直接使用 `cua-driver` MCP**：OpenClaw 可將 TryCua 的上游 `cua-driver mcp` 伺服器註冊為一般 MCP 伺服器，讓代理程式能使用 CUA 驅動程式本身的結構描述及 pid／視窗／元素索引工作流程，而不經過 Codex 市集或 PeekabooBridge 通訊端。

若要透過 OpenClaw\.app 的權限感知橋接主機使用廣泛的 macOS 自動化功能，請使用 Peekaboo。若閘道代理程式應透過任何視覺模型都能驅動的統一 `computer.act` 節點命令查看及控制桌面，請使用由代理程式驅動的電腦操作。若 Codex 模式代理程式應依賴 Codex 的原生外掛，請使用 Codex 電腦操作。若要將 CUA 驅動程式作為一般 MCP 伺服器公開給任何由 OpenClaw 管理的執行階段，請直接使用 `cua-driver mcp`。

## 啟用橋接

在 macOS 應用程式中：**Settings -> Enable Peekaboo Bridge**。由於兩者都會授予本機 UI 自動化能力，因此此切換開關要求 **Allow Computer Control** 必須開啟；關閉 Computer Control 時，切換開關會停用，主機也不會執行。若要在不啟用 Computer Control 的情況下驅動 Peekaboo，請改為執行 Peekaboo 自己的 Mac 應用程式作為主機。

啟用後（且 Computer Control 已開啟），OpenClaw 會在 `~/Library/Application Support/OpenClaw/<socket-name>` 啟動本機 UNIX 通訊端伺服器。若停用，主機會停止，而 `peekaboo` 會改用其他可用的主機。協調器也會維護舊版通訊端符號連結（Application Support 下的 `clawdbot`、`clawdis`、`moltbot`），指向目前的通訊端，以支援較舊的 `peekaboo` 安裝版本。

## 用戶端探索順序

Peekaboo 用戶端通常會依下列順序嘗試主機：

1. Peekaboo.app（完整使用者體驗）
2. Claude.app（若已安裝）
3. OpenClaw\.app（精簡代理程式）

使用 `peekaboo bridge status --verbose` 查看目前啟用的主機及使用中的通訊端路徑。可使用以下設定覆寫：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
```

## 安全性與權限

* 橋接會驗證**呼叫端程式碼簽章**；並強制執行 TeamID 允許清單（Peekaboo 主機 TeamID 加上執行中應用程式本身的 TeamID）。
* 針對「輔助使用」，應優先使用已簽署的橋接／應用程式身分，而非通用的 `node` 執行階段。將「輔助使用」權限授予 `node`，會讓該 Node 可執行檔啟動的任何套件都繼承 GUI 自動化存取權；請參閱 [macOS 權限](/zh-TW/platforms/mac/permissions#accessibility-grants-for-node-and-cli-runtimes)。
* 要求會在 10 秒後逾時（`requestTimeoutSec: 10`）。
* 若缺少必要權限，橋接會傳回清楚的錯誤訊息，而不會啟動「系統設定」。

## 快照行為（自動化）

快照儲存在記憶體中，有效期限為 10 分鐘，上限為 50 個快照（`InMemorySnapshotManager`）；清理時不會刪除成品。若需要保留更長時間，請從用戶端重新擷取。

## 疑難排解

* 若 `peekaboo` 回報 "bridge client is not authorized"，請確定用戶端已正確簽署，或僅在 **debug** 模式下使用 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` 執行主機。
* 若找不到任何主機，請開啟其中一個主機應用程式（Peekaboo.app 或 OpenClaw\.app），並確認已授予權限。

## 相關內容

* [macOS 應用程式](/zh-TW/platforms/macos)
* [macOS 權限](/zh-TW/platforms/mac/permissions)