2026年OpenClaw macOS雙LaunchAgent並存排查：ai.openclaw.gateway 與 ai.openclaw.mac 並行時的 launchctl 修復、設定統一與獨享遠端 Mac SSH 無頭運行清單 + FAQ
在單一 macOS 主機上，OpenClaw 常把職責切開：閘道（ai.openclaw.gateway）負責對外 HTTP／WebSocket 與路由；Mac 執行端（ai.openclaw.mac）承載僅 Apple 生態才有的 CLI、UI 自動化掛鉤與本機推論端點。兩者都用 launchd 常駐是合理設計——但啟動順序錯置、重複環境與埠衝突，正是最常見的故障型態。本文給出可復現的 launchctl 修復流程、OPENCLAW_* 單一來源佈局，以及獨享遠端 Mac SSH 無頭檢核表。若你要把「長駐服務＋ SSH 帳戶隔離」寫進企業 Runbook，建議延伸閱讀 2026年企業 iOS/macOS CI 選型：GitLab Runner 與 GitHub Actions 自託管 Runner 對比——獨佔遠端 Mac 節點上的併發、SSH 帳戶隔離與運維 FAQ；資源池層級的 TCO 與 SSH 穩定度取捨可對照 2026年iOS/macOS CI資源池選型：單台高配獨占遠端Mac vs 多台獨占節點 FAQ。
1. 為什麼會有兩個 LaunchAgent？
閘道（ai.openclaw.gateway）：綁定對外或 VPN 面向的埠，處理 TLS 終止（若搭配本機反向代理）、將 RPC 分發給工作者，並應在 loopback 依賴可達後再啟動。
Mac 代理（ai.openclaw.mac）：執行 macOS 專屬任務——xcodebuild、公證流程、AppleScript／捷徑、螢幕擷取類工具——而不強迫閘道行程繼承 GUI 工作階段。
標籤（Label）分開可避免 launchctl list 語意模糊，並讓你單獨重啟其中一側而不拆掉另一側。
2. 精簡結論：並存規則
- 一份環境、兩份 plist：兩個 Agent 讀同一組
EnvironmentVariables，或透過 wrapper 載入共用的~/.config/openclaw/env——不要讓OPENCLAW_HOME在兩邊分叉。 - 埠是契約：閘道聽
OPENCLAW_GATEWAY_PORT（範例）；Mac 代理走 loopback RPC 或 UNIX socket——把這組合寫進 Runbook。 - ThrottlePolicy：若 Mac 代理在鑰匙圈或 Xcode 授權精靈尚未就緒前就反覆重生，請在 plist 加
ThrottleInterval。 - 無頭 Mac：需要視窗伺服器 API 時，要有穩定的 GUI 登入脈絡；純 SSH、未授權輔助使用／螢幕錄影時，錯誤往往「看起來像隨機」。
3. 盤點：launchd 眼中的狀態
SSH 進主機、在變更 plist 前先快照：
launchctl print gui/$(id -u)/ai.openclaw.gateway，以及同樣對ai.openclaw.mac執行。- macOS 13+：
launchctl blame gui/$(id -u)/ai.openclaw.gateway可看最近一次退出原因。 log show --style syslog --predicate 'process == "launchd"' --last 15m再篩你的 Label。
4. launchctl 修復順序（建議安全序）
- Boot out 殘留工作：
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist（ai.openclaw.mac同理）。這會卸載執行中實例，不刪檔案。 - 重新載入 plist：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist——先閘道，再 Mac 代理。 - 若
RunAtLoad為 false 需手動起：launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway - 核對退出碼：
launchctl print gui/$(id -u)/ai.openclaw.gateway | grep -i lastexit
剛改過 plist 時，務必先 bootout 再 bootstrap；load／unload 在不同 macOS 世代語意有差，建議固定用現代組合。
5. 設定統一檢核表
| 關注點 | 閘道 plist | Mac 代理 plist |
|---|---|---|
OPENCLAW_HOME |
必須與安裝根目錄絕對路徑一致。 | 完全相同；避免 ~ 展開陷阱，請寫 /Users/…。 |
PATH |
若未在 ProgramArguments 寫死 node，請納入 Homebrew bin。 |
若 shell 出來呼叫 xcodebuild，補齊工具鏈路徑或先修好 xcode-select。 |
| 機密 | API 金鑰放 EnvironmentVariables，或 launchd 可讀、權限 0600 的檔案。 |
同一檔案；輪換時不要兩份 plist 各抄一份導致不同步。 |
| 工作目錄 | WorkingDirectory 指向閘道套件根。 |
常與閘道相同；若不同，仍應共用 OPENCLAW_CONFIG 路徑。 |
| 節流／當機 | KeepAlive 搭配 SuccessfulExit false，可吸收乾淨關閉。 |
開機鑰匙圈競態時，ThrottleInterval 建議 ≥ 5 秒。 |
6. 獨享遠端 Mac：SSH 無頭「單租戶」清單
把機器視為自動化的單一承租：多位管理員重疊 GUI 工作階段時，螢幕錄影與輔助使用的同意狀態最容易髒掉。
- SSH 強化：僅金鑰登入、
AllowUsers automation、長建置時調ClientAliveInterval。 - 工作階段策略：專用自動化使用者持有簽章身分鑰匙圈；不要與真人桌面帳戶混用。
- 無頭 GUI：需要視窗伺服器 API 時，確認自動登入或保留的主控台工作階段；並文件化哪些流程純 TTY 即可。
- 可觀測性：日誌 tee 到
~/Library/Logs/OpenClaw/並輪替；事故後保留launchctl print快照。 - 更新：macOS 大版本與 Xcode 升級要設閘；升級後重跑
xcode-select與公證煙測，再推 plist 變更。
7. FAQ：現象 → 懷疑 → 處置
| 現象 | 較可能原因 | 處置 |
|---|---|---|
| 只有一個 Job 起來，另一個立刻退出 | OPENCLAW_HOME 不一致，或 ProgramArguments 二進位路徑缺失。 |
在互動式 shell 用相同 argv 跑通，再把絕對路徑抄回兩份 plist。 |
閘道日誌出現 EADDRINUSE |
殘留閘道或通道仍佔埠。 | lsof -nP -iTCP:<port> -sTCP:LISTEN；bootout 閘道；對齊通道上游。 |
SSH 手動可跑、launchd 下失敗 |
環境不同（HOME、TMPDIR、鑰匙圈 ACL）。 |
把 shell 環境鏡像進 plist；在自動化 GUI 工作階段解鎖鑰匙圈一次。 |
| 每隔幾秒反覆重啟 | 網路或 DNS 尚未就緒即崩潰。 | 加 ThrottleInterval；依賴側等閘道健康檢查回 200 再啟。 |
| 螢幕擷取權限錯誤 | 無頭使用者從未完成 TCC 同意。 | 在實體／主控台工作階段完成同意；企業環境可改以 MDM 描述檔治理。 |
8. 在 Mac mini 上讓雙 Agent 安靜地常駐
雙 LaunchAgent 拓撲正是 Apple Silicon Mac mini 擅長的負載：原生 Unix 服務、可預期的溫控曲線，以及閘道 I/O 與本機推論並存時仍保有的記憶體頻寬餘裕——卻沒有塔型工作站的風扇噪音。macOS 與 launchd、SSH、開發者工具鏈銜接順手，Mac 代理路徑也不必為了虛擬化再套一層 shim。
Mac mini M4 待機往往僅數瓦級功耗，卻能維持統一記憶體架構的高頻寬；Gatekeeper、SIP、FileVault 等多層機制，也讓單租戶 SSH 自動化主機的暴露面通常小於一般常開的 Windows 工作站。若你需要獨享、長開的遠端 Mac 來承載 OpenClaw，又不想為機櫃與散熱付出過高固定成本，Mac mini M4 仍是平衡效能、體積與總擁有成本的務實起點。
若你希望把上文雙 Agent 模式跑在「不跟你搶電、也不跟你搶耳朵」的硬體上，建議從首頁的 Mac mini M4 方案出發，把同一套 plist 佈局對應到租賃或自有主機即可。