OpenClaw 9.5 升级笔记:Plugin SDK 拆分、飞书插件官方化、Live reload

OpenClaw 9.5 升级笔记：Plugin SDK 拆分、飞书插件官方化、Live reload

OpenClaw 2026.9.5 是 9 月 19 日正式发布的 9.x 系列稳定版，也是当前 npm latest——跑 openclaw update 默认就会拉到它。

这次升级把 plugin SDK 拆成 30+ 个 focused subpath，插件作者可以按需导入、bundle 更小；同时落地了 live plugin reload（装/卸插件不重启 gateway）、multi-agent team mode、async plugin state 这些运维红利。

适合升级的人：

• 多插件用户：Live plugin management，装/卸/重载插件不重启 gateway
• 飞书/Lark 用户：插件官方化（@larksuite/openclaw-lark → @openclaw/feishu）
• 二次开发者：SDK 按 subpath 导入，编译/启动更快
• 多 agent 管理：Team mode + Role template 一键复用配置

一、Plugin SDK 拆 subpath：打包体积降 50%

9.5 把原来 openclaw/plugin-sdk 的单一入口拆成 30+ 个 focused subpath。

旧（7.x）：

import { ... } from "openclaw/plugin-sdk";

新（9.5）：

import { ... } from "openclaw/plugin-sdk/core"; import { ... } from "openclaw/plugin-sdk/runtime"; import { ... } from "openclaw/plugin-sdk/routing"; import { ... } from "openclaw/plugin-sdk/agent-runtime";

好处：

• 编译出来的 plugin bundle 只包含实际用到的 subpath，打包体积下降
• jiti loader 按需 transform，冷启动更快
• 7 个 broad subpath 兼容保护到 2026-10-01，之后插件作者必须迁完

二、飞书插件大改名（国内用户感知最强）

老插件 npm i @larksuite/openclaw-lark 用 7.x 伞形 SDK，跟 9.5 不兼容。

新插件 npm i @openclaw/feishu 是 OpenClaw monorepo 内官方发布的，核心维护者是 vincentkoc 和 steipete。

迁移注意：先改 openclaw.json 里的 streaming 字段（从 bool 改成 object），再装新包，否则会回滚配置改动。

三、Live Plugin Management：最大的运维红利

以前装/卸/重载插件 = 重启 gateway = 所有 agent session 中断。

9.5 起，飞书凭证可以白天改不用凌晨重启；模型参数调完重载就生效；A/B 测试新插件上就能跑，不好就卸。

仍需重启的边界：部分底层 schema 变更（如 doctor migration）还是需要。

四、Multi-Agent Team Mode + Role Template

如果你管 5-20 个 agent，每个都要配 IDENTITY / 工具 allowlist / 模型 fallback，这是体力活。

9.5 引入 Role templates：把一组配置打成模板，新 agent 直接套用，不用再复制粘贴相似配置块。

Team preset 是团队级别配置（如整个"电商组"共用同一组飞书工具）。

五、稳定性三项关键修复

5.1 Session 自动迁移

从 7.x 升上来时，老的 sessions/sessions.json 会被识别为 legacy，启动时 gateway 主动报错阻塞。

修复方式：对每个 agent（含隐藏目录）执行： for a in a"; done

5.2 Canonical Validation

升级后首次启动会跑 canonical-validation，按 session_key 重新对账。这个步骤对 15 个 agent 总计需要 1-2 分钟，gateway 启起来没出 readyz 多半是在等这个。

5.3 Restart-loop Breaker

如果 gateway 在 5 分钟内连续 crash 3 次，会触发 restart-loop breaker，手动启动命令： openclaw gateway call channels.start --params channel:feishu,accountId:id

六、升级前准备清单（按踩坑顺序）

1. 备份：cp openclaw.json openclaw.json.bak-pre-update
2. 切 Node 24.x：brew install node@24 && brew link node@24 --force
3. 飞书 streaming 提前改 object：channels.feishu.streaming 从 bool 改成 mode: off
4. plugins.allow：去掉 openclaw-lark，加 feishu
5. 备份 LaunchAgent

七、升级后建议

1. 趁 9.5 梳理现有 agent 配置，提取 role template
2. 飞书凭证改白天改（live reload 支持热生效）
3. 插件装卸前先查官方 update-compat-inventory.json
4. 关注 compatibility.md 里 removeAfter: 2026-10-01 的记录
5. 9.x 兼容窗口约 3 个月，跳 10.0 可能有下一波 breaking

这次升级核心解决了多插件用户的运维痛点，国内飞书用户迁移略微麻烦，但整体值得升。