OpenClaw 4.9 升级踩坑指南，老用户必看

OpenClaw 4.9 值得升级，但如果你还在用旧版本，直接升上来可能会撞上几个不那么明显的问题。这篇文章把各版本升级过程中容易踩到的坑汇总了一遍，按严重程度和影响范围排列。

坑一：旧配置字段直接失效

这是最容易被忽视、影响最大的一个。

4.7 版本做了一次配置字段清理，以下旧字段被彻底移除：

• ▶talk.voiceId / talk.apiKey
• ▶Agents.*.sandbox.perSession
• ▶browser.ssrfPolicy.allowPrivateNetwork
• ▶hooks.internal.handlers
• ▶各频道的 allow 开关（改为统一的 enabled 字段）

如果你的配置文件里还有这些字段，升级后 gateway 启动时要么报错、要么静默忽略，行为会和你预期的不一样。

解决方法：升级前先跑一次 openclaw doctor --fix，它会自动检测旧字段并迁移到新的配置路径。不要跳过这一步。

坑二：Matrix 频道的 DM 策略配置失效

如果你用 Matrix 作为消息频道，旧版本里的 channels.matrix.dm.policy: "trusted" 这个配置在新版本里已经不再支持。

升级后如果不处理，DM 权限行为会出现意外：原本被信任的发送者可能无法正常触发 AI 回复，或者权限边界变宽导致非预期的访问。

解决方法：同样是跑 openclaw doctor --fix。它会把旧的 trusted 策略迁移为兼容的 DM 策略，保留你原来的 allowFrom 边界，对于空配置则默认为 pairing 模式。

坑三：Android 扫码配对概率性失败

4.9 之前的版本在 Android 扫码配对上有一个老问题：扫码后如果旧的验证码状态没有被清除，新的配对流程可能复用了过期的认证信息，导致配对看似成功但实际 session 不可用。App 切到后台再切回来还会触发自动重试，更容易把状态搞乱。

升级到 4.9 后这个问题被修复，但如果你升级前就处于配对异常状态，升级本身不会自动修复存量的坏状态。

解决方法：升级后在 Android 端手动解除配对，重新扫码走一遍完整配对流程，不要依赖残留的旧配对状态。

坑四：Slack 私有图片附件无法加载

如果你在 Slack 频道里用 OpenClaw 处理带图片附件的消息，旧版本里 url_private_download 类型的图片 URL 在经过 Slack CDN 跳转后会丢失认证 token，导致图片拉取失败、AI 看不到图片内容。

这个问题在 4.9 中修复了（跨域跳转时正确保留 bearer auth），但如果你还在用 4.7 及以下版本，图片相关的任务会静默失败——AI 会说"没有收到图片"，但实际上是认证失败了，不是图片没发。

解决方法：升级到 4.9 即可解决。升级前如果要规避，改用直接上传图片到对话而非依赖 Slack 私有 CDN 链接。

坑五：/reset 和 /new 之后模型被意外锁定

这是一个比较隐蔽的行为变化。旧版本里，如果你的会话因为报错触发了自动 fallback，AI 会切换到备用模型并把这个选择"钉住"——问题是，这个钉住的状态在你执行 /reset 或 /new 之后并不会被清除。

结果就是：你以为新会话会用默认模型，实际上还在用那个 fallback 模型，而且没有任何提示。

4.9 修复了这个逻辑：/reset 和 /new 会清除自动 fallback 锁定的模型选择，但会保留你明确手动设置的模型。

解决方法：升级即可。如果升级前已经遇到这个问题，用 /model default 或直接 /reset 后指定模型名来强制重置。

坑六：Windows 用户更新时构建失败

4.9 对 Windows 平台的 pnpm 构建步骤增加了堆内存上限，以解决更新时 Node 内存不足导致构建失败的问题。但这个修复只在 4.9 自带的更新脚本里生效——如果你用的是旧版本的更新命令去更新到 4.9，还是可能在构建阶段因为内存不足失败。

解决方法：Windows 用户升级时，建议先手动设置环境变量 NODE_OPTIONS=--max-old-space-size=4096，再执行更新命令。

坑七：Claude CLI 认证配置被清理

4.8 版本做了一个影响较大的变更：将 Claude CLI 后端从新用户引导（onboarding）流程中移除，转而主推直接 API 接入。这个变更本身没有问题，但如果你的配置里有旧的 anthropic:claude-cli 认证状态，升级到 4.8+ 之后这些配置会变成"残留"状态，可能导致 Anthropic provider 初始化时报错或走错认证路径。

解决方法：运行 openclaw doctor 检查认证状态，发现残留的 claude-cli 配置时按提示执行修复命令（4.9 的 doctor 会给出具体的 reauth 命令，不用自己猜）。

坑八：npm 直接安装的版本插件依赖缺失

如果你是通过 npm 全局安装 OpenClaw 而不是从 git 源码构建，旧版本存在一个打包问题：某些频道插件（如 Nostr）的运行时依赖没有被正确打入发布包，安装后看起来成功，但在启动时才会因为依赖找不到而崩溃。

4.9 修复了打包流程，会在 packed tarball 测试阶段提前暴露缺失依赖，不再等到运行时才崩溃。

解决方法：如果你目前遇到"启动时某个频道插件报 module not found"的问题，升级到 4.9 可以解决。升级前的临时方案是在 OpenClaw 安装目录下手动 npm install 缺失的包。

升级前的标准检查清单

汇总一下，升级之前建议按顺序做这几件事：

第一步，备份当前配置文件（通常在 ~/.openclaw/config.json 或你自定义的配置路径）。

第二步，运行 openclaw doctor 查看当前配置和认证状态中有没有已知问题。

第四步，如果你用 Android 配对，升级后重新走一遍配对流程，不要依赖旧状态。

第五步，Windows 用户在执行更新前设置 NODE_OPTIONS=--max-old-space-size=4096。

第六步，升级完成后用 /status 确认当前模型和认证状态符合预期。

总结

4.9 的这批修复整体上是把旧版本里积累的问题兜底清掉了。最需要注意的是配置迁移（坑一）和 Matrix 策略变更（坑二），这两个如果不处理，升级后行为会和你预期的明显不符。其余的坑大多是"升级后自然消失"的类型，但知道原因能省下不少排查时间。