Appearance
插件安装覆盖让维护者替换自动安装流程中的插件源，使用本地打包的 tarball 或指定 npm 版本进行测试。仅用于端到端验证和包校验，正常用户应使用 openclaw plugins install。设置两个环境变量 OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1 和 OPENCLAW_PLUGIN_INSTALL_OVERRIDES JSON 映射即可启用。覆盖仍强制检查插件 ID 一致性，且不继承官方可信源状态。建议在隔离状态目录或一次性测试机中操作。
OpenClaw 插件安装覆盖：测试与验证方法
插件安装覆盖让维护人员针对特定 npm 包或本地 npm pack 产生的 tarball 运行设置时的插件安装流程。仅适用于端到端测试和包验证。普通用户应使用 openclaw plugins install 安装插件。
警告
覆盖会执行你提供源的插件代码。请仅在隔离的状态目录或一次性测试机器中使用。
环境变量
只有同时设置以下两个变量时，覆盖才会生效：
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"
}'覆盖映射是一个 JSON，以插件 ID 为键。值支持：
npm:<registry-spec>：指定 registry 包及精确版本或标签。npm-pack:<path.tgz>：npm pack生成的本地 tarball 路径。
相对路径的 npm-pack: 从当前工作目录解析。
行为说明
当某个设置流程（如 onboard）试图安装一个出现在映射中的插件时，OpenClaw 会使用覆盖源，而不是目录源、内置源或默认 npm 源。这适用于 onboard 和其他使用共享设置时插件安装器的流程。
覆盖仍然强制检查预期的插件 ID。映射到 codex 的 tarball 必须安装一个清单 ID 为 codex 的插件。
覆盖不会继承官方的可信源状态。即使目录条目通常表示 OpenClaw 所有的包，覆盖也被视为操作员提供的测试输入。
工作区 .env 文件不能启用安装覆盖。必须在启动 OpenClaw 的可信 shell、CI 任务或远程测试命令中设置这些变量。
包端到端测试
使用隔离的状态目录，使包安装和安装记录不影响正常的 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/node_modules" -maxdepth 3 -name package.json -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/package-lock.json"对于实时的 provider 端到端测试，在启动测试命令前，从可信 shell 或 CI 密钥中引入真实 API 密钥。不要打印密钥，只报告来源以及密钥是否存在。
常见问题
为什么设置了环境变量但覆盖不生效？
检查两个变量是否都已设置且值为非空。OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES 必须等于 1，OPENCLAW_PLUGIN_INSTALL_OVERRIDES 必须是有效的 JSON 对象，并且键（插件 ID）必须与设置流程中请求的插件 ID 完全匹配。同时，确保这些变量不是在 .env 文件中，而是在启动 OpenClaw 的 shell 或 CI 中直接设置。
如何确认安装的包确实来自覆盖源？
观察控制台日志（如果设置流程有输出）或检查状态目录下 npm/node_modules 中的包路径。如果使用了 npm-pack: 路径，包内容应与 tarball 一致。也可以对比包的 version 字段或 hash 来验证。
覆盖测试后如何清理？
删除用于测试的隔离状态目录（$OPENCLAW_STATE_DIR）即可。如果是在正常状态目录中测试，建议在测试前备份或使用 mktemp -d 创建临时目录，测试完成后直接删除该目录。避免影响生产状态。