2026-04-16 無頭租賃雲端 Mac 上的 OpenClaw 網關升級與回滾
在只講 SSH 的租賃 Apple Silicon Mac 上交付 OpenClaw，升級就是純維運：沒有 Finder 點選路徑，也沒有「重啟一下應用就好」。這份 2026-04-16 手冊涵蓋入口凍結、先停後 npm 順序、對 ~/.openclaw 的校驗和備份、版本固定（不要盲用 @latest）、以 openclaw doctor 驗證、全域安裝後偶發的二次重啟網關，以及在建置失控時 3 分鐘內完成的 tarball 回滾——與 2026 年 npm 網關維運經驗一致。請交叉閱讀 環境變數與金鑰（2026-04-15）、健康偵測 與 反向代理／Webhook 入口，使 香港／日本／韓國／新加坡／美國 全端敘述一致。
無頭網關特有的升級風險
- 熱全域 npm —— Node 仍握有已開啟的檔案控管權時替換檔案會導致半安裝與「幽靈」版本。
- launchd 重疊 —— 使用者 LaunchAgent 若未先 unload，可能在升級中途拉起網關。
- 設定漂移 —— 新小版本可能重新命名鍵；將不含金鑰的
openclaw.json匯出納入 Git。 - Webhook 羊群效應 —— 未做就緒檢查就恢復 nginx 時合作方會瘋狂重試——請使用健康偵測文章中的探針。
先凍結公網流量
在使用 反向代理 的主機上，將上游切到維護模式或回傳 503 並帶 Retry-After: 90。內部金絲雀仍應能存取 127.0.0.1:18789，以便在對外開放前完成驗證。
備份矩陣：碰 npm 之前要打包什麼
| 路徑／產物 | 是否納入？ | 說明 |
|---|---|---|
~/.openclaw（或 $OPENCLAW_STATE_DIR） |
必須 | 先停網關；以 shasum -a 256 驗證 gzip 完整性 |
| 全域 npm prefix 樹 | 可選 | 儲存 npm prefix -g 與 npm ls -g --depth=0 文字便於 diff |
| launchd plist | 必须 | 从 ~/Library/LaunchAgents 复制到同一 tarball 目錄 |
TS=$(date +%Y%m%d-%H%M)
tar -czf "/Volumes/backups/openclaw-state-$TS.tgz" -C "$HOME" .openclaw
shasum -a 256 "/Volumes/backups/openclaw-state-$TS.tgz" > "/Volumes/backups/openclaw-state-$TS.tgz.sha256"
安裝與固定版本：像資料庫遷移一樣對待 semver
生產網關應在基礎設施儲存庫中追蹤顯式 semver，例如 1.24.3。CI 可以略快浮動，但面向合作方、放在 新加坡 的那台 Mac 不應在凌晨以破壞性外掛 API 給你驚喜。停止服務後：
npm install -g openclaw@1.24.3
openclaw gateway status 並與 openclaw --version 對比；不一致表示仍處於中間態。
驗證、重啟與何時需要「跳兩次」
執行 openclaw doctor 並將 stdout 送入日誌管線。依 plist 透過 launchctl bootstrap/kickstart 啟動網關。若日誌出現陳舊模組路徑或異常 require 堆疊，再執行一輪乾淨停／起——務必文件化，避免 on-call 誤判為抖動。在解除 nginx 維護前，以 健康偵測 中的合成檢查重跑一遍。
回滾：恢復狀態，而不是祈禱
- 再次停止網關與 nginx 上游。
- 如有需要解除安裝損壞的全域安裝：
npm rm -g openclaw後重裝舊 semver。 - 展開 tarball：
tar -xzf openclaw-state-....tgz -C "$HOME"（確認擁有者）。 - 若 plist 變更則恢復；按需
launchctl bootout/bootstrap。 - 驗證 doctor 與內網 curl；通過後再在公網入口回傳 200。
相關手冊與金鑰紀律
升級觸碰的檔案與金鑰輪替相同——與 launchd 環境指引 對齊，使 .env 與 plist 鍵保持一致。若增加第二個網關使用者做藍綠，請依該文拆分 OPENCLAW_STATE_DIR。反覆失敗後需要容量時，從 訂價 增加見證節點，而不是無限給一台疲憊主機打補丁。
常見問題：雲端 Mac 上的網關升級
| 問題 | 回答 |
|---|---|
| 用 pnpm 代替 npm？ | 支援——沿用相同的停／備份／固定／啟動紀律；在手冊中記錄 store 路徑。 |
| 能否每週自動升級？ | 僅在有金絲雀主機＋自動 doctor＋探針門禁時；生產無人工值守時勿自動升級。 |
| 事件記在哪裡？ | 使用現有橋接系統；與 結構化日誌 欄位關聯。 |
結論：把 OpenClaw 升級當作資料庫故障切換——凍結流量、備份狀態、固定版本、驗證兩輪，並在每個營運區域演練回滾直到形成肌肉記憶。
