文档大纲

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

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

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

对小龙虾的使用者来说，是否应该升级呢？

适合升级的人

值得，但有前提：

价值适合谁
Live plugin management（装/卸/重载插件不重启 gateway）多插件 + 频繁调插件的人
飞书插件官方化（@larksuite/openclaw-lark → @openclaw/feishu）国内飞书/Lark 用户
SDK 拆 subpath，可按需导入（编译/启动更快）二次开发、做自定义 plugin 的人
Multi-agent team mode / Role template同时管多个 agent 的人
Async plugin task/flow（worker-backed state）插件里在跑后台任务的人
Hot policy 变更（browser / Telegram / TLS 不重启）运维要频繁调策略的人
Session 自动迁移 + canonical validation多 agent + 大量历史的用户

升级前提条件

前提条件：

  • 准备好 Node 24.x（25.x 整条线 9.5 不接受）
  • 准备好做一轮飞书插件替换（lark 2026.7.x 系列用旧 SDK umbrella，与 9.5 不兼容）
  • 留出 30–60 分钟做 agent session 全量迁移
  • 备份好 openclaw.json 和所有 agent 的 SQLite 数据库

一、最大的架构变化：Plugin SDK 拆分

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

旧 vs 新 import 形态对比

// 7.x — 一个 umbrella
import { ... } from "openclaw/plugin-sdk";

// 9.5 — focused subpath
import { ... } from "openclaw/plugin-sdk/core";
import { ... } from "openclaw/plugin-sdk/runtime";
import { ... } from "openclaw/plugin-sdk/routing";
import { ... } from "openclaw/plugin-sdk/channel-entry-contract";
import { ... } from "openclaw/plugin-sdk/agent-runtime";
// ...

为什么拆 subpath 这件事重要

为什么这件事重要：

  1. 打包体积下降 — 编译出来的 plugin bundle 只包含实际用到的 subpath，而不是整个 SDK
  2. 冷启动更快 — jiti loader 按需 transform，不用扫整个 SDK 目录
  3. 版本控制更精细 — 单独 subpath 可以独立 bump，不会被整 SDK 升级绑死
  4. 兼容性承诺更具体 — plugin-sdk-broad-runtime-barrels 兼容项保护 7 个 broad subpath（agent-runtime、cli-runtime、conversation-runtime、hook-runtime、media-runtime、plugin-runtime、security-runtime）直至 2026-10-01

对你意味着什么

对你意味着什么：

  • 用现成插件（feishu/brave/deepseek/dingtalk-connector）的人：基本无感，插件作者已经把 SDK 迁移做好了
  • 自己写 plugin 的人：升级后必须用新 subpath 重新构建；老的 umbrella import 直接报 Cannot find module 'openclaw/plugin-sdk'

二、飞书插件大改名：

@larksuite/openclaw-lark → @openclaw/feishu，这可能是国内用户感知最强的变化。

发生了什么

老插件 npm i @larksuite/openclaw-lark 是飞书团队发布的，用 OpenClaw 7.x 的伞形 SDK 入口，跟 OpenClaw 9.5 不兼容。

新插件 npm i @openclaw/feishu 是 OpenClaw monorepo 内官方发布的，仓库地址 github.com/openclaw/openclaw，核心维护者是 vincentkoc 和 steipete（OpenClaw 9.5 CHANGELOG 里出现频率最高的两位）。

三个包名怎么区分

注意区别：

包名来源角色
@openclaw/feishuOpenClaw monorepo（官方）9.5+ 标准飞书插件
@larksuite/openclaw-lark飞书团队已被官方替代
@m1heng-clawd/feishu社区 @m1heng第三方维护，与本次升级无关

配置迁移的坑

channels.feishu 这个通道名不变，但 plugin id 从 openclaw-lark 变成 feishu，且 schema 有微调：

- "streaming": false,
+ "streaming": {
+   "mode": "off"
+ }

升级动作清单（6 步）

  1. openclaw plugins install @openclaw/[email protected] --accept-capabilities --acknowledge-install-policy-warning --force
  2. 把 openclaw.json 里 plugins.entries.openclaw-lark.enabled 改成 false，并加 feishu.enabled: true
  3. plugins.allow 替换 openclaw-lark 为 feishu
  4. 把 channels.feishu.streaming 从 bool 改成 object
  5. 重要：先从 openclaw.json 删除 openclaw-lark 条目，再 openclaw plugins uninstall @larksuite/openclaw-lark --force，否则卸载会顺手清空整个 channels.feishu 配置（包括 15 个飞书账号的 appId/appSecret）
  6. openclaw update repair --accept-capabilities + openclaw doctor --fix

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

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

9.5 起能做什么

  • openclaw plugins install/uninstall/update 不重启 gateway
  • openclaw plugins reload <id> 重新加载指定插件
  • 更新已激活 agent 与 managed Codex 会话中的工具 不需要整体重启

实战意义（以前 vs 现在）

实战意义：

以前现在
周二凌晨改飞书凭证，必须凌晨重启白天改凭证，热生效
调 deepseek/brave 模型参数要重启重载就生效
A/B 测试新插件得专门找窗口装上就能跑，不好就卸

仍需重启的边界

触发条件：

部分底层 schema 变更（比如 doctor migration、host peer link）还是需要重启，但日常的插件配置变更不再需要。

四、Multi-Agent Team Mode 与 Role Template

如果你管了 5-20 个 agent，每个 agent 都得配 IDENTITY / 工具 allowlist / 模型 fallback / workspace 路径等，这是个体力活。

Role templates — 模板复用

9.5 引入 Role templates：把一组配置（system prompt 风格、工具白名单、典型 fallback）打成模板，新 agent 可以直接套。

Team preset — 团队级别配置

Team preset 是团队级别配置（比如整个"电商组"都用同一组 feishu_bitable_* 工具）。

Roster-first Agents home — 团队视图

Roster-first Agents home 按 roster 列出 agent 而不是单卡片，方便团队管理。

适用场景

如果你目前所有 agent 都在复制粘贴相似的配置块，9.5 是个抽模板的好窗口。

五、稳定性的三项关键修复

5.1 session 自动迁移

如果你从 7.x 升上来，老的 sessions/sessions.json 文件会被识别为 legacy，启动时 gateway 主动报错：

Legacy session store requires migration: /Users/duanyi/.openclaw/agents/<id>/sessions/sessions.json.
Run "openclaw doctor --fix" against the same state/config before starting OpenClaw.

修复方式：

# 对每个 agent（含隐藏目录）
for a in $(ls ~/.openclaw/agents/); do
  [ -f ~/.openclaw/agents/$a/sessions/sessions.json ] && \
    openclaw doctor --session-sqlite import --session-sqlite-agent "$a"
done

# 含隐藏目录
[ -f ~/.openclaw/agents/.backup-*/sessions/sessions.json ] && \
  openclaw doctor --session-sqlite import --session-sqlite-agent .backup-xxx

这是阻塞启动的硬错误，gateway 在迁移完成前不会跑起来。

5.2 canonical validation

升级后启动 gateway 时，每个 agent 的 openclaw-agent.sqlite 都会跑一次 canonical-validation，按 session_key 重新对账。

特点：第一次启动会非常慢。对单 agent（220k+ events）这个步骤消耗 8 秒左右，15 个 agent 总计启动需要 1-2 分钟。如果 gateway 启起来没出 readyz，多半是在等这个。

5.3 restart-loop breaker

如果 gateway 在 5 分钟内连续 crash 3 次，会触发 restart-loop breaker，channel 自动启动被抑制，要在底装能读 readyz 后手动启动：

openclaw gateway call channels.start --params '{"channel":"feishu","accountId":"it-engineer"}'
openclaw gateway call channels.start --params '{"channel":"dingtalk-connector"}'

或者等 5 分钟冷却后重启 gateway 自动恢复。

六、升级前的准备清单

按本次升级踩过的坑排序：

6.1 备份（30 秒，必做）

cp openclaw.json openclaw.json.bak-pre-update-$(date +%Y%m%d-%H%M%S)
cp cron/jobs.json.migrated cron/jobs.json.migrated.bak-pre-update-$(date +%Y%m%d-%H%M%S)
cp ~/Library/LaunchAgents/ai.openclaw.gateway.plist ~/Library/LaunchAgents/ai.openclaw.gateway.plist.bak-pre-update-$(date +%Y%m%d-%H%M%S)

6.2 Node 切换到 24.x

brew install node@24
brew unlink node && brew link node@24 --force
# 改 LaunchAgent plist 里的 Node 路径为 Cellar 绝对路径（opt/node symlink 不会自动更新）

6.3 飞书 streaming 提前改 object

channels.feishu.streaming 从 bool 改成 object（详见 § 二）。

6.4 准备好 plugins.allow 改造

去掉 openclaw-lark，加 feishu（详见 § 二）。

七、升级期间容易踩的坑（按发生顺序）

7.1 openclaw update --yes 会因 plugin-sdk 报错退出

但包已经升到 9.5 — 不要慌，看 openclaw --version 确认。

7.2 首次 install @openclaw/feishu 会因 streaming 字段回滚

先改 config 再装，否则 install 会回滚你的 config 改动。

7.3 openclaw doctor --fix 会因 memory-core plugin state 顶到 50000 行而 refused

先 --state-sqlite compact + --session-sqlite compact --session-sqlite-all-agents 释放空间。

7.4 每个 agent 都要单独跑 session 迁移

doctor --fix 不会自动批量迁移。

7.5 隐藏目录 .backup-* 也要迁移

gateway 启动时扫描所有 agents/*/agent/openclaw-agent.sqlite，隐藏目录不漏。

7.6 gateway 启动超时 45s 不代表失败

canonical-validation 跑完才会真正 ready，等几分钟再查 readyz。

7.7 重复 session canonical key

升级期间如果某 agent 被误迁移两次（比如 yangxiaoli + .backup-customer-service），会出现 duplicate rows resolve to canonical session key 错误，手动 sqlite3 删除 session_windows + session_nodes 残留行。

7.8 restart-loop breaker 抑制 channel

手动启：

openclaw gateway call channels.start --params '{"channel":"feishu","accountId":"<id>"}'

八、把 9.5 用得更好的 8 条建议

8.1 多 agent 团队整理 role template

趁着 9.5 加了，把现有 agent 配置梳理一遍，提取共同点。

8.2 飞书凭证改白天改

Live plugin reload 让修飞书凭证不再需要凌晨。

8.3 重大插件升级前先 break-all-session-sqlite 一遍

避免像 memory-core 那样的 50000 行顶到上限。

8.4 遇到 gateway 启不动优先看 ~/.openclaw/logs/stability/

gateway 失败时写 stability bundle，里面有完整诊断。

8.5 openclaw doctor --state-sqlite compact 设为周跑

9.5 启用了 auto-vacuum，但 retroactively 收的 78MB 说明历史释放能力没起来。

8.6 插件装卸前先查官方 update-compat-inventory.json

这个文件列了每次 release 的 dist 兼容性承诺。

8.7 关注 compatibility.md 里 removeAfter: 2026-10-01 的 compat 记录

这是 9.5 升级给所有插件作者的一个软截止线，9.5 之后还要保留 umbrella import 的插件会越来越少。

九、值得关注的 9.x 后续方向

9.1 7 个 broad runtime subpath 在 2026-10-01 后会被移除

插件作者需要在那之前迁完。

9.2 plugin-sdk-provider-owned-helper-shims 也会在 10-01 收紧

provider-specific 快捷方式同步收紧。

9.3 plugin-sdk-session-agent-resolution-aliases 跑得更远

到 2026-11-29 才结束。

9.4 9.x 兼容窗口约 3 个月

这期间升 9.5 是稳的，再往后跳 10.0 可能又一波 breaking。

附录：升级对照速查

A.1 信息查询命令

维度命令 / 路径
看 9.5 release infoopenclaw update status –json
看 CHANGELOGcat /opt/homebrew/lib/node_modules/openclaw/CHANGELOG.md
看 compat policydocs/plugins/sdk-migration/compatibility-policy.md（在 install 包里）
看 compat registry 编译后dist/installed-plugin-index-BQ62QNRt.mjs
看本机诊断tail -100 ~/Library/Logs/openclaw/gateway.log

A.2 修复与运维命令

维度命令 / 路径
释放 state SQLiteopenclaw doctor –state-sqlite compact
释放 session SQLiteopenclaw doctor –session-sqlite compact –session-sqlite-all-agents
迁移 agent sessionopenclaw doctor –session-sqlite import –session-sqlite-agent &lt;id&gt;
手动启动 channelopenclaw gateway call channels.start –params &#x27;{&quot;channel&quot;:&quot;&lt;id&gt;&quot;,&quot;accountId&quot;:&quot;&lt;id&gt;&quot;}&#x27;
装新飞书插件openclaw plugins install @openclaw/[email protected] –force –accept-capabilities –acknowledge-install-policy-warning
阅读量： 95

网站备案号：沪ICP备2025137870号