跳转至

包验收

软件包验收任务、候选来源、套件配置、兼容性窗口和调度示例。属于 发布验证工作流 索引的一部分。

软件包验收

当问题是“这个可安装的 OpenClaw 软件包作为产品是否可用？”时，使用 Package Acceptance。它与常规 CI 不同：常规 CI 验证源代码树，而软件包验收通过用户在安装或更新后使用的同一 Docker E2E 测试框架验证单个 tarball。

任务

  1. resolve_package 检出 workflow_ref，解析一个软件包候选，写入 .artifacts/docker-e2e-package/openclaw-current.tgz，写入 .artifacts/docker-e2e-package/package-candidate.json，将两者作为 package-under-test 工件上传，并在 GitHub 步骤摘要中打印来源、workflow ref、package ref、版本、SHA-256 和配置。
  2. package_integrity 下载 package-under-test 工件，并使用 scripts/check-openclaw-package-tarball.mjs 强制执行公共软件包 tarball 契约。
  3. npm_12_install_sh 在 npm 12 下通过公共 Linux 安装器，在隔离的 home/prefix 中安装该确切工件，然后验证 CLI 版本和生命周期完成保护。
  4. docker_acceptance 使用解析出的软件包源 SHA（回退到 workflow_ref）和 package_artifact_name=package-under-test 调用 openclaw-live-and-e2e-checks-reusable.yml。可复用工作流会下载该工件，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该软件包运行所选 Docker 通道，而不是打包 workflow 检出。当某个配置选择多个目标 docker_lanes 时，可复用工作流会一次性准备软件包和共享镜像，然后将这些通道展开为具有唯一工件的并行目标 Docker 任务。
  5. package_telegram 可选地调用 NPM Telegram Beta E2E。当 telegram_mode 不是 none 时运行，并在软件包验收解析出一个时安装相同的 package-under-test 工件；独立的 Telegram 调度仍可以安装已发布的 npm spec。
  6. summary 如果软件包解析、完整性、npm 12 安装器验收、Docker 验收或可选 Telegram 通道失败，则使工作流失败。所选通道保留其首次失败；调用方无法将失败的测试降级为警告。

候选来源

  • source=npm 仅接受 openclaw@extended-stable、openclaw@beta、openclaw@latest，或确切的 OpenClaw 发布版本，例如 openclaw@2026.9.5。使用此方式对已发布的 extended-stable、预发布或稳定版进行验收。
  • source=ref 打包受信任的 package_ref 分支、标签或完整 commit SHA。解析器获取 OpenClaw 分支/标签，验证所选 commit 可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 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 secret；URL 内嵌凭据仍会被拒绝。
  • source=artifact 从 artifact_run_id 和 artifact_name 下载一个 .tgz；package_sha256 可选，但对于外部共享工件应提供。

保持 workflow_ref 和 package_ref 分离。workflow_ref 是运行测试的受信任工作流/测试框架代码。package_ref 是在 source=ref 时被打包的源 commit。这使当前测试框架能够验证较旧的受信任源 commit，而无需运行旧的工作流逻辑。

套件配置

  • smoke — npm-onboard-channel-agent、gateway-network、config-reload
  • package — 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-update
  • product — 在 package 集合中用实时 plugins 覆盖替代 plugins-offline，并加上 mcp-channels、cron-mcp-cleanup、openai-web-search-minimal、openwebui
  • full — 包含 OpenWebUI 的完整 Docker 发布路径分块
  • custom — 精确的 docker_lanes；当 suite_profile=custom 时必填

package 配置使用离线插件覆盖，因此已发布软件包验证不会受实时 ClawHub 可用性限制。可选的 Telegram 通道在 NPM Telegram Beta E2E 中复用 package-under-test 工件，并为独立调度保留已发布 npm spec 路径。

对于专门的更新和插件测试策略，包括本地命令、 Docker 通道、软件包验收输入、发布默认值和故障分诊， 请参阅 测试更新和插件。

发布检查使用 source=artifact、准备好的发布软件包工件、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 技能安装、过期插件依赖清理、已配置插件安装修复、离线插件、插件更新和 Telegram 证明都基于同一个已解析的软件包 tarball。在发布 beta 后，在 Full Release Validation 或 OpenClaw Release Checks 上设置 release_package_spec，即可在不重新构建的情况下针对已发布的 npm 软件包运行相同矩阵；仅当软件包验收需要与发布验证其余部分不同的软件包时，才设置 package_acceptance_package_spec。跨操作系统发布检查仍覆盖操作系统特定的入门、安装器和平台行为；软件包/更新产品验证应从软件包验收开始。

升级幸存者断言归属遵循所选目标的发布列车， 在源身份验证之后从其不可变包元数据中读取。 扩展稳定目标保留其随附的场景运行器、断言和 测试夹具；常规目标保持可信场景完整，包括其 服务轮次/推理后断言。 历史基线不选择断言所有者。无效目标 版本和不受支持的扩展稳定修正版本在 Docker 之前失败。

Docker 种子 CI 在运行 published-upgrade-survivor 之前，解析所选源包版本的精确已发布稳定前驱版本。它使用发布基线解析器和所选发布上下文，因此发布 latest 永远不会使第一次升级变成已是当前版本的操作。缺失的前驱版本会在 Docker 启动前失败；独立的已是当前版本控制保持不变。

published-upgrade-survivor Docker 泳道每个场景验证一个已发布包基线。在包验收中，解析出的 package-under-test tarball 始终是候选包，published_upgrade_survivor_baseline 选择回退已发布基线，默认为 openclaw@latest；失败泳道的重跑命令保留该基线。当前源发布检查为 legacy-operator-state 设置 published_upgrade_survivor_baselines=supported-lines：npm 的当前 latest、前一个稳定版本、当该标签存在时的 extended-stable，以及文档中记录的最旧受支持基线 2026.6.34。解析器在运行时读取 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 测试框架的不可变源目录元数据。较旧的源目标和扩展稳定上下文 或分支保留已验证的候选相对前驱版本。已发布候选保留该前驱版本和现有合成 场景清单，因为其资格验证路径不会准备 operator-state 测试夹具所需的注册表。 单独的 package_acceptance_package_spec 覆盖在包验收内部从其覆盖的实际包版本解析其前驱版本。

在 supported-lines 发布配置中，custom-plugin-siblings 始终使用 精确已发布的 openclaw@2026.9.4 回归驱动程序。当源候选具有相同版本时，这会保留 报告的第一跳；base 和 legacy-operator 场景保留其现有基线选择。

子工作流准备或复用新场景工件断言所需的预发布插件注册表，因此该场景仅针对 符合条件的未发布候选运行。已发布重新资格验证保留 base，或者对于浸泡测试保留所有现有 报告问题场景，因为其包路径不会准备 该注册表。历史资格验证同样仅排除新添加的 operator-state 场景。现有冻结目标兼容性检查和 显式场景省略选择加入保持不变；候选源代码 永远不会被执行以选择此配置。

对于独立的 supported-lines 选择器，组规划器仅针对单独解析的 前驱版本运行每个 现有合成场景，并针对每个受支持基线运行 legacy-operator-state。 它合并重叠组并保留每个请求的测试夹具；缺失 或移动标签的前驱版本会使规划失败。逗号和空白分隔符以及 重复的独立选择器使用解析器的常规标记语法。显式版本列表和混合选择器/版本列表保留 完整的笛卡尔基线/场景矩阵，用于有意的手动证明。选择器 来源仅作为内部可复用工作流元数据传递； 没有新的手动调度输入。

已发布升级幸存者和更新迁移选择按基线拆分为最多三个场景的组，每个矩阵中最多有 32 个定向 Docker 作业处于活动状态。分组共享执行规划器的基线兼容性策略，因此每个受支持的场景都恰好运行一次，而不会为旧基线创建空分片。每个场景都拥有全新容器和未更改的 npm 资源限制；包和镜像身份在整个矩阵中保持共享。Update Migration 每周日 03:17 UTC 以及手动触发时运行。它默认使用 supported-lines，并同时包含 plugin-deps-cleanup 和 legacy-operator-state，保留现有清理覆盖，并且不转发任何提供商密钥。每周运行会在相对于候选版本的前驱版本上保留清理，并在每个受支持基线上验证原生 operator 状态。每个场景 12 分钟的计划预留，加上共享包/镜像准备和控制所需的 30 分钟，在三个不同基线时每周约需 78 个 runner 分钟，四个基线时约需 90 个；实际计时工件决定观察到的成本。

传递 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 状态场景改为使用基线自身的 agent、exec-approvals、cron 和 plugin CLI，然后在升级后验证保留的状态和一个模拟提供商回合。Gateway 探针包括 /healthz、/readyz 和 RPC 状态。有关保留状态和成功升级的要求，请参阅 测试更新和插件。

所有受支持的基线行都需要成功更新。现有合成 base 和已报告问题夹具保留其成功断言，并在相对于候选版本的前驱版本上运行一次。该泳道不会额外运行 Doctor，也不会省略这些夹具，从而把失败的 schema 升级变成通过。

当前跨操作系统工具链在 Linux、Windows 和 macOS 上，针对 Node 24.21.0 和 Node 26.1.0 支持下限运行打包全新安装和升级检查。Windows 打包全新安装在其 Node 24 单元格中保留 Node 24.16.0，因为后续 libuv 文件监视器回归。两种运行时变体使用同一份准备好的候选 tarball。一个聚焦的 suite_filter 选择两种 Node 变体；Node 26 作业和工件具有不同名称。安装程序和 source-update 泳道保留现有 Node 24 覆盖。显式选择较旧的 workflow_ref 工具链会保留该修订版本的历史矩阵。

Windows 打包和安装程序全新泳道还会验证已安装的包能否从原始绝对 Windows 路径导入浏览器控制覆盖。OpenAI 跨操作系统 agent 回合冒烟测试在设置时默认使用 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 年六月前候选版本的断言。 缺失的清单条目、随附的本地构建元数据、缺失的 service-wrapper 支持，以及不完整的更新或插件安装记录持久化，都会使当前契约失败。当前包验证器还要求新的 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、泳道日志、阶段计时和重跑命令。优先重跑失败的包配置或精确的 Docker 泳道，而不是重跑完整发布验证。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw