macOS 上的 Gateway 生命週期

macOS 應用程式預設透過 launchd 管理 Gateway，不會將 Gateway 作為子程序啟動。它會先嘗試連接設定連接埠上已在運行的 Gateway；若無法連線，則透過外部 openclaw CLI 啟用 launchd 服務（不使用內嵌執行環境）。這讓你享有可靠的登入自動啟動以及當機自動重啟。

子程序模式（Gateway 由應用程式直接啟動）目前未使用。若你需要與 UI 更緊密的整合，請在終端機中手動執行 Gateway。

預設行為（launchd）

• 應用程式安裝一個以使用者為單位的 LaunchAgent，標籤為 ai.openclaw.gateway （使用 --profile/OPENCLAW_PROFILE 時為 ai.openclaw.<profile>；舊版 com.openclaw.* 亦支援）。
• Local 模式啟用時，應用程式確保 LaunchAgent 已載入，並在需要時啟動 Gateway。
• 日誌寫入 launchd Gateway 日誌路徑（可在 Debug Settings 中查看）。

常用指令：

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

使用具名 profile 時，請將標籤替換為 ai.openclaw.<profile>。

未簽章開發版本

scripts/restart-mac.sh --no-sign 用於沒有簽章金鑰時的快速本機建構。為防止 launchd 指向未簽章的中繼執行檔，它會：

• 寫入 ~/.openclaw/disable-launchagent。

已簽章的 scripts/restart-mac.sh 執行會在偵測到此標記時清除覆蓋。手動重設方式：

rm ~/.openclaw/disable-launchagent

僅連接模式

若要強制 macOS 應用程式永不安裝或管理 launchd，以 --attach-only（或 --no-launchd）啟動。這會設定 ~/.openclaw/disable-launchagent，讓應用程式只連接已在運行的 Gateway。你也可以在 Debug Settings 中切換此行為。

遠端模式

遠端模式不啟動本機 Gateway。應用程式使用 SSH 通道連線至遠端主機。

為什麼我們偏好 launchd

• 登入時自動啟動。
• 內建重啟／KeepAlive 語意。
• 可預期的日誌與監控。

若日後再次需要真正的子程序模式，應以獨立的、僅供開發使用的模式來記載。