OpenClaw 的模块面账本：346 个 import 子路径、38.4% 已消失、9 次开合，而「更旧的 LTS」反而给你更多入口
如果你在 OpenClaw 里写插件，你会 import 一个路径。你大概率不会问的是：这条路径现在为什么能 import，三个月前为什么不能，隔壁那条 LTS 线上为什么反而没有。
这篇文章把这些问题的答案全部落到数据上。数据源是 npm registry 返回的 openclaw 包的完整元数据（GET https://registry.npmjs.org/openclaw），本次采集 2026-10-17 06:0x（Asia/Shanghai），响应 19,886,890 字节，time.modified = 2026-10-15T23:58:29.036Z。278 个版本全部逐个解析，非抽样。
一、这张表的规模：278 个版本里只有 1 个没有 exports
先说最容易被跳过的事实基数。
| 项目 | 数值 | 说明 |
|---|---|---|
| registry 收录版本总数 | 278 | 含预发布与 LTS 线 |
含 exports 字段的版本 |
277 | 只有 0.0.1 没有 |
exports 首现版本 |
2026.1.29-beta.1 |
2026-01-30 |
| 首现时的子路径数 | 4 | .、./cli-entry、./plugin-sdk、./plugin-sdk/* |
| 最新版本子路径数 | 346 | 2026.10.4，2026-10-15 |
| 增长率 | 86.5 倍 | 346 ÷ 4 |
那个唯一没有 exports 的版本是 0.0.1。它是一个占位版本，元数据里只有 name/version/license/main/description/directories 这几个字段，连 engines 都没有。它不是「忘了写」，它是整个包在 2026-01-30 正式暴露子路径之前的起点。
也就是说：openclaw 从第 9 个版本开始就再没有一天不声明自己的模块面。 这是个很不寻常的工程纪律。对比一下：绝大多数 npm 包是先发布、后补 exports，OpenClaw 是从第一天就把「你可以从哪里 import 我」写死。
二、今天的 346 条路径长什么样
当前 latest 2026.10.4 的结构非常规整，几乎是一条规则到底：
- 2 条根入口：
.（指向./dist/index.js）和./cli-entry（指向./openclaw.mjs）。这 2 条是纯字符串形式，不带条件。 - 344 条
./plugin-sdk/*子路径，全部是条件导出对象形式，形如{ "types": "...", "default": "..." }。 - 0 条
./extension-api（这个入口从 2026-09-23 的2026.9.6起就彻底消失了，见第五节）。
也就是说 344/346 = 99.4% 的公开面集中在一个命名空间 ./plugin-sdk/ 下。主包根只留了两条路。
Node.js 对条件导出 types / default 的解析规则见官方 ESM 文档（Conditional exports）——条件对象不是「任选其一」，而是按 import 与 require 的解析上下文挑键，挑不到就报错。这一节的所有 types 键都属于「给 TypeScript 用的那一半」。
上图为仓库 main 分支 package.json 的实拍。注意第 31~38 行的 publishConfig.executableFiles：只有 5 个文件被标记为可执行。这是后面第六节要说的一处独立风险点，此处先记住这 5 个名字：dist/crabbox-wrapper.js、dist/entry.js、dist/index.js、dist/mac-node-worker.js、dist/native-hook-relay/entry.js。
三、38.4% 的路径已经死了
这是本文最重要的一张表。
把 277 个有 exports 的版本按发布时间排序，统计「历史上曾经出现过多少个不同的子路径」，再和今天仍然存在的做差集：
| 指标 | 数值 |
|---|---|
| 历史上出现过的不同子路径总数 | 562 |
今天（2026.10.4）仍存在 |
346 |
| 已消失 | 216 |
| 消失占比 | 38.4% |
| 发生过「路径数量减少」的版本数 | 33 |
换句话说：你如果照着 2026 年 3 月的插件教程写 import 路径，每三条里就有大约一条已经不存在了。
而且这不是缓慢磨损。真实发生过三次「一次性砍掉几十条」：
| 版本 | 日期 | 单次消失条数 | 消失的内容举例 |
|---|---|---|---|
2026.4.5 |
2026-04-06 | 62 | amazon-bedrock、anthropic-vertex、browser、browser-runtime |
2026.4.27-beta.1 |
2026-04-29 | 52 | bluebubbles、bluebubbles-policy、browser-cdp、browser-config-runtime |
2026.6.35 |
2026-09-10 | 70 | agent-harness-registration、agent-scope-runtime、approval-reference-runtime、archive |
单次最多砍掉 70 条，接近当时总量的五分之一。官方没有为任何一次删除留下 changelog 条目、也没有 semver 级别说明——registry 里 deprecated 字段全包只有 1 条，还只是 2026.5.19-alpha.1 那句「This alpha release is obsolete. Please install openclaw@latest.」。
判断：这不是「重构噪声」，这是模块面缺少稳定性契约。 后面第八节给出可行的应对方式。
四、最反直觉的一条：更旧的 LTS 线给你更多入口
这条单独拎出来，因为它和「新版功能更多」的直觉完全相反。
对比当前两个 dist-tag 指向的版本：
| 版本 | dist-tag | 发布日期 | 子路径数 |
|---|---|---|---|
2026.9.33 |
extended-stable |
2026-10-15 | 354 |
2026.10.4 |
latest |
2026-10-15 | 346 |
同一天发布，latest 比 extended-stable 少 8 条。 而且这不是「少一些边角料」，缺的 8 条全是常用通道：
只在 2026.9.33（LTS）存在、2026.10.4（latest）已无 |
用途判断 |
|---|---|
./plugin-sdk/discord |
Discord 通道 |
./plugin-sdk/telegram-account |
Telegram 账号层 |
./plugin-sdk/channel-lifecycle |
通道生命周期 |
./plugin-sdk/channel-message |
通道消息 |
./plugin-sdk/channel-reply-pipeline |
通道回复管线 |
./plugin-sdk/command-auth |
命令鉴权 |
./plugin-sdk/config-runtime |
配置运行时 |
./plugin-sdk/infra-runtime |
基础设施运行时 |
这 8 条即为双向差集的全部内容，没有遗漏项。
反向差集是 0 条：2026.10.4 没有任何 2026.9.33 缺的路径。也就是说 LTS 的模块面是 latest 的严格超集，差 8 条。
这个方向在 LTS 线内部也成立。2026.7.35（LTS）有 327 条，2026.8.35（更新的 LTS）只有 324 条——更新的 LTS 线比旧 LTS 线少 3 条，而 2026.8.35 相对 2026.7.35 缺失了 55 条旧路径，同时新增 52 条新路径，是一次近乎完全换血的改名。
历史峰值出现在 2026.9.7（2026-09-30），354 条。今天 latest 是 346，比两周半前的历史峰值还少 8 条。
工程结论：如果你现在因为某条路径在 latest 上 import 失败而考虑降级 LTS，请先确认那条路径在 LTS 上真的存在——上表 8 条就是可以白捡的，但方向是反的：升到 LTS 不是「少功能」，某些版本组合下反而解锁更多 import 路径。
五、两个裸入口被反复开关，共 9 次
./plugin-sdk 和 ./extension-api 这两条「聚合入口」（不带斜杠后缀，可一次性 import 整个 SDK）的开关历史，是整份数据里最能说明工程不稳定性的一段。
先看 ./plugin-sdk 在修订号线（x.y.10 及以上）上的存在区间：
| 区间 | 状态 |
|---|---|
2026.1.29-beta.1 起 → 2026.7.2-beta.4（2026-07-24）前 |
开 |
| 2026-07-24 → 2026-08-04 | 关 |
| 2026-08-04 → 2026-08-10 | 开 |
| 2026-08-10 → 2026-09-10 | 关 |
| 2026-09-10 → 2026-09-11 | 开 |
| 2026-09-11 → 2026-09-18 | 关 |
| 2026-09-18 → 2026-09-19 | 开 |
| 2026-09-19 → 2026-09-20 | 关 |
| 2026-09-20 → 2026-09-23 | 开 |
| 2026-09-23 → 至今 | 关 |
在 9 月这 13 天里，它开关了 8 次。 全版本统计，这个字段一共翻转 9 次。按发布线看，差异更刺眼：
| 发布线 | 版本数 | 含 ./plugin-sdk |
含 ./extension-api |
|---|---|---|---|
| beta | 159 | 144（91%） | 130（82%） |
| 修订号线（x.y.10+） | 53 | 53（100%） | 31（58%） |
| 主线小版本 | 53 | 38（72%） | 22（42%） |
| LTS 线 | 12 | 8（67%） | 7（58%） |
如果你写的是 import { X } from 'openclaw/plugin-sdk'，你在 2026 年 9 月的某一天升级，它就会突然报 module not found，而在 LTS 线上它可能一直好好的。
还有一条更隐蔽的：./plugin-sdk/* 通配入口只存在了 9 天——从 2026.1.29-beta.1（2026-01-30）到 2026.2.1（2026-02-02），之后被换成逐条列举。今天你能 import 的路径清单，是一份人工维护的白名单，不是通配符。
六、类型、peer 依赖与可选依赖：三个已经稳定或已经消失的层
types：自 2026-05-10 起连续 127 个版本没断过
types 字段首现于 2026.2.1（2026-02-02），最后缺失的是 2026.5.9-beta.1（2026-05-09）。从 2026.5.10-beta.1 起的 127 个版本，每一个都有 types: "./dist/index.d.ts"，无一例外。
但要注意一个不对称：346 条子路径里，2 条是纯字符串、344 条是条件导出对象；这 344 条里只有 151 条带 types 条件，剩下 193 条只有 default。也就是说 import 能跑通、但 TypeScript 拿不到类型声明的路径有 193 条。这 193 条的实测样本：
./plugin-sdk/llm、./plugin-sdk/types、./plugin-sdk/speech、./plugin-sdk/sandbox、./plugin-sdk/file-lock、./plugin-sdk/migration、./plugin-sdk/node-host、./plugin-sdk/agent-core、./plugin-sdk/acp-runtime、./plugin-sdk/browser-cdp、./plugin-sdk/cli-backend、./plugin-sdk/cli-runtime。
写 TS 插件时最可能踩的坑就在这里：错误信息不是「类型不匹配」，而是「找不到模块声明文件」。 这是两回事，处理方式也完全不同。
peerDependencies：93 个版本之后彻底归零
peerDependencies 从 2026.1.30（2026-01-31）首次出现，到 2026.4.23（2026-04-24）为止，共 93 个版本。之后连续 177 个版本完全没有 peer 依赖。今天的 2026.10.4 里 peerDependencies 和 peerDependenciesMeta 都是空。
这意味着：你不能靠 peer 依赖来获得任何官方声明的兼容性提示。 一个包是否与你环境兼容，官方在元数据层面完全不表态，唯一的硬门槛只有 engines 里的 Node 版本范围。
optionalDependencies：79 条里 53 条是原生模块的跨平台副本
| 家族 | 平台包数 | 作用 |
|---|---|---|
@esbuild/* |
26 | JS 编译器原生二进制 |
@koromix/koffi-* |
20 | FFI（对应主依赖 koffi 3.3.1） |
@ubjs/node-* |
8 | 原生运行时 |
@openclaw/fs-safe-* |
7 | OpenClaw 自有命名空间 |
@lydell/node-pty-* |
6 | 伪终端 |
@trycua/cua-driver-* |
6 | 计算机操作驱动 |
sqlite-vec-* + 裸包 |
6 | 向量检索原生扩展 |
三个值得注意的点：
@esbuild独占 26 条（32.9%），覆盖 aix、sunos、netbsd、openharmony、loong64、mips64el、riscv64、android-arm 等长尾平台。它们全是optionalDependencies，装不上不影响安装——代价是运行时才失败，而不是安装时报错。- Linux 是唯一有 GNU/musl 双变体的平台：
@ubjs/node8 条里有 gnu 4 + musl 4，@openclaw/fs-safe和@trycua/cua-driver也都成对提供 gnu/musl。Windows 对应的是 msvc 变体。在 Alpine 或其他 musl 发行版上部署，这几个原生包的行为和 glibc 环境不完全等价。 @openclaw/fs-safe-*是 OpenClaw 自己的原生包（7 条），不来自任何第三方。它有 2 个 darwin、3 个 linux（x64/arm64 + gnu/musl 各一对）、2 个 win32（x64/arm64）。官方原生扩展按平台分发的粒度，比 esbuild 细但比 esbuild 少——esbuild 有 26 个平台，fs-safe 只有 7 个，且没有任何 Linux armv7、任何 BSD、任何 android。
七、install 之外：还有一处和文件系统权限直接相关的声明
publishConfig.executableFiles 只有 5 个文件（第二节截图可见）：
dist/crabbox-wrapper.js
dist/entry.js
dist/index.js
dist/mac-node-worker.js
dist/native-hook-relay/entry.js
npm 在打包时会为这几个文件打上可执行位。但要注意 publishConfig.executableFiles 只对 npm 生效——用 pnpm、yarn 或 bun 安装同一个 tarball 时，这一位的处理由各自分发器决定。这 5 个文件里 dist/index.js 正是主入口（main 字段），也就是说「npm 装出来的包」和「pnpm 装出来的同一个包」在文件权限位上可能不同。
如果你在容器里跑 OpenClaw 且依赖其内部脚本的直接执行，这是一个需要实测确认的差异点。本文未实测该差异，仅陈述两个字段并存的事实。
八、那该怎么写才不会被这些变更打断
基于以上数据，给插件作者四条可执行的规则：
1. 不要 import 裸入口。 openclaw/plugin-sdk 和 openclaw/extension-api 在 9 月里各翻转了多次，openclaw/plugin-sdk/* 通配符只活过 9 天。只 import 明确的叶子路径。
2. 把 import 路径当成需要锁定的外部契约。 216 条已消失、38.4% 的历史路径作废、9 次入口开合——这不是可以「跟着 latest 走」的领域。写进 package.json 的 openclaw 版本要带明确上限，让 npm 的 peer 检查或你自己的一条 import 冒烟测试能在升级时立刻炸掉，而不是在生产环境里静默失败。
3. 升级前先 diff exports，不要只 diff CHANGELOG。 CHANGELOG 里没有一条记录提到过路径删除。但 diff 一次 exports 的键集合，30 行脚本就能告诉你这次升级会不会打断你的插件。这是最便宜的一道防线。
4. TS 用户优先使用那 151 条带 types 条件的路径。 另外 193 条路径能 import 但拿不到声明文件。避开它们的成本，远低于处理「TS 报找不到模块声明」的成本。
如果你想自己复现本文全部数字，最小脚本是三步：取 https://registry.npmjs.org/openclaw 的完整 JSON，按 time 字段排序，对每个 versions[v].exports 取 keys()，然后对相邻两版做集合差。
上图值得单独说一句。四个版本号 tag 之外，还散布着大量 release-publish/ 形式的标签，且全部标记为 Verified。这些是发布流水线的中间产物。它们的存在意味着同一份代码可能被反复发布，也是第三节里「同一天两次发布会拿到不同子路径数」这类现象的背景。
九、证据口径：哪些是官方明示，哪些是我的算术，哪些我不知道
官方文档明示（可复现）
exports的条件对象语义（types/default）：Node.js 官方 ESM 文档 Conditional exports 章节。package.json各字段定义：npm 官方 package.json 文档。publishConfig.executableFiles的作用范围。
我基于官方原始数据算出来的（可复现，算法已在第八节末尾给出）
- 346 / 354 / 327 / 324 / 4 / 86.5 倍：全部来自对
exports键集合的直接计数与除法。 - 562 与 216 与 38.4%：来自「历史键集合并集」与「今日键集合」的差集。
- 9 次翻转 / 33 次减少：来自对相邻版本布尔值与集合差的逐版比对。
- 「LTS 是 latest 的严格超集，差 8 条」：来自两个键集合的双向差集，反向差集为空。
UNKNOWN（我不做结论）
- 路径删除的官方理由未知。 registry 没有任何字段记录删除原因，也没有 changelog 条目。无法判断 216 条消失是「合并重构」「收窄承诺面」还是「误发布后回滚」。
- 裸入口 9 次开合是否有意为之未知。 没有对应 issue 或提交说明可引用。可能是多个并行分支各自发布，也可能是构建脚本的产物差异。我只能陈述观测到的开关序列。
2026.9.33与2026.10.4同日发布但模块面差 8 条，是否为刻意对齐未知。 两版 engines 完全相同（>=24.16.0 <25 || >=26.1.0），_from一致，看起来同源，但官方未就模块面差异作任何说明。- pnpm/yarn/bun 安装后
executableFiles权限位是否一致未实测。 本文只陈述字段存在。 0.0.1是否为真实发布还是占位，未获官方确认。 从元数据形态看是占位。- 193 条无
types的路径是否计划补齐，未知。
十、来源与方法说明
| 来源 | 用途 | 采集时间（Asia/Shanghai） |
|---|---|---|
| npm registry: registry.npmjs.org/openclaw | 主数据源。19,886,890 B，time.modified=2026-10-15T23:58:29.036Z，278 个版本 exports / types / peerDependencies / optionalDependencies / bin / publishConfig 字段全量解析 |
2026-10-17 06:0x |
| npm registry: /openclaw/latest | 交叉验证 latest 元数据：version 2026.10.4、type: module、main: dist/index.js、types: ./dist/index.d.ts、exports 计数 346、bin.openclaw=openclaw.mjs、peerDependencies 为空 |
2026-10-17 06:1x |
| Node.js 官方 ESM 文档 | 条件导出 types / default 的解析语义 |
2026-10-17 |
| Node.js 包文档 | 包入口与 exports 的模块解析规则 |
2026-10-17 |
| npm 官方 package.json 文档 | exports / types / bin / publishConfig.executableFiles 字段定义 |
2026-10-17 |
| GitHub: openclaw/openclaw 仓库 main 分支 package.json | 截图一：确认 version 2026.10.4、publishConfig.executableFiles 5 条、files 白名单同文件共存 |
2026-10-17 06:0x |
| GitHub: openclaw/openclaw Tags 列表 | 截图二：v2026.10.4 / v2026.9.33 / v2026.10.5-beta.4 / v2026.10.10-beta.1 与 release-publish/* 标签并存、均 Verified |
2026-10-17 06:0x |
| GitHub: openclaw/openclaw packages/ 目录 | 截图三：29 个子包目录，含 plugin-sdk / plugin-package-contract / sdk |
2026-10-17 06:0x |
方法说明：全部数字由脚本对 registry 返回的完整 JSON 做全量解析得出，278 个版本无一抽样。版本按 time 字段的真实时间戳升序排列（不使用版本号字符串比较——同一天内多个版本会排错）。集合运算用 Python set 直接完成。文末的最小复现脚本即本文全部数字的来源。
范围声明：本文只陈述 npm registry 与 GitHub 仓库这两个公开数据源中的元数据事实。未登录 OpenClaw 控制台、未安装任何版本、未执行任何 import 语句、未触发任何一条错误码。第三节提到的 import 失败风险是基于元数据推断的结构性风险，不是实测复现。
