---
read_when:
    - 测试针对本地打包插件的新手引导或设置流程
    - 发布插件包前对其进行验证
    - 用测试工件替代自动插件安装
sidebarTitle: Install overrides
summary: 使用设置时安装流程测试打包插件覆盖
title: 插件安装覆盖项
x-i18n:
    generated_at: "2026-07-05T11:30:07Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: adc823f49ea9f8fa86e6a89933e43fdc309d808ac24397770495dbe81cb4b0d7
    source_path: plugins/install-overrides.md
    workflow: 16
---

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

<Warning>
覆盖会执行你提供的来源中的插件代码。仅在隔离的状态目录或一次性测试机器中使用它们。
</Warning>

## 环境

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

```bash
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；相对路径从当前工作目录解析                                     |

## 行为

当设置时流程安装映射中出现其 ID 的插件时，OpenClaw 会使用覆盖来源，而不是目录、内置或默认 npm 来源。这适用于新手引导，以及使用共享设置时插件安装器的任何其他流程。

- 覆盖仍会强制检查预期的插件 ID：映射到 `codex` 的 tarball 必须安装清单 ID 为 `codex` 的插件。
- 覆盖不会继承官方可信来源状态。即使目录条目通常代表 OpenClaw 拥有的包，覆盖也会被视为操作员提供的测试输入。
- 工作区 `.env` 文件无法启用安装覆盖；这两个环境变量都在被阻止的工作区 dotenv 列表中。请在启动 OpenClaw 的可信 shell、CI 作业或远程测试命令中设置它们。

## 包 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' -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json
```

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