安装覆盖

插件安装覆盖（Plugin install overrides）允许维护者将设置期间的插件安装指向特定的 npm 包或本地 npm-pack tarball，而不是目录（catalog）、捆绑或默认的 npm 源。它们仅用于 E2E 和包验证；普通用户通过 openclaw plugins install 安装插件。

环境¶

除非同时设置两个变量，否则覆盖处于禁用状态：

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"
}'

覆盖映射（override map）是以插件 ID 为键的 JSON。支持的值包括：

行为¶

当设置期间的流程安装一个其 ID 出现在映射中的插件时，OpenClaw 会使用覆盖来源，而不是目录、捆绑或默认的 npm 源。这适用于引导（onboarding）流程以及任何其他使用共享的设置期间插件安装器的流程。

• 覆盖仍然强制校验预期的插件 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' -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json

对于实时提供商 E2E，请在启动测试命令之前，从可信 shell 或 CI 密钥中获取真实的 API 密钥。不要打印密钥；仅报告来源以及密钥是否存在。