ARTICLE · 997261
OpenClaw 8.1 升级,先查这 7 件事
今天我把 OpenClaw 从 7 月版升到 8.1，前后修了 40 分钟：网关起不来，反向代理返回 403，微信渠道崩溃循环，最后还遇到了会话不回复。
所以先给结论：OpenClaw 8.1 不适合“点一下直接升级”。 它虽然是版本号 8.1，但官方发布说明已经把它称为 OpenClaw 2.0，涉及配置、会话、插件和状态存储的变化都不少。
如果你准备升级，重点检查下面 7 件事。
1. 先看 breaking changes
8.1 的新功能很多，包括会话搜索、云 Worker、持久进度卡片、交互式 Widget 和凭证请求卡片。但升级前更应该先看 Changes 和 Breaking changes：
• 内置 OpenProse 插件和 /prose命令移除，需要迁移到 Agent Skill；• codex/*、openai-codex/*模型引用和相关路由需要迁移到openai/*；• 外部插件的 SDK 导入路径正在进入迁移窗口。
官方将部分 SDK 变化标为 2026 年 9 月 1 日的 upcoming gate，也就是即将到来的兼容门槛，不等于 8.1 已经删除所有旧入口。具体是否受影响，要看宿主版本和插件版本的组合。
2. 升级前先备份，并停止网关
先做一份带校验的备份：
openclaw backup create --verify涉及 doctor --fix、会话导入、SQLite 压缩或恢复时，先停止 Gateway。在线状态写入和离线迁移同时进行，最容易把问题变成数据库锁、状态不一致或重复迁移。
3. 用 doctor 做升级检查
升级后不要马上恢复渠道和定时任务，先执行：
openclaw doctor --lint
openclaw doctor --post-upgrade
openclaw doctor --fix三个命令的用途不同：--lint 只读检查，--post-upgrade 检查插件兼容性，--fix 才会修改配置和持久化状态。
不要把 --fix 当成万能修复键。执行前确认备份存在，执行后检查输出，必要时再运行一次 doctor --lint。
4. 多 Agent 要检查会话迁移
旧安装里的 sessions.json 和 JSONL 历史，不一定会自动变成新的 SQLite 会话。多 Agent 环境尤其不能只验证默认 Agent。
官方建议先检查、预演，再导入：
openclaw doctor --session-sqlite inspect --session-sqlite-all-agents
openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json
openclaw doctor --session-sqlite import --session-sqlite-all-agents这些操作应在网关停止、状态已备份的情况下执行。导入完成后，再检查各 Agent 的历史记录是否可见，避免出现“网关已启动，但旧会话全不见了”的情况。
5. 单独验证渠道插件
核心网关能启动，不代表微信、飞书等渠道也能用。
升级前检查插件仓库的兼容矩阵和 CHANGELOG，尤其关注 openclaw/plugin-sdk/* 导入路径。升级后执行 doctor --post-upgrade，再逐个渠道完成登录、收消息和发消息测试。
我这次微信渠道出现了 Package subpath './plugin-sdk/channel-runtime' is not defined。这类错误不能简单归因于“8.1 删除了某个入口”，更准确的判断是：宿主、插件和 SDK 导出面之间发生了兼容性问题。
临时修改 dist 文件可以用于定位问题，但不适合作为长期方案。优先更新插件、回退到兼容版本，或等待上游修复。
6. trustedProxies 不要写得过宽
如果升级后控制台返回 403，检查反向代理配置。
trustedProxies 应该填写实际的 nginx、Caddy 或 Traefik 地址，不要直接信任整个内网网段。同时让代理覆盖或安全重建 X-Forwarded-For，避免保留客户端自行追加的内容。
示意配置：
{
"gateway": {
"trustedProxies": ["127.0.0.1", "::1", "192.168.0.3"]
}
}其中 IP 只是示例，实际值要换成你的代理地址。
7. 最后做一轮真实验证
不要只看进程状态是 running。建议按这个顺序测试：
配置检查 → 网关健康 → 控制台登录 → Agent 对话
→ 各渠道收发消息 → 定时任务投递 → 会话能否继续升级前确认没有正在执行的长任务。强制停止网关可能留下“仍在回复”的会话，新消息会进记录，却不会立即派发。
如果网关曾经连续崩溃，渠道自动启动也可能被抑制。此时根据日志执行 openclaw secrets reload，再手动启动渠道，不要盲目重复重启。
一份简版清单
•记录 OpenClaw、Node.js、Agent 和插件版本 •阅读 breaking changes，确认 OpenProse、模型路由和 SDK 迁移项 •执行 openclaw backup create --verify•停止网关后执行状态迁移 •升级前后执行 doctor --lint•验证所有渠道和多 Agent 会话 •确认长任务、定时任务和消息投递正常
一句话总结：升级 OpenClaw 8.1 前，先做预检和备份；升级后，先修状态，再测插件，最后恢复业务。
参考资料
1. OpenClaw v2026.8.1 发布说明（2026-08-31 查阅） 2. OpenClaw Doctor 命令文档（2026-08-31 查阅） 3. OpenClaw Plugin SDK migration（2026-08-31 查阅） 4. OpenClaw Backup 命令文档（2026-08-31 查阅） 5. Tencent/openclaw-weixin（兼容矩阵与插件说明，2026-08-31 查阅） 6. OpenClaw issue #115478：微信插件与 SDK 子路径兼容性问题（2026-08-31 查阅）
说明：文中 40 分钟、多 Agent 和会话异常为作者本次环境中的记录；命令和版本行为以官方文档及对应项目页面为准，不代表所有安装方式都会复现相同现象。