自動化平臺最怕網關返回 401／unauthorized，而聊天渠道表面仍「在線」。在 Mac mini M4 上，根因往往不是密碼學——而是兩份配置：交互 shell 讀到的 openclaw.json 與重啟後 LaunchAgent 守護進程看到的那份是否一致。本文給出 gateway.auth 對齊矩陣、令牌輪換要點，以及八條可復現步驟，可與健康探針、doctor 輸出一併使用。
診斷：openclaw doctor 與健康診斷。就緒：健康與就緒探針。launchd：launchd 與網關就緒。價格：定價；幫助：幫助。
故障模式矩陣
| 現象 | 可能漂移 | 首選修復 |
|---|---|---|
| 網關令牌缺失 | CLI 只把令牌寫在 shell 環境 | 寫入 JSON 的 gateway.auth；重跑 doctor |
| 迴環 RPC 探針失敗 | 埠衝突或陳舊鎖文件 | lsof -i :埠；結束多餘進程後重啟 |
| 重啟後失效 | 守護進程用戶未加載 LaunchAgent | 核對 plist 路徑，對登錄用戶執行 launchctl bootstrap |
| 渠道在線但 UI 401 | 反向代理剝離 Authorization |
與 出站 TLS 指南 對齊透傳策略 |
配置單一事實來源
| 層級 | 負責內容 | 審計方式 |
|---|---|---|
~/.openclaw/openclaw.json |
網關鑑權、綁定模式、渠道 | openclaw config get gateway.auth.token（以版本文檔為準） |
| LaunchAgent plist | HOME、TMPDIR、顯式環境覆蓋 |
與交互式 printenv 做 diff |
| 密鑰庫 | 不入 Git 的長期令牌 | 輪換 runbook + CMDB 校驗和 |
無頭 Mac 提示： 若網關需在無 GUI 登錄下 survive 重啟，請驗證安裝落在 LaunchAgents 還是 LaunchDaemons——行為不同，runbook 寫清取捨。
八步排查清單
- 復現上下文： 區分僅交互失敗還是僅守護進程失敗。
- 運行 doctor： stdout/stderr 附到工單或 CI 產物。
- 比對配置： 對服務帳戶與 shell 用戶的
openclaw.json做哈希。 - 校驗令牌欄位： 與當前 CLI 大版本文檔中的鍵名一致。
- 乾淨重啟： 停網關，在文檔允許時清陳舊鎖，再拉起。
- 迴環探針： 對齊就緒文 p95 目標（< 200 ms）。
- 日誌片段： 附脫敏後最近 200 行。
- 事後： 當
gateway status日抖動 > 3 次時告警。
常見問題
為什麼 OpenClaw 網關在終端正常，在 launchd 下失敗？
交互式 shell 會加載 profile 與環境變量，LaunchAgent 默認不繼承。令牌與代理應寫在 ~/.openclaw/openclaw.json 或 plist 的 EnvironmentVariables 中，而不能僅 export 在 shell 裡。
2026 年 macOS 上網關鑑權令牌應放在哪裡？
優先放在守護進程實際讀取的 JSON 配置中的 gateway.auth 相關欄位（以所用 CLI 大版本文檔為準）。缺失時用 openclaw doctor 生成或修復，然後重啟網關並用 openclaw gateway status 驗證。
建議先在可丟棄的 Mac mini M4 租用機上演練令牌輪換與 plist 修改，再動生產網關。NodeMac 在香港、日本、韓國、新加坡、美國提供帶 SSH／VNC 的獨佔 Apple Silicon，便於快照故障布局而無需採購備機。