release-openclaw-plugin-testing

OpenClaw 预发布插件测试

当用户询问插件发布信心、插件生命周期全面检查、软件包制品插件验证，或“发布前还应该测试什么？”时，使用此技能。它可补充 openclaw-testing；选择成本最低且安全的运行器或调试失败的测试通道时，也应使用该技能。

目标

验证插件系统作为产品功能的表现，而不只是源代码测试：

• 内置插件生命周期：安装、检查、启用、禁用、卸载
• 在干净的 HOME 中验证软件包制品行为
• doctor/fix/配置验证及幂等性
• 配置发现与配置往返
• 状态/日志可见性与诊断
• 使用插件元数据快照进行网关启动/引导
• 真实外部插件的公共 SDK 兼容性
• 仅在存在安全凭据时进行近似实时的提供方/频道探测

首要检查

在 OpenClaw 仓库根目录运行：

pnpm docs:list
git status --short --branch
pnpm changed:lanes --json

请遵循 openclaw-testing，了解依赖项归属以及本地或远程验证方式的选择。

运行器选择

优先顺序如下：

1. GitHub Package Acceptance，用于可安装软件包的产品验证。
2. 当前专用 Linux 工作节点，当其具备所需依赖项和能力时，用于可信的源代码/软件包/Docker 验证。
3. ci-build-artifacts-testbox.yml Testbox，当 Docker/软件包测试通道需要预置的 dist、dist-runtime 和软件包缓存时使用。
4. ci-check-testbox.yml Testbox，用于源代码检查、针对性 Vitest、软件包边界检查或聚焦的 Docker 测试通道。
5. 仅在工作站上运行针对性命令，用于小型格式/静态/单元探测。

避免在陈旧的稀疏工作树中运行耗时较长的软件包 Docker 测试。如果 Testbox 同步报告数百个已更改文件，或开始删除软件包输入文件，请停止运行，并基于当前 main 启动一个全新的 box，或改用 Package Acceptance。

现有基线

在设计新覆盖范围之前，先运行或验证以下内容：

OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile
pnpm test:docker:plugins
OPENCLAW_PLUGINS_E2E_CLAWHUB=0 pnpm test:docker:plugins
pnpm test:docker:plugin-update

要完整验证内置插件的安装/卸载，请将打包后的全面检查拆分为多个分片：

OPENCLAW_BUNDLED_PLUGIN_SWEEP_TOTAL=8 \
OPENCLAW_BUNDLED_PLUGIN_SWEEP_INDEX=<0-7> \
pnpm test:docker:bundled-plugin-install-uninstall

此示例将所选软件包的插件清单分配到分片 0-7。除非软件包明确包含私有 QA 插件，否则这些插件仅适用于源代码模式。

信心矩阵

使用此矩阵进行发布前签核。记录通过/失败状态、运行 URL/Testbox ID、软件包 SHA/版本，以及跳过实时测试的原因。

功能面	验证方式	首选运行器
软件包制品	Package Acceptance suite_profile=package 或自定义测试通道	GitHub Actions
内置插件生命周期	分片运行 test:docker:bundled-plugin-install-uninstall	Testbox 或发布 Docker
外部插件	test:docker:plugins 和 plugins-offline	Testbox/软件包验收
更新无操作	test:docker:plugin-update	Testbox/软件包验收
Doctor/fix	预置错误配置 + doctor --fix --non-interactive	新建 Docker/Testbox 测试框架
配置往返	config set/get、检查、doctor、重新加载、差异哈希	新建 Docker/Testbox 测试框架
网关引导	干净的 HOME、启用/禁用插件组、状态 JSON	新建 Docker/Testbox 测试框架
SDK 兼容性	使用 SDK 子路径的目录、tgz 和 file: 外部插件	test:docker:plugins 加新的冒烟测试
近似实时测试	仅在存在相应环境时进行经过脱敏的提供方/频道探测	Testbox 实时测试通道

软件包验收计划

完整发布验证负责使用 Q=C 和确切的发布 tarball 完成最终候选资格验证。请将独立的软件包验收用于诊断或发布后置信度检查，而不要用它替代候选资格验证：

gh workflow run package-acceptance.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f workflow_ref=main \
  -f source=ref \
  -f package_ref=<branch-or-sha> \
  -f suite_profile=custom \
  -f docker_lanes='plugins-offline plugin-update doctor-switch update-channel-switch config-reload mcp-channels npm-onboard-channel-agent' \
  -f telegram_mode=mock-openai

对于已发布的 beta 版验证，请使用 source=npm -f package_spec=openclaw@beta。这些独立的诊断／置信度检查可以使用可信的当前测试框架代码；候选资格验证则必须保留冻结候选版本的测试框架。

对于扩展稳定版的共享发布，必须由已准入候选版本所属的 release-ci/* 测试框架在 Q=C 下完成完整的确切目标完整发布验证，并将可信的 P 准入和发布工具链分开处理。直接由规范分支或 main 生成的产物不符合受保护发布者的要求。软件包验收只是发布后的选择器冒烟测试：

gh workflow run package-acceptance.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@extended-stable \
  -f suite_profile=package \
  -f telegram_mode=mock-openai

记录解析出的版本。仍须验证该标签 all-publishable 清单中的每个软件包和选择器；一次冒烟测试不等于注册表回读。

插件 npm 构件资格验证

对于发布候选版本，完整发布验证负责插件 npm 构件资格验证。请在派发时提供发布选择；all-group 父工作流会在仅构件模式下针对确切的 Release SHA 调用 plugin-npm-release.yml，要求成功回读 tarball，并在 publicationArtifacts.pluginNpm 中记录不可变的聚合描述符。Release Prepare 和发布流程必须采用该确切描述符，而不是重新打包插件。

仅当需要进行针对性诊断，或修复常规发布候选版本之外的特定插件时，才使用独立的可信工作流预检：

release_sha="$(git rev-parse origin/release/2026.7.1)"
gh workflow run plugin-npm-release.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f preflight_only=true \
  -f publish_scope=selected \
  -f plugins=@openclaw/meta-provider \
  -f ref="${release_sha}" \
  -f npm_dist_tag=default

不要传入 release_publish_run_id。必须要求工作流成功完成 verify_plugin_npm_preflight。记录运行 URL、工作流 SHA 和源 SHA。工作流首先会创建用于暂存／回读的构件 plugin-npm-package-source-<source-sha>-<extension-id>，其中包含 npm-pack.json、preflight-manifest.json 和 tarball。随后会上传最终使用方构件 plugin-npm-package-<extension-id>-<version>-<route>-<run-id>-<attempt>，其中包含 tarball 和 plugin-publication-manifest.json。

分别记录最终构件名称和摘要。清单使用 openclaw.plugin-publication-artifact/v1，并记录目标 SHA、软件包清单哈希、发布路由和策略，以及 tarball 哈希和清单。此独立验证仅用于验证；它不授权或暂存发布，也不能替代完整发布验证中绑定清单的描述符。安全和软件包内容边界由构件清单而非解包后的源代码树决定：仅存在于源代码中的测试样例无关紧要。软件包自有、位于随附运行时和技能资源之外的测试与样例路径会导致资格验证失败；随附运行时仍须接受安全扫描。随附的 node_modules 归入依赖证据，而非插件源代码策略。

单独的 trusted_publisher_preflight=true OIDC 检查要求派发标签为受保护的 release-publish/<tooling-sha12>-<epoch>，并在 npm-publish 中运行。实际发布同样需要该工具链标签；直接由人工派发的任务会等待其 npm-release 审批作业完成后才发布。

对于已发布的版本，要求 npm dist.integrity 和 dist.shasum 与已验证的 tarball 匹配。仅当 dist-tag 缺失或可明确证明其版本更旧时，才可修复；更新或无法比较的选择器均为阻断项。

新的 Testbox 测试框架计划

如果需要更高的确定性，可添加或运行 plugin-lifecycle-matrix Docker 通道，该通道使用一个软件包 tarball 和分片插件列表。每个插件：

1. 从干净的 HOME 开始。
2. 捕获 plugins list --json。
3. 执行 plugins install <id>。
4. 执行 plugins inspect <id> --json。
5. 执行 plugins disable <id>，然后断言插件显示为已禁用。
6. 执行 plugins enable <id>；没有配置的必需配置插件除外。
7. 执行 plugins registry --refresh。
8. 执行 doctor --non-interactive。
9. 执行 plugins uninstall <id> --force。
10. 断言插件的 plugins.entries 值恰好为 { enabled: false }， 同时其允许/拒绝列表项、安装记录、受管理目录和捆绑运行时加载路径均已删除。对于历史目标，使用现有框架中按来源区分的卸载预期。
11. 断言诊断信息中不包含 level: "error"，且输出会对看似机密的值进行脱敏。

将 memory-lancedb 视为特殊情况：它需要配置。首先断言在没有嵌入配置时安装不会启用它，然后再运行一个已配置的用例。

Doctor/Fix 矩阵

注入错误状态，并要求 doctor --fix --non-interactive 修复这些状态，然后再次运行 doctor 并要求其保持幂等：

• 过期的 plugins.allow
• 过期的 plugins.entries
• 缺失频道插件对应的陈旧频道配置
• 无效的 plugins.entries.<id>.config
• plugins.load.paths 中打包的捆绑路径
• 旧版 plugins.installs
• 不得暂存运行时依赖的已禁用频道/插件配置
• 必须保持不变的 root 所有全局软件包树

Gateway 启动矩阵

在 Docker 中以干净状态启动打包版 OpenClaw：

• 启用提供商插件但没有凭据：就绪并显示警告，不崩溃
• 已配置但禁用的频道插件：不暂存运行时依赖
• 启用启动时激活的插件：就绪并反映在状态中
• 单个插件配置无效：跳过/隔离有问题的插件，其余插件保持可用

断言：

• gateway 达到就绪状态
• openclaw status --json 包含插件诊断信息
• openclaw plugins inspect --all --json 可正常解析
• 软件包树未被修改
• 日志中不包含原始令牌

配置往返代表性用例

使用具有代表性的插件系列进行深入配置往返测试，而不是测试每个插件：

• 提供商：openai、anthropic、mistral、openrouter
• 频道：telegram、discord、slack、whatsapp
• 记忆：memory-lancedb
• 功能/运行时：browser、acpx、tokenjuice

对于每个代表性用例：

1. 尽可能通过 CLI 写入配置。
2. 通过 config get 或 JSON 读回配置。
3. 运行 plugins inspect。
4. 运行 doctor --non-interactive。
5. 如果适用，触发 gateway 配置重新加载。
6. 比较无操作命令执行前后的配置哈希。

外部 SDK 冒烟测试

在软件包 Docker 通道中创建精简的外部插件，并通过以下方式安装：

• 本地目录
• .tgz
• file: npm 规格

覆盖 CJS 和 ESM 形态，并至少包含一个导入聚焦版 openclaw/plugin-sdk/* 子路径的插件。断言 plugins inspect 能识别其工具、gateway 方法、CLI 命令或服务。

近似实时探测规则

进行近似实时测试前，在 Testbox 中加载允许使用的环境变量，并生成脱敏的可用性矩阵：只标注存在/缺失，绝不显示值。

只对现有凭据运行探测。优先使用身份验证/目录/状态探测，而不是发送用户可见消息。如果探测可能联系外部用户、频道或工作区，请停止并询问用户。

报告

按以下格式报告：

package/ref:
tbx ids / run urls:
matrix:
  bundled lifecycle:
  package acceptance:
  doctor/fix:
  gateway bootstrap:
  config round-trip:
  sdk external:
  live-ish:
failures:
skips:
next highest-value gap:

如果故障源于 Testbox 同步/环境损坏，而非产品行为，请明确说明，并通过干净的重新运行或与当前主分支比较来证明。