升级到 OpenClaw 2.0（v2026.8.x 稳定线）
从任意 2026.x 版本安全升级到 OpenClaw 2.0：备份、升级、doctor 迁移、验证与回滚，覆盖 OpenProse 移除与 codex/* 路由迁移两条破坏性变更线。
准备工作
- A running OpenClaw 2026.x install (any channel)
- Terminal access and free disk space
- A verified backup completed before upgrading (step 1)
操作步骤
确认当前版本并创建验证备份
OpenClaw 2.0 带配置迁移，先记录当前版本号，再用官方备份命令生成带校验的完整状态恢复点。openclaw update 只自动保留配置副本，不等于完整备份。
命令 / 操作
openclaw --version mkdir -p ~/Backups/openclaw && openclaw backup create --output ~/Backups/openclaw --verify 小提示
- • Backup archives may contain credentials and channel state; store them owner-only
- • Note the backup point: restoring state later discards changes made after it
预览并执行升级
openclaw update 会检测安装类型（npm/pnpm/Bun/git）、拉取最新版、跑 doctor 并重启 Gateway。先用 --dry-run 预览计划再执行；生产环境保持 stable 渠道。
命令 / 操作
openclaw update --dry-run openclaw update 小提示
- • v2026.8.2 (Sep 1) is the stable line's first update: dock the Home agent with Cmd/Ctrl+Shift+H; a Linux .deb/AppImage desktop companion lands; upgrade protection improved (newer config preserved, incomplete migrations no longer claim success). Upgrading straight to it is recommended.
- • For long-lived stability switch to extended-stable: openclaw update --channel extended-stable (long-lived channel with backported fixes)
- • Avoid the beta channel on production installs
运行 doctor 完成两条迁移线
OpenClaw 2.0 有两条破坏性变更：内置 OpenProse 插件与 /prose 命令移除；codex/* 与 openai-codex/* 引用迁移到 openai/*（覆盖 provider 配置、已存会话与自动化路由）。openclaw doctor --fix 会自动处理，冲突项会标记出来。
命令 / 操作
openclaw doctor --fix 小提示
- • Gateway startup also auto-runs safe config migrations, but an explicit doctor --fix after upgrade is more reliable
重启 Gateway 并逐项验证
迁移完成后重启 Gateway，再依次确认版本、健康状态、插件清单与深度探测全部通过。
命令 / 操作
openclaw gateway restart openclaw health openclaw plugins list --json openclaw gateway status --deep --json 小提示
- • Expect version 2026.8.1; if plugins list is missing BytePlus, Mistral, Volcengine or other provider packages, run openclaw update repair and restart — providers now install on demand in 2.0
善后：.prose 文件与路由冲突
两条迁移线的收尾：原有的 .prose 文件会被保留，按上游 Agent Skill 的方式继续使用；doctor 标记出的 openai/* 路由冲突需要手动检查修复——尤其是自定义 provider 配置和自动化任务里硬编码的 codex/ 引用。
小提示
- • Search your config and automations for codex/ and openai-codex/ and switch them to openai/
- • Smoke-test any Codex-model-routed task before returning it to daily use
插件与 SDK 开发者：9 月 1 日门禁
如果维护自定义插件，注意多个 plugin-sdk-* 子路径导入将收敛为 openclaw/plugin-sdk/ 聚焦导入，官方门禁时间为 2026 年 9 月 1 日。保留的公开 helper 保持原有调用名，可先在测试环境跑兼容警告定位受影响的导入。
小提示
- • The official SDK migration guide lists the full subpath mapping — replace them one by one
- • Unmigrated plugins will hard-fail on the new runtime after September 1
出问题时分两层回滚
官方把回滚拆成两层：第一层只回退 OpenClaw 代码、保留当前状态（先试这层）；第二层才恢复更新前的备份状态（会丢弃备份之后的更改，最后手段）。
命令 / 操作
npm i -g openclaw@2026.7.1 # 代码级回滚示例：重装旧版并保留状态 openclaw gateway restart 小提示
- • Restore the backup state only when the old code cannot read the migrated config or database