在 macOS 上設定 Gateway (使用 launchd)

開發背景服務時，最煩人的就是進程管理。有時候你希望服務能獨立運作，不受主程式開啟或關閉的影響，但手動設定背景守護進程（Daemon）又很瑣碎。如果工具的內部實作跟環境變數綁得太死，除錯與維護都會變得很困難。

現在 OpenClaw.app 不再內建 Node/Bun 或 Gateway 運行環境。這意味著 macOS app 需要你安裝外部的 openclaw CLI，且不會將 Gateway 作為子進程啟動，而是透過 launchd 服務來管理。

需要準備的東西

• Node 22+: 確保你的 Mac 已經安裝此版本或更高版本。
• npm 或 pnpm: 用於安裝 CLI 工具（不推薦使用 Bun 來運行 Gateway）。

快速開始

要在 macOS 上跑起 Gateway，請遵循以下路徑：

1. 安裝 CLI

開啟你的終端機，全域安裝 openclaw：

npm install -g openclaw@<version>

你也可以在 macOS app 中點擊 Install CLI 按鈕，它會自動執行相同的 npm/pnpm 安裝流程。

2. 設定 launchd 服務

Gateway 會以 LaunchAgent 的形式運行，設定檔通常位於 ~/Library/LaunchAgents/bot.molt.gateway.plist。

你可以透過以下方式管理：

• 使用 CLI 執行 openclaw gateway install 進行安裝。
• 在 macOS app 的「Local mode」中，app 會負責安裝與更新這個 plist 檔案。

3. 驗證運行狀態

使用以下指令進行測試，確保 Gateway 可以正常啟動：

openclaw --version

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

接著檢查健康狀態：

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

運行行為與日誌

當你在 macOS 上使用這種模式時，有幾個關鍵行為你需要知道：

• 持續運行：當你開啟「OpenClaw Active」時會啟用 LaunchAgent。即使你退出了 macOS app，launchd 也會讓 Gateway 繼續在背景執行。
• 自動附加：如果 Gateway 已經在指定的 port 執行，app 會直接連接到該服務，而不會嘗試啟動一個新的進程。
• 日誌路徑：如果需要除錯，可以查看 launchd 的標準輸出與錯誤日誌：/tmp/openclaw/openclaw-gateway.log。
• 版本相容性：macOS app 會檢查 Gateway 的版本。如果兩者不相容，請更新你的全域 openclaw CLI 以符合 app 的版本。

疑難排解

版本不相容

如果 app 提示版本錯誤，通常是因為全域安裝的 openclaw 太舊。請執行 npm install -g openclaw@latest（或指定版本）來解決。

無法啟動新進程

如果你發現 app 沒有啟動新的 Gateway，請檢查是否已經有另一個 Gateway 實例佔用了相同的 port。app 在這種情況下會選擇直接連接（attach）到現有的服務。

有任何設定上的疑問嗎？你可以詢問 AI Setup Assistant 獲取即時協助。

下一步

• Gateway CLI 參數參考
• 設定設定檔與環境變數