在 macOS 上，OpenClaw 閘道常由 launchd 監督。維運人員——有時還有代理本身——會試圖從「正依賴閘道的那個工作階段」裡「順手重啟閘道」。此模式可能在啟動重啟的 RPC 仍附著時就卸載 LaunchAgent，現場常見閘道再也起不來、直到有人用另一個 shell 登入。本手冊說明原因、提供安全與不安全行為的決策表、列出七個可執行步驟與數值門檻，並連結復原與並發深度文章。
變更前先讀 LaunchAgent 閘道復原 與 互動聊天與長時工作區並發，避免重啟與沈重工作區相撞。首次安裝仍依 安裝與部署。帳號層問題見 說明中心；閘道與 CI 拆機請看 套餐。權杖與 plist 漂移請對照 權杖與設定漂移；排程與閘道對齊見 排程任務對齊；429 與退避見 速率限制矩陣。
失敗模式：launchd 下的「自斬首」
把閘道同時想成伺服器與你正在執行之指令的依賴。當代理透過閘道擁有的同一 RPC 通道發出 openclaw gateway restart（或等效包裝），launchd 可能在乾淨交接完成前就對該工作 bootout。發起重啟的 CLI 可能以傳輸錯誤結束，且無人保證會 bootstrap 回健康態——在僅暴露 SSH 的無頭主機尤其如此。
- 徵兆 A：代理一叫重啟，
gateway status在同一秒內從執行中變成消失。 - 徵兆 B：日誌裡 launchd 卸載行與 RPC 斷線錯誤相鄰。
- 徵兆 C：外部監控（HTTP 健康或 TCP）逾時數分鐘，但 loginwindow 尚未建立使用者工作階段。
矩陣：誰可以重啟閘道
| 角色 | 典型情境 | 結論 | 較安全替代 |
|---|---|---|---|
| 人類維運（第二條 SSH） | screen 或純 ssh user@host | 首選 | 依文件執行 bootout／bootstrap 並保存日誌 |
| OpenClaw 內的自動化代理 | 處理聊天時的工具呼叫 | 避免重啟 | 開票；由外部編排在互斥後重啟 |
| 排程 LaunchAgent | 夜間漂移修復 | 若 plist 隔離則可 | 與聊天尖峰錯開；見上文排程對齊連結 |
| 同一臺 Mac 上的 CI 作業 | 管線步驟「彈一下閘道」 | 不建議 | 專用管理作業佇列與分離憑證 |
第二張矩陣：重啟前檢查清單
| 檢查項 | 通過條件 |
|---|---|
| 監聽擁有權 | 設定的閘道埠族僅對應一個 PID；回滾筆記寫下該 PID |
| 日誌磁碟空間 | 狀態與日誌所在卷宗至少保留 8 GB 可用空間，避免寫入中途失敗 |
| 與長作業互斥 | 沒有工作區作業仍握著你為閘道維護定義的編譯互斥層級 |
| 權杖連續性 | 用戶端可從磁碟重載權杖，無需互動 GUI 提示 |
每次應記錄的運維數字
- 冷啟預算：
bootstrap後宣告失敗前至少留 90 秒；防毒或「完整磁碟取用」對話框待處理時更長。 - RPC 探針間隔：首分鐘每 5 秒 輪詢一次，之後指數退避。
- 並行管理動作：每臺主機同時僅允許 一項會改變閘道的操作；平行改 plist 最容易搞不清哪次變更害健康轉紅。
無頭提示：若懷疑 GUI 權限對話框，暫時以 VNC 連線點通一次，再回到純 SSH 維運。
七步主機操作（HowTo 敘事展開）
- 停止透過故障閘道下指令。對同一臺 Mac mini M4 再開第二條 SSH；此工作階段不得依賴你即將回收的那條 RPC。
- 蒐集證據：狀態、近期日誌、你認定為權威的 plist 路徑——與權杖／設定漂移指南交叉比對。
- 以
lsof等工具確認監聽者，避免實驗室共用機上bootout錯 PID。 - 依 macOS 版本使用適當的 launchd 語意卸載，再從磁碟 bootstrap，讓編輯過的 EnvironmentVariables 與 WorkingDirectory 真的生效。
- 在外部 shell 探測健康，直到 RPC 檢查通過；僅此時才重連聊天用戶端。
- 寫一行事故備註：時間戳、原因、聊天或 CI 是否受影響——之後與速率限制文章交叉極快。
- 若仍不健康，回到 LaunchAgent 復原文切換到已知良好 plist，並避免在代理會話內重試重啟迴圈。
常見問題
能用 Ansible 自動重啟嗎？
可以，前提是 Playbook 的控制連線絕不經過你正要重啟的閘道行程。把閘道當資料庫：從編排面彈性重啟，而非從客戶端查詢內重啟。
開發與正式若各有一個閘道？
分開 plist、連接埠與狀態目錄。文件化哪個 LaunchAgent 標籤對應哪個環境，bootout 才不會打錯標籤。
何時應完全拆主機？
聊天 SLO 與 CI 搶占在互斥層級後仍衝突時——從 NodeMac 再加一臺專用 Mac mini M4，比在單一 launchd 圖上堆疊不相容生命週期更安全。
可靠的 OpenClaw 維運與建置敘事相同：專用 Mac mini M4 帶來 Apple Silicon 效能與 原生 macOS，SSH 做無頭維護、需要介面權限提示時用 VNC，並可選 香港、日本、韓國、新加坡、美國 讓值班更接近凌晨三點要喚醒的機器。租用而非採購讓「閘道專用第二臺主機」在經濟上合理——當本手冊證明你不該把實驗代理與正式聊天塞在同一 launchd 圖時。在堆疊下一個風險前，先對照 套餐頁 的區域方案。