本页内容

本页内容

插件内部

插件安装覆盖

插件安装覆盖允许维护者在设置时将插件安装指向 某个特定的 npm 包或本地 npm-pack tarball,而不是目录、 捆绑包或默认的 npm 源。它们仅用于端到端测试和包验证; 普通用户通过 openclaw plugins install 安装插件。

环境

除非同时设置了以下两个变量,否则覆盖会被禁用:

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

覆盖映射是以插件 id 为键的 JSON。值支持:

前缀 来源
npm:<registry-spec> 注册表包、精确版本或标签
npm-pack:<path.tgz> 由 npm pack 生成的本地 tarball;相对路径从当前工作目录解析

行为

当一个 setup-time 流程安装其 id 出现在映射中的插件时,OpenClaw 会使用覆盖源,而不是 catalog、bundled 或默认的 npm 源。这适用于 onboarding 以及任何其他使用共享 setup-time 插件安装器的流程。

  • 覆盖仍然会强制执行期望的插件 id:映射到 codex 的 tarball 必须安装一个 manifest id 为 codex 的插件。
  • 覆盖不会继承官方受信任源状态。即使 catalog 条目通常表示一个由 OpenClaw 拥有的包,覆盖也会被 视为由操作员提供的测试输入。
  • Workspace .env 文件不能启用安装覆盖;这两个环境变量都在 被阻止的 workspace dotenv 列表中。请在受信任的 shell、CI job,或 启动 OpenClaw 的远程测试命令中设置它们。

包 E2E

使用隔离的状态目录,以便包安装和安装记录不会影响 你正常的 OpenClaw 状态:

bash
npm pack extensions/codex --pack-destination /tmp OPENCLAW_STATE_DIR="$(mktemp -d)" \OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1 \OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{"codex":"npm-pack:/tmp/openclaw-codex-2026.5.8.tgz"}' \pnpm openclaw onboard --mode local

在状态目录下验证已安装的包:

bash
find "$OPENCLAW_STATE_DIR/npm/projects" -path '*/node_modules/@openclaw/codex/package.json' -printgrep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json

对于实时 provider E2E,在启动测试命令之前,请从可信的 shell 或 CI 密钥中加载真实的 API key。不要打印密钥;只报告来源以及密钥是否存在。

本页有帮助吗?