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

OpenClaw作为企业级AI Agent开发平台，持续迭代带来了诸多新特性与性能优化。4.9版本在多个维度上进行了重要修复，然而对于从旧版本升级而来的用户而言，如果不了解其中的变更细节，很可能会遇到功能异常或行为不符预期的情况。本文将系统性地梳理各版本升级过程中容易踩到的坑，按影响程度和解决紧迫性排列，帮助开发者顺利完成迁移。

配置字段迁移问题

在升级前，建议所有用户执行以下准备步骤：首先备份当前配置文件（通常位于~/.openclaw/config.json），其次运行openclaw doctor进行全面诊断，最后执行 openclaw doctor --fix 自动迁移旧配置。这些前置操作可以避免升级后的大部分问题。

Matrix频道DM策略变更

4.7版本进行了一次配置字段清理，多个旧字段已被彻底移除，包括talk.voiceId、talk.apiKey、Agents.*.sandbox.perSession、browser.ssrfPolicy.allowPrivateNetwork以及hooks.internal.handlers等。此外，各频道的allow开关已统一改为enabled字段。如果配置文件中仍保留这些旧字段，升级后gateway启动时会报错或被静默忽略，导致功能异常。解决方法很简单：升级前运行 openclaw doctor --fix，它会自动检测并迁移旧字段到新配置路径。

其他兼容性修复

Matrix频道的DM策略也发生了重要变化。旧版本中的channels.matrix.dm.policy: "trusted"配置在新版本中不再支持，升级后会导致DM权限行为异常：原本被信任的发送者可能无法触发AI回复，或权限边界变得不可控。同样通过 openclaw doctor --fix 可以将旧策略迁移为兼容的DM策略。

Android扫码配对问题在4.9中得到修复，但升级前已存在的配对异常状态不会被自动修复。建议升级后在Android端手动解除配对，重新走一遍完整配对流程。Slack私有图片附件的认证问题也已解决，跨域跳转时能正确保留bearer auth，升级即可生效。

如有侵权，请联系删除。