依赖项
OpenClaw 仅在安装/更新时间处理插件依赖。运行时加载绝不会运行包管理器、修复依赖树,或修改 OpenClaw 包目录。
职责划分¶
插件包拥有其依赖图:
- 运行时依赖位于插件包的
dependencies或optionalDependencies中。 - SDK/核心导入是对等(peer)依赖或 OpenClaw 提供的导入。
- 本地开发插件自带已安装的依赖。
- npm 和 git 插件安装到 OpenClaw 拥有的包根目录中。
OpenClaw 仅负责插件生命周期:
- 发现插件源。
- 在显式请求时安装或更新包。
- 记录安装元数据。
- 加载插件入口点。
- 当依赖缺失时,以可操作的错误信息失败。
安装根目录¶
OpenClaw 为每个来源使用稳定的根目录:
- npm 包装入
~/.openclaw/npm/projects/<encoded-package>下的插件独立项目。 - git 包克隆到
~/.openclaw/git下。 - 本地/路径/归档安装会被复制或引用,不进行依赖修复。
这些根目录是持久的安装状态,而非缓存。删除 ~/.openclaw/npm 或 ~/.openclaw/git 会移除所有已安装的外部插件;部署清理脚本必须保留它们。被取代的插件代际由 Gateway 自身负责退役。
npm 安装在该插件独立项目的根目录中运行,使用以下命令:
cd ~/.openclaw/npm/projects/<encoded-package>
npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund
npm-pack tarball 安装¶
openclaw plugins install npm-pack:<path.tgz> 对本地 npm-pack tarball 使用相同的插件独立 npm 项目根目录:OpenClaw 读取 tarball 的 npm 元数据,将其作为复制的 file: 依赖添加到受管项目中,运行上述标准 npm 安装,然后在信任该插件之前验证已安装的锁文件元数据。该路径的存在是为了包验收和发布候选证明,即本地打包产物应表现得与其模拟的 registry 产物一致。
在发布前测试官方或外部插件包时,请使用 npm-pack:。原始归档或路径安装对本地调试很有用,但它无法证明与已安装的 npm 或 ClawHub 包具有相同的依赖路径。npm-pack: 证明了受管包的安装形态;但它本身并不能证明该插件是目录关联的官方内容。
当行为取决于捆绑插件或受信任的官方插件状态时,应将本地包验证与目录支持的官方安装,或记录官方信任的已发布包路径结合使用。特权辅助访问和受信任官方作用域处理应在该受信任的安装路径上进行验证,而不能从本地 tarball 安装中推断。
缺失的运行时导入¶
如果插件在运行时因缺少导入而失败,请修复包清单,而不是手动修复受管项目。运行时导入应放在插件包的 dependencies 或 optionalDependencies 中;受管运行时项目不会安装 devDependencies。在 ~/.openclaw/npm/projects/<encoded-package> 内执行本地 npm install 可以临时解除诊断阻塞,但不能作为包验收的证明,因为下次安装或更新会根据包元数据重新创建项目。
提升的传递依赖¶
npm 可能会将传递依赖提升到插件独立项目的 node_modules 中,与插件包并列。OpenClaw 在信任安装之前会扫描受管项目根目录,并在卸载时移除该项目,因此被提升的运行时依赖始终位于该插件的清理边界之内。
锁文件策略¶
OpenClaw 拥有的 npm 插件包绝不附带 npm 锁文件。仓库使用 pnpm-lock.yaml 作为已提交的产品依赖审查边界,仅在临时目录中生成 npm 包锁文件,以验证可发布的依赖图:
检查器会剥离插件的 devDependencies,应用工作区覆盖策略,并拒绝 pnpm-lock.yaml 中不存在的生成版本。不会向检出目录写入任何内容。第三方插件包可能仍会根据其自身的打包策略包含锁文件;OpenClaw 的安装器将该 npm 行为交由已安装的 npm 版本处理。
验证包 tarball¶
在将本地包作为发布候选证明之前,请检查将要安装的 tarball:
npm pack --pack-destination /tmp
tar -xOf /tmp/<plugin-package>.tgz package/package.json
tar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'
对于依赖变更,还需验证生产安装能否在不包含开发依赖的情况下解析运行时包:
tmpdir=$(mktemp -d)
(
cd "$tmpdir"
npm init -y >/dev/null
npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz
)
rm -rf "$tmpdir"
捆绑的运行时依赖¶
OpenClaw 拥有的 npm 插件包也可以使用显式的 bundledDependencies 进行发布。npm 发布路径会叠加运行时依赖名称列表,从已发布清单中剥离仅开发用的工作区元数据,暂存一个不含源码 node_modules 的独立包目录,并在其中运行无脚本的 npm 安装以获取运行时依赖。然后,它将这些依赖文件包含在插件 tarball 中进行打包或发布,并移除暂存目录。pnpm 管理的源码依赖树保持不变。
当直接运行时依赖的精确版本具有已批准的工作区补丁时,npm 和 ClawHub 打包会从匹配的冻结 pnpm 安装中包含该依赖。打包过程会验证已安装补丁的身份,并将其字节打包进临时依赖安装中,然后在已发布清单中恢复原始公共版本说明符。这在禁用所有运行时依赖捆绑时同样适用;无关依赖保留其正常的安装行为。过期的源码安装或显式的 bundleRuntimeDependencies: false 退出选项会停止打包,而不是发布未打补丁的依赖。
原生依赖较重的包(Codex、ACPX、Copilot、llama.cpp、memory-lancedb、Microsoft Teams、Tlon)通过 openclaw.release.bundleRuntimeDependencies: false 选择不捆绑运行时依赖;它们仍然提供精确锁定的 manifest,但 npm 会在安装期间解析运行时依赖,而不是将每个平台的二进制文件嵌入插件 tarball。根级 openclaw 包同样在安装时解析依赖,且不捆绑其完整的依赖树。参见依赖锁定。
主机对等依赖¶
导入 openclaw/plugin-sdk/* 的插件会将 openclaw 声明为对等依赖(peer dependency)。OpenClaw 不允许 npm 将宿主包的独立注册表副本安装到托管项目中,因为过期的宿主包可能会影响 npm 在该插件内部的 peer 解析。托管式 npm 安装会跳过 npm 的 peer 解析/物化(materialization),OpenClaw 会在安装或更新后,为声明了该宿主 peer 的已安装包重新建立插件本地的 node_modules/openclaw 链接。
git 安装¶
git 安装会克隆或刷新仓库,然后运行:
安装后的插件从该包目录加载,因此包本地及父级 node_modules 的解析方式与普通 Node 包相同。
本地插件¶
本地插件是由开发者控制的目录。OpenClaw 绝不会为它们运行 npm install、pnpm install 或依赖修复;如果某个本地插件包含依赖,请在加载之前在该插件中安装它们。
第三方 TypeScript 本地插件通过 Jiti 以应急路径加载。打包的 JavaScript 插件和捆绑的内部插件则通过原生 import/require 加载。
启动与重载¶
网关启动和配置重载绝不会安装插件依赖。它们会读取插件安装记录、计算入口点并加载插件。
运行时缺少依赖会导致插件加载失败,并返回一条错误,指引操作员进行明确的修复:
doctor --fix 会移除悬空的全局插件运行时符号链接,并且当配置仍引用本地安装记录中缺失的可下载插件时,可以恢复这些插件。Doctor 不会修复已安装本地插件的依赖。
捆绑插件¶
轻量级且核心关键的捆绑插件随 OpenClaw 一起发布。它们要么不携带沉重的运行时依赖树,要么迁移到 ClawHub/npm 上的可下载包中。
有关当前生成的三类插件列表——随核心包发布、需外部安装、或仅保留源码——请参阅插件清单。
捆绑插件的 manifest 不得请求依赖暂存(dependency staging)。大型或可选的插件功能应打包为普通插件,并通过与第三方插件相同的 npm/git/ClawHub 路径安装。
内部捆绑插件在其自身的 manifest 中保留依赖声明。未编译进 dist 的运行时依赖也必须在根级 OpenClaw 包的 dependencies 或 optionalDependencies 中声明,因为根包随其发布这些运行时。外部插件则将运行时依赖保留在插件本地。
包验证使用构建生成的 dist/runtime-dependency-ownership.json 来识别仅供插件使用的 chunk。每个条目将 chunk 文件名和 SHA-256 哈希绑定到其所属插件;每个所有者必须在其捆绑或已安装的 @openclaw/<id> 包 manifest 中声明该依赖。根级导入(包括根级对插件自有 chunk 的引用)仍然需要根级依赖声明。对于使用元数据生成器构建的候选包,缺失元数据或 chunk 字节变化都不能使插件获得豁免。
发布预检对早于 scripts/lib/runtime-dependency-ownership-build-plugin.mts 的源码检出有一个兼容性例外。当所有权元数据缺失时,它可以将生成的插件区域内的各个导入归属到该插件的打包或受信源码 manifest。这些区域之外的导入仍然需要根级声明。根级对某个 chunk 的引用会撤销该插件的豁免,包括通过传递性相对导入的引用。提升的静态导入遵循 chunk 的图所有权;插件区域之外的可执行导入仍属于根级引用。公共包入口始终视为根级所有。存在但无效的元数据绝不会回退到区域所有权。此验证不会改变 Node 的运行时依赖解析。
在源码检出中,先运行 pnpm install,再运行 pnpm build。OpenClaw 优先选择 dist/extensions,其次为 dist-runtime/extensions;当两个构建树均不可用时,回退到 extensions。pnpm 管理源码依赖树:postinstall 和构建准备会保留插件本地版本及工作区链接。原生 Node 导入从各个插件包解析;打包的捆绑运行时仍使用上述根级运行时声明。使用构建树时,需重新构建以获取源码改动。源码检出开发仅支持 pnpm;在仓库根目录直接运行 npm install 不会准备 pnpm 工作区。
根级构建从 Git 跟踪的文件中发现插件包及其他顶层源码条目,并保留文件名中的空格和 Unicode 字符。构建前,请将新包和自动发现的入口文件添加到 Git 索引。下面的独立构建同样支持尚未被跟踪的包。
| 安装形态 | 捆绑插件位置 | 依赖所有者 |
|---|---|---|
| 全局 npm 安装 | 包内构建的运行时树 | 根级 OpenClaw 包(内部捆绑运行时) |
| 安装形态 | 捆绑插件位置 | 依赖所有者 |
|---|---|---|
Git 检出加上 pnpm install + pnpm build |
dist/extensions,然后 dist-runtime/extensions |
根运行时声明加上插件清单 |
| 未构建的源码检出 | 当不存在已构建树时回退到 extensions/<id> |
具有显式根运行时依赖的 pnpm 工作区 |
openclaw plugins install ... |
受管理的 npm 项目/git/ClawHub 根 | 插件安装/更新流程 |
对于全局 npm 行,在 npm 12 或 npm 11.16+ 上使用
npm install -g openclaw --allow-scripts=openclaw。
在 npm 11.15 及更早版本中,省略 --allow-scripts=openclaw。插件依赖
收敛仍然有意禁用脚本,并继续使用上述
--ignore-scripts 命令。
来自独立源码构建的本机导入¶
若要直接使用 Node 导入已构建的 extensions/<package>/dist,请使用
pnpm 安装的宿主链接。如果该链接缺失,请从源码检出根目录显式准备它:
这需要 dist/plugin-sdk 中已存在的根 SDK 输出,以及所选包的独立运行时输出。如果包输出缺失,请先使用 node scripts/lib/plugin-npm-runtime-build.mjs extensions/<package> 构建它。
独立构建会运行所选包的资产构建命令,并将其声明的 openclaw.build.staticAssets 复制到 dist,包括尚未被 Git 跟踪的新包。缺失的已声明源文件会导致构建失败。
根构建和独立构建会从插件已安装的依赖项中解析 node_modules/<package>/... 下的源文件,包括提升安装的依赖项。这些是物理包路径;子路径导出映射不会限制已声明的资产。所选依赖项中缺失的文件不会借用另一个已安装版本。
在 openclaw.build.workerEntries 中声明私有 worker 源文件,使用包相对路径,例如 ./src/store.worker.ts。独立构建会将它们输出到 dist 下的匹配路径,例如 dist/src/store.worker.js(CommonJS 包为 .cjs)。当插件被选入根捆绑构建时,这些条目也会被包含。声明 worker 不会将其注册为插件入口点,也不会添加公共包导出。
准备命令不会重新构建任一输出,也不会执行插件代码。它仅将检出链接为 node_modules/openclaw,用于在 peerDependencies 或 dependencies 中声明 openclaw 的真实直接源包。它不会安装第三方依赖项;这些依赖项必须已通过 pnpm 工作区可用。
准备过程会拒绝符号链接包路径、不安全清单和冲突的依赖项路径,而不是报告成功。普通包构建仍然仅生成产物。Postinstall 和根构建准备会保留源码插件本地 node_modules,包括此链接。运行时加载永远不会执行此设置或运行包管理器。
旧版清理¶
旧版 OpenClaw 会在启动时或 doctor 修复期间生成捆绑插件依赖项根目录。打包的 postinstall 现在只清理其自身安装:dist/extensions 下过时的捆绑插件 node_modules 和 .openclaw-install-stage* 目录、打包清单中不存在的 dist 文件,以及空的 dist 目录。
doctor --fix 仅在别名本身确实悬空时,才会移除指向 plugin-runtime-deps 的全局 Node 前缀包符号链接。有效别名会被保留。Doctor 和 postinstall 都不会删除共享的 plugin-runtime-deps 根目录或镜像,因为它们可能仍服务于另一个安装或配置文件。自 2026.9.2 起,已弃用的 core/doctor/legacy-plugin-dependencies 选择器仅提供信息;它不再扫描共享根目录以进行删除。
共享的 ~/.openclaw/npm/node_modules 根目录是 2026.5.28 之前的 npm 安装布局。安装、更新、卸载和 doctor 流程仍然识别该旧版扁平根目录,仅用于恢复和清理。2026.5.28 及之后的安装会改为创建每个插件的项目根目录。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw