1. 痛點拆解：升級不是「覆蓋二進位」這麼簡單
（1）狀態目錄漂移：歷史版本可能把配置落在 ~/.moltbot 或舊前綴環境變數下；新版本統一向 ~/.openclaw 與 OPENCLAW_* 收斂。若只升級包體不遷數據，Gateway 會讀到半套舊配置，表現為「進程在跑但頻道全啞」。
（2）doctor --fix 不是萬能鍵：它能修一批常見漂移，但對頻道憑證過期、反代路徑變更、自定義 skills 路徑仍需人工決策；盲目 --fix 可能改寫你刻意保留的本地覆蓋。
（3）設備鑑權 v2：nonce 籤名與客戶端版本門檻提高後，舊設備或舊 CLI 會出現握手成功但消息不進工作流；在遠程 Mac 上若 launchd 未繼承與交互 shell 相同的環境，會放大為「本機 OK、伺服器不行」。
2. 遷移對照表：目錄、環境前綴與鑑權代際
| 維度 | 升級前常見形態 | 升級後目標形態 |
|---|---|---|
| 配置與密鑰根 | ~/.moltbot、散落 CLAWDBOT_* / MOLTBOT_* |
~/.openclaw 為單一真源；統一 OPENCLAW_* |
| launchd / systemd | plist 裡寫死舊路徑或舊 env | plist 與當前 shell profile 對齊；顯式 export OPENCLAW_* |
| 設備鑑權 | legacy v1 籤名仍被部分客戶端使用 | v2 nonce 流程；CLI/設備端同代升級 |
3. 落地五步走：可復現升級 Runbook
- 凍結快照：打包
~/.openclaw（或舊目錄）、workspace、launchd plist、當前openclaw --version與頻道 webhook 配置截圖；標註 Git 提交或包版本號。 - 只讀診斷：先跑
openclaw doctor（不帶--fix）導出文本；再跑status/gateway/logs各一輪，保存輸出。 - 受控修復：在測試副本目錄上試
doctor --fix；確認 diff 後再在生產路徑執行；禁止 SSH 裡隨手改完不存檔。 - 環境對齊：把仍依賴舊前綴的 shell 腳本、CI、launchd 全部掃一遍；用
grep -R搜遺留字符串並替換為OPENCLAW_*。 - 煙測與回滾：頻道發送探針消息、觸發一個最小 skill、檢查 Gateway 指標；失敗則按《Gateway 回滾》文章路徑恢復鏡像/包與 plist。
4. 可引用閾值（評審向）
寫進變更單可用的討論量級（需結合你的版本說明替換）：
- 若升級後連續 3 次
doctor報同類配置漂移且影響頻道接入，應暫停繼續升小版本，先完成目錄/環境前綴一次性遷移，而不是堆補丁。 - 當設備鑑權相關錯誤在日誌中佔比超過20%且集中在單一客戶端版本，優先統一升級該客戶端到支持 v2 的構建，而不是反覆重置 Gateway。
- 遠程 Mac 上若 launchd 任務與交互 shell 的
OPENCLAW_*差集非空，且差集包含密鑰或基址 URL，必須在上線前清零；否則視為未通過門禁。
5. 遠程 Mac Gateway：環境繼承決策矩陣
| 現象 | 優先懷疑 | 動作 |
|---|---|---|
| SSH 登錄後手動啟動正常，launchd 啟動失敗 | plist 未注入 PATH / API key / OPENCLAW_* |
在 plist EnvironmentVariables 顯式寫入；避免依賴 ~/.zshrc |
| 升級後僅某一頻道無回復 | Webhook URL 或籤名校驗與新版默認不一致 | 對照官方升級說明重配；參閱《無回復與 doctor》 |
| 技能裝得上但執行報權限 | workspace 路徑或沙箱邊界隨版本收緊 | 覆核 skills 目錄權限與只讀掛載；參閱《暴露面收斂》 |
6. FAQ：--fix 會不會動我的 workspace？
問：doctor --fix 和重裝哪個更安全？在有快照的前提下，先 fix 再定向修通常快於盲重裝；無快照時優先複製整個狀態目錄再操作。
問：Docker 安裝也需要遷 ~/.openclaw 嗎？取決於你是否把配置掛載進卷；宿主機與容器只能有一個真源，混用 bind-mount 時最易出現「改 A 不生效」。
問：v2 鑑權失敗後能臨時降回 v1 嗎？不建議在生產長期降級；應升級客戶端。若必須臨時驗證，限定在隔離環境並設到期拆除。
7. 深度案例：從「全靜默」到「可籤字的變更記錄」
某團隊在遠程 Mac 上跟隨小版本連續升級兩次後，Gateway 日誌顯示進程健康但 Slack 事件不再進入工作流。復盤發現三處疊加：plist 仍引用舊二進位路徑、OPENCLAW_GATEWAY_TOKEN 留在 shell profile 而未寫入 launchd、Slack App 的籤名校驗與新版默認 header 不一致。
單獨修任何一處都會「偶發恢復」，直到按 Runbook 做環境差集清零與頻道重配對才穩定。該案例說明：升級問題常被誤判為「模型壞了」或「頻道壞了」，實則是配置拓撲未隨版本契約更新。
將每次升級的 doctor 輸出、plist diff 與頻道探針截圖入庫後，二次升級耗時從數小時降到數十分鐘，且可審計。
與大規模 2.0 敘事不同，本清單聚焦高頻小版本斷裂；若你仍處 MoltBot 代際，請先完成《遷移與重配對》再使用本文閾值。
安全面在升級後常被遺忘：新版可能默認收緊綁定或技能執行邊界，應結合《暴露面收斂》覆核監聽與卷掛載。
建議在變更窗口內對 openclaw 可執行文件做 shasum 歸檔，並在工單中寫明「從 A 到 B」；當回滾時不僅降版本，還要核對 plist 是否仍指向正確路徑。多用戶機器上，若 Gateway 以 UserName 與登錄用戶不一致運行，密鑰鏈與文件 ACL 會表現為「間歇性」故障，應在煙測前用 whoami 與 plist 的 UserName 對齊檢查。
若團隊同時使用 Homebrew 與 npm 全局 兩套 openclaw，務必在 PATH 中固定唯一入口，否則 doctor 修的是 A 路徑、launchd 啟的是 B 路徑，日誌裡會出現令人困惑的「版本已最新但仍報舊錯」。
8. 可觀測性：升級窗口內的最小指標集
建議在變更窗口記錄：Gateway 啟動退出碼、頻道探針成功率、技能冷啟動耗時中位數、鑑權失敗日誌條數/小時。四項同時異常時優先懷疑環境前綴與路徑；僅鑑權異常上升則切到客戶端版本矩陣。
| 信號 | 含義 | 下一步 |
|---|---|---|
| doctor 持續提示同一鍵缺失 | 真源未統一到 ~/.openclaw |
停升版本，先完成目錄遷移 |
| 手動 OK / launchd 不 OK | 守護進程環境漂移 | 比對 plist 與交互 shell 的 env 差集 |
| 僅夜間任務失敗 | cron/launchd 與登錄會話不同用戶 | 核對運行用戶與密鑰可見性 |
8.1 與 CI、預發環境與版本凍結：別讓「流水線最新」拖垮生產 Gateway
許多團隊在 CI 裡用 npm i -g openclaw@latest 做每日構建，卻把與生產不同的 Node 大版本、不同的預設 shell，以及快取目錄一併寫進製品描述。結果是：CI 報告 green，生產 launchd 仍在舊 minor 上跑，二者對 doctor 的提示文本都不一致。正確做法是在流水線中釘死 digest 或精確 semver，並把「可執行文件絕對路徑 + shasum」寫進構建產物元資料；生產變更單只引用該元資料，而不是「latest」這個詞。
預發（staging）Gateway 若與生產共用同一 Slack Workspace，務必使用獨立 Bot 或獨立頻道，否則一次誤發的 webhook 重放可能汙染生產稽核。預發的 launchd plist 建議複製生產 plist 後僅替換金鑰與監聽埠，再跑完整煙測；若預發 plist 結構比生產「多一行 EnvironmentVariables」，說明生產已經漂移，應反向合併而不是只在預發上修。
版本凍結窗口內，禁止並行存在兩套 OPENCLAW_CONFIG_ROOT 語義：有人在 /etc/environment 寫一份、有人在用戶目錄寫一份，會在守護進程重啟時隨機勝出。升級週應臨時凍結這類全域注入，改由單一 plist 或單一 systemd drop-in 作為真源，並在工單附上 diff -u。
若你使用 Ansible/Chef 等組態管理，注意它們往往在登入會話與守護進程兩條路徑上各渲染一次範本；兩次渲染若時間不同步，會出現「中午 OK、夜裡又壞」的錯覺。把範本版本號打進 plist 註解行，便於和 CM 的 commit 對齊追溯。
最後，升級不是只面向人類操作者：任何呼叫本地 openclaw 的定時健康檢查腳本也要隨大版本切換同步升級，否則舊腳本可能解析不了新 CLI 子命令的退出碼，把 healthy 判成 critical，觸發誤重啟雪崩。
9. 收束：Windows/Linux 教程同樣要先對齊契約
（1）當前方案的客觀限制：在非 Mac 環境跟隨 OpenClaw 升級時，服務管理器與路徑差異更大，若不固定狀態目錄與 env 真源，排錯成本高於 Mac。
（2）為什麼遠程 Apple Silicon Mac 常常更省心：與官方文檔、launchd 示例及圖形/自動化工具鏈的一致性更高，減少「雙棧配置腦裂」。
（3）與 MACGPU 場景的銜接：若你希望低門檻試用常駐 Gateway 節點並由同一拓撲承接升級驗證，而不是在筆記本上反覆折騰守護進程，MACGPU 提供可租賃遠程 Mac 與公開幫助入口；下文 CTA 直達首頁套餐與幫助（無需登錄）。
（4）最後一道自檢：未附快照與 doctor 輸出的升級，視為未完成變更閉環。
10. 與安裝三棧、Docker 生產的銜接
npm 全局、Docker Compose 與 pnpm 源碼三套路徑的數據目錄並不相同；升級斷裂時先確認你正在修的是哪條鏈路的真源。參閱安裝三棧對照與 Docker 生產部署實踐，避免跨路徑混拷配置。