macOS App

OpenClaw macOS Companion（選單列 + 閘道代理程式）

macOS 應用程式是 OpenClaw 的 選單列伴隨程式。它擁有權限，在本機管理/附加至閘道（launchd 或手動），並將 macOS 功能作為節點暴露給代理程式。

功能簡介

在選單列中顯示原生通知和狀態。
擁有 TCC 提示（通知、輔助功能、螢幕錄製、麥克風、語音辨識、自動化/AppleScript）。
執行或連線至閘道（本機或遠端）。
暴露僅限 macOS 的工具（Canvas、Camera、螢幕錄製、system.run）。
在遠端模式（launchd）下啟動本機節點主機服務，並在本機模式下停止它。
選擇性地託管 PeekabooBridge 以進行 UI 自動化。
根據請求透過 npm/pnpm 安裝全域 CLI（openclaw）（不建議將 bun 用於閘道執行時）。

本機與遠端模式

本機（預設）：如果存在執行中的本機閘道，應用程式會附加至它；否則它會透過 openclaw gateway install 啟用 launchd 服務。
遠端：應用程式透過 SSH/Tailscale 連線到 Gateway，且永不啟動本機程序。應用程式會啟動本機 node host service，讓遠端 Gateway 能夠連線到此 Mac。應用程式不會將 Gateway 產生為子程序。 Gateway 探索現在會優先使用 Tailscale MagicDNS 名稱而非原始 tailnet IP，因此當 tailnet IP 變更時，Mac 應用程式能更可靠地復原。

Launchd 控制

應用程式管理標記為 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，請從應用程式啟用它或執行 openclaw gateway install。

節點功能

macOS 應用程式將自己呈現為一個節點。常見指令：

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

該節點會報告一個 permissions 映射，以便代理程式決定允許什麼。

節點服務 + 應用程式 IPC：

當無頭節點主機服務執行時（遠端模式），它會作為節點連接到 Gateway WS。
system.run 在 macOS 應用程式（UI/TCC 上下文）中透過本機 Unix 套接字執行；提示和輸出保留在應用程式內。

圖表 (SCI)：

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

執行核准 (system.run)

system.run 由 macOS 應用程式中的執行核准控制（設定 → 執行核准）。安全性 + 詢問 + 允許清單會在本機 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 ），然後與應用程式的環境合併。
對於 shell 包裝程式（ bash|sh|zsh ... -c/-lc ），請求範圍的環境變數覆寫會被縮減為一個小的明確允許清單（ TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR ）。
在允許清單模式下對「一律允許」的決策，已知的調度包裝器（env、nice、nohup、stdbuf、timeout）會保留內部可執行檔路徑，而不是包裝器路徑。如果解包不安全，則不會自動保留任何允許清單項目。

Deep links

該應用程式註冊了 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，執行過程將為無人看管（適用於個人自動化）。

上線流程（典型）

安裝並啟動 OpenClaw.app。
完成權限檢查清單（TCC 提示）。
確保 Local 模式已啟用且 Gateway 正在執行。
如果您想要終端機存取權，請安裝 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）

使用 debug 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>：從設定解析（預設：config 或 local）
--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 在遠端模式下執行時，它會開啟 SSH 通道，讓本機 UI 元件能夠與遠端 Gateway 通訊，就像該 Gateway 位於 localhost 一樣。

控制通道（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 將會看到的節點 IP 為 127.0.0.1。如果您希望顯示真實的用戶端 IP，請使用 Direct (ws/wss) 傳輸（請參閱 macOS remote access）。

關於設定步驟，請參閱 macOS remote access。關於協定細節，請參閱 Gateway protocol。