openclaw update · 備份釘扎 · doctor · 回滾
已上線 OpenClaw 的開發者與小團隊在跟進版本時，常見痛苦不是「不會跑 openclaw update」，而是升級後 Gateway 起不來、埠仍被舊程序佔用、PATH 指向舊二進位制、配置遷移與工具配置被靜默改寫。本文先拆五條升級風險，再給官方 update 路徑與 npm 全域性、原始碼安裝的對照表、六步可復現 Runbook（含備份與通道策略）、升級後 doctor 與健康檢查順序，以及埠衝突與雙安裝證據表；並與多平臺安裝與守護程序、安裝與 doctor 排障、執行期排障互鏈，便於把升級、觀測與回滾一次對齊。
官方文件推薦 openclaw update 並在升級後跑 openclaw doctor，但生產環境還會疊加守護程序未隨包管理器切換、舊 Gateway 未釋放監聽、以及多份 CLI 並存。若你已在閱讀生產加固清單，會知道通道白名單與監聽面收斂和升級順序強相關；跳過停止 Gateway 直接換包，常見症狀是 18789 埠仍被舊程序佔用。
程序與包版本脫節：全域性 npm 已升到新版本，但 launchd 或 systemd 仍拉起舊工作目錄裡構建的二進位制，表現為 openclaw --version 與 gateway status 報告不一致。
配置遷移與靜默改寫：大版本可能調整 openclaw.json 欄位語義，doctor 會嘗試遷移，但若合併策略與團隊 GitOps 流程未對齊，會出現「檔案在磁碟上變了但評審記錄裡沒有」。
自動更新通道與變更視窗衝突：穩定通道延遲與抖動設計是為避免全員同時爆炸，但若與業務釋出視窗未對齊，會在週五晚觸發計劃外重啟；與通道探針組合時更要先確認 Gateway 真重啟成功。
回滾證據不足：沒有備份或釘版本記錄時，只能「再裝一遍最新」而不是回到已知良好狀態；與常駐雲端部署聯用時，節點上往往還有定時任務與外部 webhook，回滾順序錯了會放大停機。
觀測欄位缺失：只儲存「升級成功」截圖而不儲存 gateway status --deep 與監聽地址，事後無法證明當時繫結面是否符合安全基線。
把以上五條寫成釋出前勾選清單，再進入下一節對比安裝路徑，才能把「能更新」升級到「可審計、可回滾的更新」。個人筆記本上的休眠與系統更新視窗也會讓守護程序狀態短暫不一致；需要合同化 SLA 的雲端 Mac 節點才能把升級視窗與可用性條款寫進驗收範圍。
三條路徑沒有絕對優劣，只有與團隊規模、是否要釘提交審計、以及是否允許自動重啟 Gateway是否匹配。官方 update 子命令適合大多數團隊；全域性包管理器路徑適合 CI 映象；原始碼適合要貢獻補丁或鎖 dev 通道的工程組。
| 維度 | openclaw update | npm 全域性 / brew | git 原始碼構建 |
|---|---|---|---|
| 上手成本 | 低；一條命令串聯拉取、doctor、重啟提示 | 中；需自己串聯 doctor 與 gateway 重啟 | 高；需 pnpm 構建與路徑管理 |
| 版本可追溯 | 中；依賴釋出後設資料 | 強；鎖 package 版本號 | 強；可釘 commit SHA |
| 回滾路徑 | 中；配合釘版本與備份 | 強；npm i -g openclaw@x | 強；git checkout 後重建 |
| 自動化友好 | 強；適合 runbook | 強；適合映象層 | 弱；構建耗時與快取策略複雜 |
| 與守護程序 | 需確認 stop 再 start 順序 | 同左 | 最易出現雙路徑並存 |
可持續升級的關鍵，是「失敗能否用版本號與備份路徑解釋」，而不是「偶爾能起 gateway」。
若你已在實踐多平臺 install-daemon，把本節選型結論寫進運維手冊，可避免「文件寫 brew、機器上卻是 npm、定時任務又指向第三條路徑」的三體問題。
下面六步刻意可在 on-call 手冊裡逐條打勾：無論你用何種安裝方式，只要順序一致，新同事可以在一小時內完成一次演練。與執行期三段分流聯用時，請在升級後保留一份 gateway status 輸出片段，便於與通道層、模型層問題區分。
凍結變更視窗：在變更單裡寫明目標版本號與允許中斷的分鐘數；禁止與大規模模型金鑰輪換同一晚執行。
備份配置與身份路徑：使用官方備份能力或至少打包 ~/.openclaw 中與配置、身份相關的目錄；校驗備份校驗和。
優雅停止 Gateway：先 openclaw gateway stop，確認監聽釋放，再執行更新命令；避免半升級態佔用埠。
執行更新並記錄通道：若使用 openclaw update，儲存命令輸出中的版本與通道資訊到工單索引欄位。
執行 doctor 與 health：按順序執行，收集遷移提示與告警；有非預期欄位變更時暫停自動重啟並人工 diff。
探針通道與最小訊息：在允許的環境發一條探針訊息或呼叫 channels status，確認回撥路徑仍可達。
openclaw gateway stop openclaw update openclaw doctor openclaw gateway start openclaw health openclaw gateway status --deep
提示：若 update 內建重啟與手動指令碼併發，可能短暫出現雙監聽；升級指令碼應序列化「停—裝—起」而非並行。
社群常見問題包含「升級後埠仍被佔用」與「CLI 顯示新版本但程序仍是舊構建」。排障時先收斂到單一真相源：監聽地址、程序二進位制路徑、包安裝路徑，再才懷疑配置。與安裝與 doctor 清單交叉閱讀時，把下列表格當作附錄貼上進工單。
埠占用：證據為 lsof -i :18789 或平臺等價命令顯示舊 PID；動作為先 gateway stop，失敗再按手冊安全殺程序並複核無殘留。
雙安裝路徑：證據為 which openclaw 與 npm root -g 指向不同字首；動作為統一 PATH 並移除冗餘全域性包或固定別名。
守護單元未重新整理：證據為 plist 或 unit 仍引用舊 WorkingDirectory；動作為重灌 daemon 或執行文件中的 force 安裝步驟後再 kickstart。
配置校驗失敗：證據為 doctor 報欄位遷移衝突；動作為從備份恢復後分步升級或手工合併 JSON 並二次 doctor。
健康檢查假綠：證據為 health 透過但通道無回撥；動作為按執行期排障文做三段分流，不提前結案。
回滾後仍異常：證據為環境變數或 shell 啟動指令碼仍注入舊 NODE_PATH；動作為清理登入會話與 CI 映象層快取。
注意：在共享節點上「幫同事試一下」臨時 export 的路徑若寫進 profile，會把個人試錯變成全域性事故；共享池場景請用獨立 Unix 使用者或容器邊界。
下列三條來自大量小團隊落地 OpenClaw 的經驗區間，用於立項前核對而非廠商承諾；你應用真實工單樣本替換它們。
| 團隊規模 | 變更頻率 | 風險承受 | 更穩的第一選擇 |
|---|---|---|---|
| 個人 | 隨意 | 高 | 官方 update + 手動停起；保留備份 zip |
| 小團隊 | 每週 | 中 | 釘 npm 版本 + 變更單 + doctor 輸出歸檔 |
| 平臺化 | 每日 | 低 | 映象層構建 + 金絲雀節點 + 自動化探針 |
| 外包協作 | 不規則 | 中 | 只讀執行手冊 + 獨立節點；禁止共享 HOME |
個人裝置上的休眠、磁碟空間與系統更新視窗會持續打斷守護程序；即便升級流程正確，本地環境仍難滿足「可驗收的升級 SLA」。相較之下，可合同化的雲端 Mac Mini 節點才能把程序常駐、網路入口與維護視窗寫進條款。
常見誤區：把「health 透過」當成「通道與模型側也健康」；健康檢查只覆蓋閘道器子集，完整驗收仍需按執行期排障順序走一遍。
若團隊需要可回滾的 OpenClaw 升級與可觀測的 Gateway 生命週期，又希望節點始終線上、避免筆記本休眠導致 Agent 中斷，對需要生產級自動化與 iOS 相關構建環境 的場景，VpsMesh 的 Mac Mini 雲端租賃通常是更優解：按週期計費、區域可選、專用節點可審計，讓升級討論建立在真實可用性之上。