> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 插件安装覆盖

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

<Warning>
  覆盖会从你提供的源执行插件代码。仅在隔离的状态目录或可丢弃的测试机器上使用它们。
</Warning>

## 环境

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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"
}'
```

覆盖映射是以插件 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
find "$OPENCLAW_STATE_DIR/npm/projects" -path '*/node_modules/@openclaw/codex/package.json' -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json
```

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