2026 OpenClaw 升級護航實操：`openclaw backup create`、驗收階梯與 ACP / `gateway probe` 迴歸分診 Runbook

升級護航最常見的六種失誤（先認清再動手）

1. 只改映像 tag、不做 backup create：回滾時只能憑記憶改設定，無法證明「上一良好態」的配對與通道狀態。
2. 把「dashboard 能開啟」當成「probe 已通過」：2026 多起社群 issue 顯示 daemon 健康但 loopback probe 仍逾時（尤其 Windows 上 provider 擴充套件拖慢啟動）。
3. Node 基線未對齊就升 OpenClaw：官方建議 Node 24；在 22.x 上硬升易出現 CLI 與 Gateway 握手分裂，見Node 24 onboard Runbook。
4. 半升級 split-brain：CLI 已是新版本、Gateway 行程未 reload；表象與tools.profile 工具不執行類似，但根因是行程未載入新執行環境。
5. ACP 迴歸被當成「模型壞了」：2026.3.13+ ACP bridge / device 流失敗時，直連 acpx 可能仍正常——應走本篇 ACP 分診，而非先換模型。
6. 在會睡眠的筆電上做正式升級視窗：合蓋後 probe 失敗被誤判為版本問題；權威 Gateway 應落在常電遠端 Mac，見SSH 轉發常駐 Runbook。

2026 上游與社群文件 increasingly 把「升級」定義為可逆狀態遷移，而不是單次 npm install -g。openclaw backup create 會把目前 ~/.openclaw（或 Docker 磁碟區對應的目錄）打成可命名歸檔，讓你在 probe 連續失敗、ACP 註冊遺失時，有分鐘級恢復到升級前組合的選項——這與發行通道釘版矩陣裡的「已知良好 tag/digest」是同一套 FinOps 思維的兩面：一個鎖二進位，一個鎖執行態設定與配對。

實務上，許多團隊在第一次正式升級時只把變更單寫成「更新 OpenClaw 版本」，卻沒有把備份檔路徑、SHA、還原演練日期寫進工單。當晚高峰若同時進行映像 pull 與全量 probe，網路頻寬與磁碟 I/O 飽和會把「probe 逾時」誤判成「ACP 壞掉」，值班人員便在聊天視窗反覆試同一句 prompt，白白吃掉整個發布視窗。護航 Runbook 的價值，就是把這類隱性成本變成可稽核、可重播、可指派責任人的步驟鏈。

若你的 Gateway 必須對外提供 7×24 服務，建議在變更窗口開始前，先確認只有一個權威 Gateway 行程監聽權威埠，並在遠端 Mac 上預留足夠磁碟水位與頻寬餘裕。筆電僅透過 SSH 本地轉發存取 Control UI，可避免「本機睡眠導致 Gateway 假死」與「probe 路徑與業務路徑不一致」兩類假陽性同時出現。

從 SRE 視角看，升級護航與版本遷移總清單的差異在於：總清單回答「要搬哪些目錄、怎麼切換多機」；本篇回答「單機或單叢集在已升級的當下，如何用 probe/ACP 證據決定留版或回退」。兩份文件應在變更單上並列連結，而不是讓值班人員在長文之間自行拼湊順序。對使用 GHCR 映像的團隊，請同時在工單記錄 digest SHA 與 backup 檔案路徑，形成「二進位 + 狀態樹」雙錨點。

Windows 與 macOS 筆電路徑還有一個常被忽略的變因：防毒或端點防護會掃描 ~/.openclaw，在 backup create 當下拖長 I/O，導致備份半截或 probe 啟動競態。若你必須在筆電完成備份，請在變更窗口暫停即時掃描或把狀態目錄列入排除清單，並把該決策寫進工單以利稽核。較佳實務仍是把 backup 與驗收都落在遠端 Mac 伺服器上，由筆電只做轉發與簽核。

另一個實務建議是：為每次升級建立「證據包」資料夾（版本輸出、probe JSON、doctor 摘要、backup 路徑），與變更單號同名壓縮留存 90 天。當監控顯示 probe 假陽性率飆升時，你可以用歷史證據包比對是啟動鏈變慢還是監控門檻過嚴，而不是憑記憶爭論「上週好像也紅過」。證據包還能支援安全審計——證明升級前確實做過 backup、升級後確實跑過階梯——這在客戶要求 SOC2 或內部變更管理制度時尤其有用。

升級前：openclaw backup create 與目錄邊界檢查表

在變更視窗開始前，固定執行備份 → 記錄版本指紋 → 確認只有一個權威 Gateway。備份指令以你安裝的 CLI 為準（2026 文件常見寫法如下）；若子指令名稱在不同頻道略有差異，以 openclaw backup --help 輸出為準，但原則不變：升級前必須有一份可恢復的本地歸檔。

建議在變更單附件欄位上傳：backup 檔案路徑與大小、openclaw --version 輸出、Node 版本、目前映像 digest（若使用 Docker）、以及 gateway status 摘要。這些欄位能在 probe 失敗的凌晨，讓下一班值班不必重新蒐集證據。對合規團隊，請一併註記 backup 是否含 Token，以及恢復後是否計畫輪換憑證——避免「還原成功但安全審計不通過」的第二波事故。

備份不應被視為「可選的保險」：它是升級護航的第一個硬性關卡。沒有備份證據的變更單，在事後檢討時往往無法回答「上一良好態的配對與通道狀態長什麼樣」。對使用 Docker Compose 的團隊，請確認 bind mount 指向宿主机固定路徑，且該路徑未進入 iCloud 或網碟同步；對遠端 Mac 常駐部署，請在工單中寫明 OPENCLAW_STATE_DIR 與負責人，方便跨時區值班銜接。

敏感材料（Token、配對檔）通常會落在狀態樹內。歸檔應按機密等級存放，恢復前評估是否要輪換憑證。若你規劃把生產 Gateway 遷到專用遠端 Mac，可先對照租賃價格說明與協助中心的接入流程，避免在筆電上完成備份後才發現磁碟或頻寬不足以承載完整狀態樹。

對已使用 GHCR 映像與 Control UI 的團隊，請在 backup 前後各做一次 volume 唯讀巡檢，確認 skills、通道憑證與自訂設定仍在預期路徑。Docker 與 npm 混用（compose Gateway + 本機 CLI）時，backup 必須明確對應哪一側的狀態樹，避免還原到錯誤宿主。遠端 Mac 常駐場景下，建議把 backup 檔放在與狀態目錄同磁碟或同機器，跨區複製前先驗證 checksum，防止「備份存在但還原時損壞」的二次事故。

openclaw --version
node -v   # 目標：v24.x；不符先對齊 Node 基線再升 OpenClaw

openclaw backup create
# 可選：列出现有備份
ls -la ~/.openclaw/backup 2>/dev/null || ls -la "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/backup"

# 凍結「已知良好」組合（寫入變更單）
openclaw gateway status
openclaw config get gateway.auth.token 2>/dev/null | head -c 8; echo "…(redacted)"

升級後驗收階梯：從 status 到「可上線」判定

升級完成後，禁止只看 Control UI 或聊天視窗一句「你好」就關變更單。建議固定階梯（每步失敗即停，記錄 stderr 與版本號）：

1. openclaw status — CLI 與設定可讀
2. openclaw gateway status — 行程/埠/綁定摘要
3. openclaw gateway probe（或 --json）— loopback 握手與延遲
4. openclaw doctor — 設定與相依性告警
5. 最小業務探針：唯讀工具或單通道 channels status --probe
6. 若啟用 ACP：驗證 bridge 註冊與工作階段建立（見下節分診）

「可上線」建議定義為：階梯 1–4 連續通過，且第 5 步在你實際使用的通道/工具面上通過。「必須回退」建議定義為：同一階梯在 reload/重啟後連續兩輪仍失敗，且影響正式 Agent；此時先恢復備份或按digest 回滾回到變更單記錄的 tag/digest，而不是在壞版本上疊加更多設定補丁。

probe 與 dashboard 的分裂是 2026 年最常見的「假成功」：daemon 摘要顯示 healthy，但 loopback probe 仍逾時。這在 Windows 上常與 provider 擴充套件拖慢啟動有關；在 Linux/macOS 的 Docker 路徑上，則常與升級後未對同一 compose 專案做單次 reload有關。請把「升級後 reload 一次」寫進工單模板，並避免 launchd 與手動各起一份 Gateway 同時監聽 18789。

若你啟用 ACP，請把 bridge 註冊與 openclaw devices list 納入階梯 6。2026.3.x 的已知迴歸窗口內，CLI device 流與 Gateway 版本不匹配時，表象很像「模型壞了」，但直連 host 上的 acpx 可能仍正常——此時應走本篇分診表，而不是先換模型或改路由。

驗收階梯的輸出請貼進工單或變更系統，至少包含：OpenClaw 版本字串、Node 版本、gateway probe 的延遲或錯誤碼、doctor 的警告摘要。若你使用 --json，可把 JSON 存成附件，方便第二台機器或事後檢討時重播。對需要與tools.profile 分診交叉的情況，請在階梯 5 明確註記「最小工具探針」通過與否，避免把工具 allowlist 問題誤判為 probe 或 ACP 故障。

值班時請把本頁加入書籤，並在變更系統中固定連結本篇與 digest 回滾文；緊急時依序執行比搜尋聊天記錄更快。建議順序：openclaw backup create → upgrade → reload → status → gateway status → gateway probe → doctor → channels status --probe。

以下為升級當晚最短指令摘要（不可取代完整階梯與分診表）：backup create → 升級 → 單次 reload → status → gateway status → gateway probe → doctor → channels status --probe →（若啟用 ACP）bridge／devices 檢查 → 關單或 restore／digest 回滾。跳步會把「半升級」與「probe 假陽性」混在一起，事後難以稽核。

反代或 Cloudflare Tunnel 路徑上，loopback probe 可能與外部 dashboard 路徑不一致。若 probe 失敗但外部通道正常，請先在遠端主機本機 loopback執行 probe，排除反代 Upgrade 標頭或閒置逾時；再對照反向代理檢查清單。不要把「對外 URL 能開」直接等同「loopback 握手成功」。

openclaw status
openclaw gateway status
openclaw gateway probe
openclaw doctor

# Docker 路徑：升級後務必 reload 同一 compose 專案
# docker compose pull && docker compose up -d
# docker compose restart <gateway-service>

openclaw channels status --probe

繼續修設定 vs 釘版回退 vs 暫時停用 ACP：決策矩陣

on-call 最容易在「再試一次 config」與「立刻回滾」之間搖擺。可用下表快速定奪（列=影響面，欄=建議動作）。請把決策結果寫進工單，避免下一班重複同一輪試錯。

舉一個常見夜間場景：升級後 Telegram 通道正常、工具探針通過，但 gateway probe 逾時且 dashboard 仍開。此時應落在矩陣第一列——業務通道正常、僅 probe 紅。建議動作是記錄為監控雜訊並調查 provider 啟動耗時，而不是立刻 digest 回滾。若你的監控 SLA 把 probe 當作硬性門禁，則在變更單註記「業務無損但 SLA 觸發」，選擇回退 patch 或暫時停用拖慢啟動的外掛。另一場景是 ACP 全斷但 Slack 聊天正常：優先查 bridge 註冊，在已知 regression 窗口可 minor 回退，或暫時關閉 ACP 以保住通道 SLA。第三場景是 probe、通道、工具全紅：除非 backup 還原後單步驗證，否則不要疊加 config 修補——這時候每多改一個 YAML 欄位，都會讓事後無法對齊「是哪個變更導致失敗」。

六步「備份—升級—階梯驗收—留痕」Runbook

1. 開變更單：寫明目前 OpenClaw 版本、Node 版本、映像 tag/digest、是否遠端 Mac Gateway。
2. backup create + 目錄檢查表：確認備份檔大小合理、狀態目錄未進同步碟。
3. 執行升級：npm 全域或 compose pull/up；同一工單只升一檔（例如 beta→stable 不要跳兩頻道）。
4. 單次 reload：保證僅一個 Gateway 行程監聽權威埠；Docker 與 launchd 勿雙啟。
5. 跑驗收階梯 1–6：任一步失敗則截圖日誌、停止後續步驟。
6. 關單或回退：通過則更新內部「已知良好組合」表；失敗則 backup restore 或 digest 回滾，並記錄 MTTR。

建議每季在非正式流量的專用遠端 Mac 上做一次輕量桌演：刻意從 digest A 升到 B 再回到 A，驗證備份還原與階梯腳本仍與文件一致。演練產出的日誌 tarball 與 compose SHA 應留存於可搜尋的工單系統，便於稽核與跨時區值班銜接。

六步 Runbook 的時間盒建議（可依團隊調整）：開單與備份 10–15 分鐘、執行升級與 reload 5–10 分鐘、階梯驗收 10–15 分鐘、失敗時回退決策 5 分鐘內啟動。總計在預先釘好 digest 與 backup 的前提下，常見 MTTR 應落在 15–35 分鐘區間；若超過 60 分鐘仍無法判定，多半是「同時改了太多變因」或「沒有單一權威 Gateway」，應暫停變更、先恢復已知良好組合，再在非高峰重做單步升級。不要把「長時間試設定」誤當成勤奮——在升級護航語境裡，快速恢復服務優先於追根究底，根因分析應在服務恢復後的獨立工單進行。

Runbook 第六步「關單或回退」應明確指派決策人與時限：例如 probe 連續兩輪失敗後 10 分鐘內必須選擇 backup restore 或 digest 回滾，避免 on-call 在聊天群組無限嘗試設定。回退完成後，請更新內部「已知良好組合」表（OpenClaw 版本 + Node + 映像 digest + 最後通過 probe 的時間戳），並與發行通道矩陣對齊，防止下週再次漂移到未驗證的 latest。

五條應寫進變更單的量化口徑

• 升級護航 MTTR：從「probe 首次失敗」到「恢復已知良好組合」的中位分鐘數；小團隊建議 ≤15 分鐘（前提是 backup 與 digest 已預先釘好）。
• 假陽性 probe 率：dashboard/通道正常但 probe 紅的比例；若連續兩週 >25%，應修啟動鏈或調整監控探針，而非每週強制回滾。
• 無備份升級占比：變更單裡沒有 backup 證據的升級次數；正式環境目標為 0。
• 階梯跳步率：未跑完 1–6 就關單的比例；應透過工單必填欄位壓到接近 0。
• 回退後 24h 重犯率：同一 digest 組合在一天內再次升級失敗的次數；高於 2 次應凍結頻道並開根因工單。

建議每半年審閱一次本 Runbook，對照上游 release note 更新「已知 regression 窗口」與 ACP 分診列，避免沿用過時版號區間誤導值班；審閱紀錄可附在變更管理制度附錄，並標註審閱人與日期以利稽核。

在六國遠端 Mac 上，建議把升級視窗與穩定性驗收、磁碟水位檢查並列：晚高峰同時做映像 pull + 全量 probe，容易把「網路抖動」誤判為「ACP 壞了」。更穩妥的是：在常電、獨占、可寫工單的節點上完成升級與驗收，筆電僅透過 SSH 轉發存取 Control UI。

npm 全域路徑與 Docker Compose 路徑的護航差異

本機 npm 全域升級後，最常見的遺漏是「CLI 已新、launchd 管理的 Gateway 行程仍舊」。請在升級後執行一次單一機制的 reload：要麼 openclaw gateway restart（以你環境文件為準），要麼重載 launchd unit，但不要同時再手動前景啟動第二份行程。Docker 路徑則要把「pull 新映像」與「對同一 compose 專案 up -d」綁在同一工單步驟，並在 up 之後立刻跑階梯 1–4；若只 pull 不 up，或 up 了另一份 compose 檔，會出現與半升級相同的 split-brain。

兩條路徑的 backup 含義一致：都要在變更前後能證明狀態樹完整。Docker 使用者請確認 volume 未指向會被 docker compose down -v 誤刪的路徑；npm 使用者請確認狀態目錄未進同步碟。當你需要在六國節點間遷移 Gateway 時，backup 檔應隨工單轉移並在目的地先做還原演練，而不是在目的地「空配置直接升級」賭運氣。

與 WebSocket 1006、配對衝突的銜接

升級後若 Control UI 出現 1006 或配對衝突，請暫停「繼續改模型或通道」的衝動，先完成階梯 1–3 並對照配對與 1006 Runbook。許多團隊在升級當晚同時改了反代、Token 與 OpenClaw 版本，導致無法判斷根因；建議工單上把變更分成「版次升級」與「網路/反代調整」兩張子單，升級子單未通過 probe 階梯前不要合併網路變更。若 1006 在 backup 還原後消失，則把根因記為「升級後設定或執行環境變更」，而非「上游永久壞版」。

收束：升級不是「賭最新」，而是「可逆遷移」

只在聊天裡試一句「升級成功了嗎」、或只靠手工改兩三個 YAML 欄位，無法通過稽核，也無法在第二台機器重播同一護航路徑。相對地，把 backup create、驗收階梯與 ACP/probe 分診寫進 runbook，能把「升級踩雷」從一整晚盲試，壓到有備份、有回退點、有指標的十分鐘級事件。

若你仍堅持在個人筆電上追新頻道，要接受三項隱性成本：睡眠導致 Gateway 假死、probe 與業務路徑不一致、以及升級視窗與本機電源策略衝突。對需要 7×24、Node 24 基線穩定、變更可工單化 的 OpenClaw 正式 Gateway，把環境落在 MACCOME Mac mini（M4 / M4 Pro）與六國彈性租期上，通常比在合蓋筆電上與 probe 逾時搏鬥更省總成本；公開檔位可先對照多區域節點與租期指南，再與 SSH 常駐 Runbook 串聯拓撲。

MACCOME 轉換的關鍵不是「多一台 Mac」，而是把備份、probe 階梯、ACP 分診寫進可重複的變更劇本：專用遠端 Mac 提供常電與獨占狀態目錄，六國節點讓你依延遲與合規選擇接入點，彈性租期讓升級視窗與成本對齊。當你把這套劇本與內部工單系統、監控告警綁定後，升級從個人技巧變成團隊能力——值班只需照表執行，而不是在聊天記錄裡考古上一版設定。

最後請把本文與你團隊的「變更單模板」對齊：模板中應有 backup 證據欄位、階梯 1–6 勾選、決策矩陣勾選、MTTR 起迄時間。缺少欄位的模板會把護航退化為口頭傳承。若你正在評估從筆電遷到遠端 Mac，可先閱讀多區域節點與租期指南估算檔位，再在非高峰窗口做一次完整的 backup→升級→階梯→（可選）還原演練，用真實分鐘數校準 MTTR 目標，而不是抄襲他團隊的數字。

升級護航交付清單（可貼進工單）

• 變更單已連結版本遷移總清單、digest 回滾與本篇 Runbook。
• 已完成 backup create，附件含路徑、大小、版本指紋。
• 已確認單一權威 Gateway，無 launchd/compose 雙啟。
• 升級僅跨一個頻道或一檔版本，未跳頻。
• 升級後已單次 reload，並保存階梯 1–6 輸出。
• probe 失敗時已按症狀表分診，未同時改模型與反代。
• 若回退：已執行 backup restore 或 digest 回滾，並更新已知良好組合表。
• 已記錄 MTTR 與是否觸發假陽性 probe 統計。

把清單做成工單勾選後，新同事也能在第一次值班時完成護航閉環；這比資深工程師口頭補充「我們通常會先 backup」更可擴展。當團隊擴大到跨六國節點時，清單還能作為穩定性驗收的前置條件，避免把區域網路抖動誤判為 OpenClaw 版本缺陷，進而在錯誤的維度上反覆回滾。

若你正在把 OpenClaw 從「個人實驗」推進到「團隊基礎設施」，請把本篇 Runbook 與無人值守 Gateway 檢查清單一併納入入職材料：前者定義升級當晚怎麼做，後者定義平日怎麼維持常駐與日誌/磁碟健康。兩者加起來，才能把「升級護航」從一次性英雄主義，變成可複製的平台慣例。MACCOME 六國遠端 Mac 的價值在於提供這套慣例的硬體與租期底座——常電、獨占、可寫工單——讓你在正確的伺服器上執行正確的 CLI 階梯，而不是在合蓋筆電上與 probe 逾時搏鬥。

延伸閱讀（與本篇串聯）

• 版本遷移總清單：目錄搬遷與多 Gateway 切換。
• 坏版本 digest 回滾：映像 digest 鎖定與 compose 步驟。
• SSH 轉發常駐：筆電與遠端 Mac 拓撲。
• 穩定性驗收：多區 probe 變異與驗收。

護航成功的判斷標準不是「聊天機器人回了一句 OK」，而是「階梯輸出已存檔、backup 可還原、且決策矩陣已勾選」。請把這三項作為變更關閉的硬性條件，避免主觀感受主導回退或硬留壞版。

若你已在 MACCOME 遠端 Mac 上執行過多次升級，建議把「上次通過 probe 的 digest + backup 檔名」貼在機器描述或工單範本頂部，縮短下一輪 on-call 的搜尋時間。對跨國團隊，請在變更窗口表註明執行 probe 的時區與節點區域，避免亞洲同事在美洲節點晚高峰 pull 映像時，把區域頻寬飽和誤判為 OpenClaw 缺陷。最後提醒：本篇所有 CLI 範例均應以你環境的 openclaw --help 為準；子命令或旗標若有變更，請在 Runbook 註腳記錄對應版本，確保六個月後仍能重播同一護航路徑。若需評估專用節點與租期，請一併參考站內多區域指南與租賃價格，把基礎設施決策與升級護航證據鏈放在同一張變更單上閉環。