macOS 應用程式
macOS 應用程式是 OpenClaw 的選單列配套工具，負責管理權限、Gateway 連線，並向代理公開 macOS 功能。
OpenClaw macOS Companion（選單列 + Gateway 代理）
macOS 應用程式是 OpenClaw 的選單列配套工具。它擁有權限管理、在本機管理/附接 Gateway（透過 launchd 或手動），並以節點形式向代理公開 macOS 功能。
功能介紹
- 在選單列顯示原生通知與狀態。
- 擁有 TCC 提示（通知、輔助使用、螢幕錄製、麥克風、語音辨識、自動化/AppleScript）。
- 執行或連接 Gateway（本機或遠端）。
- 公開 macOS 專屬工具（Canvas、Camera、Screen Recording、
system.run）。 - 在遠端模式下啟動本機節點主機服務（launchd），在本機模式下則停止。
- 可選擇託管 PeekabooBridge 以進行 UI 自動化。
- 依請求透過 npm/pnpm 安裝全域 CLI（
openclaw）（不建議將 bun 用於 Gateway 執行環境）。
本機模式 vs 遠端模式
- Local（預設）：應用程式會附接到執行中的本機 Gateway（如有）；否則透過
openclaw gateway install啟用 launchd 服務。 - Remote：應用程式透過 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使用命名設定檔時，將標籤替換為 ai.openclaw.<profile>。
如果 LaunchAgent 尚未安裝，可從應用程式啟用，或執行 openclaw gateway install。
節點功能（mac）
macOS 應用程式以節點形式呈現。常用指令：
- Canvas：
canvas.present、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.* - Camera：
camera.snap、camera.clip - Screen：
screen.record - System：
system.run、system.notify
節點會回報 permissions 映射，讓代理判斷哪些操作是被允許的。
節點服務 + 應用程式 IPC：
- 當無介面的節點主機服務正在執行（遠端模式），它會透過 WS 連接 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 模式。- 包含 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）會保存內部可執行檔路徑，而非包裝器路徑。如果解包不安全，則不會自動保存允許清單項目。
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。
建置與開發流程（原生）
cd apps/macos && swift buildswift 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 應用程式以 Remote 模式執行時，它會開啟 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 通道使用迴路位址，因此 Gateway 會將節點 IP 視為
127.0.0.1。如果想顯示真實的客戶端 IP，請使用 Direct (ws/wss) 傳輸方式（參見 macOS remote access）。
設定步驟請參見 macOS remote access。協定詳情請參見 Gateway protocol。