2026 OpenClaw 版本升級與執行態遷移
設定目錄備份、Gateway 切換與回滾一步一檢（Docker／本機）

約 18 分鐘閱讀 · MACCOME

已在線上跑 OpenClaw 的團隊在 2026 年面對頻繁發版時，最怕三件事：latest 漂移、狀態目錄沒備份就升、Gateway 停錯順序導致權杖與卷不一致。本文不寫從零安裝，而是與《三平臺安裝》《Docker 生產》《裝後排查》《Linux systemd＋Tunnel》分工，給出痛點拆解、本機與容器雙路徑對照表、症狀—回滾矩陣、備份指令片段、六步升級 Runbook、三條值班口徑；要治理 Secrets 與暴露面時繼續讀《進階實戰》。

本文解決什麼：與站內既有 OpenClaw 系列怎麼分工

安裝篇解決「怎麼裝」；Docker 生產篇解決「怎麼常駐與排常見容器錯」；裝後篇解決「裝完跑不起來按症狀查」；Linux＋Tunnel 篇解決「裸機 systemd＋不回網暴露」。本篇只涵蓋「已在跑」前提下的升級、換機、換部署形態與回滾—把變更單寫成可簽字版本。下列六類痛點在真實值班裡最高頻，建議直接貼進變更描述。

  1. 映像或套件版本漂移：生產用 latest 或浮動標籤，回滾時找不到可復現的上一版 digest。
  2. 只備份程式庫不備份狀態：~/.openclaw（或文件指定目錄）內的金鑰、工作區與閘道設定未隨卷一併快照。
  3. 停機順序錯誤：先殺容器再匯出卷，或先改 DNS 再停舊 Gateway，導致雙寫與配對狀態錯亂。
  4. 本機與容器混用路徑：同一主機上 npm 與 Compose 爭用埠或讀寫同一目錄，升級後「以為遷完了」其實仍在讀舊路徑。
  5. 冷升級無驗證用例：升完只看行程在，不做最小模型呼叫與 Control UI 登入驗證。
  6. 回滾只降版本不還原卷：新版本已改 schema 或工作區檔案，舊二進位回來仍炸，需要卷級還原策略。

表 1：本機（npm／腳本）與 Docker Compose：升級維度對照

用於評審「這一版到底走哪條路徑升」，避免口頭約定。欄位名稱以你目前 fork／發行說明為準。

維度本機路徑Docker Compose 路徑
版本錨點鎖 npm／pnpm 版本與 lockfile；記錄 Node 小版本鎖映像 tag 或 digest；禁止 silent latest
狀態落點~/.openclaw 與本機工作區路徑bind mount／命名卷對應到宿主路徑
金鑰與權杖環境變數、鑰匙圈或 .env（勿入庫）.env、Docker secrets 或編排側變數；升前匯出備份
健康檢查CLI／本機埠探活compose ps、容器內健康命令與宿主埠
回滾抓手重裝指定套件版本＋還原目錄 tar回退映像 digest＋還原卷快照

表 2：症狀 → 優先動作（含回滾與綁定類提示）

與《裝後排查》互補：這裡強調升級窗口內的決策順序。若涉及 Control UI 與公網暴露，仍須對齊《進階實戰》的暴露面策略。

症狀優先懷疑先做仍失敗再
Gateway 重啟循環綁定位址與 UI 白名單未對齊改 loopback 綁定或補齊 allowedOrigins 類設定後重試回退上一映像 digest 並還原卷快照
配對／裝置授權異常雙實例並行或權杖輪換未通知用戶端確保舊實例完全停止；用 CLI 列裝置並依官方流程重配從備份還原舊權杖檔並短暫回滾版本
模型連通逾時出口、Proxy 或金鑰變更在容器內／宿主分別 curl 探活；輪換金鑰最小化試跑對照供應商狀態頁與防火牆策略
磁碟暴漲後升級失敗工作區與日誌無輪替清日誌前先快照；升前預留 ≥ 官方建議的剩餘空間擴碟或遷工作區到獨立卷
bash
# 例：升級前打包狀態目錄（路徑以你環境為準；勿把壓縮包提交到 git）
tar czf openclaw-state-$(date +%Y%m%d).tgz -C "$HOME" .openclaw

# Compose：在 .env 或 compose 中固定映像 digest／次要版本號，再執行 pull & up
# docker compose pull && docker compose up -d
warning

注意：任何含金鑰的備份檔權限應限制在維運角色；還原後應輪換仍可能外洩的權杖，並與《進階實戰》中的 Secrets 稽核節奏一致。

六步升級 Runbook（可貼進變更系統）

  1. 讀發行說明：標註 breaking change、資料庫／工作區 schema 遷移指令與最低 Node／核心需求。
  2. 凍結版本錨點：寫入映像 digest 或套件版本號；禁止在生產窗口內順手改 latest。
  3. 冷備份：狀態目錄 tar、compose 使用的卷或綁定路徑、以及目前 .env 的安全副本（脫敏存稽核庫）。
  4. 維護窗內切換：先停流量入口（反代／Tunnel）再停舊 Gateway；啟新實例後做健康檢查再恢復入口。
  5. 驗證：CLI 狀態、Gateway 日誌無異常、Control UI 登入、最小模型對話用例各一次。
  6. 記錄與收尾：成功則更新維運文件中的版本與 digest；失敗則執行表 2 回滾支路並開事故單。

三條應寫進值班的「硬核」口徑

  1. 可復現錨點是否存在：任意生產環境必須能回答「目前執行的 digest／套件版本號是什麼」，否則不算升級完成。
  2. 備份校驗：tar 或卷快照還原演練至少每季一次；只備份沒還原過等於沒備份。
  3. 升級—回滾時間預算：維護窗長度應覆蓋「驗證失敗＋完整還原」的最壞路徑，而不是只覆蓋 happy path。

補充：當團隊同時在筆電與伺服器上各跑一份 Gateway 時，建議在監控裡給實例加明確標籤，否則告警裡只會寫「down」卻分不清該切哪條 DNS；這與《Docker 生產》裡強調的權杖與暴露面合同是同一件事的延伸。

僅依賴個人電腦或臨時 VPS 做長期 Gateway 的局限

筆電睡眠、系統更新與不可預期的磁碟占用會把「升級窗口」變成隨機事件；臨時 VPS 若未做快照與租期對齊，回滾時往往缺一塊碟。要把 Gateway 當生產元件，需要可預期的上線時間、可恢復的磁碟與可選擇的地區，並把升級 Runbook 與監控綁定。

個人裝置與碎片化主機還難與團隊 Secrets 治理、稽核留痕對齊：誰最後一次改了權杖、哪台機器在跑 digest X，常常說不清。MACCOME 在多地區提供 Mac Mini M4／M4 Pro 實體節點與彈性租期，適合作為 OpenClaw 穩定執行層或專用 Gateway 宿主；與《多地區節點與租期指南》《SSH 與 VNC 接入決策》一起評審後，可在租賃價格說明對齊方案並在協助中心核對帳單與接入口徑。

若仍處試點階段，建議先用短租在目標區域跑通備份—升級—回滾演練，再決定是否把基線遷到月租或季租，避免把未驗證的 Runbook 直接綁在長期合約上。

常見問題

升級前最不該省略的三件事是什麼？

固定映像或套件版本錨點、完整備份狀態目錄與卷、在窗口內寫清回滾責任與驗證用例。商業條款請開 租賃價格說明 與 協助中心。

Gateway 升級後 Control UI 異常，先看什麼？

綁定位址與健康檢查、Docker 場景下 loopback 與 UI 白名單類設定；本機路徑查埠與權杖。詳細分症狀流程仍以《裝後排查》為主。

與 Docker 生產篇怎麼搭配？

生產篇講常駐與常見容器故障；本篇講升級前後的備份順序、版本錨點與回滾抓手。兩文與《Docker 生產》一起放進同一份維運手冊目錄。