OpenClaw 2026.9.7 → 2026.10.3 升级实操：npm 直装 + Node 钉住 + 插件修复

日期：2026-10-15 16:30-17:15 执行人：Hermes（AI 辅助）+ 风哥确认 结果：✅ GREEN，5/5 飞书通道正常，全部插件对齐 备份：~/openclaw-state-pre-upgrade-2026-10-15-162959/

背景：为什么升级

1.1 10 月 10 日升级失败遗留

前几天（2026-10-10）尝试用 openclaw update 升级，但失败了。具体现象：

1. readiness 检查误报：readiness check failed: "embeddings" not ready — 两个 agent 依赖本地 managed embedding（marketing-seo-specialist、editor-blog-yuntianchen），本地模型 all-MiniLM-L6-v2.gguf 未就绪，导致整个升级流程被卡住。
2. 账本卡死：openclaw update status 显示 46m 前有一条 not serving 记录，状态机没有清理，后续任何 update 都被阻塞。
3. 结果：当前停在 2026.9.7，npm 上有 2026.10.3 可升。

1.2 当前版本信息

openclaw --version
# OpenClaw 2026.9.7

npm view openclaw version
# 2026.10.3

差距：从 2026.9.7 到 2026.10.3，跨了一个大版本段（9.x → 10.x），需要认真对待。

1.3 升级策略

核心决策：绕过 openclaw update，用 npm install -g openclaw@2026.10.3 直接安装。

当 openclaw update 因 ledger 卡死或 readiness 误报无法走官方路径时，这就是 openclaw update 失败之后的标准解法：npm 直装 + 手动 doctor 迁移。

理由：

• 2026.9.7 的 updater 在 ledger 中有卡死记录，且 updater 逻辑本身有 bug（readiness 检查误报）
• npm 直装是干净路径，不经过 ledger，不触发 readiness 检查
• 2026.9.9+ 的 updater 已经修复了这些问题，但我们现在还在 9.7 上，修不了自己
• npm 直装后手动跑 doctor + doctor --fix 完成配置迁移

升级前状态检查

2.1 版本与通道状态

openclaw gateway status

输出（截取关键部分）：

Service: systemd enabled (user service)
Command: /usr/bin/node
Runtime: node 24.22.0
...
Gateway:
  Diagnostics: /usr/bin/node (v24.22.0)
Channels:
  Feishu:
  - 总编云天  enabled connected
  - 梦行志    enabled connected
  - default   enabled connected
  - 云天博    enabled connected
  - OC工程师  enabled connected
Workload:
  Active: 288
  Sessions: 258

发现：Gateway 正常运行，5 个飞书通道全部 connected。但 Node 版本有问题 — 服务用的是 /usr/bin/node（v24.22.0），而 openclaw 是 NVM 里装的（v24.16.0）。

2.2 Node 分裂问题：systemd ExecStart 指向系统 node

systemctl --user cat openclaw-gateway
# ExecStart=/usr/bin/node /home/oklife/.nvm/versions/node/v24.16.0/lib/node_modules/openclaw/dist/index.js gateway --port 18789

which node
# /home/oklife/.nvm/versions/node/v24.16.0/bin/node
node -v
# v24.16.0

结论：systemd service 的 ExecStart 用系统 node（24.22.0）跑 NVM 里装的 openclaw 包。两个 Node 版本分裂，存在二进制兼容性风险。

2.3 Workshop proposal 脏数据检查

python3 -c "
import sqlite3
con = sqlite3.connect('/home/oklife/.openclaw/state/openclaw.sqlite')
con.execute('SELECT COUNT(*) FROM skill_workshop_proposals')
print(con.fetchone()[0])
"
# 0

结论：干净，0 行。不阻塞 migration。（9 月 14 日就是被这里的脏数据坑过的。）

2.4 Doctor 基线

openclaw doctor

关键输出：

Gateway service:
  File: ~/.config/systemd/user/openclaw-gateway.service
  Config issues: 1
    systemd: gateway service PATH includes version managers or package managers (prefer the exact OpenClaw-managed runtime path)

结论：确认 Node 路径问题。这是升级前需要顺手修复的。

升级执行：7 阶段 SOP

阶段 1：前置检查

已完成（见第二节）。关键结论：

• Workshop proposal = 0（干净）
• 5/5 通道 green
• Node 分裂需要修复
• 可以安全升级

阶段 2：备份

TS=$(date +%F-%H%M%S)
BK=~/openclaw-state-pre-upgrade-$TS
mkdir -p $BK
cp -av ~/.openclaw/state $BK/state
cp -av ~/.openclaw/openclaw.json $BK/openclaw.json
cp -av ~/.openclaw/openclaw.json.full $BK/openclaw.json.full
cp -av ~/.config/systemd/user/openclaw-gateway.service $BK/openclaw-gateway.service

输出：

state  -> openclaw-state-pre-upgrade-2026-10-15-162959/state
openclaw.json -> openclaw-state-pre-upgrade-2026-10-15-162959/openclaw.json
openclaw.json.full -> openclaw-state-pre-upgrade-2026-10-15-162959/openclaw.json.full
openclaw-gateway.service -> openclaw-state-pre-upgrade-2026-10-15-162959/openclaw-gateway.service

$ du -sh $BK
248M  ~/openclaw-state-pre-upgrade-2026-10-15-162959/

完整性校验：

python3 -c "
import sqlite3
con = sqlite3.connect('/home/oklife/.openclaw/state/openclaw.sqlite')
print('integrity:', con.execute('PRAGMA integrity_check;').fetchone()[0])
"
# integrity: ok

阶段 3：停 Gateway（kill -9 绕过 SIGTERM 卡顿）

systemctl --user stop openclaw-gateway.service

输出（EXIT 1，SIGTERM 卡顿已知问题）：

● openclaw-gateway.service - OpenClaw Gateway 2026.9.7
   Active: deactivating (stop-sigterm)

确认是否真的停了：

pgrep -f "openclaw.*dist/index.js"
# 125652

kill -9 125652

验证端口释放：

ss -tlnp | grep 18789
# 无输出，端口已释放

阶段 4：钉 Node（gateway install 指向 NVM node）

export PATH="$HOME/.nvm/versions/node/v24.16.0/bin:$PATH"
hash -r
openclaw gateway install --runtime node --runtime-path "$HOME/.nvm/versions/node/v24.16.0/bin/node" --force

输出：

Gateway service installed.

验证：

systemctl --user cat openclaw-gateway | grep ExecStart
# ExecStart=/home/oklife/.nvm/versions/node/v24.16.0/bin/node /home/oklife/.nvm/versions/node/v24.16.0/lib/node_modules/openclaw/dist/index.js gateway --port 18789

systemctl --user cat openclaw-gateway | grep -E "Environment=|Wants"
# Environment=NODE_EXTRA_CA_CERTS=...
# Environment=OPENCLAW_GATEWAY_PORT=18789
# Wants=network-online.target
# After=network-online.target

关键变化：ExecStart 从 /usr/bin/node 变成了 /home/oklife/.nvm/versions/node/v24.16.0/bin/node。Node 分裂问题已修复。

注意：PATH 警告仍在（因为 .nvm 路径包含 version managers），但这是已知非阻断问题，不影响运行。

阶段 5：验证 9.7 在新 Node 路径上正常

启动 gateway，确认旧版本在新 Node 路径上还能跑：

systemctl --user start openclaw-gateway.service
sleep 90

然后跑深度检查：

openclaw gateway status --deep

关键输出：

Gateway:
  Mode: local
  Bind: loopback
  Port: 18789
  Daemon: running (pid 22462)
  Probe ok. No errors found.

Channels:
  Feishu:
  - 总编云天  enabled connected ws://127.0.0.1:18789
  - 梦行志    enabled connected ws://127.0.0.1:18789
  - default   enabled connected ws://127.0.0.1:18789
  - 云天博    enabled connected ws://127.0.0.1:18789
  - OC工程师  enabled connected ws://127.0.0.1:18789

Workload:
  Sessions: 258

结论：2026.9.7 在新 Node 路径（nvm 24.16.0）上完全正常，5/5 通道 green。Node 钉住安全。

阶段 6：npm 直装 2026.10.3

export PATH="$HOME/.nvm/versions/node/v24.16.0/bin:$PATH"
hash -r
npm install -g openclaw@2026.10.3
openclaw --version

输出：

added 1 package, changed 3 packages, and audited 148 packages in 3m
OpenClaw 2026.10.3 (59cb447)

版本已升到 2026.10.3。

然后停 gateway，跑 doctor（停机状态下，避开 SQLite 锁争用）：

systemctl --user stop openclaw-gateway.service
sleep 8
pgrep -f "openclaw.*dist/index.js" && kill -9 $(pgrep -f "openclaw.*dist/index.js") || echo "stopped"

openclaw doctor

输出（doctor 无修复）：

Gateway service:
  Install: ok

Runtime:
  node version: v24.16.0
  node path: /home/oklife/.nvm/versions/node/v24.16.0/bin/node

Skills: 14 ready
Security: 5 warnings (same as before, all non-blocking design decisions)
Embedding: local managed llama.cpp ready ✅

Result: 5 warnings, 0 blockers

关键发现：

• doctor 不再报 embedding readiness 警告 — 本地 managed llama.cpp embedding 已就绪
• Node 路径正确指向 nvm 24.16.0
• 无 schema 错误

然后跑 doctor --fix：

openclaw doctor --fix

输出（420 秒超时，但实际完成了工作）：

[plugins] openclaw-weixin: plugin load failed: cannot import openclaw/plugin-sdk/infra-runtime
[plugins] openclaw-weixin: plugin not found or loadable
[memory] sync ready: local managed llama.cpp embedding ready

doctor --fix 超时是已知行为 — 它在后台完成了配置迁移 + 插件修复 + gateway 重启，但 CLI 端等不到全部完成就超时了。

发现：openclaw-weixin 插件加载失败！这是新出现的。

阶段 7：插件版本漂移修复 + 最终验证

openclaw plugins update openclaw-weixin

输出：

openclaw-weixin: 2.4.9 -> 2.4.10

然后重启 + 验证：

systemctl --user start openclaw-gateway.service
sleep 90

openclaw gateway status --deep

关键输出：

Gateway:
  Mode: local
  Bind: loopback
  Port: 18789
  Daemon: running (pid 164887)
  Probe ok. No errors found.

Channels:
  Feishu:
  - 总编云天  enabled connected ws://127.0.0.1:18789
  - 梦行志    enabled connected ws://127.0.0.1:18789
  - default   enabled connected ws://127.0.0.1:18789
  - 云天博    enabled connected ws://127.0.0.1:18789
  - OC工程师  enabled connected ws://127.0.0.1:18789

Workload:
  Sessions: 258

openclaw --version
# OpenClaw 2026.10.3 (59cb447)

openclaw config validate
# config OK

openclaw channels status --probe
# 5/5 connected, works

插件版本检查：

openclaw plugins list | grep -E "2026\.[0-9]+\.[0-9]+" | grep -v "2026\.10\.3"
# 无输出 — 全部 @openclaw/* 插件对齐 2026.10.3

openclaw-weixin 单独体系，当前 2.4.10。

结论：✅ GREEN，升级完成。

升级后残留问题（低优先级）

这三项都不阻塞当前使用，不影响 5/5 飞书通道和 258 个 session。

知识沉淀

5.1 Skill 拆分

升级过程中发现 ai-agent-ops skill 太杂（55KB，混了 Hermes 升级、AionUi 调试、OpenClaw 运维），决定拆出独立的 openclaw-ops skill：

skills/devops/
├── ai-agent-ops/     ← 通用 Hermes/AionUi 运维（精简）
└── openclaw-ops/     ← OpenClaw 专属：升级 SOP、事故模式、插件管理
    ├── SKILL.md       ← 升级 SOP + 6 个事故模式 + 15 项已知问题基线
    └── references/
        ├── known-issues.md      ← 详细问题记录
        └── upgrade-history.md   ← 完整升级历史

openclaw-ops 的核心内容：

• 当前 LKG 基线（2026.10.3）
• 升级 SOP（7 步验证流程）
• 6 个事故模式（agnes 提案、schema 半迁移、插件漂移、SIGTERM 卡顿、Node 分裂、weixin 不兼容）
• 15 项已知非阻断问题
• 升级历史时间线（2026-08 → 2026-10）

5.2 文档更新

同步更新了两份 Obsidian 权威文档：

• 06-排障/2026-09-02-现存非阻断问题清单.md：LKG 基线更新至 2026.10.3，#2/#7/#11 状态更新
• 06-排障/2026-09-02-已修复问题清单.md：新增批次 10，时间线表同步更新

关键经验

6.1 绕过 updater 的判断标准

openclaw update 在以下情况应该绕过，改用 npm install -g：

1. Updater 的 ledger 有卡死记录（openclaw update status 显示 stuck/pending）
2. Readiness 检查误报（非核心功能被判定为 blocking）
3. 当前版本的 updater 本身有已知 bug 且无法自我修复

6.2 升级前必做三件事

# 1. 查 workshop proposal 脏数据（期望 0）
python3 -c "import sqlite3; print(sqlite3.connect('/home/oklife/.openclaw/state/openclaw.sqlite').execute('SELECT COUNT(*) FROM skill_workshop_proposals').fetchone()[0])"

# 2. 备份（state + 配置 + service）
TS=$(date +%F-%H%M%S); BK=~/openclaw-state-pre-upgrade-$TS
mkdir -p $BK
cp -av ~/.openclaw/state $BK/state
cp -av ~/.openclaw/openclaw.json $BK/openclaw.json
cp -av ~/.config/systemd/user/openclaw-gateway.service $BK/openclaw-gateway.service

# 3. 完整性校验
python3 -c "import sqlite3; print(sqlite3.connect('/home/oklife/.openclaw/state/openclaw.sqlite').execute('PRAGMA integrity_check;').fetchone()[0])"

6.3 Node 钉住

如果 openclaw 是 NVM 管理的，systemd service 的 ExecStart 必须显式指向 NVM 的 node 路径：

openclaw gateway install --runtime node --runtime-path "$HOME/.nvm/versions/node/v24.16.0/bin/node" --force

否则服务会用 /usr/bin/node（系统 node），和 NVM 里装的 openclaw 包版本分裂。

6.4 插件兼容性

跨大版本升级（9.x → 10.x）时，第三方插件可能不兼容新版 plugin-sdk。升级后必须检查：

openclaw plugins list | grep -E "2026\.[0-9]+\.[0-9]+" | grep -v "2026\.10\.3"

有版本漂移就逐个 openclaw plugins update <name>@latest。

6.5 重启永远用 kill -9

systemctl --user stop 会触发 SIGTERM，gateway 卡在 deactivating (stop-sigterm) 50+ 秒。始终用：

kill -9 $(pgrep -f "openclaw.*dist/index.js")
systemctl --user start openclaw-gateway.service

参考链接

• 已修复与升级记录（Obsidian 内部文档：06-排障/2026-09-02-已修复问题清单.md）
• 现存非阻断问题清单（Obsidian 内部文档：06-排障/2026-09-02-现存非阻断问题清单.md）
• OpenClaw Ops Skill（本机路径：~/.hermes/skills/devops/openclaw-ops/SKILL.md）
• 备份：~/openclaw-state-pre-upgrade-2026-10-15-162959/（248M）

相关实操

• 2026.9.4 升级事故复盘（本文背景 1.1 的前情）
• 2026.9.2 升级实战与配置漂移修复
• 升级后 doctor 报 PATH 警告的处理决策
• OpenClaw 常规更新指南（本文为何绕开它）
• Gateway 反复重启与 SIGTERM 排障延伸