插件安装覆盖（测试用）

概述

插件安装覆盖允许维护者在测试设置时安装流程时，针对特定 npm 包或本地 npm-pack tarball 进行测试。仅用于 E2E 和包验证，普通用户应使用 openclaw plugins install。

核心要点

• 覆盖仅在两个环境变量同时设置时生效
• 覆盖不继承官方可信来源状态，视为运维提供的测试输入
• Workspace .env 文件不能启用安装覆盖，必须在可信 shell/CI 中设置
• 覆盖仍强制检查插件 id，tarball 必须安装 manifest id 匹配的插件

支持的覆盖值格式：

• npm:<registry-spec> — 注册表包和精确版本或 dist-tag
• npm-pack:<path.tgz> — npm pack 生成的本地 tarball（相对路径从 cwd 解析）

配置/使用

启用覆盖：

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

包 E2E 测试（隔离状态目录）：

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/node_modules" -maxdepth 3 -name package.json -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/package-lock.json"

相关页面

• concepts/plugin-manage — 正常插件安装、更新、卸载流程
• concepts/plugin-dependency-resolution — 插件依赖解析机制
• concepts/plugin-building — 插件开发和发布指南