OpenClaw 只在插件安装或更新时处理依赖解析和安装，运行时不会重新运行包管理器或修复依赖树。npm 插件安装到 ~/.openclaw/npm，git 插件克隆到 ~/.openclaw/git，本地插件需自行安装依赖。如果运行时提示依赖缺失，可以通过 openclaw plugins update <id>、openclaw plugins install <source> 或 openclaw doctor --fix 修复。捆绑插件的依赖由 OpenClaw 安装流程或 pnpm workspace 管理，落后版本遗留的 plugin-runtime-deps 等目录可通过 doctor --fix 清理。

OpenClaw 插件依赖解析：安装机制与故障排查

OpenClaw 在插件安装或更新时处理依赖解析，运行时不会调用包管理器、修复依赖树或修改 OpenClaw 包目录。

责任划分

插件包负责其自身的依赖关系：

• 运行时依赖写在插件包的 dependencies 或 optionalDependencies 中
• SDK / 核心导入使用 peer 依赖或 OpenClaw 自带导入
• 本地开发插件的依赖由开发者提前安装好
• npm 和 git 插件安装到 OpenClaw 托管的包根目录下

OpenClaw 只负责插件生命周期：

• 发现插件来源
• 按需安装或更新插件包
• 记录安装元数据
• 加载插件入口
• 在依赖缺失时给出可操作的错误提示

安装根目录

OpenClaw 按来源使用固定的根目录：

• npm 包安装在 ~/.openclaw/npm
• git 包克隆到 ~/.openclaw/git
• 本地/路径/存档安装直接复制或引用，不修复依赖

npm 安装会在 npm 根目录下执行：

cd ~/.openclaw/npm
npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

openclaw plugins install npm-pack:<path.tgz> 也会使用同一个 npm 根目录处理本地 tgz 文件。OpenClaw 读取 tgz 中的 npm 元数据，将其作为 file: 依赖复制到托管根目录，运行正常 npm install，然后验证 lockfile 元数据后才信任该插件。这主要用于包验收和候选版本验证，让本地打包产物行为与 registry 发布产物一致。

npm 可能会把传递依赖提升到 ~/.openclaw/npm/node_modules 里与插件包同级。OpenClaw 在信任安装结果前会扫描托管 npm 根目录，卸载时也通过 npm 删除包，因此提升的运行时依赖始终处于托管清理边界内。

已发布的 npm 插件可以包含 npm-shrinkwrap.json。npm 在安装时会使用这个可发布的 lockfile，OpenClaw 的托管 npm 根目录通过正常 npm install 流程支持它。OpenClaw 自家发布的插件必须包含从该插件包依赖图生成的 shrinkwrap：

pnpm deps:shrinkwrap:generate
pnpm deps:shrinkwrap:check

生成器会去掉插件 devDependencies、应用 workspace 覆盖策略，并为每个设置了 publishToNpm 的插件写入 extensions/<id>/npm-shrinkwrap.json。第三方插件也可以打包 shrinkwrap，OpenClaw 不强求但 npm 会遵循。

OpenClaw 自家 npm 插件还可以使用 bundledDependencies 显式打包依赖。npm publish 流程会列出运行时依赖名、移除 dev-only 元数据、在包内运行无脚本 npm install 安装运行时依赖，然后带着这些依赖文件打包或发布。依赖原生插件（如 Codex 和 ACP 运行时）通过 openclaw.release.bundleRuntimeDependencies: false 跳转，这些包仍然携带 shrinkwrap，但依赖在安装时才解析，不嵌入平台二进制。根包 openclaw 不会打包完整依赖树。

插件如果导入 openclaw/plugin-sdk/*，需要把 openclaw 声明为 peer 依赖。OpenClaw 不允许 npm 在托管根目录额外安装一份宿主包，因为旧版本会影响后续插件安装时的 peer 解析。托管 npm install 会跳过共享根的 peer 解析/物化，并在安装/更新/卸载后重新设置插件本地的 node_modules/openclaw 链接。

git 安装先克隆或刷新仓库，然后运行：

npm install --omit=dev --ignore-scripts --no-audit --no-fund

已安装的插件从该包目录加载，因此包内和父级 node_modules 的解析行为与普通 Node 包一致。

本地插件

本地插件被视为开发者控制的目录。OpenClaw 不会为其运行 npm install、pnpm install 或修复依赖。如果本地插件有依赖，在加载之前需要自行安装。

第三方 TypeScript 本地插件可以使用紧急 Jiti 路径。打包的 JavaScript 插件和内联捆绑插件通过原生 import/require 加载，不使用 Jiti。

启动与重载

网关启动和配置重载不会安装插件依赖。它们只会读取插件安装记录、计算入口文件并加载。

如果运行时依赖缺失，插件加载失败，错误提示应指向明确的修复命令：

openclaw plugins update <id>
openclaw plugins install <source>
openclaw doctor --fix

doctor --fix 可以清理旧版 OpenClaw 遗留的依赖状态，并恢复配置中引用但本地安装记录缺失的可下载插件。Doctor 不会修复已安装的本地插件的依赖。

捆绑插件

轻量或核心关键的捆绑插件随 OpenClaw 一起发布。这些插件要么没有复杂运行时依赖，要么应移至 ClawHub/npm 作为独立可下载包。

当前随核心包发布的插件清单，以及哪些需要额外安装、哪些仅源码可用，请参见 Plugin inventory。

捆绑插件的 manifest 不得请求依赖暂存。大型或可选插件功能应作为普通插件打包，通过 npm、git、ClawHub 路径安装。

在源码 checkout 中，OpenClaw 将仓库视为 pnpm monorepo。运行 pnpm install 后，捆绑插件从 extensions/<id> 加载，因此包内 workspace 依赖可用且编辑可直接生效。源码开发仅支持 pnpm，在仓库根目录执行 npm install 不是受支持的捆绑插件依赖准备方式。

安装形态	捆绑插件位置	依赖归属
npm install -g openclaw	包内构建的运行时树	OpenClaw 包本身，以及显式的插件 install/update/doctor 流程
Git checkout 加 pnpm install	extensions/<id> workspace 包	pnpm workspace，包含每个插件包自身的依赖
openclaw plugins install ...	托管 npm/git/ClawHub 插件根目录	插件 install/update 流程

遗留清理

旧版 OpenClaw 会在启动或 doctor 修复时生成捆绑插件依赖根目录。当前 doctor 在使用 --fix 时会清理这些过期目录和符号链接，包括旧的 plugin-runtime-deps 根目录、指向已清理的 plugin-runtime-deps 目标的全局 Node prefix 符号链接、.openclaw-runtime-deps* 清单、生成的插件 node_modules、安装暂存目录以及包内 pnpm store。打包后的 postinstall 也会在清理遗留目标根目录之前移除这些全局符号链接，避免升级后留下悬挂的 ESM 包导入。

这些路径仅作为遗留残留存在。新安装不应创建它们。

常见问题

插件依赖缺失，运行时加载失败怎么办？

运行 openclog plugins update <插件ID> 或 openclog plugins install <插件来源> 重新安装依赖。如果插件安装记录本身有问题，可以尝试 openclog doctor --fix，它会清理旧版依赖残留并恢复配置中存在的可下载插件。

本地插件怎么安装依赖？

本地插件是开发者控制的目录，OpenClaw 不会自动安装依赖。请在插件目录内手动执行 npm install 或 pnpm install 后再加载。

openclaw doctor --fix 会修复本地插件的依赖吗？

不会。doctor --fix 只处理可下载的插件（npm、git、ClawHub）以及清理旧版 OpenClaw 遗留的依赖目录。对于已经安装的本地插件，doctor 不修复其依赖。