OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

macOS 上的閘道

OpenClaw.app 不會內含節點或閘道執行階段。macOS App 需要安裝外部 openclaw 命令列介面，不會將閘道當作 子行程啟動，並管理每位使用者各自的 launchd 服務，讓閘道 持續執行（或連接至已在本機執行的閘道）。

自動設定

在全新的 Mac 上，於新手引導期間選擇 This Mac。App 會在閘道精靈之前執行其 已簽署且內含的安裝程式指令碼：它會安裝 使用者空間的節點執行階段，以及相符的 openclaw 命令列介面至 ~/.openclaw 下， 接著安裝並啟動每位使用者各自的 launchd 服務。此方式不需要 終端機、Homebrew 或管理員權限。

App 僅內含安裝程式指令碼，不包含節點或閘道承載內容； 設定時需要網際網路連線，以下載執行階段及相符的 OpenClaw 套件。

手動復原

手動安裝建議使用節點 24.15+；節點 22.22.3+ 也可運作。全域安裝 openclaw：

bash
npm install -g openclaw@<version>

自動設定失敗後，請使用 Retry setup。若仍然失敗， 請使用上述命令手動安裝命令列介面，然後在新手引導中選擇 Check again。

Launchd（將閘道作為 LaunchAgent）

標籤：ai.openclaw.gateway（預設設定檔），或具名設定檔使用 ai.openclaw.<profile>。

Plist 位置（每位使用者）：~/Library/LaunchAgents/ai.openclaw.gateway.plist （或 ai.openclaw.<profile>.plist）。

在本機模式下，macOS App 負責預設設定檔的 LaunchAgent 安裝／更新。 命令列介面也可以直接安裝：openclaw gateway install （透過 OPENCLAW_PROFILE 環境變數選取具名設定檔）。

行為：

  • 「OpenClaw Active」會啟用／停用 LaunchAgent。
  • 結束 App 不會停止閘道（launchd 會讓它保持執行）。
  • 如果閘道已在設定的連接埠上執行，App 會連接至該閘道， 而不是啟動新的閘道。

記錄：

  • launchd 標準輸出：~/Library/Logs/openclaw/gateway.log（設定檔使用 gateway-<profile>.log）
  • launchd 標準錯誤：已抑制
  • 如果主機因重複的 EADDRINUSE 或快速重新啟動而陷入迴圈，請檢查是否有 重複的 ai.openclaw.gateway／ai.openclaw.node LaunchAgent，以及 閘道疑難排解中的 launchd 標記因應措施。

版本相容性

macOS App 會將閘道版本與其自身版本比較。如果現有命令列介面不存在或 不相容，新手引導會自動執行受管理的設定。使用 Retry setup 可重新安裝， 或在修復外部命令列介面後使用 Check again。

macOS 上的狀態目錄

請將 OpenClaw 狀態保存在本機、未同步的磁碟上。避免使用 iCloud Drive 和其他 雲端同步資料夾；同步延遲和檔案鎖定可能會影響工作階段、 認證資訊及閘道狀態。

僅在需要覆寫時，才將 OPENCLAW_STATE_DIR 設為本機路徑。 openclaw doctor 會針對常見的雲端同步狀態路徑發出警告，並建議 移回本機儲存空間。請參閱 環境變數和 診斷工具。

偵錯 App 連線能力

使用原始碼簽出中的 macOS 偵錯命令列介面，測試 App 所使用的相同閘道 WebSocket 交握和探索邏輯：

bash
cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect 接受 --url、--token、--timeout、--probe 和 --json （以及用戶端身分覆寫；使用 --help 執行以取得完整清單）。 discover 接受 --timeout、--json 和 --include-local。需要區分 命令列介面探索問題與 App 端連線問題時，請將 探索輸出與 openclaw gateway discover --json 比較。

快速檢查

bash
openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

然後：

bash
openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

相關內容

Was this useful?
On this page

On this page