doctor 當門禁、用巢狀路徑刪錯鍵，最後把閘道熱重載與必重啟欄位分開，並把輸出接進 CI 工件。內鏈：部落格列表、技能／回滾／doctor、閘道認證排錯、首頁。
痛點拆解：① 釋出線升級後舊片段留下未知鍵，doctor 報 invalid-key 卻不易一眼看出檔案列號。② 同一主機多 Runner／多使用者，npm prefix 與 PATH 在非互動 shell 與本機互動 shell 不一致，導致「本機過、CI 爆」。③ 以為改完 openclaw.json 已熱更新，實際監聽埠或 Bearer 模式仍握在舊行程。④ 門禁日誌沒進工件，事後無法對照二四八秒重試與網路抖動。
決策矩陣：門禁動作 × 閘道是否需重啟
| 變更類型 | 建議門禁 | 熱重載風險 | 建議動作 |
|---|---|---|---|
| 僅調整非敏感文字標籤 | doctor 乾跑 | 通常低 | 觀察 gateway status 後放行 |
| bind／TLS／auth 模式 | 乾跑＋探針 | 高 | 重啟閘道再驗 webhook |
移除 invalid-key | diff 設定＋doctor | 中 | 保留備份檔比對後合併 |
釘版 openclaw@x.y.z | npm ls -g 門禁 | 低 | 與閘道映像主線對齊表 |
前置條件清單
- Node：
node -v顯示 22.12 或以上；將node -p process.versions寫入工件避免 PATH 誤用。 - CLI 與閘道主線：全域
openclaw釘在與伺服端一致的 2026.3.x 區間，避免「客戶端 schema 新、閘道舊」的假陰性。 - 可寫目錄：
~/.openclaw與日誌路徑在 CI 使用者下可寫；磁碟可用空間預留給備份與暫存。 - 出站策略：若門禁需連模型供應商或內部鏡像，先確認代理與白名單與 RAG 預拉 文一致。
逐步命令
下列順序可在本機或 MacPull 遠端 Mac 上原樣複製；將標準輸出重新導向後上傳為建置工件即可做跨版本 diff。
set -euo pipefail
node -v
node -p "process.versions"
npm install -g "openclaw@^2026.3.0"
cp -a "${HOME}/.openclaw/openclaw.json" "${HOME}/.openclaw/openclaw.json.ckpt.${CI_PIPELINE_ID:-local}"
openclaw doctor || true
openclaw doctor --json > "${TMPDIR:-/tmp}/openclaw-doctor.json" 2>&1 || true
openclaw gateway status --json > "${TMPDIR:-/tmp}/openclaw-gateway-status.json" 2>&1 || true
檢查點命名：檔名帶 pipeline id 或提交 SHA，與 回滾教學 的 .bak 並存，便於二分搜尋。
刪 invalid-key：依 doctor 印出的巢狀路徑（例如 gateway.auth 下的未知鍵）精準刪除；勿整檔替換以免丟失註解與排序約定。
熱重載注意：文字型參數有機會由執行緒重讀，但埠、憑證、認證模式變更後請執行守護程序重載流程並再以 curl 打健康路徑驗收。
失敗重試：可恢復網路錯誤採二／四／八秒退避至多三次；超過閾值改記錄鏡像與 TLS 指紋。
回滾：npm install -g openclaw@<上一穩定版> 並還原 openclaw.json.ckpt.*；重載後再跑一輪 doctor。
常見報錯簽名與排查
簽名：invalid-key ＋ 巢狀路徑
多為複製了過期範本或第三方片段。用 doctor 全文對照官方文件欄位表；必要時暫時註解區塊外提成獨立 PR，避免與功能變更混在同一合併單。
簽名：token／password 並存阻擋
與 閘道認證排錯 相同根因：改為單一 gateway.auth.mode 或改用環境變數注入；檢查 launchctl 是否覆寫 OPENCLAW_GATEWAY_TOKEN。
簽名：Node 版本不符或原生模組載入失敗
低於 22.12 時部分依賴鏈可能無法滿足預編譯矩陣。升級 runtime 後清 npm cache 並重裝全域包。
與 CI 工件歸檔聯動
將 openclaw-doctor.json、openclaw-gateway-status.json、npm ls -g openclaw --json 與設定檔去敏後的 diff 一併上傳；若流水線支援，另附 curl -sv 健康檢查原始標頭（遮罩授權值）。與 Argo CD Webhook 摘要 類似，把「合併前狀態」與「部署後狀態」分檔命名，方便資安稽核與事後還原。
檢查表／步驟清單（列印用）
- Node 版本與
which node已寫入工件 openclaw.json備份檔已帶 pipeline／SHA 後綴doctor無invalid-key或已開追蹤單- 涉及 bind／TLS／auth 的變更已完成閘道重啟並留存狀態 JSON
- Webhook／健康探針在重試策略下連續成功
補充 FAQ
為何強調 2026.3.x 與 CLI 釘版並列？
設定 schema 與守護程序行為會隨小版本演進；門禁應讀取釋出說明中的破壞性變更段，並在矩陣中為 LTS 與最新各保留一條乾跑線。
遠端 Mac 與雲端 CI 混跑會不會漂移？
以相同黃金映像與同一套環境變數模板為準；差異只應出現在祕鑰來源，而非 Node 或全域包版本。