何时 migrate · plan/dry-run · JSON 怎么读 · VNC 下 Gateway 八步
v2026.4.26 在 CLI 上强化了「把外部权威并入 OpenClaw」的路径：openclaw migrate 支持 plan、dry-run、JSON 报告 与 预迁移备份，并内置可从 Claude Code / Claude Desktop 导入指令、MCP、技能与凭据提示 的合并流程。与此同时，OPENCLAW_PLUGIN_DIR 场景下对可写依赖根的修正在远程租机上更容易暴露为「依赖装到一半失败」或「冷注册表与磁盘路径对不齐」。本文面向要换机、要合仓、要从中台配置迁入的中高级用户，给出 migrate 与 openclaw update 的决策矩阵、八步 Runbook、四条可贴进工单的结论文本、以及 在 VNC 图形会话里对 Gateway（常见 18789）与系统面板的按序验收表；并链到 《官方 Docker 部署》、《守护进程与 launchd》、《常见报错 10 解》 与 《4.25 冷持久化插件注册表》 以便 upgrade、migrate 与日常巡检分工清晰。
把两件事混用是工单爆炸的第一原因。Update 解决的是「同一台机器、同一路线」上跟随补丁；migrate 解决的是「多来源配置要合并、目录结构要变、或要跨机对齐权威」。下面六条是常见误判，与站内 旧版配置迁移文 相比，4.26 的 migrate 更偏可审阅的合并与导入，不是简单的五个字段手抄。
同机小版本、无新导入：优先 openclaw update，跑 openclaw doctor 即可，不必为迁移而迁移。
换机 / 新节点：用 migrate 的 plan + dry-run 对照目录与端点，避免手拷 .json 把相对路径、端口与 state dir 拷成孤儿。
Claude 工作区有成熟指令、MCP、Skill：用 4.26 带的合并导入路线，比「两边各开一份再人肉合并」可审计得多。
插件/依赖与只读根冲突：把 OPENCLAW_PLUGIN_DIR 与可写根放到 migrate 的变更清单里，一次看清「装到哪里算合法」。
Docker/Compose 与裸机混跑：先读 Docker 长文 的卷与回环，再进 migrate，避免同端口双登记。
长期 launchd/launchctl：改配置树后用 launchd 文 里的验收步复核plist环境是否仍注入正确。
| 现象 | 优先怀疑 | 次优先 | 先别做 |
|---|---|---|---|
| 同机小版本，日志仅提示包过期 | update + doctor | 镜像缓存/权限 | 整仓 migrate |
| 新机器，路径全变 | migrate plan 对路径映射 | 手拷 json | 先启动 Gateway 再改文件 |
| Claude 侧有 MCP/Skill 清单要并进 | 4.26 合并导入 + dry-run | 只贴 prompts | 在两边各维护一份真值 |
| 依赖安装报 EACCES/只读 | 可写根 + OPENCLAW_PLUGIN_DIR | plugins repair | 用 sudo 全局改权限糊弄过去 |
| 升级后「混合旧新」Gateway | 版本对齐 + 注册表 | 见 4.25 文 + 本稿步骤 6 | 只重启不核对二进制 |
下列顺序写进 Runbook 标题即可给外包执行；远程 Mac 上请保证与 Gateway 同一用户能开 VNC 图形会话，以便处理浏览器与系统级同意链。
版本指纹：openclaw --version 与 openclaw doctor 全量输出存档；标注渠道（stable/beta）与是否容器。
备份：按发行说明使用 claw backup 或文档推荐快照；云节点另做卷/目录级镜像更好回滚。
Plan：运行 openclaw migrate 的 plan/预览类子命令，收集将要触碰的路径、provider、插件与 secrets 面。
Dry-run 与 JSON：在合并窗口审 JSON：哪些键是添加、哪些是改别名/迁移 canonical、哪些要人工二选一。
Claude 导入核对：对指令文件、MCP 端点、Skill 与凭据提示做脱敏后比对；有冲突时写明真值源在 OpenClaw 还是 Claude 工作区。
可写根与 OPENCLAW_PLUGIN_DIR：把依赖装到可写根；再跑 openclaw plugins repair 与 plugins doctor 对齐 4.25 以来的注册表逻辑。
拉 Gateway：本机或反代到 18789 的控制台、WebSocket、健康与日志，对照 报错文 的分流表。
冻结变更单：写清「从 dry-run 到 apply 的差异、回滚点、与 Docker/launchd 的衔接」。
# 以你环境文档为准，占位符只表达顺序而非固定子命令名 openclaw --version && openclaw doctor claw backup # 或等效预迁移快照 openclaw migrate <plan|dry-run 参数> # 审 JSON/差异 # 审阅完毕后再 apply / 合入 Claude 侧 openclaw plugins repair && openclaw plugins list openclaw status # 关注 Gateway/health
OPENCLAW_PLUGIN_DIR 与只读镜像冲突时，根因归类为可写性而非「网络不好」；修复顺序是先路径与权限、再 repair。| 项 | 在 VNC 中做什么 | 通过线 |
|---|---|---|
| 本机回环/反代 | 浏览器开控制台与 Network 面板 | 无 401/403 级联、WS 不抖断 |
| 系统权限 / 剪贴板 | 如迁移涉及自动化浏览器或本地桥 | 弹窗在同用户会话中点完，不是后台猜答案 |
| 多屏/睡眠 | 对长期连线节点确认节能策略 | 与 launchd plist 的期望一致 |
| 插件页 / Doctor | 在 UI 中核对列表与版本线 | 与 CLI plugins list 对齐 |
卷、回环、容器内 verify 与裸机对比。
阅读 →改配置树后环境变量与常驻进程如何对齐。
阅读 →repair 与混合版本 Gateway 的例行巡检。
阅读 →见第一节：同机、同路径、无外部 bulk 导入时通常 update 即够；换机或合仓再走 migrate 的 plan/dry-run。
先让依赖根在可写卷落稳，再跑 plugins repair；与 4.25 注册表文连读。
命令与审 JSON 可以；浏览器/系统侧以第五节为准。
4.25 重稳态与 repair；4.26 migrate 重并入与可写根修正。
migrate 把「换机 / 合仓 / 合配置」从一次性手工拷贝，推成了可预演、可 JSON 审计、可回滚 的工程动作；但只要你仍在只读镜像层、睡眠策略混乱、或 SSH 与图形会话用户不一致的环境里硬推，失败依然会表现为「某步权限没点完」的玄学工单。
在自有矿机上自负盈亏固然可行，但要同时扛硬件、电力、系统更新与无人值班。相较之下，按项目租一台可 SSH、可 VNC 的 Apple Silicon 远程 Mac、把机头状态交给平台镜像与 SLA，更适合把团队精力放在 migrate 的真值与合并策略上。
若你需要一台便于按本文八步在同一会话里对 Gateway 与系统面板做验收 的节点，可通过 VNCMac 租用云端 Mac：主按钮进入购买页；选型与产品说明见首页；与 OpenClaw 相关的多语言长文与帮助页在站内公开目录下可交叉打开。