OpenClaw macOS 配套應用程式（選單列 + gateway broker）

macOS 應用程式是 OpenClaw 的選單列配套程式。它管理權限、 在本機管理或連接 Gateway（launchd 或手動），並將 macOS 的功能以節點形式提供給代理程式使用。

功能說明

  • 在選單列顯示原生通知與狀態。
  • 管理 TCC 權限提示（通知、輔助使用、螢幕錄製、麥克風、語音辨識、自動化/AppleScript）。
  • 執行或連線至 Gateway（本機或遠端）。
  • 提供 macOS 專屬工具（Canvas、相機、螢幕錄製、system.run）。
  • 在遠端模式下啟動本機節點主機服務（launchd），在本機模式下則停止該服務。
  • 可選擇性地提供 PeekabooBridge 進行 UI 自動化。
  • 依需求透過 npm/pnpm 安裝全域 CLI（openclaw）（不建議以 bun 作為 Gateway 執行環境）。

本機與遠端模式

  • 本機（預設）：應用程式會連接已在運行的本機 Gateway；若沒有，則透過 openclaw gateway install 啟用 launchd 服務。
  • 遠端：應用程式透過 SSH/Tailscale 連線至遠端 Gateway，不啟動本機程序。 應用程式會啟動本機 節點主機服務，讓遠端 Gateway 能存取這台 Mac。 應用程式不會將 Gateway 作為子程序啟動。

Launchd 控制

應用程式管理一個以使用者為單位的 LaunchAgent，標籤為 ai.openclaw.gateway （使用 --profile/OPENCLAW_PROFILE 時為 ai.openclaw.<profile>；舊版 com.openclaw.* 仍會卸載）。

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

使用具名 profile 時，請將標籤替換為 ai.openclaw.<profile>。

若 LaunchAgent 尚未安裝，可從應用程式啟用或執行 openclaw gateway install。

節點功能（mac）

macOS 應用程式以節點身分運作。常用指令：

  • Canvas：canvas.present、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.*
  • 相機：camera.snap、camera.clip
  • 螢幕：screen.record
  • 系統：system.run、system.notify

節點會回報 permissions 對應表，讓代理程式判斷可使用的功能。

節點服務與應用程式 IPC：

  • 無頭節點主機服務運行時（遠端模式），會以節點身分透過 WebSocket 連線至 Gateway。
  • system.run 在 macOS 應用程式中執行（UI/TCC 環境），透過本機 Unix socket 通訊；提示與輸出留在應用程式內。

架構圖（SCI）：

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

執行核准（system.run）

system.run 由 macOS 應用程式中的 Exec approvals 控制（Settings → 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 pattern。
  • 包含 shell 控制或展開語法（&&、||、;、|、`、$、<、>、(、)）的原始 shell 命令文字會被視為允許清單未命中，需要明確核准（或將 shell 執行檔加入允許清單）。
  • 在提示中選擇「Always Allow」會將該指令加入允許清單。
  • system.run 環境變數覆蓋會經過過濾（移除 PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4），然後與應用程式的環境合併。
  • 對於 shell 包裝器（bash|sh|zsh ... -c/-lc），請求層級的環境變數覆蓋會縮減至一小組明確允許的清單（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
  • 在允許清單模式下選擇「永遠允許」時，已知的分派包裝器（env、nice、nohup、stdbuf、timeout）會保存內部執行檔路徑而非包裝器路徑。若無法安全展開，則不會自動保存允許清單項目。

應用程式註冊 openclaw:// URL scheme 用於本機操作。

openclaw://agent

觸發 Gateway agent 請求。

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

查詢參數：

  • message（必要）
  • sessionKey（選用）
  • thinking（選用）
  • deliver / to / channel（選用）
  • timeoutSeconds（選用）
  • key（選用，無人值守模式金鑰）

安全性：

  • 沒有 key 時，應用程式會提示確認。
  • 沒有 key 時，應用程式會在確認提示中限制訊息長度，並忽略 deliver / to / channel。
  • 提供有效 key 時，以無人值守方式執行（設計用於個人自動化）。

引導流程（標準）

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

狀態目錄位置（macOS）

避免將 OpenClaw 狀態目錄放在 iCloud 或其他雲端同步資料夾中。 同步路徑可能增加延遲，偶爾也會造成工作階段與憑證的檔案鎖定／同步競爭。

建議使用本機非同步路徑，例如：

OPENCLAW_STATE_DIR=~/.openclaw

若 openclaw doctor 偵測到狀態位於以下路徑：

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

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

建構與開發流程（原生）

  • cd apps/macos && swift build
  • swift run OpenClaw（或 Xcode）
  • 打包應用程式：scripts/package-mac-app.sh

除錯 Gateway 連線（macOS CLI）

使用除錯 CLI 來測試 macOS 應用程式使用的相同 Gateway WebSocket 交握與探索邏輯，無需啟動應用程式。

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

連線選項：

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

探索選項：

  • --include-local：包含會被篩選為「local」的 Gateway
  • --timeout <ms>：整體探索時間窗口（預設：2000）
  • --json：結構化輸出，便於比對

提示：將結果與 openclaw gateway discover --json 比對，看看 macOS 應用程式的探索管線（NWBrowser + tailnet DNS-SD 退回方案）是否與 Node CLI 基於 dns-sd 的探索有差異。

遠端連線機制（SSH 通道）

當 macOS 應用程式以遠端模式運行時，會開啟 SSH 通道，讓本機 UI 元件能像存取 localhost 一樣與遠端 Gateway 通訊。

控制通道（Gateway WebSocket 連接埠）

  • 用途： 健康檢查、狀態、Web Chat、設定及其他控制平面呼叫。
  • 本機連接埠： Gateway 連接埠（預設 18789），固定不變。
  • 遠端連接埠： 遠端主機上相同的 Gateway 連接埠。
  • 行為： 不使用隨機本機連接埠；應用程式重用既有的健康通道或在需要時重啟。
  • SSH 形式： ssh -N -L <local>:127.0.0.1:<remote> 加上 BatchMode + ExitOnForwardFailure + keepalive 選項。
  • IP 回報： SSH 通道使用 loopback，因此 Gateway 看到的節點 IP 為 127.0.0.1。若要顯示真實客戶端 IP，請使用 Direct (ws/wss) 傳輸方式（參閱 macOS 遠端存取）。

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

相關文件

arrow_back
上一頁
Platforms
下一頁
Linux
arrow_forward