OpenClaw 插件安装覆盖Plugin Install Overrides为 E2E 与发包验证重定向 setup-time 安装源【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw插件安装覆盖Install Overrides是 OpenClaw 为维护者提供的一套测试专用机制在仅用于测试的前提下将 onboarding 等 setup-time 流程中的自动插件安装从目录catalog、内置bundled或默认 npm 源重定向到指定的 npm 包或本地npm pack生成的 tarball。本文基于 install-overrides.md 整理其环境变量、行为约束与完整 E2E 操作步骤并结合 CLI 安装文档 说明它与常规openclaw plugins install的边界关系。读完本文你将能在隔离状态目录中用本地打包产物完成插件安装路径的端到端验证并在不污染正式状态的前提下确认包内 manifest 与安装记录。什么时候需要安装覆盖OpenClaw 的插件安装由openclaw plugins install统一承载支持多种来源官方目录openclaw/package、任意 npm 包、clawhub:专用源、npm:显式 npm 源、npm-pack:path.tgz本地 tarball、git:仓库以及本地路径见 CLI 插件命令参考。普通用户完全不需要覆盖机制直接使用openclaw plugins install即可。覆盖机制面向的是以下三类维护者场景对应原文档read_when元数据针对本地打包后的插件测试 onboarding 或 setup 流程在发布前验证插件包的完整性与安装行为将自动安装流程中的插件源替换为测试产物例如用npm pack出来的 tarball 顶替目录或 npm 默认源。因此安装覆盖是 E2E 与发包验证专用工具不是日常安装入口。原文档同时给出明确警告覆盖机制会执行你指定来源中的插件代码因此只能在隔离的状态目录或一次性测试机器上使用切勿在正式环境开启。环境变量与覆盖映射表覆盖机制默认关闭只有同时设置以下两个环境变量才会生效export OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES1 export OPENCLAW_PLUGIN_INSTALL_OVERRIDES{ codex: npm-pack:/tmp/openclaw-codex-2026.5.8.tgz, openclaw-web-search: npm:openclaw/web-search2026.5.8 }其中OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES是总开关任何非 1 的值都视为未开启OPENCLAW_PLUGIN_INSTALL_OVERRIDES是以插件 id 为 key 的 JSON 映射表每个 value 指定该插件在 setup-time 安装时使用的替代来源。支持两种前缀前缀来源说明npm:registry-specnpm 仓库包支持精确版本或 tag例如npm:openclaw/web-search2026.5.8npm-pack:path.tgz本地 tarball由npm pack生成相对路径以当前工作目录为基准解析例如npm-pack:/tmp/openclaw-codex-2026.5.8.tgz这两个前缀与openclaw plugins install支持的来源语法保持一致见 CLI 参考 中的npm:package与npm-pack:path.tgz便于维护者先在命令行验证某个来源可安装再将其固化到覆盖映射中。一个关键限制工作区 dotenv 无法启用覆盖覆盖机制对.env文件做了显式封禁OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES和OPENCLAW_PLUGIN_INSTALL_OVERRIDES都在工作区 dotenv 的屏蔽名单上写入项目.env不会生效。两个变量必须在启动 OpenClaw 的可信 shell、CI 任务或远程测试命令中设置。这一设计把覆盖能力严格限制在维护者可控的测试环境内避免仓库内.env被利用来改变安装来源。行为约束不是“绕过”而是“受控替换”当 setup-time 流程onboarding 及所有复用共享 setup-time 插件安装器的流程安装一个 id 出现在映射表中的插件时OpenClaw 会改用覆盖源而不再使用目录、内置或默认 npm 源。但替换不等于放弃检查原文档明确了三条不可逾越的约束插件 id 仍被强制校验映射到codex的 tarball其安装出来的插件 manifest id 必须是codex。覆盖源与目标 id 不匹配时安装失败杜绝“张冠李戴”。不继承官方可信源身份即使目录中该条目本应是 OpenClaw 官方包一旦走覆盖路径就被视为操作者提供的测试输入不自动获得官方可信源地位。这意味着原有的完整性、兼容性、信任、安装策略与能力同意检查依然生效——这一点与常规安装中“ClawHub 和官方目录是可信源而任意 npm、npm-pack:等新来源需--force确认”的规则见 CLI 文档相互印证。状态隔离是使用前提覆盖会真实执行插件代码并写入安装记录因此必须配合隔离状态目录使用见下文 E2E 流程。发包验证 E2E完整可复现步骤原文档给出了一套完整的包级 E2E 流程。第一步把目标扩展打包成 tarball 并放到临时目录npm pack extensions/codex --pack-destination /tmpnpm pack会生成类似/tmp/openclaw-codex-2026.5.8.tgz的归档。第二步使用隔离状态目录启动本地 onboarding避免安装与安装记录污染正常的 OpenClaw 状态OPENCLAW_STATE_DIR$(mktemp -d) \ OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES1 \ OPENCLAW_PLUGIN_INSTALL_OVERRIDES{codex:npm-pack:/tmp/openclaw-codex-2026.5.8.tgz} \ pnpm openclaw onboard --mode local这条命令的三要素分别是OPENCLAW_STATE_DIR指向全新临时目录mktemp -d自动创建、总开关置 1、覆盖映射把codex指向刚打包的 tarball。执行后onboarding 在安装codex时就会读取该 tarball 而非目录源。第三步在状态目录下验证安装结果确认包确实落地且锁文件记录了依赖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第一条命令用于确认 tarball 解压出的openclaw/codex包出现在项目 node_modules 中第二条命令用于在package-lock.json中核对包名被正确记录。两者都通过后说明该 tarball 能在真实 setup-time 安装路径下完整走通。面向 live provider 的 E2E 注意点如果 E2E 涉及真实服务提供商provider原文档强调从可信 shell 或 CI 密钥中导入真实 API key 后再启动测试命令。同时遵守密钥卫生要求——不要打印 key 本身只报告 key 的来源以及是否存在。这样既能覆盖真实网络路径又不会把密钥泄露进日志。覆盖机制与常规安装的边界小结维度常规安装openclaw plugins install安装覆盖Install Overrides适用人群所有用户插件维护者E2E/发包验证安装源目录 / 内置 / npm / ClawHub / git / 本地路径仅npm:spec与npm-pack:path.tgz启用方式CLI 命令显式指定两个环境变量同时设置插件 id 校验安装目标由用户指定覆盖源必须匹配映射表中的插件 id可信源身份官方目录/ClawHub 受信覆盖一律视为测试输入不继承可信地位dotenv 支持支持常规配置两个变量均在 dotenv 屏蔽名单中安全前提按安装策略执行代码仅限隔离状态目录 / 一次性测试机总结来说Plugin Install Overrides 是 OpenClaw 插件发布流水线中的“最后一道预检”在正式发布前用与真实 onboarding 完全相同的安装路径验证npm pack产物的可安装性与 id 一致性同时通过环境变量开关、dotenv 屏蔽与状态目录隔离把实验风险牢牢限制在测试环境内。维护者只需把本文的环境变量模板与 E2E 命令固化到 CI 脚本中即可获得可复现、可审计的插件发包验证能力。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考