OpenClaw 2.0（v2026.8.1）是这个项目史上最大的一次更新：933 名贡献者、合并超过 1.6 万个 PR（接近历史总量的一半），安装器、浏览器控制台、会话存储、权限体系几乎全部重写。新用户装完普遍反馈"真香"，但从 2026.7.x 及更早版本带着旧环境升级的老用户，翻车率相当高——Reddit、Discord 上线当天就堆满了"升级后 Gateway 直接起不来"的帖子。
这篇文章把社区真实报错和官方升级动作清单揉在一起，照着做可以避开 90% 的坑。
一、先搞清楚 2.0 到底变了什么（为什么老环境容易挂）
升级前理解底层变化，排错时才不会瞎撞：
- 会话存储从 JSONL 文件迁到 SQLite：全局库 + 每个工作区独立库。升级后首次启动自动迁移，但旧版本读不了新库——回滚必须先恢复备份，没有后悔药。
- Gateway 重构：冷启动从约 1.6 秒降到约 575 毫秒，并发按 CPU 自动伸缩（典型机器 8-16 路）。启动更快，但配置结构和通道管理也变了。
- 插件机制收紧：官方 provider 包改为按需安装；插件 API 版本校验更严格，旧插件 API 版本不匹配会被直接跳过（skip discovery）。
- 权限体系重做：新增会话权限模式、掩码凭据输入（密钥不进聊天和模型上下文）、自动化一次性授权、插件来源强制展示。
- Node.js 版本要求提高：命令行新装要求 Node.js 22.22.2+，旧 Node 会直接报错。
二、两个破坏性变更（不处理必然报错）
1. OpenProse 插件被移除
内置 OpenProse 插件和 /prose 命令在 2.0 中删除。升级后运行 openclaw doctor --fix 清理残留配置；.prose 源文件会保留，按官方迁移指引改用上游 Agent Skill 即可。
2. OpenAI 路由迁移
所有 codex/*、openai-codex/* 的模型引用、provider 配置、存储会话和自动化路由，会被迁到 openai/*。Codex 运行时意图保留，但有冲突的配置会被标记出来等你确认。
三、社区真实翻车现场与修复
坑 1：升级后 Gateway 起不来——schema 版本错位
典型报错（Mac mini 真实案例）：
OpenClaw state database /Users/xxx/.openclaw/state/openclaw.sqlite uses newer schema version 15; this OpenClaw build supports 1. plugins.entries.acpx: plugin requires plugin API >=2026.7.1, but this host is 2026.6.11; skipping discovery plugins.entries.codex: plugin not installed: codex — install with: openclaw plugins install @openclaw/codex
根因：机器上有多个 OpenClaw 命令入口（npm 全局、pnpm、brew 等），只升级了其中一个——终端里已经是新版，后台跑的 Gateway 还是旧版，旧版打开了新版写过的 SQLite 库，schema 版本对不上。
修复：
- 先停掉所有 Gateway 进程：
openclaw gateway stop，必要时按openclaw logs找到残留进程手动 kill； - 确认所有入口版本一致：
which -a openclaw（Mac/Linux）或where.exe openclaw（Windows），逐个openclaw --version； - 旧入口卸载或升级到同一版本；
- 还在 beta 通道的先切 stable：
openclaw update --channel stable； - 缺的官方插件按提示补装：
openclaw plugins install @openclaw/codex等，装完openclaw gateway restart。
坑 2：六个官方插件要同步迁移，第三方插件直接报警
2.0 把火山引擎、Mistral、BytePlus 等 provider 包移出了核心，改为按需安装。升级后 doctor 会列出 "plugin not installed" 清单，逐条执行 openclaw plugins install ... 即可。第三方插件如果没适配新工具合约（tool schema），注册阶段就会被拦——这类只能等插件作者更新，不要强行改配置绕过。
坑 3：Gateway 反复重启 → 崩溃循环断路器把通道全熔断
这是最有迷惑性的一个坑：你好不容易把 Gateway 修好，发现钉钉、飞书、微信、企业微信、Telegram 这些通道全都不自动启动，日志里写着"自动启动被崩溃循环断路器抑制（crash-loop breaker suppressed）"。
这不是通道配置写错了——是 Gateway 前面翻车次数太多，保护机制把通道自启锁死了，防止故障放大。修复：确认 Gateway 稳定运行一段时间后，手动逐个拉起通道（openclaw gateway restart 后在 Control UI 或配置里重新启用对应 channel），断路器解除后恢复正常。别上来就删通道配置重装。
坑 4：安全配置"裸奔"警告
升级后 openclaw security audit 可能报一堆 dangerously- 开头的警告：允许不安全认证、关闭设备认证、放宽源站校验……更危险的是配置写着绑定 lan 实际监听 0.0.0.0（全网卡可达）。2.0 安装器会拦截未认证的网络 Gateway，但升级安装不保证默认安全。务必：
- 跑一遍
openclaw security audit和openclaw sandbox explain，逐项处理危险项； - Gateway 不要暴露到公网零认证——尤其放在云服务器上的同学，安全组只放行必要端口，或加反代+鉴权；
- 控制面报
operator.read权限缺失时，在共享配置里补上对应角色权限。
坑 5：依赖环境——Git 没进 PATH、Node 版本旧、权限目录敏感
- Node.js：升级到 22.22.2+，
node -v确认； - Git：2.0 用 Git 做配置同步和版本管理，Git 不在 PATH 会直接报错（比 Python 缺失更容易踩）；
- 磁盘：会话日志、记忆快照、模型临时文件建议预留 20GB 以上；
- 安装目录权限：2.0 对安装目录权限更敏感，Windows 下避免装在需要管理员写入的系统目录，Linux/macOS 不要随手
sudo混跑导致属主错乱。
坑 6：依赖旧文件结构的自动化会静默失效
会话迁到 SQLite 后，直接读 ~/.openclaw/sessions/*.json 的备份脚本、分析工具、CI/CD 集成会静默失败（不报错但没数据）。升级前盘点所有外部自动化，改用新的 sessions API；升级后跑 openclaw config validate 清理废弃配置项。
四、官方五步升级清单（照抄就行）
# 1. 先备份配置和状态（升级失败时回滚用） cp -r ~/.openclaw ~/.openclaw.bak-$(date +%F) # 2. 升级（beta 通道用户先切 stable） openclaw update --channel stable # 3. 迁移破坏性变更 + 清理残留配置 openclaw doctor --fix # 4. 验证 Gateway 正常启动 openclaw doctor openclaw gateway status openclaw logs --follow # 5. 缺 provider 包就补装，装完重启 Gateway openclaw update repair openclaw gateway restart
Windows 用户把第 1 步换成 PowerShell：Copy-Item -Recurse $env:USERPROFILE\.openclaw "$env:USERPROFILE\.openclaw.bak-$(Get-Date -Format yyyy-MM-dd)"。
五、升级后的最小验收闭环
日志没有持续报错才算完。按这个顺序过一遍：
openclaw --version确认所有入口版本一致；openclaw status+openclaw gateway status正常；- Control UI 能打开，发一条文本消息有响应；
- 读一个工作区文件、执行一个低风险 Skill，验证权限链路；
- 常用通道（Slack/飞书/Telegram 等）逐个发消息测试——注意崩溃循环断路器可能需要手动解除；
openclaw security audit无高危项。
六、回滚方案（最后防线）
2.0 的 SQLite 库旧版本读不了，回滚 = 恢复备份：
- 停止 OpenClaw 全部进程；
- 把
~/.openclaw改名归档，恢复升级前的.openclaw.bak-日期； - 通过包管理器装回旧版本（npm/pnpm/brew 对应命令）；
- 启动后确认会话和配置回到升级前状态。
生产环境建议：先在测试机或云服务器上演练一遍升级，确认插件和通道都正常，再动主力环境。
常见问题
升级后日志里全是 "plugin requires plugin API >=2026.7.x, but this host is 2026.6.x" 怎么办？
这是典型的多入口版本不一致：后台 Gateway 还是旧版。按"坑 1"的步骤统一所有 openclaw 入口版本，重启 Gateway 即可。
openclaw doctor 提示 "This install is not a git checkout" 是失败了吗？
不是。这只是说你不是 git 克隆安装，提示你用包管理器（npm/pnpm）更新而已，按提示跑 openclaw update 后重新 openclaw doctor。
升级后历史会话还在吗？
在。首次启动自动把 JSONL 导入 SQLite。但导入是单向的，降级前必须恢复备份，否则旧版本看不到新会话。
2.0 值得升级吗？
新环境直接装 2.0，没有历史包袱；老环境按本文 SOP 先备份再升级，收益（浏览器控制台、云会话、权限体系、3 倍 Gateway 启动速度）远大于迁移成本。跑关键自动化的环境建议先在测试机验证。
信息来源：OpenClaw v2026.8.1 官方发布说明与升级文档、官方博客《OpenClaw 2.0, Accidentally》（2026-08-30）、社区升级实录（Answer Overflow、CSDN、博客园，2026 年 8 月 31 日 - 9 月 4 日）。本文命令以官方发布说明为准，升级前请核对官方文档最新表述。