多節點滾動升級的風險，常延後在「npm -g 順序差一步」或「探針只看單一維度」時才爆開。在 clustervps 專用 Mac 上，請把 openclaw@2026.4.x 當成一條有閘門的生產線：金絲雀節點先行、每節點 doctor、健康探針合併再動流量，並以結構化失敗廣播取代堆疊洗版。

本文與《多可用區金絲雀、技能切片與探針合併》、《租戶切片、巡檢合併與 Webhook 失敗摘要》、《多可用區網關與 Webhook 摘要》銜接；此處補上全域 CLI 升級順序、2026.4.x 線插件 peer 依賴與鏡像產出的中立版本脈絡（社群與發行說明曾提及 peer 連結解析修補、以及鏡像／產物生成路徑的調整—請務必以實際安裝與 lock 為準，本文不背書單一廠商敘事），以及步驟清單＋回滾點。

步驟清單與回滾點（R0／R1／R2）

建議列成值班表的一頁紙：每行一節點、每列一個閘門。下列編號可對照稽核 JSONL 與聊天機器人摘要欄位。

  • R0（凍結）：全叢集 npm ls -g --depth=0、openclaw version --json、LB 權重與 skills/current 符號連結截圖入庫。未快照不升級。
  • ① 金絲雀節點：依下文 npm -g 順序裝妥 openclaw@2026.4.x；執行 該節點 doctor；跑 合併探針；將小比例流量掛上該節點。
  • ② 觀察窗：至少兩個探針週期＋錯誤預算；Webhook／digest 僅作合併 JSON 的一欄。
  • ③ 逐節點滾動：其餘 Mac 重複 ①，一次一臺；每臺升級後立刻 doctor，避免「只有 LB 綠燈」。
  • ④ 收斂：權重回到均衡或既定目標圖；寫入 promotions／upgrade 稽核一行。
回滾點 R1：僅金絲雀節點與小比例流量—可單節點 npm install -g openclaw@<上一版> 並還原符號連結，權重拉回 R0。回滾點 R2：已滾動多節點—須對全叢集執行同一套還原與 kickstart，並廣播「已觸發 R2」避免半套狀態。

npm -g 升級順序（演練骨架）

實務上先升級官方文件標示的核心 CLI／守護行程套件，再依字母或團隊維護清單對齊外掛，最後跑一輪 npm doctor 與 openclaw doctor。若 2026.4.x 變更了 peer 解析，中途插單升級某一顆外掛最容易讓執行期才報 ERESOLVE 類訊息—故順序寫進 runbook 比憑記憶可靠。

# 示意：請替換為貴團隊 lock／文檔中的實際套件名
set -euo pipefail
/opt/homebrew/bin/npm install -g openclaw@2026.4.x
# 其次：官方 bundles 或內部 mirror 上的外掛（同 major／peer 約束）
/opt/homebrew/bin/npm install -g @openclaw/plugin-foo @openclaw/plugin-bar
/opt/homebrew/bin/npm ls -g --depth=0 | tee "/var/db/openclaw/audit/npm-global-${HOSTNAME}-$(date -u +%Y%m%dT%H%M%SZ).txt"

2026.4.x 前後若出現插件 peer 依賴連結或 registry 解析的修正，請在變更單上註記「僅驗證解析與啟動路徑」，不要把它和業務 SLO 混成同一個「感覺 OK」。

插件 peer 依賴與鏡像產出：中立版本背景

近期 2026.4.x 相關討論中，常見兩類變更被並列提及：一是peer 依賴在安裝／連結階段的行為（例如對元資料或別名的解析更嚴格或更一致）；二是鏡像或離線產物生成路徑的調整，讓 CI 與網關拉取同一顆校驗和。對營運而言，兩者都應落到可重現的安裝與探針上，而非口頭「應該相容」。建議在 staging 用與生產相同的 npm config get registry 與 bundle 目錄演練一輪，再把結果寫進工單。

每節點 doctor：滾動的硬閘門

每一臺 clustervps Mac 在 npm -g 之後都須跑 openclaw doctor（多租戶則加 --tenant）。Doctor 通過前不進下一臺，可把「跨節點版本漂移」壓在 R1。若 doctor 對某外掛報 peer 警告，優先對照該外掛維護者的相容表，而不是先調 LB。

/usr/local/bin/openclaw doctor --json >/tmp/doctor.json
/usr/bin/jq -e '.ok == true' /tmp/doctor.json

健康探針合併：單一 URL、多訊號

負載平衡仍打單一 /readyz（或內網等價路徑），但 JSON 應合併：進程／semver、租戶 doctor 摘要、佇列或內建佇列深度、以及可選的 Webhook digest 欄。semver 與 lock 不一致時必須硬失敗；digest 單獨綠燈不足以推進滾動。實作可沿用金絲雀文的合併腳本，把 probe_sha256 寫進稽核。

#!/usr/bin/env bash
set -euo pipefail
TENANT_CANARY="${TENANT_CANARY:-acme}"
SKILL_PATH="/var/db/openclaw/skills/current"
/usr/bin/readlink "${SKILL_PATH}" | /usr/bin/tee /tmp/skill_path.txt
/usr/local/bin/openclaw doctor --tenant "${TENANT_CANARY}" --json >/tmp/doctor.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:9099/v1/webhook-digest" -o /tmp/digest.json
/usr/bin/python3 - <<'PY'
import hashlib, json, pathlib
blob = pathlib.Path("/tmp/doctor.json").read_bytes() + pathlib.Path("/tmp/digest.json").read_bytes()
print(json.dumps({"probe_sha256": hashlib.sha256(blob).hexdigest(),"skill_resolved": pathlib.Path("/tmp/skill_path.txt").read_text().strip()}))
PY

Doctor 可呈現 degraded 以允許小流量觀察；semver 與鎖檔不一致仍須硬失敗。

失敗廣播：節點、版本、探針摘要與回滾狀態

滾動期間合併探針紅燈時，值班頻道應收到同一模板：主機名、openclaw 與關鍵外掛版本、doctor 一行程式可讀摘要、probe_sha256、是否已執行 R1／R2。與租戶 Webhook 文並用時，建議第一行可機器解析（JSON），第二行給人讀摘要。

金絲雀流量與回滾劇本（對齊 R1／R2）

比例建議自約 5% 起跳並階梯加權；觀察窗至少兩個探針週期。觸發 R2 時須同時還原 LB 權重快照、skills/current 與全域 npm 版本，再 kickstart。產物若依 rsync 扇出，請一併對照《rsync 與建置鎖矩陣》。

#!/usr/bin/env bash
set -euo pipefail
./lb_restore_weights.sh /var/db/openclaw/audit/last_good_weights.json
sudo /bin/ln -sfn "/var/db/openclaw/skills/${ROLLBACK_SEMVER}" /var/db/openclaw/skills/current
/opt/homebrew/bin/npm install -g "openclaw@${ROLLBACK_NPM_VER}"
sudo launchctl kickstart -k system/com.openclaw.gateway
/usr/bin/curl -fsS http://127.0.0.1:8088/readyz | /usr/bin/jq .

每步調權重或升級結束後，於 writer 節點追加 promotions.jsonl（含 probe_sha256），方便事後用 jq 對帳。

FAQ

能否跳過某臺 doctor？ 不建議；滾動意義在於每節點可觀測，跳過等於把 R2 風險藏到流量之後。

peer 解析修補是否代表可關閉探針？ 相反：解析收緊時，探針與 doctor 才是統一語言。

最少幾臺演練？ 仍建議三台 clustervps Mac：兩臺穩定、一臺金絲雀，與多可用區系列文一致。

本文為維運指引。OpenClaw 版本差異大，請以實際安裝版本校驗旗標；負載平衡 API 因廠商而異，殼層片段為模式示意，非可直接貼上的機密。
滾動升級與硬體席次

把 npm 順序與探針合併跑在專用 Mac 上，而不是筆電熱點

已有叢集演練可接續金絲雀與技能切片、租戶切片與 Webhook、多 AZ 網關、rsync 矩陣。需要加節點或新開環境時，請瀏覽方案與價格並開購買頁；日常請將說明中心與首頁放在 runbook 同層，值班對齊帳號、SSH 與責任邊界。

購買／加開節點 查看方案