Platforms overview

macOS 應用程式

macOS app 是 OpenClaw 的選單列伴隨應用程式。它負責權限、在本機管理/附加至 Gateway（launchd 或手動），並將 macOS 能力以 Node 形式提供給代理。

它的作用

在選單列顯示原生通知與狀態。
負責 TCC 提示（通知、輔助使用、螢幕錄製、麥克風、語音辨識、自動化/AppleScript）。
執行或連線至 Gateway（本機或遠端）。
提供僅限 macOS 的工具（Canvas、Camera、Screen Recording、system.run）。
在遠端模式（launchd）啟動本機 Node 主機服務，並在本機模式停止它。
可選擇託管 PeekabooBridge 以進行 UI 自動化。
依需求透過 npm、pnpm 或 bun 安裝全域 CLI（openclaw）（app 會優先使用 npm，其次是 pnpm，再來是 bun；Node 仍是建議的 Gateway 執行階段）。

本機與遠端模式

本機（預設）：如果已有執行中的本機 Gateway，app 會附加到它；否則會透過 openclaw gateway install 啟用 launchd 服務。
遠端：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.snapshot、screen.record
System：system.run、system.notify

Node 會回報 permissions 對應表，讓代理可以決定允許哪些操作。

Node 服務 + app IPC：

當無頭 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 中的執行核准控制（設定 → 執行核准）。安全性 + 詢問 + 允許清單會儲存在 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 模式，或透過 PATH 呼叫命令時的裸命令名稱。
包含 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 配置以用於本機動作。

`openclaw://agent`

觸發 Gateway agent 請求。 OC_I18N_900004 查詢參數：

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

安全性：

沒有 key 時，app 會提示確認。
沒有 key 時，app 會對確認提示強制套用較短的訊息長度限制，並忽略 deliver / to / channel。
使用有效的 key 時，執行會是無人值守（用於個人自動化）。

入門流程（典型）

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

狀態目錄放置位置（macOS）

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

建議使用本機非同步狀態路徑，例如： OC_I18N_900005 如果 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。 OC_I18N_900006 連線選項：

--url <ws://host:port>：覆寫設定
--mode <local|remote>：從設定解析（預設：設定或本機）
--probe：強制執行新的健康探測
--timeout <ms>：請求逾時（預設：15000）
--json：用於比較差異的結構化輸出

探索選項：

--include-local：包含原本會被篩選為「本機」的 Gateway
--timeout <ms>：整體探索時間窗（預設：2000）
--json：用於比較差異的結構化輸出

遠端連線管線（SSH 通道）

當 macOS app 在遠端模式執行時，它會開啟 SSH 通道，讓本機 UI 元件可以像 Gateway 位於 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 通道使用 local loopback，因此 gateway 會看到 Node IP 為 127.0.0.1。如果你希望顯示真實用戶端 IP，請使用 Direct (ws/wss) 傳輸（請參閱 macOS 遠端存取）。

設定步驟請參閱 macOS 遠端存取。通訊協定詳細資訊請參閱 Gateway 通訊協定。

macOS 應用程式

它的作用

本機與遠端模式

Launchd 控制

Node 能力（mac）

執行核准（system.run）

深層連結

`openclaw://agent`

入門流程（典型）

狀態目錄放置位置（macOS）

建置與開發工作流程（原生）

偵錯 Gateway 連線能力（macOS CLI）

遠端連線管線（SSH 通道）

控制通道（Gateway WebSocket 連接埠）

相關文件

Ask OpenClaw

# 它的作用

# 本機與遠端模式

# Launchd 控制

# Node 能力（mac）

# 執行核准（system.run）

# 深層連結

# openclaw://agent

# 入門流程（典型）

# 狀態目錄放置位置（macOS）

# 建置與開發工作流程（原生）

# 偵錯 Gateway 連線能力（macOS CLI）

# 遠端連線管線（SSH 通道）

# 控制通道（Gateway WebSocket 連接埠）

# 相關文件

它的作用

本機與遠端模式

Launchd 控制

Node 能力（mac）

執行核准（system.run）

深層連結

`openclaw://agent`

入門流程（典型）

狀態目錄放置位置（macOS）

建置與開發工作流程（原生）

偵錯 Gateway 連線能力（macOS CLI）

遠端連線管線（SSH 通道）

控制通道（Gateway WebSocket 連接埠）

相關文件