OpenClaw macOS IPC 架構詳解

在 macOS 上開發自動化工具時，你一定遇過權限管理的痛點。明明在終端機執行沒問題，一旦變成背景服務或換個方式啟動，系統就會彈出沒完沒了的 TCC（透明度、同意與控制）視窗，甚至直接拒絕訪問。處理 headless service 與 UI 視窗之間的溝通，往往比寫業務邏輯還要麻煩。

OpenClaw 透過一套 IPC（進程間通訊）架構解決了這個問題。這篇文章會帶你快速了解它的運作原理，讓你掌握如何穩定地在 macOS 上執行系統指令。

需要準備的東西

• macOS 系統
• 有效的 Apple 開發者簽署身分 (SIGN_IDENTITY)
• OpenClaw 專案源碼

快速開始

如果你想快速啟動並測試這套架構，只需執行以下步驟：

1. 設定簽署身分並重啟服務 在終端機中執行腳本，這會自動完成 Swift 編譯、封裝並透過 launchd 啟動服務：

   SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh

2. 確認運行狀態 腳本會清理舊的實例並重新啟動 LaunchAgent。你可以檢查 openclaw-mac 偵錯 CLI 來確認連線是否正常。

它是如何運作的

OpenClaw 的核心理念是讓一個擁有固定簽署 Bundle ID 的 GUI App 來接管所有涉及 TCC 的工作（例如通知、螢幕錄製、AppleScript 等）。

Gateway 與 Node 傳輸層

App 本身會以 local mode 執行 Gateway，並作為一個 Node 連接上去。所有的 Agent 動作都會透過 node.invoke 觸發，例如 system.run 或 canvas.*。

Node Service 與 App IPC

當一個 headless Node host service 連接到 Gateway 的 WebSocket 後，它會透過本地 Unix socket 與 macOS App 通訊：

• system.run 請求會轉發給 App。
• App 在 UI 上下文中執行指令，必要時彈出提示，最後回傳結果。

通訊架構圖：

Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)

UI 自動化 (PeekabooBridge)

針對 UI 自動化，OpenClaw 使用了獨立的 Unix socket (bridge.sock) 與 PeekabooBridge 協議。客戶端會依序嘗試連接：Peekaboo.app → Claude.app → OpenClaw.app → 本地執行。

為了安全，這部分通常要求 TeamID 匹配。在開發環境中，如果你需要測試未簽署的客戶端，可以使用以下環境變數：

PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1

安全強化建議

在處理這類權限敏感的架構時，安全性是首要考量：

• 權限隔離：IPC socket 權限應設為 0600，並配合 HMAC 挑戰/響應機制與短時間的 TTL。
• 身分驗證：建議強制要求所有連線對象的 TeamID 必須匹配。
• 穩定性：確保簽署的 Bundle ID 保持一致，這樣 TCC 授權才不會因為重新編譯而失效。

疑難排解

• TCC 權限重複彈出：請檢查 SIGN_IDENTITY 是否正確，並確保 Bundle ID 在重啟過程中沒有變動。
• PeekabooBridge 連線失敗：若在開發模式下遇到權限問題，請確認是否已開啟 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 標記。
• 多實例衝突：App 啟動時會檢查相同 Bundle ID 的實例，如果已有其他實例在運行，新實例會自動退出。

如果你在設定過程中遇到任何問題，可以直接詢問 AI Setup Assistant。

下一步

• PeekabooBridge 使用手冊