本文档列出了 OpenClaw 更新和插件行为的验证清单，确保安装包能正确迁移用户状态、清理遗留数据，并支持从本地目录、git、npm、ClawHub 安装/更新/卸载插件。关键验证命令包括 pnpm release:check（打包前检查）和 pnpm test:docker:plugins（Docker 插件安装测试），插件依赖在托管 npm 根下管理，需要扫描信任后安装。

OpenClaw 更新与插件测试验证清单

这是 OpenClaw 更新和插件验证的专用检查清单。目标是证明安装包能够迁移真实用户状态、通过 doctor 修复遗留旧状态，并能从支持的来源安装、加载、更新和卸载插件。

更广泛的测试运行器地图请参见 测试总览。涉及实时 provider 密钥和网络请求的套件请参见 在线测试。

验证目标

更新和插件测试保护以下合约：

• 包 tarball 完整，包含有效的 dist/postinstall-inventory.json，不依赖仓库解包文件。
• 用户可以从已发布的旧包迁移到候选包，不丢失配置、智能体、会话、工作区、插件允许列表或渠道配置。
• openclaw doctor --fix --non-interactive 拥有遗留清理和修复路径。启动过程不应为陈旧插件状态新增隐藏兼容性迁移。
• 插件安装支持本地目录、git 仓库、npm 包和 ClawHub 注册表路径。
• 插件 npm 依赖安装在托管的 npm 根目录下，安装前扫描信任，卸载时通过 npm 删除，避免提升的依赖残留。
• 插件在无变化时更新应保持稳定：安装记录、解析源、依赖布局和启用状态不变。

本地开发阶段的快速验证

从窄范围开始：

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 运行配置/文档/API 漂移检查、写入包分发清单、执行 npm pack --dry-run、拒绝禁止打包的文件、将 tarball 安装到临时前缀、运行 postinstall 并冒烟测试内置渠道入口点。

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 moving-ref 更新、带提升传递依赖的 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 状态。
• test:docker:update-restart-auth：安装候选包，启动托管 token 认证的 Gateway，取消设置调用者 gateway 认证环境变量用于 openclaw update --yes --json，要求候选更新命令重启 Gateway 后再进行正常探测。
• test:docker:update-migration：这是清理密集型已发布更新测试线。从已配置的 Discord/Telegram 风格用户状态开始，运行基线 doctor 使配置的插件依赖有机会生成，为配置的打包插件植入遗留插件依赖碎片，更新到候选 tarball，并要求更新后 doctor 移除遗留依赖根。

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

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
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

可用场景包括 base、feishu-channel、bootstrap-persona、plugin-deps-cleanup、configured-plugin-installs、stale-source-plugin-shadow、tilde-log-path 和 versioned-runtime-deps。在聚合运行中，OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues 展开为所有已报告问题的场景，包括已配置插件安装迁移。

完整更新迁移故意与完整发布 CI 分开。当发布问题是“从 2026.4.23 起的每个已发布稳定版本能否更新到此候选包并清理插件依赖碎片”时，使用手动 Update Migration 工作流：

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

Package Acceptance 包门禁

Package Acceptance 是 GitHub 本机包门禁。它将一个候选包解析为 package-under-test tarball，记录版本和 SHA-256，然后针对该精确 tarball 运行可复用的 Docker E2E 测试线。工作流框架引用独立于包源引用，因此当前测试逻辑可以验证旧的可信发布。

候选源：

• source=npm：验证 openclaw@beta、openclaw@latest 或精确发布的版本。
• source=ref：使用选定的当前框架打包可信分支、标签或提交。
• source=url：验证带有必需 package_sha256 的 HTTPS tarball。
• source=artifact：重用另一个 Actions 运行上传的 tarball。

完整发布验证默认使用 source=artifact，由解析的发布 SHA 构建。发布后验证，传递 package_acceptance_package_spec=openclaw@YYYY.M.D 使相同的升级矩阵针对已发货的 npm 包。

发布检查调用 Package Acceptance 包含以下测试线集：

doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update

当启用发布浸泡时，还传递：

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15
published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai

这使包迁移、更新频道切换、损坏托管插件容错、陈旧插件依赖清理、离线插件覆盖、插件更新行为和 Telegram 包 QA 保持在同一个解析制品上，而不必让默认发布包门禁遍历每个已发布版本。

last-stable-4 解析为最新的四个稳定 npm 已发布 OpenClaw 版本。发布包门禁固定 2026.4.23 作为第一个插件更新兼容性边界，2026.5.2 作为插件架构变动边界，2026.4.15 作为较旧的 2026.4.1x 已发布更新基线；解析器会去重已存在于最新四个版本中的固定版本。需要穷举已发布更新迁移覆盖时，请在单独的 Update Migration 工作流中使用 all-since-2026.4.23 而不是完整发布 CI。release-history 仍可用于手动更宽样品，当你还需要旧日期锚点时。

当选择多个已发布升级幸存者基线时，可复用的 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_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai

如果发布问题包括 MCP 渠道、cron/子智能体清理、OpenAI 网页搜索或 OpenWebUI，请使用 suite_profile=product。仅当需要完整 Docker 发布路径覆盖时使用 suite_profile=full。

默认发布验证流程

对于发布候选，默认的验证堆栈为：

1. pnpm check:changed 和 pnpm test:changed 用于源码级回归。
2. pnpm release:check 用于包制品完整性。
3. Package Acceptance package 配置或发布检查自定义包测试线用于安装/更新/重启/插件合约。
4. 跨操作系统发布检查用于特定操作系统的安装程序、onboarding 和平台行为。
5. 仅当变更表面触及 provider 或托管服务行为时，才运行在线套件。

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

向后兼容性限制

兼容性宽容度窄且有时间限制：

• 直到 2026.4.25（含 2026.4.25-beta.*）的包，在 Package Acceptance 中可能容忍已发布的包元数据缺口。
• 已发布的 2026.4.26 包可能对已发布的本地构建元数据戳文件发出警告。
• 后续包必须满足现代合约。相同缺口将导致失败而不是警告或跳过。

不要为这些旧形态新增启动迁移。请添加或扩展 doctor 修复，然后通过 upgrade-survivor、published-upgrade-survivor 或 update-restart-auth 证明它（当更新命令拥有重启时）。

新增测试覆盖

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

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

默认保持新的 Docker 夹具封闭。使用本地夹具注册表和伪造包，除非测试的重点是实时注册表行为。

故障排查方法

从制品身份开始：

• Package Acceptance resolve_package 摘要：源、版本、SHA-256 和制品名称。
• Docker 制品：.artifacts/docker-tests/**/summary.json、failures.json、测试线日志和重新运行命令。
• 升级幸存者摘要：.artifacts/upgrade-survivor/summary.json，包含基线版本、候选版本、场景、阶段时序和配方步骤。

优先使用相同的包制品重新运行失败的确切测试线，而不是重新运行整个发布总括。

常见问题

更新或插件测试失败了怎么排查？

先查看 Package Acceptance 的 resolve_package 摘要，确认包源、版本和 SHA-256。然后检查 Docker 制品中的 .artifacts/docker-tests/**/failures.json 和对应测试线日志。对于升级幸存者测试，查看 .artifacts/upgrade-survivor/summary.json 确认阶段时序和配方步骤。优先用相同的包制品重新运行失败的具体测试线。

如何运行 Docker 测试验证插件更新？

使用 pnpm test:docker:plugins 验证插件安装和更新基础行为。如果需要更深入的插件生命周期检验（安装、禁用、启用、升级、降级），运行 pnpm test:docker:plugin-lifecycle-matrix。还可以通过 pnpm test:docker:plugin-update 单独验证不变插件更新时安装记录保持不变。

Package Acceptance 有什么用？

Package Acceptance 是 GitHub Actions 工作流，它将一个候选包解析为 tarball 并针对该精确制品运行一系列 Docker 验证（安装、更新、重启、插件等）。通过它可以确保发布候选包在真实容器环境中通过所有合约检查，而不依赖仓库源代码。