跳转至

更新和插件测试

Checklist for update and plugin validation: prove the installable package can update real user state, repair stale legacy state through doctor, and still install, load, update, and uninstall plugins from every supported source.

For the broader test runner map, see Testing. For live provider keys and network-touching suites, see Testing live.

本页内容

我们保护的内容

  • 包 tarball 完整,具有有效的 dist/postinstall-inventory.json, 并且不依赖于未解包的仓库文件。
  • 用户可以从旧版已发布包迁移到候选包,而不会丢失配置、agents、会话、工作区、插件允许列表或 通道配置。
  • openclaw doctor --fix --non-interactive 负责遗留迁移和修复, 包括真正悬空的插件运行时别名。包 postinstall 负责 包本地依赖残留;两者都会保留其他安装或配置文件可能使用的有效共享运行时根目录。启动时不应为过时的插件状态增加隐藏的兼容性迁移。
  • 插件安装可从本地目录、git 仓库、npm 包以及 ClawHub 注册表路径正常工作。
  • 插件 npm 依赖项按每个插件一个受管理的 npm 项目进行安装, 在信任之前会被扫描,并在插件卸载期间通过 npm uninstall 移除, 以免提升的依赖项残留。
  • 当没有变化时,插件更新是空操作:安装记录、解析后的 来源、已安装的依赖项布局和启用状态保持完整。

开发期间的本地验证

从范围较窄的开始:

pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed

对于插件安装、卸载、依赖项或包清单更改,还要 运行覆盖已编辑接缝的聚焦测试:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

在任何包 Docker 通道使用 tarball 之前,先证明包产物:

pnpm release:check

release:check 会运行生成的配置/文档和插件检查(配置模式、 配置文档基线、插件 SDK 导出和 API 表面预算、插件 版本/清单),写入包 dist 清单,运行 npm pack --dry-run,拒绝禁止的打包文件,将 tarball 安装到 临时前缀中,运行 postinstall,并对捆绑的通道入口点进行冒烟测试。

对于 Plugin SDK 更改,请单独比较确切的提交:

base_sha=$(git merge-base origin/main HEAD)
head_sha=$(git rev-parse HEAD)
pnpm plugin-sdk:api:diff -- --base "$base_sha" --head "$head_sha"

发布 npm 预检会针对先前发布的 dist-tag 使用相同的可读 diff,并在该 发布更改 Plugin SDK API 时打印所需的 8 字符确认摘要。

无头节点自动更新验证

pnpm test:e2e:node-auto-update <built-openclaw.tgz> [new-artifact-directory] 在 Linux 上运行真实的已安装包场景。请在具有 Node、npm 和注册表访问权限的任务专属 Testbox 或 Crabbox 中运行它。它不需要提供商凭据 并且是可选加入的;默认的 pnpm test:e2e 聚合不会运行它。

在测试主机上构建并打包候选版本,然后传入该确切的 tarball:

pnpm build
node scripts/package-openclaw-for-docker.mjs --skip-build \
  --output-dir /tmp/openclaw-node-update-package \
  --output-name openclaw-node-update.tgz
pnpm test:e2e:node-auto-update \
  /tmp/openclaw-node-update-package/openclaw-node-update.tgz \
  /tmp/openclaw-node-update-proof

该验证会启动隔离的 Gateway、配对节点、supervisor 和 fixture-registry 进程。它会验证忙碌工作延迟、空闲激活、保留的配对 和启动选项、激活冷却、所有三个公开退出选项,以及当候选版本格式错误时保留正在工作的节点。一个相同状态的 Gateway/节点 用例确认,在节点激活其私有运行时期间,Gateway 进程、配置和全局安装 保持不变。一个单独的测试单元 针对候选版本运行已发布的 openclaw@2026.9.4 更新器。

一个遗留插件用例会在子进程继续运行时从其命令返回, 然后证明缺失的空闲工作回调会阻止激活,既在 该工作期间,也在子进程完成后。 一个默认插件节点,没有插件限制或节点命令允许列表, 必须在空闲时激活已准备好的更新。

每次运行时,请使用源检出之外的新产物目录,或省略 它以创建新的临时目录。该场景会在那里保留 observations.json 和每个进程的日志,并在完成或失败时停止其子进程。 在停止远程租约之前收集验证结果。该场景证明 Linux 行为;它不建立 Windows 或 macOS 激活覆盖。有关 操作员契约,请参阅 节点自动更新。

Docker 测试通道

Docker 测试通道是产品级验证。它们在 Linux 容器中安装或更新真实 包,并通过 CLI 命令、Gateway 启动、HTTP 检查、RPC 状态和文件系统状态来断言行为。

在迭代期间使用聚焦通道:

pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration

重要测试通道:

  • test:docker:plugins 覆盖插件安装冒烟、本地文件夹安装、本地文件夹更新跳过行为、带有预装依赖的本地文件夹、file: 包安装、带 CLI 执行的 git 安装、git 移动引用更新、带有提升传递依赖的 npm 注册表安装、npm 更新无操作、拒绝格式错误的 npm 包元数据、本地 ClawHub 测试夹具安装和更新无操作、市场更新行为,以及 Claude-bundle 启用/检查。设置 OPENCLAW_PLUGINS_E2E_CLAWHUB=0 可保持 ClawHub 块隔离/离线。
  • test:docker:plugin-lifecycle-matrix 在裸容器中安装候选包,对一个 npm 插件依次执行安装、检查、禁用、启用、显式升级、显式降级,以及在删除插件代码后卸载。它会按阶段记录 RSS 和 CPU 指标。
  • test:docker:plugin-update 验证未更改的已安装插件在 openclaw plugins update 期间不会重新安装或丢失安装元数据。
  • test:docker:upgrade-survivor 在脏的旧用户测试夹具上安装候选 tarball,运行包更新和非交互式 doctor,然后启动回环 Gateway 并检查状态保留。
  • test:docker:published-upgrade-survivor 首先安装最新稳定版,通过预置的 openclaw config set 配方进行配置,将其更新到候选 tarball,运行 doctor,检查遗留清理,启动 Gateway,并检查 /healthz、/readyz 和 RPC 状态。基线配方通过环境变量引用的 API 密钥配置 Anthropic、Google Gemini 和 OpenAI,并保持 OpenAI 作为代理的主要模型。
  • test:docker:update-restart-auth 安装候选包,启动托管 token-auth Gateway,取消设置 openclaw update --yes --json 的调用方 gateway 认证环境变量,并要求候选更新命令在正常检查之前重启 Gateway。
  • test:docker:update-migration 是清理密集的已发布更新通道。它默认安装最新稳定版,从已配置的 Discord/Telegram 风格用户状态开始,注入包本地插件依赖残留和共享运行时哨兵,并更新到候选 tarball。包 postinstall 必须移除包本地残留,同时 update 和 Doctor 保留共享运行时根目录。

将 OPENCLAW_UPGRADE_SURVIVOR_LIVE_MODELS 设置为以空白分隔的模型引用列表,以便在更新后为每个模型运行一次 openclaw agent --local 标记轮次。Anthropic 使用 ANTHROPIC_API_KEY,Google 使用 GEMINI_API_KEY,OpenAI 使用 OPENAI_API_KEY;缺少所选密钥会导致该通道失败。Docker 仅转发所选提供商密钥。每个轮次都有自己的会话和 live-<provider>.json / .err 工件(同一提供商的额外模型使用 -2、-3 等)。summary.json 记录 liveModels.models 条目,包含 model、ok 和 latencyMs。

旧版 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI=1 形式仍会选择 openai/gpt-5.5,或在提供 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI_MODEL 时选择该值。显式模型列表优先于该标志;摘要记录 liveModels.source 和 overridesLiveOpenai。现有的 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI_TIMEOUT_SECONDS 预算(默认 180 秒)分别应用于每个轮次。实时轮次使用配方中配置的 thinking 默认值,以便每个模型可以应用其支持的推理级别。禁止实时提供商的场景保留该限制。

冻结的 extended-stable 候选目标使用其历史 runner,并在 Docker 启动前拒绝两个实时选择变量,退出码为 2。

# Export the three provider keys before invoking the lane.
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.9.5 \
OPENCLAW_UPGRADE_SURVIVOR_LIVE_MODELS="openai/gpt-5.5 anthropic/claude-opus-5 google/gemini-3.1-pro-preview" \
pnpm test:docker:published-upgrade-survivor

base 和 sqlite-volume 的源固定 tarball 运行会在更新前验证候选提交,并在候选检查之前,将已安装的应用程序负载与冻结 tarball 进行比较。这可以区分具有相同版本字符串的不同构建。npm 仍负责依赖具体化;未选择源 SHA 的手动 tarball 运行保留其现有约定。这些通用场景不需要 worker-cell 基线身份工件。更新后,缺失或不可读的 tarball 和已安装负载会在任何候选检查运行之前,以相应的候选身份诊断失败。

有用的已发布升级幸存者变体:

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.6.1 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.7.1-2 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=sqlite-volume \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.8.33 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=legacy-operator-state \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS=openclaw@2026.9.4 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=custom-plugin-siblings \
pnpm test:docker:published-upgrade-survivor

可用场景:base、acpx-openclaw-tools-bridge、feishu-channel、bootstrap-persona、channel-post-core-restore、plugin-deps-cleanup、configured-plugin-installs、custom-plugin-siblings、stale-source-plugin-shadow、tilde-log-path、meeting-transcripts-sqlite、versioned-runtime-deps、cron-scheduled-authority、legacy-operator-state 和 sqlite-volume。在聚合运行中,OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues 会展开 release-soak 测试夹具,但排除昂贵的 sqlite-volume 场景。使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=far-reaching 可包含它。

可选启用的 backup-schedule 场景使用已发布的 openclaw@2026.9.7 CLI 初始化一个 Git 备份仓库,启用其由 Gateway 拥有的 24 小时计划,并记录一次 Git 备份和一次归档备份。已发布的更新器安装源固定的候选 tarball。在非交互式 Doctor 和 Gateway 启动之后,该场景检查原始计划声明和 argv、通过 backup.status 的两个旧账本行、状态备份行、Doctor 错误以及 HTTP 就绪状态。它还要求 storage.locations 保持不存在,并且 Cloudflare 插件保持未激活。此手动/发布场景被排除在聚合别名和每个 PR 的 CI 之外。

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS=openclaw@2026.9.7 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=backup-schedule \
pnpm test:docker:published-upgrade-survivor

custom-plugin-siblings 场景从已发布的 2026.9.4 或更高版本开始,其中启用的自定义内存插件从其运行时入口和 Doctor 配置修复契约中都导入 ../shared/value.mjs。它针对所选候选 tarball 运行已发布的更新器,并要求该契约和 Gateway 插件注册都以私有 canary 状态中的预期 sibling 值执行。仅就绪状态是不够的。它还检查更新前后的实际插件加载、保留的启用状态以及未更改的原始源文件。当前源码 Full Release Validation 将此场景纳入其常规 Package Acceptance 覆盖范围和 release soak。这些默认发布运行将此场景固定到已发布的 2026.9.4 driver,即使源候选仍报告版本 2026.9.4;其他场景保留其现有基线选择。

可选启用的 projects-doctor 和 projects-startup-migration 场景要求精确的已发布 openclaw@2026.9.4 基线和一个冻结的候选 tarball。它们使用隔离状态、手动重启,并且不使用实时 providers 或 registry companion fixtures;它们都不通过 reported-issues 或 far-reaching 运行。它们验证原始已发布 driver 和已安装候选 payload 的字节,包括当它们的版本字符串相等时。使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIO 选择其中一个,并设置 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.9.4。

projects-doctor 保留一个已注册项目和一个已配置工作区,然后两次运行真实的 doctor --lint --only core/doctor/project-clone-shape --json。它检查存储行、schema、sentinels 以及只读快照清理。projects-startup-migration 通过已发布的 owners 使用本地 Git 准备两个独立的 project/worktree 样本。每个样本都有一个已验证的备份,以及通过已发布 Doctor 导入的合成 legacy session JSON/JSONL。更新必须通过候选 Doctor 修复第一个样本的规范工作区。第二个状态保持在该更新的发现范围之外。在启动之前,候选的 Doctor schema owner 在其维护锁下运行,以升级该数据库,同时保留 legacy workspace 字段和精确的 session/transcript 字节。其第一次正常 Gateway 启动必须保留该状态。在干净关闭之后,显式的 doctor --fix --non-interactive 修复其规范工作区;第二次启动必须使修复后的状态保持不变。这些是受支持的 legacy 格式导入,而不是历史运行时生成的会话。两次 Gateway 运行都必须变为就绪状态,并在持久化读回之前报告干净关闭。将 OPENCLAW_UPGRADE_SURVIVOR_STARTUP_BINDINGS 设置为一个经过审查的 JSON 文件,其中包含候选的 commit、agentSchema,以及 operations.prepare/operations.open 的三元组:编译后的 basename、精确导出符号和 SHA-256。快照准备器和 SQLite opener 必须与已安装的候选 payload 匹配;该文件以只读方式挂载。此场景不使用远程仓库或模型轮次。

可选启用的 channel-owner-policy 场景使用相同的固定 openclaw@2026.9.4 已发布 driver 和候选包检查。它在已发布数据库的 machine-state 表中播种一个现有的 operator.channelPolicy JSON 样本,然后运行已安装的更新器。它要求 state schema 19 内容、保留的 role/identity 策略和已配置 owners,以及跨两次候选 Gateway 启动的稳定 configured-owner 引用。该样本是合成的现有状态,而不是声称已发布基线铸造了恢复引用。此测试单元使用隔离状态和手动重启;它不证明更新器拥有的服务重启或旧 reader 降级行为。

legacy-operator-state 场景使用已发布基线自身的 CLI 创建第二个 agent、允许列表 exec 审批,以及两个命令 cron 任务:一个没有显式 agent,另一个由 ops 拥有。它保持 systemAgent 未设置,通过本地 registry 安装一个版本匹配的 npm 插件,并保留一个 workspace skill。它还配置 DuckDuckGo 但没有安装记录:捆绑基线使用其自身的 CLI web-search 设置;较新的基线接收一个已经损坏的升级所保留的配置。本地 registry 提供候选的官方外部 DuckDuckGo 包。在独立 Doctor 或 consent 修复之前,断言要求 npm 安装记录、候选包版本和完整性、plugins list 条目,以及干净的 config validate --json。另一个隔离的 missing-plugin 状态在没有更新或 capability 接受的情况下执行 doctor --fix --non-interactive。一个模拟 OpenAI 服务器在更新前后验证一个真实 agent 轮次,而不使用 provider 凭据。更新之后,lane 检查审批和 legacy-file 退役、有效 cron owners、候选插件 artifact、候选 state schema、幂等更新以及 Gateway 健康状态。断言在独立 Doctor 可能掩盖不完整更新迁移之前运行。

已发布的 companion 包版本在整个测试 fixture 中保留相同的归档字节。如果源候选仍使用已发布 companion 的版本,registry 和安装断言会保留该已发布归档。新的 companion 版本则使用准备好的候选 artifact。两种情况下 npm 完整性保护都保持启用;测试 fixture 从不替换已发布版本的字节以使更新通过。

无主 cron 任务会在添加第二个代理之前创建,因为较新的基线会拒绝含糊的新任务。审批快照会在比较前通过基线 CLI 写回:JSON 时代的读取可能会分配 ID,但不会持久化这些 ID。最终播种状态仍然包含两个代理、两个任务,且没有显式的 systemAgent。

PR/main 门禁使用 OPENCLAW_UPGRADE_SURVIVOR_UPDATE_RESTART_MODE=auto-auth。 在此场景中,基线更新器必须替换其正在运行的受管 Gateway;测试框架会检查进程替换和已配置的认证。Cron 所有者会在该首次更新后立即查询,在任何同意修复可能掩盖不完整迁移之前。默认本地 manual 模式会传递 --no-restart 并启动候选版本进行检查,因此它不能证明由更新器自身执行的重启。两种模式都要求一份干净的 doctor --lint --json 报告。

架构快照会在 schema-before.json 和 schema-after.json 中同时记录已发布的 userVersion 和已应用的 contentVersion。该泳道会将已应用内容与候选包的架构常量进行比较。自 #141109 起,共享状态发布可能因旧更新器的五分钟最终宽限期而滞后于已完成的迁移;如果立即要求已发布编号,会拒绝一次健康的升级。代理架构仍使用其已发布版本。观察者以只读方式打开数据库,并且从不触发迁移或发布。参见 架构版本提升与旧更新器。

前置快照还会记录基线中已配置的代理名册以及代理作用域的旧版样本,包括会话行、转录和轨迹文件、轨迹指针以及技能提示 blob。模型目录和与每个代理无关的产物不属于该观察者的会话迁移范围。在候选检查或代理轮次之前,每个具有现有 SQLite 或旧版会话历史的代理都必须拥有候选代理架构下的存储。观察者会验证导入的会话标识和转录事件、已完成的归档回执以及保留的源字节,以及未更改的提示 blob。没有旧版历史的未使用代理仍可能延迟创建其存储。这些检查遵循 Doctor 会话 SQLite 迁移契约;观察者从不导入文件或打开可写数据库。

每个受支持的基线(包括 2026.9.2)都必须完成更新,并将其数据库迁移到候选架构。类型化的 update-schema-bump-unfenced 拒绝、回滚、未迁移的数据库或不可用的 Gateway 都会使该泳道失败。必需的插件能力同意只能在自动迁移断言通过后使用现有的显式恢复步骤;它从不允许失败的架构修复。

其他场景保留其现有的成功断言。它们故意注入的旧版文件可能会阻止基线在更新前启动;更新器必须在候选检查之前迁移这些测试夹具。该泳道不会预先修复或跳过这些较旧的迁移样本。

auth-profile-v2026-7-2-beta-5 可以在那些聚合别名之外被显式选择。它会导入历史 JSON 凭据夹具,验证当前共享存储中的凭据和认证顺序,并检查已归档的源字节。它不测试在已发布 SQLite 存储中创建的凭据的保留情况。

sqlite-volume 场景默认将已配置的 Matrix、Discord 和 Telegram 插件/通道状态与 4,800 个会话、23,890 个转录事件以及 2,200 个 cron 爬取任务组合在一起。对于暴露插件状态 SDK 的基线,它会使用该已安装的 SDK 创建已发布的共享数据库,并在两个命名空间中写入 512 条永久记录,然后检查每个存储值和时间戳是否都能保留下来。没有该 API 的旧基线会显式报告此部分不适用。它还会播种账户作用域的配对请求和允许列表,以及工作区身份、说明和内存文件。它会在更新后立即、在任何独立 Doctor 修复可能掩盖不完整迁移之前,验证精确的 JSONL 到 SQLite 和 cron 迁移、旧版归档、数据库完整性、账户隔离以及工作区内容。然后,它通过 Gateway RPC 读取抽样对话,运行一次幂等 Doctor 检查,并在 Gateway 重启后重复历史和保留检查。

这是 Docker 内部的一个包更新测试。它不能证明容器镜像替换或后台更新活动;有关这些独立入口点,请参见 更新。必需的插件能力同意仍然是一个显式恢复步骤,并记录在 survivor 摘要中。

从 2026.9.2 到 2026.9.3 的 survivor 转换会验证已安装的更新器。共享状态迁移内容可以是最新的,而已发布的架构版本可能仍保持为 15,直到旧更新器清除其发布宽限期。架构证明会记录这两个值并要求当前内容;它不会等待或强制发布。参见 旧更新器架构处理。

test:docker:release-upgrade-user-journey 单独覆盖显式外部包管理器和全新 Doctor 流程,包括由所有者停止的 Gateway、已验证的备份,以及通过 Gateway 历史保留的基线和新对话。其回执记录 selfUpdatePassed: false 和 not-run 自更新状态;外部安装不是内部更新器结果的证据。代理架构和不受支持的共享状态迁移拒绝仍由 Doctor 所有者测试覆盖。

使用 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_SESSIONS、 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_EVENTS_PER_SESSION 和 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_CRON_JOBS 来扩展测试夹具。在幂等 Doctor 检查之前, 测试框架会统计已持久化的会话、转录事件、cron 任务以及不同的已启用插件根。其预算为 60 秒固定开销,加上每个会话 80 毫秒、每个事件 2 毫秒、每个 cron 任务 20 毫秒以及每个插件根 20 秒,并向上取整到整秒。60 秒下限覆盖小型状态;每单位额度为慢速硬件提供了相对于实测 473 秒 AWS 运行的余量,同时仍会拒绝该夹具上的两倍变慢。计时 Doctor 运行从不决定自己的预算。计数以及计算/有效限制会出现在场景输出和 volume-doctor-budget.json 中;摘要还会记录 timings.idempotenceBudgetSeconds。现有的 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_IDEMPOTENCE_BUDGET_SECONDS 覆盖项仍可用于显式主机校准。独立的 OPENCLAW_UPGRADE_SURVIVOR_COMMAND_TIMEOUT 看门狗仍默认为 900 秒;当将夹具扩展到超过该时长时,请显式增加它。

Update Migration 工作流每周运行,并支持手动触发。其默认 supported-lines 基线集合会在运行时解析 npm dist-tags 和已发布版本:latest、上一个稳定版发布、当该标签存在时的 extended-stable,以及受支持下限 2026.8.33。重复版本只运行一次。它会将每个基线更新到所选的 package_ref 制品(默认为 main),以验证插件清理和旧版 operator 状态。将 baselines 留空即可使用该默认值。若要显式从 2026.6.1 以来的每个已发布稳定版发布进行历史重放,请传入 baselines=all-since-2026.6.1:

gh workflow run update-migration.yml \
  --ref main \
  -f workflow_ref=main \
  -f package_ref=main \
  -f baselines=all-since-2026.6.1 \
  -f scenarios=plugin-deps-cleanup

包验收

包验收是 GitHub 原生的包门禁。它会将一个候选包解析为 package-under-test tarball,记录版本和 SHA-256,然后针对该确切 tarball 运行可复用的 Docker E2E 泳道。工作流 harness ref 与包源 ref 相互独立,因此当前测试逻辑可以验证较早的可信发布。

候选来源:

  • source=npm:验证 openclaw@extended-stable、openclaw@beta、openclaw@latest,或某个精确的已发布版本。
  • source=ref:使用所选的当前 harness 打包一个可信分支、标签或提交。
  • source=url:验证带有必需 package_sha256 的公共 HTTPS tarball。此路径会拒绝 URL 凭据、非默认 HTTPS 端口、私有/内部主机名或 DNS/IP 结果、特殊用途 IP 地址空间以及不安全重定向。
  • source=trusted-url:根据 .github/package-trusted-sources.json 中由维护者拥有的策略,验证带有必需 package_sha256 和 trusted_source_id 的 HTTPS tarball。对于企业/私有镜像,请使用此方式,而不是通过输入级 allow-private 开关削弱 source=url。当策略配置了 Bearer 认证时,使用固定的 OPENCLAW_TRUSTED_PACKAGE_TOKEN secret。
  • source=artifact:复用由另一个 Actions 运行上传的 tarball。

完整发布验证默认使用 source=artifact,基于解析后的发布 SHA 构建。对于发布后证明,请传入 package_acceptance_package_spec=openclaw@YYYY.M.PATCH,使同一升级矩阵改为针对已发布的 npm 包。

发布检查会调用包验收,并传入 package/update/restart/plugin 集合:

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

当启用 release soak 时(对 release_profile=stable 和 full 强制开启),它们还会传入:

published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai

这使包迁移、更新通道切换、损坏的受管插件容错、过期插件依赖清理、离线插件覆盖、插件更新行为以及 Telegram 包 QA 都运行在同一个已解析制品上,而不会让默认发布包门禁遍历每个已发布版本。

当前源发布检查使用相同的 supported-lines 基线展开,并在 Docker fanout 之前一次性解析为精确包。候选源元数据必须暴露新的 harness,且其 YYYY.M.PATCH 基础版本至少不低于可信工作流包的基础版本;预发布后缀在此比较中会被忽略。子流程会准备或复用预发布插件注册表。默认场景集包括 base 和 legacy-operator-state;release soak 运行 reported-issues。

独立的 supported-lines 选择器仅展开 legacy-operator-state。所有现有合成场景仍保留在单独解析的候选相对前驱上,包括每周 plugin-deps-cleanup 证明。接受逗号和空白分隔符以及重复选择器。显式版本列表和混合选择器/版本列表会保留完整笛卡尔矩阵,用于手动证明。

较旧的源目标、extended-stable 资格验证、已发布包以及单独的 npm 覆盖项会保留候选相对前驱和先前的场景集。已发布资格验证不会准备新 operator-state 场景所需的注册表。历史 soak 会保留所有现有 reported-issue fixture;它不会自动启用冻结目标场景省略。有关确切边界,参见发布资格验证。候选项仍然是所选的 package-under-test tarball。每个 PR 的 docker-seed-e2e tripwire 仍仅限于 latest 和 legacy-operator-state,并且也会在每次运行 CI 的规范 main 推送上运行。匹配 **/*.md 和 docs/** 的仅文档推送会跳过 CI;混合文档和代码推送仍会运行 CI。

对于手动历史覆盖,last-stable-4 会选择四个最近的稳定 npm 已发布版本。精确版本、all-since-2026.6.1 和 release-history 仍可通过 published_upgrade_survivor_baselines 使用。当前工具会执行从 2026.6.1 开始的基线。release-history 会选择六个最近的受支持稳定版发布,而不会添加更早的三月或四月锚点。若要重放六月之前的升级,请选择匹配的历史工具;对于旧安装,请先升级到 2026.9.5,再安装最新发布。在重放有界受支持基线集之外的迁移时,使用这些覆盖项。

当选择多个 published-upgrade survivor 基线时,可复用的 Docker 工作流会将每个基线分片为各自的目标 runner 作业。每个基线分片仍会运行所选场景集,但日志和制品保持按基线隔离,且实际耗时受最慢分片限制,而不是一个大型串行作业。

在发布前验证候选项时,手动运行一个包配置:

gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=package \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai

对于已发布的 extended-stable 金丝雀版本,设置 package_spec=openclaw@extended-stable。Package Acceptance 会在 Docker 泳道运行前,将该选择器解析为确切的 tarball。

当发布问题涉及 MCP 通道、cron/subagent 清理、OpenAI 网络搜索或 OpenWebUI 时,使用 suite_profile=product。仅当需要完整的 Docker 发布路径覆盖时,才使用 suite_profile=full。

发布默认

对于发布候选版本,默认验证栈是:

  1. pnpm check:changed 和 pnpm test:changed,用于源码级回归。
  2. pnpm release:check,用于包工件完整性。
  3. Package Acceptance package 配置文件,或 release-check 自定义包泳道,用于安装/更新/重启/插件契约。
  4. 跨操作系统发布检查,用于操作系统特定的安装程序、引导流程和平台行为。
  5. 仅当变更面触及提供商或托管服务行为时,才运行实时套件。

在维护者机器上,除非明确进行本地验证,否则广泛门禁和 Docker/包产品验证应在 Testbox 中运行。

旧版兼容性

Package Acceptance 应用当前元数据和持久化契约,不包含已退役的 2026 年 6 月之前的警告或跳过路径。要复现这些历史候选版本的验收,需要使用它们历史的 workflow_ref 工具。

对于保留的升级契约,将迁移保留在 Doctor 中,并在更新命令拥有重启时,使用 upgrade-survivor、published-upgrade-survivor 或 update-restart-auth 证明变更。2026 年 6 月之前的任务和工作流 sidecar 导入已退役;请使用中间升级流程来保留这些记录。

添加覆盖

当更改更新或插件行为时,在能够因正确原因失败的最底层添加覆盖:

  • 纯路径或元数据逻辑:在源码旁添加单元测试。
  • 包清单或打包文件行为:package-dist-inventory 或 tarball 检查器测试。
  • CLI 安装/更新行为:Docker 泳道断言或 fixture。
  • 已发布版本的迁移行为:published-upgrade-survivor 场景。
  • 由更新拥有的重启行为:update-restart-auth。
  • 注册表/包源行为:test:docker:plugins fixture 或 ClawHub fixture 服务器。
  • 依赖布局或清理行为:同时断言运行时执行和文件系统边界。npm 依赖项可能会被提升到插件管理的 npm 项目中,因此测试应证明该项目被扫描/清理,而不是假设只有插件包本地的 node_modules 树。

默认保持新的 Docker fixture 自包含。除非测试重点是实时注册表行为,否则使用本地 fixture 注册表和假包。

故障分诊

从工件身份开始:

  • Package Acceptance resolve_package 摘要:源、版本、SHA-256 和工件名称。
  • Docker 工件:.artifacts/docker-tests/**/summary.json、failures.json、泳道日志和重跑命令。
  • 升级幸存者摘要:.artifacts/upgrade-survivor/summary.json,包括基线版本、候选版本、场景、阶段计时和配置配方覆盖。

legacy-operator-state 幸存者会通过移动标签(latest、beta 或 alpha)安装匹配的已发布 companion。如果 npm 确认确切的 companion 版本从未发布,则该行在 baselineCompanion 中将该 companion 记录为不可用,并继续剩余的 operator-state 和外部插件迁移检查。注册表错误仍会导致 fixture 设置失败。尚未开始的更新报告 unknown 结果;失败的更新尝试报告 failed,独立于后续场景断言。

故障捕获会在私有诊断快照中保留最新的会话 SQLite 迁移清单和 Doctor 问题报告,受有界大小限制约束。已发布的诊断包含问题直方图和捕获遗漏,而不是原始会话详情。在移除测试主机之前收集私有工件。容器拥有的观察目录可能需要在该隔离主机上使用 sudo tar;请保持其权限完整。通过远程包装器收集时,使用不同的成功/失败下载目标。成功下载不会改变幸存者退出码或 summary.status。

优先使用相同的包工件重跑失败的确切泳道,而不是重跑整个发布伞。

  • 测试 - 测试参考索引,每个读者任务一页
  • 测试 - 完整测试套件:测试套件、实时泳道和 Docker 运行器
  • 发布策略 - 此检查清单所门禁的发布流程

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