OpenClaw 迭代很快，版本号是按日期命名的（格式 2026.x.x），每次更新都可能带 Breaking Changes。这篇文章整理了真实踩过的坑，来源是 GitHub Issues 和官方 Changelog，每个问题都有对应的解决方式。

升级之前，先把这一步做了：

openclaw doctor
openclaw doctor --fix

openclaw update 命令本身会在升级后自动跑 openclaw doctor 并重启 Gateway，但额外手动跑一次不会有坏处。

坑一：配置字段被废弃，Gateway 升级后起不来

这是 GitHub Issue #35957 记录的真实案例，从 v2026.3.2 升级到 v2026.3.3 之后，有用户的 Gateway 连续崩溃了 18 个小时。

报错日志类似这样：

"gateway.controlUi: Unrecognized keys: \"autoApproveDevices\", \"requirePairing\""

原因是 v2026.3.3 的配置 schema 里删掉了 autoApproveDevices 和 requirePairing 这两个字段，但 OpenClaw 对未知字段的处理是直接拒绝启动，而不是忽略。

解决方式：手动编辑 ~/.openclaw/openclaw.json，删掉报错提示的那些字段，然后重启：

openclaw gateway restart

预防方式：升级之前先检查配置合法性：

openclaw doctor
# 如果 doctor 支持的话
openclaw config validate

升级后发现 Gateway 启动失败，先看日志找具体报错字段：

openclaw gateway logs

坑二：升级时 dist 文件被覆盖，Gateway 当场崩溃

这是 GitHub Issue #54790 记录的问题，从 v2026.3.13 升级到 v2026.3.24 时触发，表现是 Gateway 升级完直接崩溃，重启也失败。

根本原因：npm install -g openclaw 会直接覆盖 dist/ 目录，但此时 Gateway 进程还在运行，它引用的模块文件被替换掉了，立刻报找不到模块的错误：

Error: Cannot find module '.../dist/audit-membership-runtime-BT91Am6G.js'

热加载机制检测到异常后发送 SIGTERM 杀掉 Gateway，launchd / systemd 尝试重启又因为文件还没完全写入而失败，触发启动限速，陷入循环。

临时解决（macOS launchd）：

launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

临时解决（Linux systemd）：

openclaw gateway stop
openclaw gateway start

预防方式：升级前先手动停掉 Gateway，升级完再启动：

openclaw gateway stop
npm install -g openclaw  # 或 openclaw update
openclaw gateway start

官方的 openclaw update 命令理论上应该处理这个顺序，但实际遇到问题时手动控制更可靠。

坑三：CLAWDBOT_ / MOLTBOT_ 环境变量改名

v2026.3.22 是一次大版本清理，彻底移除了旧名字时代（Clawdbot、Moltbot）遗留的所有环境变量名，没有兼容层。

如果你的 .env、docker-compose、systemd 服务配置里有这类变量：

CLAWDBOT_GATEWAY_PORT=18789
MOLTBOT_STATE_DIR=/data/openclaw

升级后它们会被完全忽略，相关功能静默失效，不会报错，很难发现。

解决方式：全局搜索你的配置文件，把所有 CLAWDBOT_* 和 MOLTBOT_* 改成对应的 OPENCLAW_*：

# 找出所有相关文件
grep -r "CLAWDBOT_\|MOLTBOT_" ~/.openclaw/ /etc/systemd/ ~/

常见的改名对照：

旧变量名 新变量名
CLAWDBOT_GATEWAY_PORT OPENCLAW_GATEWAY_PORT
MOLTBOT_STATE_DIR OPENCLAW_STATE_DIR
CLAWDBOT_CONFIG_PATH OPENCLAW_CONFIG_PATH

同版本还移除了 ~/.moltbot 状态目录的自动检测，如果你的数据还在 ~/.moltbot，升级前手动迁移：

mv ~/.moltbot ~/.openclaw

坑四：插件 HTTP 路由 API 变更（影响自定义插件开发者）

v2026.3.2 删掉了插件 HTTP 路由的旧 API api.registerHttpHandler(...)，新的写法是：

// 旧写法（v2026.3.2 之前）
api.registerHttpHandler(path, handler)

// 新写法
api.registerHttpRoute({
  path,
  auth,
  match,
  handler,
})

如果你自己写了插件或用了第三方插件，升级后插件 webhook 可能在启动时直接挂掉。

解决方式：搜索插件代码里的 registerHttpHandler，全部替换为新写法。如果用的是第三方插件，等插件作者更新后再升级，或者暂时锁定在旧版本。

坑五：工具权限 profile 默认值改变，AI 突然”不会”执行操作

v2026.3.2 修改了 tools.profile 的默认值，新安装的 onboarding 默认值变为 "coding"。如果你从旧版升级，已有的配置里没有显式设置这个字段，升级后可能发现 AI 突然无法执行某些工具操作，比如 Shell 执行或文件写入。

检查当前 profile：

openclaw config get tools.profile

如果返回值和你预期的不符，手动设置：

openclaw config set tools.profile "coding"

可用的 profile 值参考官方文档的工具策略部分。

坑六：ClawHub 成为插件默认来源，旧的 npm 直装命令行为改变

v2026.3.22 之后，openclaw plugins install <包名> 默认先查 ClawHub，找不到才回退到 npm。如果你之前有脚本或 CI 流程直接用包名从 npm 安装插件，行为可能发生变化。

如果确实需要从 npm 安装（ClawHub 上没有的包），加上显式来源参数。具体参数参考 openclaw plugins install --help。

标准升级流程

把以下步骤做成习惯，能避开大部分升级坑：

  1. 升级前看一眼 GitHub Releases，找 BREAKING 关键词
  2. 停掉 Gateway：openclaw gateway stop
  3. 执行升级：openclaw update
  4. 跑诊断：openclaw doctor --fix
  5. 检查配置合法性，处理已知 Breaking Changes 里涉及的字段
  6. 重启 Gateway：openclaw gateway start
  7. 验证运行：openclaw gateway status --deep

一张表总结

问题 触发版本 解决方式
配置字段废弃导致 Gateway 不启动 v2026.3.3 删掉报错字段，重启
升级时 dist 覆盖导致崩溃 v2026.3.24 升级前先 stop，升级后再 start
旧环境变量名失效 v2026.3.22 全局替换 CLAWDBOT_ / MOLTBOT_ 为 OPENCLAW_
插件 HTTP 路由 API 变更 v2026.3.2 替换 registerHttpHandler 为 registerHttpRoute
工具 profile 默认值变化 v2026.3.2 检查并手动设置 tools.profile
插件来源改为 ClawHub 优先 v2026.3.22 了解新行为，脚本里加显式来源参数

遇到任何升级后的异常，第一步永远是：

openclaw doctor --fix
openclaw gateway logs

大部分问题在日志里都有明确的报错信息，按报错字段名去 Releases 页面 搜对应版本的 Breaking Changes 说明，基本都能找到处理方式。