包验收
软件包验收作业、候选来源、套件配置、兼容性窗口和调度示例。是发布验证工作流索引的一部分。
软件包验收¶
当问题是“这个可安装的 OpenClaw 软件包能否作为产品正常工作?”时,使用 Package Acceptance。它与常规 CI 不同:常规 CI 验证源代码树,而软件包验收通过用户在安装或更新后使用的同一 Docker E2E 测试框架验证单个 tar 包。
作业¶
resolve_package检出workflow_ref,解析一个软件包候选,写入.artifacts/docker-e2e-package/openclaw-current.tgz,写入.artifacts/docker-e2e-package/package-candidate.json,将两者上传为package-under-test工件,并在 GitHub 步骤摘要中打印来源、工作流引用、软件包引用、版本、SHA-256 和配置。package_integrity下载package-under-test工件,并使用scripts/check-openclaw-package-tarball.mjs强制校验公共软件包 tar 包契约。npm_12_install_sh在 npm 12 下通过公共 Linux 安装器,在隔离的 home/prefix 中安装该确切工件,然后验证 CLI 版本和生命周期完成保护,并强制校验已安装软件包树预算。docker_acceptance调用openclaw-live-and-e2e-checks-reusable.yml,使用解析出的软件包源 SHA(回退到workflow_ref)以及package_artifact_name=package-under-test。可复用工作流下载该工件,校验 tar 包清单,在需要时准备 package-digest Docker 镜像,并针对该软件包运行所选 Docker 通道,而不是打包工作流检出。当某个配置选择多个目标docker_lanes时,可复用工作流只准备一次软件包和共享镜像,然后将这些通道展开为具有唯一工件的并行目标 Docker 作业。package_telegram可选调用NPM Telegram Beta E2E。当telegram_mode不是none时运行,并在软件包验收解析出一个工件时安装相同的package-under-test工件;独立的 Telegram 调度仍可以安装已发布的 npm 规格。summary在软件包解析、完整性、npm 12 安装器验收、Docker 验收或可选 Telegram 通道失败时使工作流失败。所选通道保留其首次失败;调用方不能将失败的测试降级为警告。
已安装软件包树预算¶
scripts/check-openclaw-installed-package-budget.mts 测量通过 npm 安装的软件包树,包括 tar 包检查无法看到的依赖项。它统计根目录和每个目录项,不跟随符号链接,并累加每个常规文件的大小,包括 npm 的隐藏 node_modules/.package-lock.json 文件,因为已发布的更新器也会计算这些字节。硬链接路径单独计数。报告按条目数列出最大的贡献项,并将总计添加到 GitHub 步骤摘要中。
已发布的 2026.9.3–2026.9.8 更新器冻结上限为 50,000 个条目 / 1 GiB。发布预算为 47,500 个条目 / 900 MiB:2,500 个条目的预留(5%)覆盖 npm 版本、依赖提升以及按平台的可选依赖项差异,并且大于常规依赖项升级,因此检查会失败,而每个已发布的更新器仍可以安装该候选。字节数距离上限很远,但会因平台原生预构建而变化更多,因此字节预算保留大约 12% 的预留。
较新的更新器允许 500,000 个条目 / 8 GiB,如果扫描达到这些资源限制,则继续候选激活和发布,并执行目录标识、版本和启动器检查,同时警告完整软件包内容未经验证。这不会改变发布预算或已安装的驱动程序。在 2026.9.8 或更早的 supervisor 版本下,候选准入会拒绝超过 50,000 个条目的树,并给出手动 npm i -g openclaw@latest 命令(在指定时保留请求的版本或标签);它无法绕过旧驱动程序的遍历。
要使用候选 tar 包在本地复现:
tmp="$(mktemp -d)"
npm install -g --prefix "$tmp" ./openclaw.tgz
node scripts/check-openclaw-installed-package-budget.mts "$tmp/lib/node_modules/openclaw"
失败时,通过裁剪最大的依赖项或 dist 块和预压缩资产数量来减少已安装条目;对于字节预算失败,减少大文件。不要提高预算:上限无法在已发布的更新器中更改。
候选来源¶
source=npm仅接受openclaw@extended-stable、openclaw@beta、openclaw@latest,或确切的 OpenClaw 发布版本,例如openclaw@2026.9.5。使用此方式对已发布的 extended-stable、预发布或稳定版本进行验收。source=ref打包受信任的package_ref分支、标签或完整提交 SHA。解析器获取 OpenClaw 分支/标签,验证所选提交可从仓库分支历史或发布标签到达,在分离的工作树中安装依赖项,并使用scripts/package-openclaw-for-docker.mjs打包。source=url下载公共 HTTPS.tgz;package_sha256为必填项。此路径拒绝 URL 凭据、非默认 HTTPS 端口、私有/内部/特殊用途主机名或解析出的 IP,以及超出同一公共安全策略的重定向。source=trusted-url从.github/package-trusted-sources.json中命名的可信来源策略下载 HTTPS.tgz;package_sha256和trusted_source_id为必填项。仅将其用于维护者拥有的企业镜像或需要配置主机、端口、路径前缀、重定向主机或私有网络解析的私有软件包仓库。如果策略声明了 bearer 身份验证,工作流会使用固定的OPENCLAW_TRUSTED_PACKAGE_TOKEN密钥;嵌入在 URL 中的凭据仍会被拒绝。source=artifact从artifact_run_id和artifact_name下载一个.tgz;package_sha256可选,但对于外部共享工件应提供。
保持 workflow_ref 和 package_ref 分离。workflow_ref 是运行测试的可信工作流/测试框架代码。package_ref 是在 source=ref 时被打包的源提交。这使得当前测试框架能够验证较旧的可信源提交,而无需运行旧的工作流逻辑。
套件配置¶
smoke—npm-onboard-channel-agent,gateway-network,config-reloadpackage—npm-onboard-channel-agent,doctor-switch,update-channel-switch,skill-install,update-corrupt-plugin,upgrade-survivor,published-upgrade-survivor,root-managed-vps-upgrade,update-restart-auth,plugins-offline,plugin-updateproduct— 使用实时plugins覆盖替代plugins-offline的package集合,外加mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebuifull— 包含 OpenWebUI 的完整 Docker 发布路径分块custom— 精确的docker_lanes;当suite_profile=custom时必需
package 配置使用离线插件覆盖,因此已发布包的验证不会受实时 ClawHub 可用性的限制。可选的 Telegram 泳道在 NPM Telegram Beta E2E 中复用 package-under-test 工件,同时保留已发布 npm 规范路径用于独立调度。
关于专门的更新和插件测试策略,包括本地命令、Docker 泳道、Package Acceptance 输入、发布默认值和故障分诊,请参阅 测试更新和插件。
发布检查以 source=artifact 调用 Package Acceptance,使用准备好的发布包工件、suite_profile=custom、docker_lanes='doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape' 以及 telegram_mode=mock-openai。这使包迁移、更新、实时 ClawHub 技能安装、过期插件依赖清理、已配置插件安装修复、离线插件、plugin-update 和 Telegram 证明都基于同一个已解析的包 tarball。在发布 beta 后,在 Full Release Validation 或 OpenClaw Release Checks 上设置 release_package_spec,即可针对已发布的 npm 包运行相同矩阵而无需重新构建;仅当 Package Acceptance 需要与发布验证其余部分不同的包时,才设置 package_acceptance_package_spec。跨操作系统发布检查仍覆盖操作系统特定的引导、安装程序和平台行为;包/更新产品验证应从 Package Acceptance 开始。
Upgrade-survivor 断言归属遵循所选目标的发布列车,并在源身份验证后从其不可变包元数据中读取。extended-stable 目标保留其随附的场景运行器、断言和测试夹具;常规目标保持可信场景完整,包括其 serving-turn/post-inference 断言。历史基线不会选择断言归属者。无效的目标版本和不受支持的 extended-stable 修正版本会在 Docker 之前失败。
Docker seed CI 在运行 published-upgrade-survivor 之前,会解析所选源包版本的精确已发布稳定前驱版本。它使用发布基线解析器和所选发布上下文,因此发布 latest 永远不会使第一次升级变成已是当前版本的操作。缺少前驱版本会在 Docker 启动前失败;独立的已是当前版本控制保持不变。
published-upgrade-survivor Docker 泳道为每个场景验证一个已发布包基线。在 Package Acceptance 中,已解析的 package-under-test tarball 始终是候选,published_upgrade_survivor_baseline 选择回退已发布基线,默认为 openclaw@latest;失败泳道重跑命令会保留该基线。当前源发布检查为 legacy-operator-state 设置 published_upgrade_survivor_baselines=supported-lines:npm 当前的 latest、前一个稳定版本、当该标签存在时的 extended-stable,以及文档中记录的最旧受支持基线 2026.8.33。解析器在运行时读取 npm view openclaw versions 和 npm view openclaw dist-tags,在扇出前固定精确版本,并对重叠的发布线去重。常规当前源发布检查保留 base 并添加 legacy-operator-state 和 custom-plugin-siblings;发布浸泡选择 reported-issues,包括这些以及现有的问题形态夹具。同源场景使用 2026.9.4 及之后的基线,并要求来自私有更新金丝雀的实际自定义插件 Doctor 契约执行,以及更新后完整的源文件和插件加载。
在定向 Docker 扇出之前,可信组规划器会在一次性 npm 前缀中安装每个不同的已发布基线,并针对合成隔离状态检查 openclaw --version 以及 openclaw config set gateway.mode local。配置写入会加载 CLI 设置路径,因为版本/帮助和配置读取可以使用快速路径。退出失败的已安装 CLI 会被记录为不可用的已发布基线,其跳过的场景和捕获的错误会出现在作业摘要和 upgrade-baseline-checks-* 工件中。跳过的场景永远不会被计为成功升级。安装错误、检查超时和进程启动失败会导致规划失败。候选安装和升级保留其现有失败门控。
当挂载预发布注册表时,基线包安装和初始手动基线 Gateway 启动会使用已配置的已发布上游。已发布包和候选包可以共享精确版本,但包含不同的字节;仅保留已发布 dist-tags 并不能将它们隔离。在这些基线命令之后,候选安装继续使用已验证的候选注册表,包括其精确版本依赖项。
legacy-operator-state 伴随夹具会在两个注册表阶段中保留其包名称/版本的已发布存档。当候选伴随包具有相同版本时,安装断言要求使用保留的已发布字节。不同版本会选择并验证准备好的候选存档。这使同版本核心更新证明不会模拟 npm 重新发布;测试更改的伴随包字节需要不同的伴随包版本。
扩展发布资格验证要求候选版本的 YYYY.M.PATCH 基础版本至少不低于可信工作流包的基础版本,在此比较中忽略预发布后缀。随后,它会读取用于 operator-state 测试框架的不可变源目录元数据。较旧的源目标以及 extended-stable 上下文或分支保留经过验证的候选相对前驱版本。已发布候选版本保留该前驱版本以及既有的合成场景清单,因为其资格验证路径不会准备 operator-state 测试夹具所需的注册表。
单独的 package_acceptance_package_spec 覆盖会在 Package Acceptance 内部根据覆盖项的实际包版本解析其前驱版本。
在 supported-lines 发布配置中,custom-plugin-siblings 始终使用精确发布的 openclaw@2026.9.4 回归驱动程序。当源候选版本具有相同版本时,这会保留报告的第一跳;base 和 legacy-operator 场景保留其现有基线选择。
子工作流会准备或复用新场景的工件断言所需的预发布插件注册表,因此该场景仅针对符合条件的未发布候选版本运行。已发布重新资格验证保留 base,或者在 soak 中保留所有既有的已报告问题场景,因为其包路径不会准备该注册表。历史资格验证同样仅排除新添加的 operator-state 场景。现有冻结目标兼容性检查和显式场景省略选择加入保持不变;绝不会执行候选源代码来选择此配置。
对于独立的 supported-lines 选择器,组规划器仅针对单独解析的前驱版本运行所有既有的合成场景,并对每个受支持基线运行 legacy-operator-state。它会合并重叠的组并保留所有请求的测试夹具;缺失的前驱版本或移动标签前驱版本会导致规划失败。逗号和空白分隔符以及重复的独立选择器使用解析器的常规标记语法。显式版本列表和混合选择器/版本列表保留完整的笛卡尔基线/场景矩阵,用于刻意的人工证明。选择器来源仅作为内部可复用工作流元数据传递;没有新增手动调度输入。
扩展的已发布升级 survivor 和 update-migration 选择为每个受支持的基线/场景对使用一个作业,每个矩阵最多有 32 个目标 Docker 作业处于活动状态。规划器优先接纳包含 update-restart-auth、plugin-update 和 root-managed-vps-upgrade 的现有组,以便这些较长的更新作业不会排在扩展场景矩阵之后。在每个扩展升级家族内,精确基线队列按最新优先运行,使实测较慢的近期升级排在较旧基线之前。队列内的场景和其他组保留其输入顺序;未解析的基线标签保留调用方顺序。分组共享执行规划器的基线兼容性策略,因此每个受支持场景恰好运行一次,而不会为旧基线创建空分片。每个场景拥有一个新的容器和未更改的 npm 资源限制;包和镜像标识在整个矩阵中保持共享。Update Migration 每周日 03:17 UTC 运行,并支持手动调度。它默认使用 supported-lines,同时包含 plugin-deps-cleanup 和 legacy-operator-state,保留现有清理覆盖,并且不转发任何提供商密钥。每周运行在候选相对前驱版本上保持清理,并在每个受支持基线上验证原生 operator 状态。每个场景 12 分钟的规划预留加上 30 分钟的共享包/镜像准备和控制,在三个不同基线下每周约需 78 个 runner 分钟,四个基线则约需 90 个 runner 分钟;实际计时工件决定观察到的成本。
传递 baselines=all-since-2026.6.1 以进行详尽的历史清理;last-stable-4、release-history 和精确历史版本仍为显式手动选择。本地聚合运行可以通过 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 传递解析后的精确规格,使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 保持单个通道,或设置 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS 以指定场景矩阵。现有场景保留其内置的 openclaw config set 配方和摘要记录。新的 operator-state 场景则使用基线自身的 agent、exec-approvals、cron 和插件 CLI,然后在升级后验证保留的状态和一个 mock-provider 回合。Gateway 检查包括 /healthz、/readyz 和 RPC 状态。有关保留状态和成功升级要求,请参阅 测试更新和插件。
所有受支持基线行都要求成功更新。现有合成 base 和已报告问题测试夹具保留其成功断言,并在候选相对前驱版本上运行一次。该通道不会运行额外的 Doctor 或省略这些测试夹具,以将失败的模式升级变为通过。
当前跨操作系统工具在 Linux、Windows 和 macOS 上,针对 Node 24.21.0 和 Node 26.1.0 支持下限运行打包全新安装和升级检查。由于后续 libuv 文件监视器回归,Windows 打包全新安装在其 Node 24 单元格中保留 Node 24.16.0。两种运行时变体使用相同的已准备候选 tarball。聚焦的 suite_filter 选择两种 Node 变体;Node 26 作业和工件具有不同名称。安装程序和源更新通道保留其现有 Node 24 覆盖。显式选择较旧的 workflow_ref 工具会保留该修订版本的历史矩阵。
Windows 打包和安装程序全新通道还会验证已安装包能否从原始绝对 Windows 路径导入浏览器控制覆盖。OpenAI 跨操作系统 agent-turn 冒烟测试在已设置时默认使用 OPENCLAW_CROSS_OS_OPENAI_MODEL,否则使用 openai/gpt-5.6-luna,因此安装和 gateway 证明使用较低成本的 GPT-5.6 测试层级。
旧版兼容窗口¶
当前升级幸存运行需要已发布的基线为 2026.6.1
或更高版本。历史选择器会过滤掉更早的发布版本;release-history
会选择最近六个受支持的稳定发布版本。精确的六月前基线会被拒绝,即使 dist-tag 解析到其中一个基线也是如此。请使用匹配的历史
workflow_ref 工具来重放旧升级。现有历史回执仍可读。
Package Acceptance 不再放宽对 2026 年六月前候选项的断言。
缺失的清单条目、已发布的本地构建元数据、缺失的服务包装器
支持,以及不完整的更新或插件安装记录持久化都会导致
当前契约失败。当前包验证器还要求新的 tarball 中同时不存在两种 npm lockfile
格式。要重现历史验收
结果,请选择匹配的历史 workflow_ref 工具。
示例¶
# Validate the current beta package with product-level coverage.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@beta \
-f suite_profile=product \
-f telegram_mode=mock-openai
# Validate the published extended-stable package with package coverage.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@extended-stable \
-f suite_profile=package \
-f telegram_mode=mock-openai
# Pack and validate a release branch with the current harness.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=ref \
-f package_ref=release/YYYY.M.PATCH \
-f suite_profile=package \
-f telegram_mode=mock-openai
# Validate a tarball URL. SHA-256 is mandatory for source=url.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=url \
-f package_url=https://example.com/openclaw-current.tgz \
-f package_sha256=<64-char-sha256> \
-f suite_profile=smoke
# Validate a tarball from a named trusted private mirror policy.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=trusted-url \
-f trusted_source_id=enterprise-artifactory \
-f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-current.tgz \
-f package_sha256=<64-char-sha256> \
-f suite_profile=smoke
# Reuse a tarball uploaded by another Actions run.
gh workflow run package-acceptance.yml \
--ref main \
-f workflow_ref=main \
-f source=artifact \
-f artifact_run_id=<run-id> \
-f artifact_name=package-under-test \
-f suite_profile=custom \
-f docker_lanes='install-e2e plugin-update'
调试失败的包验收运行时,请从 resolve_package 摘要开始,以确认包来源、版本和 SHA-256。然后检查 docker_acceptance 子运行及其 Docker 工件:.artifacts/docker-tests/**/summary.json、failures.json、lane 日志、阶段计时和重运行命令。建议重运行失败的包配置文件或确切的 Docker lanes,而不是重运行完整发布验证。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw