梦行志
所有文章 梦 行 志 标签 分类 关于 游乐帮
梦行志

目录

OpenClaw 连续三次升级踩坑全记录：从 2026.9.1 到 2026.10.3 的排障方法论

9.1→9.2 顺利升级、9.7→9.9 失败换 agent 兜底、10.3 验收审查，三次升级沉淀出可复用的升级 SOP

梦行志 收录于 码艺轩・以技立身，实干谋生
   约 3684 字   预计阅读 8 分钟 
/images/Code-Art-Studio-images/openclaw-upgrade-troubleshooting-9.1-to-10.3/openclaw-upgrade-troubleshooting-9.1-to-10.3.webp

这是我家"OC工程师"agent 从 9 月 8 日到 10 月 17 日的三次升级实录。三次升级，两种结局：一次干净利落，一次失败到要换 agent 兜底，一次是纯粹的验收审查。把它完整写下来，因为每次升级踩的坑几乎都不一样，而排障方法论是可以复用的。

OpenClaw 升级链路 9.1 到 10.3

写在前面：环境基线

先交代环境，后面所有判断都基于这个基线：

  • 硬件：Ubuntu 桌面，/home 是 187G 的独立分区（NVMe），/data 是 1.5T 大分区
  • OpenClaw：systemd user service 跑 Gateway（端口 18789），--max-old-space-size 从 15756 调到 8192 过
  • Agent 规模：27 个写作场景 agent / 全量 286 个，插件 62/87+
  • 通道：5 条飞书通道（总编云天、财富导师梦行志、默认、kb-writer、oc-engineer），这是"升级没炸"的最终验收标准
  • LKG 机制：每次升级前后记录 Last Known Good 基线（版本号、配置 MD5、插件数、通道状态），升级失败能回滚的依据就靠它

三次升级分别是：

日期路径结果
09-082026.9.1 → 2026.9.2✅ 手动 npm 升级，验收通过
10-102026.9.7 → 2026.9.9（目标）❌ openclaw update 失败，停在 9.7
10-152026.9.7 → 2026.10.3✅ 换 hermes agent 兜底完成，oc-engineer 做全面审查

第一次：9.1 → 9.2，教科书式的顺利升级

9 月 8 日那次升级基本是标准流程，但"顺利"本身也藏了两个教训。

升级前的标准摸底

oc-engineer 做了一整套只读检查，这套动作以后可以照抄：

  1. openclaw status：确认当前版本、Gateway 运行状态、飞书通道 5/5 works
  2. openclaw config validate：配置合法性
  3. 配置 MD5 对比：当前配置 vs .last-good（发现 LKG 记录里的 hash 过期了，升级后要同步更新）
  4. 拉 2026.9.2 的 CHANGELOG，列出收益和风险点
  5. 磁盘检查：df -h /home 当时 86%，26G 剩余，升级前必须确认有空间
  6. 已知问题清单：SIGTERM 优雅关闭卡顿（2026.8.2 引入的老毛病，workaround 是 kill -9 + systemctl start，不能用 openclaw gateway restart）
升级前摸底检查清单

关键产出是一个"升级前评估报告"，核心结论就三句话：

  • 这是小版本更新（.1 → .2），无破坏性变更
  • 最大风险点是 Swarm 默认启用（并发子 agent 编排），不影响单 agent 场景
  • 回滚点：openclaw.json.pre-upgrade-2026.9.2 备份 + kill -9 重启

两个教训，都在"顺利"里

教训一：MEMORY.md 的 LKG 基线会过期。 记录里写着配置 hash 是 6 月 9 日的 a41c6e45...，实际当前已经是 df66ede...。升级后 oc-engineer 更新了 LKG 记录，但第一次 edit 因为 oldText 匹配不上失败了，重新 grep 定位行号才改对。教训：LKG 记录必须跟着实际配置走，编辑前用 grep -n 定位，别凭记忆。

教训二：升级验收不能只看版本号。 用户说"我已手动升级"，agent 第一反应是跑验收：版本号 2026.9.2 (3928bad) ✅、config validate ✅、5/5 通道 ✅、agent 名称完好 ✅。但用户发过一个升级操作文档，agent 没看，只看了自己的验收结果就汇报"升级完成"，被用户骂了"你眼睛瞎的吗"。事后排查发现文档藏在 gateway 的附件卸载目录里（media://inbound/pasted-text-...），agent 翻遍 /tmp、workspace、会话历史都没找着。教训：用户给的文档/附件，先找附件卸载目录，别只在自己预期的地方找。

遗留问题清单（这次升级发现的）

升级后 doctor 报了一堆，但和 9 月 2 日的"现存非阻断问题清单"对比后，大部分可以归档不动：

  • systemd PATH 警告：doctor 逻辑有 bug（symlink 路径 vs 具体版本路径），已确认不改
  • SIGTERM 卡顿：仍复现，workaround 不变
  • 配置文件权限 664：含 API key，已 chmod 600
  • 258 个孤儿 agent 目录：历史遗留，不影响生产
  • kb-writer bootstrap 超限（AGENTS.md + MEMORY.md 超 48K 截断）：调到 bootstrapMaxChars=128000, bootstrapTotalMaxChars=256000

这一条值得单独说：agent 的长期记忆文件会越长越大，bootstrap 截断是静默的——被截断的 agent 不会报错，只会"失忆"。2026.9.2 的 changelog 里有"Doctor upgrade settings"相关修复，但 bootstrap 超限这事得自己盯。

第二次：9.7 → 9.9，失败的那次

10 月 10 日，openclaw update 失败。从记录里能拼出的过程：

  1. 升级前评估照常做：LKG 基线 2026.9.7、飞书 5/5、27 个写作 agent、备份到 ~/openclaw-backup-2026-10-10-220548/
  2. 切换 writing 场景后执行升级，场景切换脚本被 SIGTERM 打断（gateway 重启触发的系统消息：Your previous turn was interrupted by a gateway restart）
  3. 备份验证、配置校验都过了，但升级最终没有成功落到 9.9，版本停在 2026.9.7 (c074824)

这次失败有几个值得记的细节：

  • 升级本身触发了 gateway 重启，而 gateway 的 SIGTERM 卡顿是已知问题——升级过程中 gateway 的 deactivating 阶段卡住，连带把正在跑的升级脚本也拖死了。这是"已知遗留问题"在升级场景下引爆的典型例子
  • 备份做了三件套：openclaw.json + openclaw.json.full + state.tar.gz（51M），这是标准回滚点
  • 场景切换（switch-scene.py writing）要在升级前做，避免升级在 286 agent 全量场景下跑内存爆掉

10 月 15 日，用户让另一个 agent（hermes）读升级失败的文档，把它兜底升级到了 2026.10.3。oc-engineer 的工作变成了验收别人完成的升级，这个审查过程本身很有价值。

第三次：10.3 的验收审查——失败升级该怎么"验尸"

hermes 升级完成（2026.9.7 → 2026.10.3，跳过了 9.9/10.1/10.2），oc-engineer 做全面审查，发现四个问题，按严重度排：

问题一：磁盘 97%，最致命

/dev/nvme1n1p3  187G  172G  5.8G   97% /home

升级后磁盘直接红了。这是 10 月 17 日"腾 /home 空间"那篇的起因，这里不展开。

问题二：perplexity skill 引用了已禁用插件

academic-narratologist（writing 场景 27 个 agent 之一）的 skills 列表里引用了 perplexity-deep-search，但 perplexity 插件是 disabled 状态。排查路径值得记：

  1. 确认这个 agent 是不是当前场景的核心 agent（是）
  2. 查 skill 文件是否在磁盘上（~/.openclaw/skills/perplexity-deep-search/SKILL.md 存在，7 月就在了）
  3. 判断：skill 文件在磁盘上不代表可用，插件 disabled 时它实际不生效

结论：不阻断生产，但属于"配置漂移"——agent 配置引用了不存在的工具。

问题三：embedding 配置冲突

memory.search.provider 是 local，但 managed local embeddings 不可用（需要 llama.cpp server 配置），日志里反复刷 memory sync failed。这个和 OpenClaw 的 memory 检索有关，不影响 agent 对话，但会把日志刷脏。

问题四：版本跳跃的代价

9.7 直接到 10.3，跨了 9.8/9.9/10.1/10.2 四个版本。9.9 的 changelog 亮点（GPT-6.1 Sol、更新失败可回滚、Doctor 长数据库检查可 Ctrl+C）全部白拿，但也意味着中间版本的 bugfix 没法单独验证，出问题只能整体归因。

排障方法论总结

把三次升级（两次半）的动作抽象出来，以后升级 OpenClaw 可以直接照这个 SOP 走：

升级前（只读，不动手）

  1. openclaw status：版本、Gateway、通道
  2. openclaw config validate + 配置 MD5 对比 LKG 记录
  3. df -h /home：空间低于 15% 先腾空间再升级
  4. 拉目标版本 CHANGELOG，列收益 + 风险点
  5. 备份三件套：openclaw.json、openclaw.json.full、state/
  6. 切到最小场景（writing 27 agent，别用 286 agent 全量）

升级中

  • 手动升级（npm install -g openclaw@xxx）比 openclaw update 可控
  • gateway 有 SIGTERM 卡顿的话，重启一律 kill -9 <pid> && systemctl --user start openclaw-gateway.service
  • 长任务被 SIGTERM 打断是正常的（升级本身会重启 gateway），被打断后先查备份和版本状态，再决定重跑还是继续

升级后（验收）

  1. openclaw --version 确认落地版本
  2. openclaw config validate
  3. openclaw channels status --probe：5/5 works 是硬标准
  4. openclaw doctor：区分"新出现的 drift"和"已知遗留"
  5. 业务 smoke test：主 agent 发一条消息
  6. 更新 LKG 记录（版本号、配置 hash、日期、上一版）
  7. 对比"现存非阻断问题清单"：已归档的不动，新出现的单独评估

失败升级的"验尸"清单

失败验尸六步排查

如果升级没成功（版本没落地），按这个顺序查：

  1. 版本到底落没落（openclaw --version，别信日志里的中间状态）
  2. 备份还在不在（三件套齐全才敢回滚）
  3. gateway 活没活（通道 5/5）
  4. 磁盘红没红（升级前后各查一次）
  5. 配置漂移没有（agent 引用不存在的 skill/工具）
  6. 日志刷不刷脏（memory sync failed 之类）
备份三件套

几个可以直接抄走的命令

# 备份三件套
TS=$(date +%F-%H%M%S)
mkdir -p ~/openclaw-backup-$TS
cp ~/.openclaw/openclaw.json ~/openclaw-backup-$TS/
cp ~/.openclaw/openclaw.json.full ~/openclaw-backup-$TS/ 2>/dev/null
tar czf ~/openclaw-backup-$TS/state.tar.gz -C ~/.openclaw state
echo "Backup: ~/openclaw-backup-$TS"

# 重启（绕过 SIGTERM 卡顿）
kill -9 $(pgrep -f "openclaw.*gateway") && systemctl --user start openclaw-gateway.service

# 验收三连
openclaw --version
openclaw config validate
openclaw channels status --probe

# 磁盘
df -h /home

参考来源

  • OpenClaw 官方文档：https://docs.openclaw.ai
  • 2026.9.2 Release：https://github.com/openclaw/openclaw/releases/tag/v2026.9.2
  • 2026.9.9 Release notes：https://docs.openclaw.ai/releases/2026.9.9
  • 本文素材：OC工程师 agent 会话记录（2026-09-08 / 2026-10-10 / 2026-10-15）
更新于 2026-10-17
 OpenClaw, 升级, 排障
返回 | 主页