已在使用 OpenClaw 旧版，准备升级到 2026.3.x 却担心配置不兼容？2026.3.x 调整了默认配置逻辑（如 tools.profile、ACP dispatch），旧教程里的写法可能失效。本文说明为何要迁移、升级前必做的备份与检查、5 步迁移流程（安装/升级 → onboard 向导 → API 与权限 → 守护进程 → 验证），以及权限回退、端口冲突、环境变量等在 VNC 远程 Mac 上的常见坑与 FAQ，帮你少踩雷、一次跑通。
① 2026.3.x 为何要迁移？旧教程失效与主要变更说明
2026.3.x 对安全与默认行为做了收紧：新安装时 tools.profile 默认改为 messaging（仅消息/会话工具），若你依赖文件读写、终端执行等，升级后会出现「没权限」；ACP 的 dispatch 默认开启，可能改变多 Agent 路由行为；插件 HTTP 注册方式也有变更。因此沿用旧版配置或照抄旧教程，容易升级后无法正常使用。
| 变更项 | 旧版常见状态 | 2026.3.x 默认/建议 |
|---|---|---|
| tools.profile | 未显式或为 coding/full | 新装默认 messaging；需读写/执行时改为 coding 或 full |
| acp.dispatch | 多未配置 | 默认 enabled；仅要 /acp 不自动路由时可关闭 |
| 插件 HTTP 注册 | registerHttpHandler 等 | 注册行为变更，需检查插件代码与文档 |
② 升级前必做：备份、版本确认、依赖检查
升级前完成三件事，可避免升级失败或配置丢失后无法回退。
备份配置与工作区
复制 ~/.openclaw/openclaw.json 与 ~/.openclaw/workspace/ 到安全位置。迁移到新机器时这两处一起拷贝，再执行 openclaw doctor 与 openclaw gateway restart。
版本与依赖
确认当前 Node 版本（推荐 20+）；运行 openclaw doctor 做迁移与修复；运行 openclaw config validate 检查配置语法。
检查现有 tools 与 ACP
执行 openclaw config get tools 查看当前 profile；若使用 ACP，确认 acp.dispatch.enabled 是否符合预期。
③ 5 步迁移流程：安装/升级 → onboard 向导 → API 与权限 → 守护进程 → 验证
步骤 1：通过 npm install -g openclaw@latest 或官方安装脚本升级到 2026.3.x。
步骤 2：运行 openclaw onboard 进入配置向导，按提示选择使用场景（个人/团队）、安装方式（QuickStart 等）、AI 模型与 API（OpenAI/Claude/第三方）。
步骤 3：在 ~/.openclaw/openclaw.json 中确认或设置 tools.profile 为 coding（常规文件与运行）或 full；如需关闭 ACP 自动路由，设置 acp.dispatch.enabled: false。
步骤 4：若使用 daemon/LaunchAgent，执行 openclaw onboard --install-daemon 或按文档配置守护进程，并确保 plist/环境变量中含正确 PATH 与 API 相关变量。
步骤 5：执行 openclaw gateway restart，再用 openclaw health 验证服务正常；在远程 Mac 上建议用 VNC 连上桌面做一次完整操作，确认无未处理的权限弹窗。
④ 常见坑：权限回退、端口冲突、环境变量、在 VNC 远程 Mac 上的注意点
权限回退：升级后若出现「无读/写/执行权限」，多半是 tools.profile 被设为 messaging；改回 coding 或 full 并重启 gateway。
端口冲突：若提示端口被占用，用 lsof -i :端口号 查占用进程，结束或修改配置换端口。
环境变量：通过 launchd 或 PM2 启动时，需在 plist 或 ecosystem 中显式配置 PATH 与 API 相关变量，否则交互终端能跑、后台服务报错。
VNC 远程 Mac：升级与首次授权时务必用 VNC 连上桌面，以便处理系统权限弹窗与 Keychain；升级完成后可再配合 SSH 做自动化。避免在仅 SSH 环境下升级，否则弹窗无法点击会导致卡死。
openclaw doctor 自动应用迁移与修复；迁移到新机器时同时拷贝 ~/.openclaw/ 与 ~/.openclaw/workspace/ 可保留配置、通道状态与凭证。⑤ FAQ：回滚、多实例、与站内部署/排错文章的衔接
如何回滚？ 若有备份的 openclaw.json 与工作区，可恢复后安装旧版 npm 包并重启服务；无备份时需按新逻辑重新配置。
多实例如何迁移？ 每个实例对应独立配置目录；分别备份、分别升级并验证，注意端口与 profile 区分。
站内相关文章：若遇安装失败或运行报错，可参考本站《OpenClaw 常见报错与排查指南》；若需在远程 Mac 上处理授权弹窗，可参考《OpenClaw 授权弹窗与安全隔离》；环境选型可参考《OpenClaw v2026.3.7 环境选型》。
结语：在远程 Mac 上升级 OpenClaw 为何更推荐带 VNC 的环境？
2026.3.x 的配置迁移涉及多次「首次运行」与可能的系统权限、Keychain 弹窗，纯 SSH 无法点击这些对话框，容易卡在 halfway 状态。在带 VNC 的远程 Mac上，你可以像在本地一样完成 onboard、处理弹窗、查看 openclaw health 与日志，升级路径清晰、排障也更快。若你希望减少「升级后起不来、权限对不上」的反复折腾，在 VNCMac 提供的远程 Mac 节点上做升级与验证，再按需用 SSH 做日常自动化，往往是更稳、更省时的选择。