Plugins 导读

Plugin Install Overrides 是维护者测试插件安装包时的临时换轨工具

这页讲 setup-time plugin install 的测试覆盖机制。维护者可以把某个 plugin id 指向指定 npm spec 或本地 npm-pack tarball，用于 E2E 和包验证。覆盖来源会执行插件代码，因此只应在隔离 state directory 或一次性测试机器里使用。

先讲这一页到底在解决什么

Plugin Install Overrides 是维护者测试插件安装包时的临时换轨工具

原文共 4 节，先看 Start Here 路径：/plugins/install-overrides 查看官方原文

第一站

什么时候该用，什么时候不该用

适合用

发版前想验证某个 npm 版本、本地 npm pack tarball、或 setup-time install 流程能不能正确识别插件。

不适合用

普通用户日常安装、生产环境长期配置、或任何来源不清楚的包。

安全提醒

override 不是“官方可信来源”的延伸。即使原目录里是官方插件，你指定的新来源也只是操作者提供的测试输入。

记忆法

像火车临时换轨测试新轨道，测试完要撤掉，不要让所有乘客都走临时轨。

第二站

开关必须两把钥匙同时打开

环境变量缺一不可：一个允许 override 机制启动，另一个给出 plugin id 到来源的映射。

环境变量

export OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1
export OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{
  "codex": "npm-pack:/tmp/openclaw-codex-2026.5.8.tgz",
  "openclaw-web-search": "npm:@openclaw/web-search@2026.5.8"
}'

npm:

指向一个 npm package spec，适合验证某个发布版本或 tag。

npm-pack:

指向本地 npm pack 产物，适合发版前试装 tarball。

id 仍要对

映射到 codex 的 tarball，安装出来的 manifest id 也必须是 codex，不能偷梁换柱。

第三站

一次安全的本地包 E2E 像这样走

打包

先对目标 extension 运行 npm pack，得到本地 tarball。

隔离

用临时 OPENCLAW_STATE_DIR，不要污染正常 OpenClaw 状态。

覆盖

只把要测的 plugin id 映射到测试来源。

核对

安装后检查 state directory 和 runtime inspect，确认装的是预期插件。

最后记住

install override 是测试工具，不是用户功能

它帮助维护者验证“如果 setup 流程要装这个插件，会不会正确安装和识别”。测试结束后撤掉环境变量，回到正常 catalog、bundled 或 npm 来源。