2026 OPENCLAW
UPDATE_
WROTE_
WRONG_
NODE.

升級到 OpenClaw v2026.5.20 前後，一類極易被誤判為「假升級」或「頻道鑑權壞了」的故障，其實是：LaunchAgent 裡固化的 Node 路徑與目前 shell 裡 which node 不一致，openclaw update 在 follow-up 步驟裡用 PATH 上的「另一個 Node」重寫了服務單元，下次 gateway restart 直接起不來。5.20 官方修復（PR #84043）要求全程使用託管 Gateway 的 service Node，並在 gateway status --json 中暴露執行版本以識別 CLI/Gateway 協議 skew。本文給出症狀矩陣—決策表—六步 Runbook—三道門檻—案例—FAQ，並與站內《假升級與 gateway status》《LaunchAgent token 過期》《invalid config 與 doctor》分工，協助你在遠端 Apple Silicon Gateway上完成 7×24 對照驗收與回滾。

1. 痛點拆解：不是版本號不一致，而是 Node 二進位漂移

1）多 Node 並存極常見：同一台 Mac 上 Homebrew /opt/homebrew/opt/node/bin/node、nvm 預設 22.x、fnm 全域 20.x 同時存在；openclaw gateway install 時會把當時的 node 絕對路徑寫進 ai.openclaw.gateway plist。2）PATH 切換觸發漂移：你在終端機 nvm use 25 後執行 openclaw update，舊版邏輯會用新 PATH 的 node 跑 post-install、doctor、重啟——若 package root 未變，服務單元卻被悄悄換成另一套全域 npm 前綴下的 openclaw。3）與「假升級」分工：假升級是 CLI 已 5.20、執行中 Gateway 仍 5.12；本文是二進位與 engines.node 不匹配導致啟動即崩潰或 WS 握手失敗。4）協議 skew：5.20 保留「CLI 比 Gateway 新一個小版本」時的 restart health check；若 Node 漂移導致 Gateway 起不來，你會看到 unauthorized 或 RPC 逾時，而非單純的版本字串不一致。5）遺留 updater LaunchAgent：Issue #82167 描述 ai.openclaw.update.* 反覆 relaunch、SIGTERM 閘道；5.20 起 update 會 best-effort disable 遺留 job——升級 Runbook 必須包含 launchctl 清單核對。

2. 決策矩陣：先對齊 Node，還是先回滾包？

現場信號	首選動作	禁止
openclaw --version 與 plist 內 node 路徑指向不同 major	凍結 PATH → 用 service Node 重跑 update 或 gateway install --force	禁止在未備份 plist 前手改 ProgramArguments
gateway status --json 無 runningVersion	先 gateway restart --wait，再查 launchd 退出碼	禁止刪除整個 ~/.openclaw
升級後僅 Telegram 偶發斷連	先排除 Node 漂移，再查頻道層	禁止與 5.2 HTTP 逾時混修（見專稿）
筆電驗證 OK、遠端 Mac 全掛	對照節點比對 plist node 與 npm root -g	禁止把本機 nvm 路徑複製到遠端
需生產變更審計	遠端對照機先跑六步 + 30 分鐘探針	禁止週五晚高峰無回滾視窗升級

3. 六步落地 Runbook

Step 1 凍結「三元組」證據

記錄：openclaw --version、which node 與 node -v、LaunchAgent plist 中 ProgramArguments 前兩段（node 路徑 + openclaw 入口）。另存 openclaw gateway status --json 輸出中的 runningVersion（5.20+）。

Step 2 解析 engines.node 門檻

在全域 openclaw 包目錄查看 package.json 的 engines.node（或 release 註記）。若 service Node 的 major 低於要求，先升級 service 所用 Node，再動 openclaw 包——避免 doctor 通過但 Gateway 啟動失敗。

Step 3 對齊託管 Gateway 的 Node（5.20 推薦路徑）

升級到 2026.5.20 後執行 openclaw update：官方會優先使用 LaunchAgent 內 baked node 跑 follow-up。若你已漂移，執行 openclaw gateway install --force 用當前 intended 的 node 重新固化路徑，並確認 npm root -g 與 plist 一致。

Step 4 清理遺留 updater LaunchAgent

launchctl list | grep openclaw：若存在 ai.openclaw.update.* 且反覆重啟，在 5.20+ 上由 update 自動 disable；舊版可手動 launchctl bootout gui/$UID/ai.openclaw.update.*（先確認非進行中任務）。對照 Issue #82167 避免「升級腳本已成功但閘道每 3 分鐘 SIGTERM」。

Step 5 Gateway 有序重啟與 JSON 探針

openclaw gateway restart --force --wait 後，連續三次 openclaw gateway status --json，要求 runningVersion 與目標一致、RPC 在閾值內成功。遠端 Mac 用 launchctl kick -k gui/$UID/ai.openclaw.gateway 後重複。

Step 6 遠端 7×24 對照與回滾視窗

在對照節點保持未切換 nvm 的乾淨 PATH，重複 Step 1–5。若生產仍失敗，釘版本並保留 plist/npm 前綴 diff；連續 30 分鐘 channels.probe 全綠才 closure。

4. 三道自檢門檻

第一道Node 門檻：plist 內 node 路徑存在且 node -v 滿足 engines.node。第二道版本門檻：gateway status --json 的 runningVersion 與 openclaw --version 在可接受 skew 內（5.20 健康檢查覆蓋一小版差異）。第三道頻道門檻：openclaw channels status --probe 無紅，且 30 分鐘內無「重啟後立刻退出」。

5. 深度案例：「update 成功，次晨 Gateway 全頻道離線」

團隊先按《假升級》專稿查版本字串，發現 CLI 與 status 都是 5.20，誤判為頻道 token。直到對比 plist 與 which node 才定位Node 漂移。在 MACGPU 對照機上用單一 Homebrew Node 重裝 Gateway 後，生產 Studio 僅替換 plist 前兩段並 gateway install --force，30 分鐘內恢復。復盤寫入變更單：禁止從帶 nvm 的互動 shell 對遠端 launchd 服務執行 update；升級視窗統一用 service 帳戶或 env -i 最小 PATH。

6. 產業洞察：Agent 閘道「執行時釘扎」與 Mac 託管實踐

2026 年 Node 生態分裂（nvm/fnm/Volta/Homebrew）讓「全域 CLI」與「daemon 固化執行時」成為兩套真相。OpenClaw 5.20 把managed service Node寫進更新鏈，標誌著 Agent 維運從「能裝就行」進入可釘扎、可 diff、可回滾階段。甲方開始要求升級工單附帶：plist node 路徑、engines.node 校驗截圖、gateway status JSON——而非僅版本號截圖。

在 Windows/Linux 上同樣存在多 Node 並存，但 macOS launchd 的絕對路徑語意更「硬」——漂移一次就全站離線。Apple Silicon 遠端 Mac 因獨佔記憶體、Metal 生態與 7×24 圖形/Agent 混合負載，常被用作黃金對照環境：PATH 乾淨、磁碟可快照、日誌可工單回放。若你希望把 5.20 升級、Node 對齊與回滾放在與本機 nvm 隔離的節點上完成，可租賃 MACGPU 遠端 Mac：先在對照機跑通六步與 30 分鐘探針，再動生產。

7. 可引用數字門檻

① plist node 與 which node 路徑不一致：禁止宣告升級成功。② engines.node 要求 Node ≥22（以你安裝包為準）：service Node 不滿足則先換執行時。③ 升級後 30 分鐘 內 launchd 退出碼非 0 超過 3 次：預設回滾並保留 plist diff。④ gateway status --json 三次拿不到 runningVersion：Unhealthy。⑤ 遠端與本地 npm 全域前綴不同：禁止複製 plist 片段跨機貼上。

8. FAQ

問：和假升級有何不同？答：假升級看版本字串；本文看Node 二進位與 plist 路徑。問：必須升到 5.20 嗎？答：5.20 起官方修復漂移；更低版本請手動 gateway install --force 對齊。問：Docker 部署呢？答：容器內通常單一 Node；注意掛載卷與映像 tag 即可。問：能否手改 plist？答：可以但須備份；推薦 gateway install --force。問：MACGPU 節點做什麼？答：對照驗收、PATH 隔離與回滾視窗，不替代變更審批。