OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

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 命令列介面。請參閱電腦操作。
  • 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
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

安全性與權限

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

快照行為（自動化）

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

疑難排解

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

相關內容

Was this useful?
On this page

On this page