openclaw-pre-release-plugin-testing

OpenClaw 预发布插件测试

当用户询问插件发布的可信度、插件生命周期全面检查、软件包产物插件验证，或“发布前还应该测试什么？”时，请使用此技能。此技能与 openclaw-testing 配合使用；选择成本最低且安全的运行器或调试失败的测试环节时，也请使用该技能。

目标

验证插件系统作为产品功能，而不只是通过源码测试：

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

首要检查

在 OpenClaw 仓库根目录中：

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

在 .codex/worktrees 下的 Codex 工作树中，node_modules 必须是指向主 OpenClaw 检出目录的符号链接。请勿在那里运行 pnpm install。对于大范围或涉及大量软件包的验证，请使用 Blacksmith Testbox 或 GitHub Actions。

运行器选择

优先顺序如下：

1. GitHub Package Acceptance，用于可安装软件包的产品验证。
2. 当 Docker/软件包测试环节需要预置 dist、dist-runtime 和软件包缓存时，使用 ci-build-artifacts-testbox.yml Testbox。
3. 对于源码检查、针对性 Vitest、软件包边界检查或专门的 Docker 测试环节，使用 ci-check-testbox.yml Testbox。
4. 仅对小型格式/静态/单元探测使用本地针对性命令。

避免在过时的稀疏工作树中运行耗时较长的软件包 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
pnpm test:docker:bundled-channel-deps:fast

如需完整验证内置插件的安装/卸载，请将打包测试拆分执行：

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

当前预期的打包范围：116 个公开内置插件，分为 0-7 共 8 个测试分片。除非软件包明确包含私有 QA 插件，否则这些插件仅在源码模式下可用。

可信度矩阵

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

功能面	验证方式	首选运行器
软件包产物	Package Acceptance suite_profile=package 或自定义测试环节	GitHub Actions
内置插件生命周期	8 分片 test:docker:bundled-plugin-install-uninstall	Testbox 或发布 Docker 环境
外部插件	test:docker:plugins 和 plugins-offline	Testbox/package acceptance
更新无操作	test:docker:plugin-update	Testbox/package acceptance
频道运行时依赖	test:docker:bundled-channel-deps:fast 加关键频道	Testbox/package acceptance
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 实时测试环节

Package Acceptance 计划

在验证发布分支、Beta 版或候选软件包时使用：

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 bundled-channel-deps-compat 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。除非发布流程另有说明，否则请将 workflow_ref 保持为可信的当前测试框架代码。

新 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. 断言不存在配置项、允许或拒绝残留项、安装记录、受管目录或 内置的 dist/extensions/... 加载路径。
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 用户拥有的全局软件包目录树，必须保持未修改

网关启动引导矩阵

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

• 提供商插件已启用但无凭据：带警告进入就绪状态，不崩溃
• 频道插件已配置为禁用状态：不暂存运行时依赖
• 启动时激活插件已启用：进入就绪状态，并体现在状态中
• 单个插件配置无效：跳过或隔离错误插件，其他插件仍保留

断言：

• 网关进入就绪状态
• 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. 如适用，触发网关配置重载。
6. 比较无操作命令前后的配置哈希。

外部 SDK 冒烟测试

在软件包 Docker 测试任务中，创建小型外部插件，并从以下来源安装：

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

涵盖 CJS 和 ESM 形态，此外至少包含一个导入特定 openclaw/plugin-sdk/* 子路径的插件。断言 plugins inspect 能识别其工具、 网关方法、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 同步或环境损坏而非产品行为，请明确说明， 并通过在干净环境中重跑或与当前 main 比较来证明。