OpenClaw macOS 應用程式：設定與 Gateway 整合指南

身為開發者，你一定遇過這種狀況：想在 macOS 上跑 AI Agent，卻被各種權限彈窗搞得很煩，或者要在終端機跟選單列工具之間不停切換。這篇要介紹的 OpenClaw macOS 伴侶應用程式，就是為了幫你搞定這些瑣事而生的。

這款 App 不只是個選單列的小工具，它還是 OpenClaw 的權限管家與 Gateway 代理，讓你的 Agent 能順暢地調用 Mac 的原生功能。

功能介紹

• 在選單列顯示原生通知與狀態。
• 管理 TCC 權限提示（通知、輔助功能、螢幕錄製、麥克風、語音辨識、自動化/AppleScript）。
• 執行或連接到 Gateway（本地或遠端）。
• 提供 macOS 專屬工具（Canvas, Camera, Screen Recording, system.run）。
• 在 Remote 模式下啟動本地 Node 主機服務 (launchd)，並在 Local 模式下停止它。
• 可選擇託管 PeekabooBridge 用於 UI 自動化。
• 根據需求透過 npm/pnpm 安裝全域 CLI (openclaw)（不建議用 bun 執行 Gateway 執行環境）。

本地 vs 遠端模式

• Local (預設)：App 會連接到正在運行的本地 Gateway；如果沒有，它會透過 openclaw gateway install 啟用 launchd 服務。
• Remote：App 透過 SSH/Tailscale 連接到 Gateway，且不會啟動本地程序。App 會啟動本地的 Node 主機服務，讓遠端 Gateway 可以連到這台 Mac。App 不會將 Gateway 作為子程序啟動。現在 Gateway 發現功能會優先使用 Tailscale MagicDNS 名稱而非原始 tailnet IP，因此當 tailnet IP 變動時，Mac App 的恢復會更可靠。

Launchd 控制

App 會管理一個標籤為 ai.openclaw.gateway 的使用者級別 LaunchAgent（使用 --profile/OPENCLAW_PROFILE 時則為 ai.openclaw.<profile>；舊版的 com.openclaw.* 仍會被卸載）。

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

如果使用具名設定檔，請將標籤替換為 ai.openclaw.<profile>。

如果尚未安裝 LaunchAgent，可以從 App 內啟用，或執行 openclaw gateway install。

Node 功能 (mac)

macOS App 會將自己呈現為一個 Node。常見指令包括：

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: camera.snap, camera.clip
• Screen: screen.record
• System: system.run, system.notify

Node 會回報一個 permissions 映射表，讓 Agent 決定哪些操作是被允許的。

Node 服務 + App IPC：

• 當 headless Node 主機服務運行時（遠端模式），它會作為 Node 連接到 Gateway WS。
• system.run 會透過本地 Unix socket 在 macOS App（UI/TCC 上下文）中執行；提示與輸出會保留在 App 內。

架構圖 (SCI)：

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

執行核准 (system.run)

system.run 由 macOS App 中的 Exec approvals 控制（設定 → Exec approvals）。安全性、詢問機制與允許清單儲存在 Mac 本地的以下路徑：

~/.openclaw/exec-approvals.json

範例：

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

注意事項：

• allowlist 項目是解析後二進位路徑的 glob 模式。
• 包含 Shell 控制或擴展語法（&&, ||, ;, |, `, $, <, >, (, )）的原始 Shell 指令文字會被視為未命中允許清單，需要明確核准（或將 Shell 二進位檔加入允許清單）。
• 在提示中選擇「永遠允許」會將該指令加入允許清單。
• system.run 的環境變數覆蓋會經過過濾（移除 PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4），然後與 App 的環境變數合併。
• 對於 Shell 包裝器 (bash|sh|zsh ... -c/-lc)，請求範圍的環境變數覆蓋會縮減為一個小的明確允許清單（TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR）。
• 對於允許清單模式下的「永遠允許」決定，已知的調度包裝器（env, nice, nohup, stdbuf, timeout）會持久化內部可執行檔路徑而非包裝器路徑。如果拆解包裝不安全，則不會自動持久化允許清單項目。

深層連結

App 註冊了 openclaw:// URL scheme 用於本地操作。

openclaw://agent

觸發 Gateway 的 agent 請求。

open 'openclaw://agent?message=Hello%20from%20deep%20link'

查詢參數：

• message (必填)
• sessionKey (選填)
• thinking (選填)
• deliver / to / channel (選填)
• timeoutSeconds (選填)
• key (選填，用於自動化模式的金鑰)

安全性：

• 若無 key，App 會提示確認。
• 若無 key，App 會對確認提示強制執行短訊息限制，並忽略 deliver / to / channel。
• 若有有效的 key，則會以自動化模式執行（適用於個人自動化工作流）。

安裝流程 (一般情況)

1. 安裝並啟動 OpenClaw.app。
2. 完成權限檢查清單（TCC 提示）。
3. 確保 Local 模式已啟用且 Gateway 正在運行。
4. 如果你需要終端機存取權限，請安裝 CLI。

狀態目錄位置 (macOS)

避免將你的 OpenClaw 狀態目錄放在 iCloud 或其他雲端同步資料夾中。同步路徑可能會增加延遲，偶爾還會導致 Session 和憑證的檔案鎖定或同步衝突。

建議使用本地非同步的狀態路徑，例如：

OPENCLAW_STATE_DIR=~/.openclaw

如果 openclaw doctor 偵測到狀態位於：

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

它會發出警告並建議移回本地路徑。

建置與開發工作流 (原生)

• cd apps/macos && swift build
• swift run OpenClaw (或使用 Xcode)
• 打包 App：scripts/package-mac-app.sh

除錯 Gateway 連線 (macOS CLI)

使用除錯 CLI 來測試與 macOS App 相同的 Gateway WebSocket 握手和發現邏輯，而不需要啟動 App。

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

連線選項：

• --url <ws://host:port>: 覆蓋設定
• --mode <local|remote>: 從設定解析（預設：設定或本地）
• --probe: 強制進行新的健康檢查
• --timeout <ms>: 請求逾時（預設：15000）
• --json: 用於比對的結構化輸出

發現選項：

• --include-local: 包含原本會被過濾掉的「本地」Gateway
• --timeout <ms>: 整體發現窗口（預設：2000）
• --json: 用於比對的結構化輸出

提示：將結果與 openclaw gateway discover --json 進行比較，看看 macOS App 的發現管線（NWBrowser + tailnet DNS-SD 備援）是否與 Node CLI 基於 dns-sd 的發現有所不同。

遠端連線管道 (SSH 隧道)

當 macOS App 在 Remote 模式下運行時，它會開啟一個 SSH 隧道，讓本地 UI 組件可以像訪問 localhost 一樣與遠端 Gateway 通訊。

控制隧道 (Gateway WebSocket 埠)

• 用途： 健康檢查、狀態、Web Chat、設定以及其他控制平面調用。
• 本地埠： Gateway 埠（預設 18789），始終固定。
• 遠端埠： 遠端主機上相同的 Gateway 埠。
• 行為： 不使用隨機本地埠；App 會重用現有的健康隧道，或在需要時重啟。
• SSH 形式： ssh -N -L <local>:127.0.0.1:<remote>，帶有 BatchMode + ExitOnForwardFailure + keepalive 選項。
• IP 回報： SSH 隧道使用 loopback，因此 Gateway 會將 Node IP 視為 127.0.0.1。如果你希望顯示真實的客戶端 IP，請使用 Direct (ws/wss) 傳輸方式（參閱 macOS 遠端存取）。

有關設定步驟，請參閱 macOS 遠端存取。有關協定細節，請參閱 Gateway 協定。

相關文件

• Gateway 運行手冊
• Gateway (macOS)
• macOS 權限
• Canvas

---

下一步：

• 了解如何配置 macOS 權限 以獲得完整體驗。
• 探索 Canvas 如何在 Mac 上實現視覺化互動。

需要協助設定嗎？試試我們的 AI Setup Assistant。