用了 5 个月 OpenClaw：升级命令很简单，5 个坑全在第二天

我用 OpenClaw 已经 5 个月。第一次记录是 2026-04-02，今天是 2026-09-21，第 183 天。

中间踩过 5 个坑。4 个和升级有关，1 个和通道插件有关。

升级命令本身很简单。麻烦都在第二天。

今天把升级指南和踩坑记录整理出来。所有版本号、报错文本、issue 编号都是实测的。

01 升级命令本身很简单

官方升级命令：

openclaw update
openclaw update status          # 查当前渠道和可用版本
openclaw update --dry-run       # 预览，不写配置不装包不重启
openclaw update --channel beta  # 切渠道
openclaw update repair          # 核心包已更但收尾没走完时重跑
openclaw update --no-restart    # 不重启 Gateway
openclaw update --json          # 机器可读输出

几个值得记的选项：

• --dry-run 不改配置、不装包、不同步插件、不重启。升级前先看一眼。
• --no-restart 跳过升级后自动重启。但包管理器升级如果确实重启了，会先验证重启后的服务返回预期版本，命令才算成功。
• --yes 跳过所有确认提示，包括降级确认。降级前不要加这个参数。
• --json 输出里 postUpdate.plugins.warnings 和 postUpdate.plugins.integrityDrifts 两个字段，是升级后唯一值得盯的地方。
• 默认单步超时 --timeout 1800 秒。网络差的话要调。

没有 --verbose 参数。要预览用 --dry-run，要机器可读用 --json，要查渠道用 update status --json。Gateway 控制台的 --verbose 和文件日志级别 logging.level: "debug" 是两回事，别混。

降级要注意：官方文档明确写了，降级需要确认，因为老版本会破坏新配置。如果会话已经迁到 SQLite，降级前先恢复归档的旧版转录文件。

金句：升级命令很简单，代价都在第二天。

02 第 1 个坑：升级后命令签名悄悄变了

2026-09-04 升级到 OpenClaw 2026.8.2 (0965053)。当天凌晨的定时任务连续 2 次超时，日志只有一句模糊的 timeout。

排查后发现是命令签名变了。

报错原文：

Multiple agents configured but no explicit owner

修复：给命令加 --agent write。

同一个升级还连带一个路径问题。旧脚本引用的 AppData/Roaming/npm/openclaw.cmd 不存在了，实际路径在 AppData/Local/nvm/v24.15.0/openclaw.cmd。

before:  openclaw rem-backfill                      → 报错
after:   openclaw rem-backfill --agent write        → 成功
before:  AppData/Roaming/npm/openclaw.cmd          → 不存在
after:   AppData/Local/nvm/v24.15.0/openclaw.cmd   → 存在

改完脚本，重新注册 Windows 计划任务，手动跑一遍，81 篇历史文件回填完成。

关键教训：升级后要跑一遍所有脚本里调用的 openclaw 命令，不是只测命令行。命令行手动跑通不代表脚本里的调用签名还对。

金句：手动跑通不算升级完成，脚本跑通才算。

03 第 2 个坑：Gateway 正常启动不等于认证完成

2026-04-07，第一次接触 Gateway 相关命令：

gateway connect failed: GatewayClientRequestError: pairing required
nodes status failed: Error: gateway closed (1008): pairing required

Gateway 服务本身正常，监听在 ws://192.168.0.11:18789。问题不在服务，在认证。

修复三步：

openclaw qr                                  # 生成配对二维码
# App 扫码
openclaw devices approve <requestId>         # 批准配对

17:43 报错，17:45 修好，中间 2 分钟。

关键教训：nodes 报 gateway closed (1008) 时，第一反应查端口，第二反应查配对。端口通不代表链路通。

04 第 3 个坑：隐式继承链，最坑

这个坑花了两周才定位。

2026-09-02 到 09-09，会话压缩连续失败。累计 13 次：09-02×4（401）、09-04×3、09-05×2、09-06×1、09-09×3（no summary text）。

每次报错都是「Compaction failed」，以为是 provider 抖动，没深究。

根因：agents.defaults.compaction.model 未设置时，压缩摘要用当前会话的活跃模型。模型一抖，长摘要调用就返回空、401 或 429。safeguard 模式为了保历史取消压缩，上下文永不释放，每轮重试每轮报错。

修复：显式指定压缩用哪个模型。

agents.defaults.compaction.model = "<稳定模型>"

2026-09-15 config hot reload 生效后，09:47 压缩成功，73k → 25k。

两个教训：

1. 改 cron 的 model 不等于改了所有链路。交互会话的压缩、辅助调用这些隐式继承链还吃原模型。修 provider 抖动影响面，要同时查隐式继承。
2. 诊断先看完整错误行。no summary text 和 401 是两种不同签名，截断版看不出差别。

金句：显式配置比隐式继承安全。

05 第 4 个坑：网关被自己的重试压满

修 04 那一步走审批通道时，连续 30 秒超时两次。

原因：上下文卡 97% 后每轮重试，把 Gateway 压满了。审批通道走同一个 Gateway，一起超时。

08:00 和 08:05 两次走审批都超时，08:58 复核配置字段仍未落地。

最后绕过去：在控制台手工加行，hot reload 生效。

关键教训：反复重试是有害的。系统越卡越重试，越重试越卡。审批通道和普通调用共用网关时，前者会被后者拖死。

06 第 5 个坑：通道插件的 token 会耗尽，重启没用

这个坑和升级无关，但代价一样高。

2026-06 中旬，我把 5 个定时推送从飞书切到微信，统一走 openclaw-weixin。当时飞书通道有推送限制，微信是当时能跑通的选项。

跑了快三个月。

2026-09-06，微信推送彻底停摆。

Gateway 重启后正常，会话正常，消息能发出，但永远收不到成功回执。

根因定位在 openclaw-weixin 的 issue #81：context_token 耗尽。

Token 耗尽的表现藏得极深——不是报错，是静默。消息发了，系统不说不说，就是没到。

我试了重启。重启没用，因为 token 状态不随进程重建恢复。

最终方案：全部迁回飞书。

2026-06-11  5 个推送 cron：飞书 → 微信（绕开推送限制）
2026-09-06  微信 context_token 耗尽，重启无效
2026-09-06  5 个推送 cron：微信 → 飞书（全部迁回）

来回一趟，白折腾三个月。

关键教训：通道插件的鉴权状态，重启修不了。选通道时不能只看「现在能发」，要看这个通道的状态是不是可恢复的。

金句：能发出去的通道不等于可持续的通道。

07 升级前该做的 6 件事

5 个月踩完这 5 个坑，总结一份升级清单：

1. openclaw update --dry-run 看计划动作，确认不会重装或清配置。
2. 查 openclaw update status 看当前渠道和可用版本。ahead of extended-stable 说明装的是比渠道新的版本。
3. 备份 workspace：配置文件、脚本、计划任务注册信息。Git 跟踪的走 commit，不跟踪的打包。
4. 列一遍所有脚本里调用的 openclaw 命令，升级后逐个手动跑一遍。签名会变。
5. 确认 agents.defaults.compaction.model 显式设置。不要靠隐式继承。
6. 升级后盯 postUpdate.plugins.warnings 和 integrityDrifts。这两个字段有内容就要处理。

收尾没走完时用 openclaw update repair。这是官方支持的恢复路径，专门处理「核心包已装但插件同步、注册表刷新、doctor 修复没收敛」的情况。

金句：升级前 5 分钟的准备，省升级后 2 天的排查。

08 一个反直觉的发现

5 个月里最反直觉的一件事：升级失败不可怕，静默失效才可怕。

openclaw rem-backfill 报 Multiple agents configured but no explicit owner，你会立刻去查。

但如果你用的是脚本调用，脚本只会往上抛一个 timeout。你看到的是「定时任务超时了」，第一反应是网络问题，第二反应是脚本超时配置太短，真正的签名变更藏在报错里第三层。

同理，压缩失败如果只报 Compaction failed，你会以为是 provider 问题。完整错误行是 All summarization attempts failed，后面跟着具体签名。

最狠的是 06 那个坑。context_token 耗尽连报错都没有，只有「消息没到」。三个月里它一直是健康的，直到某一天突然全部静默。

规则：不要看报错标题，要看完整错误行。没有报错比报错更危险。

升级很简单，代价都在第二天。