migrate 與 update · plan / dry-run · JSON · Gateway 18789
v2026.4.26 把「把外部權威併入 OpenClaw」這條路從手抄與口頭約定，推進到可預演、可審 JSON、可對照 apply 前後的工程動作：openclaw migrate 具備 plan、dry-run、報告取向的結構化輸出與預遷移備份思路，並內建從 Claude Code / Claude Desktop 合流指令稿、MCP、技能與憑證提示的防護欄。租用遠端 Mac 時，OPENCLAW_PLUGIN_DIR 若落在唯讀層或與資料卷切分不當，最容易呈現為「依賴裝到一半」「UI 外掛頁與 CLI 列表不一致」這類中間態故障。本文面向換節點、合併多倉設定、以 Claude 工作區為準更新 OpenClaw 真值的中高階維運：先給 update 與 migrate 的決策邊界，再列八步 Runbook、四條可貼變更單的陳述、以及只在 VNC 圖形工作階段才能收尾的 Gateway（常見 18789）與系統權限核對表。站內長文僅使用各語言 blog-data.js 已登記的檔名：官方 Docker/Compose 實戰、守護行程與 launchd、常見報錯十解、4.25 冷持久化外掛註冊表；並以 3.x 配置遷移指南對照「五步走抄欄位」舊范式，凸顯 4.26 以機器可讀 diff 為中心的變化。
實務上，migrate 之夜最常爆炸的不是語法，而是誰是 canonical沒寫清：Claude 專案裡的 prompts 目錄與 OpenClaw 主設定如果各自演進，dry-run JSON 會逼你在合併窗口做顯式取捨。把決策寫進內部 Wiki（而不是 Slack 串）才能讓兩週後的 on-call 不至於猜測「當初到底是誰拍板」。同時，若你已用 Docker固定 Gateway 的網路邊界，migrate 後仍要複核 compose 卷掛載與 launchd plist 注入的環境是否仍指向同一資料根；否則會出現「容器內 doctor 全綠、宿主瀏覽器console 報路径漂移」的分裂現象。
Update維持單一路徑上的版本新鮮度；migrate處理多來源真值、目錄結構重塑或跨機對齊。把兩者混用是工單質量崩壞的第一張骨牌：patch 日卻跑整套 migrate 會徒增噪音；相反地，在兩份分叉設定上只做 update 會讓 Gateway、外掛目錄與 state dir 形成黑箱。
讀者若剛從 3.x 遷移指南過來，請注意：當時強調的是欄位對齊與守護行程啟停；4.26 則期待你把「計劃→預演→人工判斷→寫入」拆成可稽核步驟。外掛面相至今仍須與 4.25的冷註冊表敘事扣在一起，否則 repair 與 migrate 的順序會在深夜互相覆寫。
同機小版號、無外掛批次匯入：優先 openclaw update + openclaw doctor。
換機／新路徑：migrate plan + dry-run 對照埠與相對路徑，避免手拷 JSON 成孤兒。
Claude 側已有成熟 MCP/Skill：走 4.26 合併匯入並保留 JSON 審計軌跡。
外掛依賴與唯讀根衝突：把 OPENCLAW_PLUGIN_DIR 與可寫根設計納入 migrate 變更單。
Docker 與裸機並存：先讀 Docker 長文對卷與回環，再進 migrate。
長期 launchd：樹狀設定改動後用 launchd 文複核 EnvironmentVariables。
矩陣列的是「預設懷疑對象」，不是診斷書：若同時懷疑網路與磁碟，先按可觀測性高的路徑（本機 curl、doctor、plugins list）收窄，再翻 十解 的長表。
| 現象 | 優先 | 次優先 | 先別做 |
|---|---|---|---|
| 僅套件過期提示 | update + doctor | 鏡像快取／權限 | 整倉 migrate |
| 新機器路徑全變 | migrate plan | secrets 人工二選一 | 先啟 Gateway 再改檔 |
| Canonical 在 Claude | 4.26 合併 + dry-run | 工單脫敏貼上 | 兩邊各自維護真值 |
| EACCES／唯讀 | 可寫根 + OPENCLAW_PLUGIN_DIR | plugins repair | 全域 chmod 糊弄 |
| 升級後混合 Gateway | 版本對齊 + registry | 4.25 文 | 只重啟不核對二進位 |
順序可直接寫進變更票標題；遠端 Mac 務必讓與 Gateway 同一使用者能開 VNC 圖形工作階段，以處理瀏覽器與系統級同意鏈。18789 監聽是走本機回環或反向代理，須與 dry-run 輸出一致。
實務上 Port、環境變數、反代上游三件事若各寫各的，migrate JSON 就算漂亮也會在執行面撞牆。請把 常見報錯十解 裡的「靜默失敗／401 風暴／WS 斷流」分類表放在第二螢幕，對照 Network 面板逐條消去。備份若只做目錄 tarball 而沒有雲卷快照，回滾會變成考古：變更單務必註明快照 ID 與保留時間。若節點在商用雲，亦應標註資料卷與系統卷是否分離，以免誤刪只讀層並留下隱性債。
版本指紋：openclaw --version、完整 openclaw doctor、渠道與是否容器。
備份：claw backup 或發行說明推薦快照；雲節點加做卷級快照利於一回滾。
Plan：列出將觸碰的路徑、provider、外掛與 secrets 面。
Dry-run／JSON：標示新增、改別名／canonical、需人工作決的鍵。
Claude 匯入核對：指令檔、MCP、技能與憑證提示脫敏後比對衝突。
可寫根：依賴落地後跑 openclaw plugins repair、plugins doctor 對齊 4.25 以降註冊表邏輯。
Gateway：本機或反代至 18789，對照 報錯十解分流。
凍結變更單：記錄 dry-run→apply 差異、回滾點、與 Docker／launchd 銜接。
openclaw --version && openclaw doctor claw backup openclaw migrate <依文件：plan|dry-run> openclaw plugins repair && openclaw plugins list openclaw status
這四則刻意寫成被動語態少、責任主語清楚，方便貼進 Jira / ServiceNow 的「實施摘要」。若稽核方詢問 openclaw migrate 與舊版手抄遷移差異，可直接指向本文與 3.x 指南的對照段。
OPENCLAW_PLUGIN_DIR 類故障歸因可寫性設計，而非暫時網路抖動。以下項目與純 SSH 稽核不重疊：瀏覽器親自點選的同意鏈、可視化外掛清單、以及與 十類典型錯誤 文案相互印證的 Gateway 現象。共享雲主機上還要確認螢幕鎖定與省电不會在打開的 VNC 視窗背後悄悄切斷長連線。
若組織規定所有變更必須留有螢幕錄影或截圖證據，請在同一工作階段內錄製：切換使用者會讓 TCC 與鑰匙圈語境斷裂，錄影也會變成無效證據。對照表通過後，把時間戳與 doctor 輸出摘要一併貼進變更結案欄。
| 項 | 在 VNC 中 | 通過線 |
|---|---|---|
| 回環／反代 | 開發者工具看 Network／WS | 無 401 風暴、WS 不斷流 |
| 系統權限 | 自動化瀏覽器等同意 | 同一使用者點完 |
| 睡眠／省电 | 長連線節點策略 | 與 launchd 期望一致 |
| 外掛 UI | 圖形列表核對 | 與 plugins list 對齊 |
見節01：同機同徑無批次匯入通常 update；換機或合倉再走 plan/dry-run。若合併牽涉多個 Git 遠端，請先在 Wiki 寫 canonical 再跑 CLI。
先可寫卷，再 repair；與 4.25 文連讀。
CLI 與 JSON 可；瀏覽器／系統依節05。
4.25 穩態 repair；4.26 大型併入與可寫根。
migrate 把合倉從「 tarball 心態」推向可預演、可 JSON 審計、可回滾；但若唯讀映像、睡眠策略或 SSH 與圖形使用者不一致等環境債不還，失敗仍會偽裝成玄學權限工單。與 3.x 手抄五步走 相比，4.26 要的是能把 diff 當證據鏈保存的習慣。
自架硬體要扛資本、電力與無人值守更新；要把心力留在合併策略與安全邊界者，可選可 SSH 又可 VNC 覆核的 Apple Silicon 遠端 Mac。若需節點：VNCMac 主按鈕進購買頁；規格與產品說明見首頁。建議把本站 OpenClaw 專題以資料夾方式收藏：upgrade、migrate、registry 健康三條線並行閱讀時最不容易漏閘門。