搞定 macOS 上的 Gateway 生命週期管理

身為開發者，最煩的就是後台服務莫名其妙掛掉，或者每次開機都要手動去跑一堆指令。如果背景程序沒管理好，你的 App 基本上就沒辦法正常運作。我們在 macOS 上選擇了一套更穩定的方案，讓你不用整天擔心服務有沒有跑起來。

需要準備的東西

macOS App 預設會透過 launchd 來管理 Gateway，而不是把它當成子程序（child process）啟動。App 會先嘗試連接已經在運行中的 Gateway；如果連不上，就會透過外部的 openclaw CLI 啟動 launchd 服務。

這樣做的好處是：當你登入系統時它會自動啟動，萬一當機了也會自動重啟。

常用的管理指令如下：

# 重啟 Gateway 服務
launchctl kickstart -k gui/$UID/bot.molt.gateway

# 停止 Gateway 服務
launchctl bootout gui/$UID/bot.molt.gateway

如果你有使用 --profile 或 OPENCLAW_PROFILE，請將標籤替換為 bot.molt.<profile>。

當你使用 scripts/restart-mac.sh --no-sign 進行快速本地開發時，為了防止 launchd 指向未簽名的程式碼，系統會建立一個 ~/.openclaw/disable-launchagent 檔案。

如果你之後跑了有簽名的版本，這個標記會自動被清除。你也可以手動重設：

rm ~/.openclaw/disable-launchagent

如果你希望 App 完全不要安裝或管理 launchd，可以在啟動時加上 --attach-only 或 --no-launchd 參數。這會讓 App 進入純連接模式，只會嘗試連接已經存在的 Gateway。你也可以在 Debug Settings 裡切換這個設定。

在遠端模式下，App 絕對不會啟動本地 Gateway。它會透過 SSH tunnel 連接到遠端主機，並直接使用該連線。

Gateway 沒有自動啟動：檢查是否存在 ~/.openclaw/disable-launchagent 檔案，這會阻止 App 管理 launchd。
找不到日誌：Gateway 的日誌會寫入到 launchd 指定的路徑，你可以直接去 Debug Settings 裡查看具體位置。

如果你在設定過程遇到任何卡關，可以直接詢問 AI Setup Assistant。

OpenClaw Expert

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。