OPENCLAW 2026
FAKE_
UPGRADE_
VERSION_SKEW.

維護窗內跑完 openclaw update 顯示成功，但外掛出現 requires OpenClaw ≥ 指定版、頻道空白，或 openclaw status 與 openclaw gateway status 的執行中版本仍舊——這是假升級（版本漂移）：套件層已更新，常駐 Gateway 進程未切到新二進位或未完整重載。本文提供症狀—證據—動作矩陣、五步對齊 Runbook、三道門檻與可引用門檻；並內鏈《Gateway 未就緒與 PATH》《v2026.5.x 分層維運》《升級 breaking》《systemd／launchd》。若需要乾淨對照面，請在 MACGPU 遠端 Apple Silicon 重播本 Runbook。

1. 痛點拆解

1）CLI 與 Gateway 的版本敘述可能來自不同安裝前綴。2）熱重載若在校驗階段中止，會留下「更新成功、宿主仍舊」的組合。3）多 Node／多前綴：互動 shell 與 plist 子程序不一致。4）遠端 Mac：SSH 登入 profile 與 launchd 最小環境不同；不應先用模型 API 限流解釋。

2. 症狀—證據矩陣

現象	優先懷疑	證據
CLI 新、gateway status 舊	進程未重啟	PID 啟動時間、status --all
requires 錯誤	宿主版本低於門檻	日誌 host 版本行
僅維護後出現	重載中止／節流	launchctl print
僅遠端	PATH／Node plist	plist EnvironmentVariables

3. 五步對齊 Runbook

Step 1 凍結三元證據

同一 shell 依序執行 openclaw --version、openclaw status、openclaw gateway status 並存證。

Step 2 對齊 PID 與二進位路徑

確認 PID 對應的可執行檔是否落在新前綴樹。

Step 3 冷重啟 Gateway

停止→釋放埠→啟動；若仍舊，執行 gateway install --force 與註冊稿對齊。

Step 4 驗證 requires

以具門檻的外掛做探針。

Step 5 遠端 launchd 冷啟動

無人登入狀態重跑 Step 1。

4. 三道門檻

版本號一致前不得結案；requires 仍紅不得切回生產；遠端未通過冷啟動不得以筆電隧道為唯一依賴。

5. 深度案例

團隊在遠端 Mac mini 以 nvm Node 22 升級，plist 仍指向舊前綴；熱重載中止後形成 skew。修正：統一 plist 絕對路徑、完整停止、gateway install --force、無人登入複驗。與 v2026.5.x 稿並讀：先把宿主 bump，再談外掛體驗。

6. 產業觀察

週期小版本釋出使「進程真 bump」應成發布產物；互動 shell 與 launchd 應分線驗收。若主環境在 Windows／Linux，macOS 對照可顯著降低變因；可租 MACGPU 遠端 Mac 作黃金節點，將五步與門檻模板化。

在實務上，建議把「升級後自動工作」改成明確的狀態機：下載成功、註冊成功、重載成功、執行中版本號一致，四個節點各自有 log 切片與負責人簽核；任一節點失敗就不得進入下一節點。這比單純要求同仁「再跑一次 update」更能避免無限重試造成的設定漂移。

對於已導入 v2026.5.x 外掛 npm 路徑與 Gateway 懶載入語意的團隊，skew 往往發生在「外掛元資料已新、宿主尚未 bump」的短窗；此時更應把 requires 當成強制門檻探針，而不是噪音。若你把探針寫進變更單，排錯會從「猜誰的鍋」變成「看證據鏈缺哪一環」。

Windows 或 Linux 自建可行，但桌面工作階段與瀏覽器工具鏈變因較多；先在 Apple Silicon 驗證宿主版本，再擴異構節點較務實。

7. 可引用門檻

① 停止至新 PID 恢復逾 180 秒 應升級架構檢視。② 同窗 gateway install --force 逾 2 次應停手 diff。③ requires 與宿主差 ≥2 小版仍上線視為事故級。④ 冷啟動後三元不一致：零容忍，禁止回切流量。

另：必匯出停止前後各 10 分鐘 logs；並避免並行互相覆蓋的全域 npm 安裝。

8. FAQ

doctor 全綠可略 PID？不可。與 token_mismatch？token 偏鑑權；skew 偏版本行與 requires。reload aborted？應冷重啟。