快速开始
插件安装覆盖项
插件安装覆盖允许维护者在设置时将插件安装指向特定的 npm 包或本地 npm pack tarball，而不是目录、内置或默认 npm 来源。它们仅用于 E2E 和包验证；普通用户使用 openclaw plugins install 安装插件。
环境
除非同时设置两个变量，否则覆盖会被禁用：
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/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 状态：
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验证状态目录下已安装的包：
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对于实时提供商 E2E，请在启动测试命令前，从可信 shell 或 CI secret 加载真实 API key。不要打印 key；只报告来源以及 key 是否存在。
Was this useful?
