openclaw-pre-release-plugin-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Pre-Release Plugin Testing

OpenClaw插件预发布测试

Use this skill when the user asks for plugin release confidence, plugin lifecycle sweeps, package-artifact plugin proof, or "what else should we test before release?" It complements

openclaw-testing

; use that skill too when choosing the cheapest safe runner or debugging a failing lane.

当用户询问插件发布信心、插件生命周期全面测试、包制品插件验证，或是“发布前还应测试哪些内容？”时，可使用本skill。它是

openclaw-testing

的补充；在选择成本最低的安全运行器或调试失败流程时，也可结合使用该skill。

Goal

目标

Prove the plugin system as a product surface, not just as source tests:

bundled plugin lifecycle: install, inspect, enable, disable, uninstall
package artifact behavior from a clean
```
HOME
```
doctor/fix/config validation and idempotence
config discovery and config round-trip
status/log visibility and diagnostics
gateway startup/bootstrap with plugin metadata snapshots
public SDK compatibility for real external plugins
live-ish provider/channel probes only when safe credentials exist

验证插件系统作为产品层面的可靠性，而非仅局限于源码测试：

捆绑插件生命周期：安装、检查、启用、禁用、卸载
从干净
```
HOME
```
环境验证包制品行为
doctor/fix/配置的验证与幂等性
配置发现与配置往返测试
状态/日志可见性与诊断
网关启动/引导及插件元数据快照
面向真实外部插件的公开SDK兼容性
仅在存在安全凭据时执行类实时的提供商/通道探测

First Checks

初始检查

From the OpenClaw repo root:

bash

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

In Codex worktrees under

.codex/worktrees

node_modules

must be a symlink to the main OpenClaw checkout. Do not run

pnpm install

there. For broad or package-heavy proof, use Blacksmith Testbox or GitHub Actions.

从OpenClaw仓库根目录执行：

bash

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。

Runner Choice

运行器选择

Prefer this order:

GitHub Package Acceptance for installable-package product proof.
ci-build-artifacts-testbox.yml
Testbox when Docker/package lanes need seeded
```
dist
```
,
```
dist-runtime
```
, and package caches.
ci-check-testbox.yml
Testbox for source checks, targeted Vitest, package-boundary checks, or focused Docker lanes.
Local targeted commands only for small format/static/unit probes.

Avoid long package Docker runs from a stale sparse worktree. If Testbox sync reports hundreds of changed files or starts deleting package inputs, stop and warm a fresh box from current

main

, or switch to Package Acceptance.

优先按以下顺序选择：

GitHub包验收测试：用于可安装包的产品验证。
ci-build-artifacts-testbox.yml
Testbox：当Docker/包流程需要预加载
```
dist
```
、
```
dist-runtime
```
和包缓存时使用。
ci-check-testbox.yml
Testbox：用于源码检查、针对性Vitest测试、包边界检查或聚焦式Docker流程。
仅本地针对性命令：用于小型格式/静态/单元探测。

避免从陈旧的稀疏工作树运行耗时较长的包Docker测试。如果Testbox同步报告数百个已更改文件或开始删除包输入，请停止操作，从当前

main

分支重新创建一个新的干净环境，或切换到包验收测试。

Existing Baseline

现有基准测试

Run or verify these before inventing new coverage:

bash

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

For full bundled install/uninstall proof, shard the packaged sweep:

bash

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

Expected current packaged scope: 116 public bundled plugins over shards

0-7

. Private QA plugins are source-mode only unless a package explicitly includes them.

在开发新测试覆盖范围之前，先运行或验证以下测试：

bash

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

如需完整的捆绑插件安装/卸载验证，可拆分打包测试：

bash

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

当前预期的打包范围：116个公开捆绑插件，分为

0-7

分片。私有QA插件仅支持源码模式，除非某个包明确包含它们。

Confidence Matrix

信心矩阵

Use this matrix for pre-release signoff. Record pass/fail, run URL/Testbox ID, package SHA/version, and skipped-live reason.

Surface	Proof	Preferred runner
Package artifact	Package Acceptance `suite_profile=package` or custom lanes	GitHub Actions
Bundled lifecycle	8-shard `test:docker:bundled-plugin-install-uninstall`	Testbox or release Docker
External plugins	`test:docker:plugins` and `plugins-offline`	Testbox/package acceptance
Update no-op	`test:docker:plugin-update`	Testbox/package acceptance
Channel runtime deps	`test:docker:bundled-channel-deps:fast` plus key channels	Testbox/package acceptance
Doctor/fix	seeded bad configs + `doctor --fix --non-interactive`	new Docker/Testbox harness
Config round-trip	`config set/get` , inspect, doctor, reload, diff hash	new Docker/Testbox harness
Gateway bootstrap	clean `HOME` , plugin groups enabled/disabled, status JSON	new Docker/Testbox harness
SDK compatibility	directory, tgz, and `file:` external plugins using SDK subpaths	`test:docker:plugins` plus new smoke
Live-ish	redacted provider/channel probes only for present env	Testbox live lanes

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

测试层面	验证方式	首选运行器
包制品	包验收测试 `suite_profile=package` 或自定义流程	GitHub Actions
捆绑生命周期	8分片的 `test:docker:bundled-plugin-install-uninstall`	Testbox或发布版Docker
外部插件	`test:docker:plugins` 和 `plugins-offline`	Testbox/包验收测试
更新无操作	`test:docker:plugin-update`	Testbox/包验收测试
通道运行时依赖	`test:docker:bundled-channel-deps:fast` 加上关键通道	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实时流程

Package Acceptance Plan

包验收测试计划

Use this when validating a release branch, beta, or candidate package:

bash

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

Use

source=npm -f package_spec=openclaw@beta

for published beta proof. Keep

workflow_ref

as trusted current harness code unless the release process says otherwise.

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

bash

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

保持为可信的当前测试框架代码。

New Testbox Harness Plan

新Testbox测试框架计划

If more certainty is needed, add or run a

plugin-lifecycle-matrix

Docker lane that uses one package tarball and sharded plugin lists. Per plugin:

Start with a clean
```
HOME
```
.
Capture
```
plugins list --json
```
.
```
plugins install <id>
```
.
```
plugins inspect <id> --json
```
.
```
plugins disable <id>
```
, then assert disabled visibility.
```
plugins enable <id>
```
, except config-required plugins without config.
```
plugins registry --refresh
```
.
```
doctor --non-interactive
```
.
```
plugins uninstall <id> --force
```
.
Assert no config entry, allow/deny residue, install record, managed dir, or bundled
```
dist/extensions/...
```
load path remains.
Assert diagnostics contain no
```
level: "error"
```
and output redacts secret-looking values.

Keep

memory-lancedb

special: it is config-required. First assert install does not enable it without embedding config, then run a second configured case.

如需更高的确定性，请添加或运行

plugin-lifecycle-matrix

Docker流程，该流程使用单个包tarball和分片插件列表。针对每个插件：

从干净
```
HOME
```
环境开始。
捕获
```
plugins list --json
```
输出。
执行
```
plugins install <id>
```
。
执行
```
plugins inspect <id> --json
```
。
执行
```
plugins disable <id>
```
，然后验证已禁用状态可见。
执行
```
plugins enable <id>
```
，但不包含未配置的需配置插件。
执行
```
plugins registry --refresh
```
。
执行
```
doctor --non-interactive
```
。
执行
```
plugins uninstall <id> --force
```
。
验证不存在残留的配置条目、允许/拒绝记录、安装记录、管理目录或捆绑的
```
dist/extensions/...
```
加载路径。
验证诊断信息中不包含
```
level: "error"
```
，且输出已脱敏类似密钥的敏感值。

注意

memory-lancedb

的特殊性：它需要配置。首先验证未嵌入配置时安装不会启用它，然后运行第二个已配置的测试用例。

Doctor/Fix Matrix

Doctor/Fix矩阵

Seed bad states and require

doctor --fix --non-interactive

to repair them, then run doctor again and require idempotence:

stale
```
plugins.allow
```
stale
```
plugins.entries
```
stale channel config for missing channel plugin
invalid
```
plugins.entries.<id>.config
```
packaged bundled path in
```
plugins.load.paths
```
legacy
```
plugins.installs
```
disabled channel/plugin config that must not stage runtime deps
root-owned global package tree that must remain unmodified

植入错误状态并要求

doctor --fix --non-interactive

修复，然后再次运行doctor并验证其幂等性：

过期的
```
plugins.allow
```
过期的
```
plugins.entries
```
针对已缺失通道插件的过期通道配置
无效的
```
plugins.entries.<id>.config
```
```
plugins.load.paths
```
中的打包捆绑路径
遗留的
```
plugins.installs
```
已禁用的通道/插件配置（不得加载运行时依赖）
根用户所有的全局包树（必须保持未修改状态）

Gateway Bootstrap Matrix

网关引导矩阵

Start packaged OpenClaw in Docker with clean state:

provider plugins enabled, no credentials: ready with warnings, no crash
channel plugins configured disabled: no runtime deps staged
startup-activation plugins enabled: ready and reflected in status
invalid single plugin config: bad plugin skipped/quarantined, others remain

Assert:

gateway reaches ready
```
openclaw status --json
```
includes plugin diagnostics
```
openclaw plugins inspect --all --json
```
is parseable
package tree is not mutated
logs contain no raw tokens

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

提供商插件已启用，但无凭据：正常启动并显示警告，不崩溃
通道插件已配置为禁用：不加载运行时依赖
启动激活插件已启用：正常启动并在状态中体现
单个插件配置无效：跳过/隔离有问题的插件，其他插件正常运行

验证：

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

Config Round-Trip Representatives

配置往返测试代表插件

Use representative plugin families instead of every plugin for deep config round-trip:

providers:
```
openai
```
,
```
anthropic
```
,
```
mistral
```
,
```
openrouter
```
channels:
```
telegram
```
,
```
discord
```
,
```
slack
```
,
```
whatsapp
```
memory:
```
memory-lancedb
```
feature/runtime:
```
browser
```
,
```
acpx
```
,
```
tokenjuice
```

For each representative:

Write config through CLI when possible.
Read it back through
```
config get
```
or JSON.
Run
```
plugins inspect
```
.
Run
```
doctor --non-interactive
```
.
Trigger gateway config reload if applicable.
Compare config hash before/after no-op commands.

使用代表性插件家族而非所有插件进行深度配置往返测试：

提供商：
```
openai
```
,
```
anthropic
```
,
```
mistral
```
,
```
openrouter
```
通道：
```
telegram
```
,
```
discord
```
,
```
slack
```
,
```
whatsapp
```
内存：
```
memory-lancedb
```
功能/运行时：
```
browser
```
,
```
acpx
```
,
```
tokenjuice
```

针对每个代表性插件：

尽可能通过CLI写入配置。
通过
```
config get
```
或JSON读取配置。
运行
```
plugins inspect
```
。
运行
```
doctor --non-interactive
```
。
如有必要，触发网关配置重新加载。
对比无操作命令前后的配置哈希值。

External SDK Smoke

外部SDK冒烟测试

In a package Docker lane, create tiny external plugins and install them from:

local directory
```
.tgz
```
```
file:
```
npm spec

Cover CJS and ESM shapes, plus at least one plugin importing focused

openclaw/plugin-sdk/*

subpaths. Assert

plugins inspect

sees its tool, gateway method, CLI command, or service.

在包Docker流程中，创建小型外部插件并从以下来源安装：

本地目录
```
.tgz
```
文件
```
file:
```
npm规范

覆盖CJS和ESM格式，至少包含一个导入

openclaw/plugin-sdk/*

子路径的插件。验证

plugins inspect

能识别其工具、网关方法、CLI命令或服务。

Live-Ish Probe Rules

类实时探测规则

Before live-ish work, source allowed env in Testbox and generate a redacted availability matrix: present/missing only, never values.

Only run probes for credentials that exist. Prefer auth/catalog/status probes over sending user-visible messages. If a probe might contact an external user, channel, or workspace, stop and ask the user.

执行类实时工作之前，在Testbox中加载允许的环境变量并生成脱敏的可用性矩阵：仅记录存在/缺失状态，绝不记录具体值。

仅对存在凭据的对象执行探测。优先选择认证/目录/状态探测，而非发送用户可见的消息。如果探测可能联系外部用户、通道或工作区，请停止操作并询问用户。

Reporting

报告

Report in this shape:

text

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:

Say clearly when a failure is Testbox sync/env damage rather than product behavior, and prove that with a clean rerun or current-main comparison.

请按以下格式报告：

text

包/引用:
Testbox ID / 运行URL:
矩阵:
  捆绑生命周期:
  包验收测试:
  Doctor/fix:
  网关引导:
  配置往返测试:
  外部SDK:
  类实时测试:
失败项:
跳过项:
最高价值的待完善点:

明确说明故障是由Testbox同步/环境问题而非产品行为导致的，并通过重新运行干净环境或与当前main分支对比来证明。