2026 OpenClaw 網關排障 Runbook：從官方 command ladder 到 gateway install --force——解決「Runtime: stopped」、18789 埠佔用與非 loopback 綁定鑑權失敗（Mac 雲 7×24）
升級或換機後最常見不是「模型壞了」，而是網關 Runtime 顯示 stopped、18789 被舊進程佔住、或把 bind 改成 lan/tailnet 卻未配 gateway.auth。本文寫給已在 Mac 雲或自建 macOS 上跑 OpenClaw、需要可抄值班 Runbook 的運維：先按官方推薦的 command ladder 收集證據，再用 gateway status --deep 區分「CLI 配置」與「launchd 服務」漂移；明確何時應執行 gateway install --force 與 gateway restart；最後給出 Mac 雲 7×24 下 plist 與日誌路徑、升級後三條驗收與 FAQ。讀完你應能把「憑感覺重啟」收斂為可復現步驟。
本文要點
1. 導語：為何先 ladder 再談模型與通道
OpenClaw 網關同時承載本地 RPC、控制面健康檢查與通道插件：「通道不回」與「Runtime: stopped」表象相似，根因常在控制面。若跳過 openclaw status 與 openclaw gateway status 直接改模型或重登 IM，容易把「非 loopback 未配 gateway.auth.token」誤判成「提供商 429」，把「舊 launchd 單元仍佔 18789」誤判成「Docker 網絡壞了」。2026 年官方 troubleshooting 推薦的最低紀律仍是固定順序：status → gateway status → logs → doctor →（必要時）channels status --probe；僅在證據指向服務元數據陳舊時，再進入 gateway install --force 與重啟。下文先把四條高頻痛點拆開，再給分流表與可執行步驟。
2. 痛點拆解：stopped、埠、bind/auth、服務漂移
- Runtime: stopped：常見於升級後 stricter 默認、
gateway.mode丟失或未設local；也可能只是 launchd 單元未加載成功，CLI 仍讀舊 home 下配置。 - 18789 EADDRINUSE：舊網關進程、並行 Docker 映射或遺留 launchd 任務未退出；需用
lsof -i :18789與gateway status --deep對照「誰持有監聽」。 - 非 loopback 綁定鑑權：將
gateway.bind設為lan/tailnet/custom時，若未配置gateway.auth或 token 漂移，日誌會出現refusing to bind類提示；這與模型側超時無關。 - CLI 與服務配置不一致：同一臺 Mac 雲既用終端調試又用 launchd 託管時，
Config (cli)與Config (service)路徑不一致會導致「終端裡好了、服務仍起不來」；gateway install --force用於把服務元數據與當前 profile 對齊。
3. 症狀 → 根因分流表
| 現象 | 優先根因 | 第一反應（避免） |
|---|---|---|
Runtime: stopped 且日誌提示 gateway.mode | 配置缺失或被覆蓋 | 先重裝整包依賴 |
| 啟動即 EADDRINUSE 18789 | 舊進程/重複服務單元 | 改隨機埠逃避 |
| 非 loopback 綁定失敗 | gateway.auth 未對齊 | 把 bind 改回 0.0.0.0 卻不設 token |
| CLI 正常、launchd 仍失敗 | 服務安裝漂移 | 僅手動 node 拉起而不修單元 |
install --force 前截取 gateway status --deep 與最近 200 行日誌時間窗，便於區分一次性事故與配置漂移。
4. 落地步驟：ladder → deep → install --force（≥5 步）
- 跑官方 ladder：
openclaw status→openclaw gateway status→openclaw logs --follow（短窗）→openclaw doctor→openclaw channels status --probe；期望gateway status出現Runtime: running與探針 ok。 - 加深掃描：
openclaw gateway status --deep對照「CLI vs service」路徑、重複單元提示、埠佔用摘要。 - 修復綁定與鑑權：若必須非 loopback，補齊
gateway.auth.mode/gateway.auth.token與反向代理或 Tailscale 策略；否則先把 bind 收斂到 loopback 驗證通路。 - 處理 18789 衝突：
lsof -i :18789定位 PID；優雅退出舊網關後再啟動；Docker 場景核對是否雙容器映射同一宿主機埠。 - 對齊服務元數據：當 deep 顯示安裝漂移或升級後單元未刷新時執行
openclaw gateway install --force，隨後openclaw gateway restart，再用 ladder 前兩條驗收。
示例：在確認非生產調試可短暫停機時，可用下列順序（按環境替換路徑與用戶）：
5. 可引用技術信息：埠、探針與 plist 欄位
- 默認監聽：網關默認 HTTP 埠 18789；變更後需在防火牆與安全組同步放行，並在 Mac 雲安全組文檔中登記。
- 探針期望：
gateway status健康時應能看到運行態與連通性探針 ok；若僅 CLI 正常而服務 stopped，優先查 launchd 退出碼與日誌目錄掛載。 - launchd：常見 plist 由
gateway install寫入用戶LaunchAgents；升級後若域或 WorkingDirectory 改變，會導致「能裝不能跑」，需用--deep提示清理重複單元。 - 日誌窗口：排障時固定 2～5 分鐘時間窗比對「配置變更」與「首次失敗」時間戳，避免把歷史 WARN 當成當前根因。
- 回滾策略：在執行
install --force前備份~/.openclaw下與網關相關的 json/yaml 與自定義 env；回滾時恢復文件再重啟服務。
6. Mac 雲與替代方案局限：為何長期仍推薦獨佔 Mac 節點
在共用 Linux VPS 或臨時容器裡硬跑網關，短期可驗證功能，但會遇到三類長期成本：內核與 launchd 語義不一致導致排障手冊無法復用到 macOS 真機；埠與卷權限漂移讓 18789 與日誌路徑更難對齊值班；安全面更難做到「最小暴露 + 可審計 Token」與團隊 SSH 習慣統一。相較之下，租賃 VPSMAC 的 M4 Mac 雲節點能把網關與通道放在原生 launchd + 獨佔磁碟上，按本文 ladder 與 install --force 流程即可與站內 Docker Compose、生產加固長文銜接；需要收斂暴露面與 Token 輪換時，請繼續閱讀 OpenClaw 生產加固專題完成閉環。