openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 21:00:55 +00:00
parent 872dad802b
commit 8b978d8a4c
4 changed files with 176 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/zh-CN/cli/update.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你想安全地更新源代码检出副本
- 你正在调试 `openclaw update` 的输出或选项
- 你需要了解 `--update` 简写行为
summary: '`openclaw update` 的 CLI 参考（相对安全的源码更新 + Gateway 网关自动重启）'
- 你想安全地更新源码检出副本
- 你正在调试 `openclaw update` 输出或选项
- 你需要了解 `--update` 的简写行为
summary: '`openclaw update` 的 CLI 参考（较安全的源更新 + Gateway 网关自动重启）'
title: 更新
x-i18n:
generated_at: "2026-05-03T20:54:25Z"
generated_at: "2026-05-04T20:59:52Z"
model: gpt-5.5
provider: openai
source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
source_path: cli/update.md
workflow: 16
---
@ -18,8 +18,7 @@ x-i18n:
安全更新 OpenClaw，并在 stable/beta/dev 渠道之间切换。
如果你通过 **npm/pnpm/bun** 安装（全局安装，没有 git 元数据），
更新会通过 [更新](/zh-CN/install/updating) 中的包管理器流程完成。
如果你是通过 **npm/pnpm/bun** 安装的（全局安装，没有 git 元数据），更新会通过 [更新](/zh-CN/install/updating) 中的包管理器流程进行。
## 用法
@ -40,16 +39,15 @@ openclaw --update
## 选项
- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。会重启 Gateway 网关的包管理器更新会先验证重启后的服务报告预期的更新版本，然后命令才会成功。
- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；会持久化到配置中）。
- `--tag <dist-tag|version|spec>`：仅为本次更新覆盖包目标。对于包安装，`main` 会映射到 `github:openclaw/openclaw#main`。
- `--dry-run`：预览计划的更新操作（channel/tag/target/restart 流程），不会写入配置、安装、同步插件或重启。
- `--json`：打印机器可读的 `UpdateRunResult` JSON，包括在更新后插件同步期间检测到 npm 插件构件漂移时的
`postUpdate.plugins.integrityDrifts`。
- `--timeout <seconds>`：每个步骤的超时时间（默认 1800s）。
- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。会重启 Gateway 网关的包管理器更新会先验证重启后的服务报告预期的已更新版本，然后命令才会成功。
- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；持久化到配置中）。
- `--tag <dist-tag|version|spec>`：仅为本次更新覆盖包目标。对于包安装，`main` 映射到 `github:openclaw/openclaw#main`。
- `--dry-run`：预览计划的更新操作（渠道/标签/目标/重启流程），不写入配置、不安装、不同步插件，也不重启。
- `--json`：打印机器可读的 `UpdateRunResult` JSON，包括在更新后插件同步期间检测到 npm 插件构件漂移时的 `postUpdate.plugins.integrityDrifts`。
- `--timeout <seconds>`：每个步骤的超时时间（默认是 1800 秒）。
- `--yes`：跳过确认提示（例如降级确认）。
`openclaw update` 没有 `--verbose` 标志。使用 `--dry-run` 预览计划的 channel/tag/install/restart 操作，使用 `--json` 获取机器可读结果；如果你只需要渠道和可用性详情，请使用 `openclaw update status --json`。如果你在调试更新前后的 Gateway 网关日志，控制台详细程度和文件日志级别是分开的：Gateway 网关 `--verbose` 会影响终端/WebSocket 输出，而文件日志需要在配置中设置 `logging.level: "debug"` 或 `"trace"`。参见 [Gateway 网关日志](/zh-CN/gateway/logging)。
`openclaw update` 没有 `--verbose` 标志。使用 `--dry-run` 预览计划的渠道/标签/安装/重启操作，使用 `--json` 获取机器可读结果；当你只需要渠道和可用性详情时，使用 `openclaw update status --json`。如果你在调试更新期间的 Gateway 网关日志，控制台详细程度和文件日志级别是分开的：Gateway 网关 `--verbose` 会影响终端/WebSocket 输出，而文件日志需要在配置中设置 `logging.level: "debug"` 或 `"trace"`。参见 [Gateway 网关日志](/zh-CN/gateway/logging)。
<Warning>
降级需要确认，因为旧版本可能会破坏配置。
@ -57,7 +55,7 @@ openclaw --update
## `update status`
显示当前更新渠道 + git tag/branch/SHA（针对源码 checkout），以及更新可用性。
显示当前更新渠道 + git 标签/分支/SHA（针对源码检出），以及更新可用性。
```bash
openclaw update status
@ -68,12 +66,11 @@ openclaw update status --timeout 10
选项：
- `--json`：打印机器可读的状态 JSON。
- `--timeout <seconds>`：检查超时时间（默认 3s）。
- `--timeout <seconds>`：检查超时时间（默认是 3 秒）。
## `update wizard`
交互式流程，用于选择更新渠道，并确认更新后是否重启 Gateway 网关
（默认会重启）。如果你选择 `dev` 但没有 git checkout，它会询问是否创建一个。
用于选择更新渠道并确认更新后是否重启 Gateway 网关的交互式流程（默认会重启）。如果你在没有 git 检出的情况下选择 `dev`，它会提示创建一个检出。
选项：
@ -83,79 +80,77 @@ openclaw update status --timeout 10
当你显式切换渠道（`--channel ...`）时，OpenClaw 也会保持安装方式一致：
- `dev` → 确保存在 git checkout（默认：`~/openclaw`，可用 `OPENCLAW_GIT_DIR` 覆盖），
更新它，并从该 checkout 安装全局 CLI。
- `dev` → 确保存在 git 检出（默认：`~/openclaw`，可用 `OPENCLAW_GIT_DIR` 覆盖），更新它，并从该检出安装全局 CLI。
- `stable` → 使用 `latest` 从 npm 安装。
- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 缺失或早于当前稳定版本时，会回退到 `latest`。
- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 缺失或比当前稳定版本更旧时，会回退到 `latest`。
Gateway 网关核心自动更新器（通过配置启用时）会在实时 Gateway 网关请求处理器之外启动 CLI 更新路径。控制平面 `update.run` 包管理器更新会在包替换后强制执行非延迟、无冷却的更新重启，因为旧 Gateway 网关进程可能仍有内存中的 chunk 指向新包已删除的文件。
Gateway 网关核心自动更新器（通过配置启用时）会在实时 Gateway 网关请求处理器之外启动 CLI 更新路径。控制平面的 `update.run` 包管理器更新会在包替换后强制执行一次非延迟、无冷却的更新重启，因为旧 Gateway 网关进程内存中可能仍有指向新包已移除文件的分块。
对于包管理器安装，`openclaw update` 会在调用包管理器前解析目标包版本。npm 全局安装使用分阶段安装：OpenClaw 会把新包安装到临时 npm prefix，验证其中打包的 `dist` inventory，然后把这棵干净的包树替换到真实全局 prefix。如果验证失败，更新后的 Doctor、插件同步和重启工作不会从可疑的包树运行。即使已安装版本已经匹配目标，命令也会刷新全局包安装，然后运行插件同步、核心命令补全刷新和重启工作。这会让打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，同时把完整的插件命令补全重建留给显式的 `openclaw completion --write-state` 运行。
对于包管理器安装，`openclaw update` 会在调用包管理器之前解析目标包版本。npm 全局安装使用分阶段安装：OpenClaw 会把新包安装到临时 npm 前缀中，在那里验证打包的 `dist` 清单，然后将这个干净的包树替换到真正的全局前缀中。如果验证失败，更新后 Doctor、插件同步和重启工作都不会从可疑的包树运行。即使已安装版本已经匹配目标版本，该命令也会刷新全局包安装，然后运行插件同步、核心命令补全刷新以及重启工作。这会让打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，同时把完整插件命令补全重建留给显式的 `openclaw completion --write-state` 运行。
当本地托管的 Gateway 网关服务已安装且启用了重启时，包管理器更新会先停止正在运行的服务，再替换包树，然后从更新后的安装刷新服务元数据、重启服务，并在报告成功前验证重启后的 Gateway 网关报告预期版本。在 macOS 上，更新后检查还会验证 LaunchAgent 已为当前 profile 加载/运行，并且配置的 loopback 端口健康。如果 plist 已安装但 launchd 没有监管它，OpenClaw 会自动重新 bootstrap LaunchAgent，然后重新运行健康/版本/渠道就绪检查。全新的 bootstrap 会直接加载 RunAtLoad job，因此更新恢复不会立即对新生成的 Gateway 网关执行 `kickstart -k`。如果 Gateway 网关仍然无法变为健康状态，命令会以非零状态退出，并打印重启日志路径，以及明确的重启、重新安装和包回滚说明。使用 `--no-restart` 时，
包替换仍会运行，但托管服务不会停止或重启，因此正在运行的 Gateway 网关可能会继续使用旧代码，直到你手动重启它。
当本地托管的 Gateway 网关服务已安装且启用重启时，包管理器更新会先停止正在运行的服务，然后替换包树，再从更新后的安装刷新服务元数据，重启服务，并在报告成功前验证重启后的 Gateway 网关报告预期版本。在 macOS 上，更新后检查还会验证活动配置文件的 LaunchAgent 已加载/正在运行，并且配置的 loopback 端口健康。如果 plist 已安装但 launchd 没有监管它，OpenClaw 会自动重新 bootstrap LaunchAgent，然后重新运行健康/版本/渠道就绪检查。全新 bootstrap 会直接加载 RunAtLoad 作业，因此更新恢复不会立即对新生成的 Gateway 网关执行 `kickstart -k`。如果 Gateway 网关仍未变为健康，命令会以非零状态退出，并打印重启日志路径以及明确的重启、重装和包回滚说明。使用 `--no-restart` 时，包替换仍会运行，但托管服务不会被停止或重启，因此正在运行的 Gateway 网关可能会继续使用旧代码，直到你手动重启它。
## Git checkout 流程
## Git 检出流程
### 渠道选择
- `stable`：checkout 最新的非 beta tag，然后构建并运行 Doctor。
- `beta`：优先使用最新的 `-beta` tag，但当 beta 缺失或更旧时回退到最新的稳定 tag。
- `dev`：checkout `main`，然后 fetch 并 rebase。
- `stable`：检出最新的非 beta 标签，然后构建并运行 Doctor。
- `beta`：优先使用最新的 `-beta` 标签，但当 beta 缺失或更旧时，回退到最新稳定标签。
- `dev`：检出 `main`，然后 fetch 并 rebase。
### 更新步骤
<Steps>
<Step title="验证干净的工作树">
<Step title="验证干净工作树">
要求没有未提交的更改。
</Step>
<Step title="切换渠道">
切换到所选渠道（tag 或 branch）。
切换到选定渠道（标签或分支）。
</Step>
<Step title="Fetch upstream">
仅 dev。
<Step title="拉取上游">
仅限 dev。
</Step>
<Step title="预检构建（仅 dev）">
在临时 worktree 中运行 lint 和 TypeScript 构建。如果 tip 失败，会向前回退最多 10 个 commit，寻找最新的干净构建。
在临时工作树中运行 lint 和 TypeScript 构建。如果顶端提交失败，会向前回退最多 10 个提交，以找到最新的干净构建。
</Step>
<Step title="Rebase">
Rebase 到所选 commit（仅 dev）。
Rebase 到选定提交（仅 dev）。
</Step>
<Step title="安装依赖">
使用仓库包管理器。对于 pnpm checkout，更新器会按需 bootstrap `pnpm`（先通过 `corepack`，然后回退到临时的 `npm install pnpm@10`），而不是在 pnpm workspace 中运行 `npm run build`。
使用仓库包管理器。对于 pnpm 检出，更新器会按需 bootstrap `pnpm`（先通过 `corepack`，然后回退到临时 `npm install pnpm@10`），而不是在 pnpm 工作区内运行 `npm run build`。
</Step>
<Step title="构建 Control UI">
构建 Gateway 网关和 Control UI。
</Step>
<Step title="运行 Doctor">
`openclaw doctor` 会作为最终安全更新检查运行。
`openclaw doctor` 会作为最终的安全更新检查运行。
</Step>
<Step title="同步插件">
将插件同步到当前渠道。Dev 使用内置插件；stable 和 beta 使用 npm。更新被跟踪的插件安装。
将插件同步到当前渠道。Dev 使用内置插件；stable 和 beta 使用 npm。会更新被跟踪的插件安装。
</Step>
</Steps>
在 beta 更新渠道上，跟随默认/latest 线的已跟踪 npm 和 ClawHub 插件安装会先尝试插件 `@beta` 版本。如果插件没有 beta 版本，OpenClaw 会回退到记录的默认/latest spec。精确版本和显式 tag 不会被改写。
在 beta 更新渠道上，遵循默认/latest 线的已跟踪 npm 和 ClawHub 插件安装会先尝试插件 `@beta` 版本。如果插件没有 beta 版本，OpenClaw 会回退到记录的默认/latest spec。对于 npm 插件，当 beta 包存在但安装验证失败时，OpenClaw 也会回退。精确版本和显式标签不会被重写。
<Warning>
如果精确固定的 npm 插件更新解析到的构件完整性与存储的安装记录不同，`openclaw update` 会中止该插件构件更新，而不是安装它。只有在确认你信任新构件后，才应显式重新安装或更新该插件。
如果精确固定的 npm 插件更新解析到的构件与存储的安装记录完整性不同，`openclaw update` 会中止该插件构件更新，而不是安装它。只有在验证你信任新构件后，才显式重新安装或更新该插件。
</Warning>
<Note>
更新后插件同步失败会使更新结果失败，并停止后续重启工作。修复插件安装或更新错误后，重新运行 `openclaw update`。
更新后插件同步失败会使更新结果失败，并停止后续重启工作。修复插件安装或更新错误，然后重新运行 `openclaw update`。
更新后的 Gateway 网关启动时，插件加载仅做验证：启动不会运行包管理器，也不会修改依赖树。包管理器 `update.run` 重启会在包树替换后绕过正常的空闲延迟和重启冷却，因此旧进程无法继续懒加载已删除的 chunk。
更新后的 Gateway 网关启动时，插件加载仅做验证：启动不会运行包管理器，也不会修改依赖树。包管理器 `update.run` 重启会在包树已替换后绕过正常的空闲延迟和重启冷却，因此旧进程不能继续惰性加载已移除的分块。
如果 pnpm bootstrap 仍然失败，更新器会提前停止并给出特定于包管理器的错误，而不是尝试在 checkout 中运行 `npm run build`。
如果 pnpm bootstrap 仍然失败，更新器会提前停止并给出包管理器特定错误，而不是尝试在检出内运行 `npm run build`。
</Note>
## `--update` 简写
`openclaw --update` 会改写为 `openclaw update`（适用于 shell 和 launcher scripts）。
`openclaw --update` 会重写为 `openclaw update`（对 shell 和启动器脚本有用）。
## 相关
- `openclaw doctor`（在 git checkout 上会提示先运行 update）
- `openclaw doctor`（在 git 检出上会先提议运行更新）
- [开发渠道](/zh-CN/install/development-channels)
- [更新](/zh-CN/install/updating)
- [CLI 参考](/zh-CN/cli)

120
docs/zh-CN/help/testing-updates-plugins.md
View File

@ -1,34 +1,34 @@
---
read_when:
- 更改 OpenClaw 的更新、Doctor、软件包验收或插件安装行为
- 更改 OpenClaw 更新、Doctor、软件包验收或插件安装行为
- 准备或批准发布候选版本
- 调试软件包更新、插件依赖清理或插件安装回归问题
- 调试包更新、插件依赖清理或插件安装回归问题
sidebarTitle: Update and plugin tests
summary: OpenClaw 如何验证更新路径、包迁移以及插件安装/更新行为
title: 更新和插件测试
x-i18n:
generated_at: "2026-05-03T08:22:52Z"
generated_at: "2026-05-04T20:59:52Z"
model: gpt-5.5
provider: openai
source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
source_path: help/testing-updates-plugins.md
workflow: 16
---
这是用于更新和插件验证的专用检查清单。目标很简单：证明可安装的软件包能够更新真实用户状态，通过 `doctor` 修复陈旧的旧版状态，并且仍然可以从受支持的来源安装、加载、更新和卸载插件。
这是更新和插件验证的专用检查清单。目标很简单：证明可安装包能够更新真实用户状态，通过 `doctor` 修复过时的旧版状态，并且仍然能从受支持来源安装、加载、更新和卸载插件。
更广泛的测试运行器映射见 [测试](/zh-CN/help/testing)。实时提供商密钥和会触达网络的套件见 [实时测试](/zh-CN/help/testing-live)。
如需更广泛的测试运行器映射，请参阅[测试](/zh-CN/help/testing)。如需实时提供商密钥和会触达网络的套件，请参阅[实时测试](/zh-CN/help/testing-live)。
## 我们保护什么
更新和插件测试保护这些契约：
- 软件包 tarball 是完整的，具有有效的 `dist/postinstall-inventory.json`，并且不依赖未打包的仓库文件。
- 用户可以从较旧的已发布软件包迁移到候选软件包，而不会丢失配置、智能体、会话、工作区、插件 allowlist 或渠道配置。
- `openclaw doctor --fix --non-interactive` 负责旧版清理和修复路径。启动过程不应为陈旧的插件状态增长隐藏的兼容性迁移。
- 插件可从本地目录、git 仓库、npm 软件包和 ClawHub 注册表路径安装。
- 插件 npm 依赖会安装在托管 npm 根目录中，在信任前被扫描，并在卸载期间通过 npm 移除，避免提升的依赖残留。
- 当没有任何变更时，插件更新应保持稳定：安装记录、解析后的来源、已安装依赖布局和启用状态都保持不变。
- 包 tarball 完整，包含有效的 `dist/postinstall-inventory.json`，并且不依赖未打包的仓库文件。
- 用户可以从较旧的已发布包迁移到候选包，而不会丢失配置、智能体、会话、工作区、插件允许列表或渠道配置。
- `openclaw doctor --fix --non-interactive` 负责旧版清理和修复路径。启动过程不应为过时插件状态增加隐藏的兼容性迁移。
- 插件安装可从本地目录、git 仓库、npm 包和 ClawHub 注册表路径正常工作。
- 插件 npm 依赖安装在受管理的 npm 根目录中，在信任前会被扫描，并在卸载期间通过 npm 移除，因此提升安装的依赖不会残留。
- 当没有任何变化时，插件更新保持稳定：安装记录、解析后的来源、已安装依赖布局和启用状态都保持完整。
## 开发期间的本地证明
@ -40,25 +40,25 @@ pnpm check:changed
pnpm test:changed
```
对于插件安装、卸载、依赖或软件包清单变更，还要运行覆盖已编辑接缝的聚焦测试：
对于插件安装、卸载、依赖或包清单变更，还要运行覆盖已编辑边界的聚焦测试：
```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
```
在任何软件包 Docker lane 使用 tarball 之前，先证明软件包构件：
在任何包 Docker 通道消费 tarball 之前，先证明包构件：
```bash
pnpm release:check
```
`release:check` 会运行配置/文档/API 漂移检查，写入软件包 dist 清单，运行 `npm pack --dry-run`，拒绝禁止打包的文件，将 tarball 安装到临时前缀中，运行 postinstall，并对内置渠道入口点进行 smoke 测试。
`release:check` 会运行配置/文档/API 漂移检查，写入包 dist 清单，运行 `npm pack --dry-run`，拒绝被禁止打包的文件，将 tarball 安装到临时前缀中，运行 postinstall，并对内置渠道入口点执行冒烟测试。
## Docker lanes
## Docker 通道
Docker lanes 是产品级证明。它们在 Linux 容器内安装或更新真实软件包，并通过 CLI 命令、Gateway 网关启动、HTTP 探测、RPC 状态和文件系统状态断言行为。
Docker 通道是产品级证明。它们会在 Linux 容器内安装或更新真实包，并通过 CLI 命令、Gateway 网关启动、HTTP 探测、RPC Status 和文件系统状态断言行为。
迭代时使用聚焦 lanes：
迭代时使用聚焦通道：
```bash
pnpm test:docker:plugins
@ -69,16 +69,16 @@ pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-migration
```
重要 lanes：
重要通道：
- `test:docker:plugins` 验证插件安装 smoke、本地文件夹安装、本地文件夹更新跳过行为、带预安装依赖的本地文件夹、`file:` 软件包安装、带 CLI 执行的 git 安装、git 移动引用更新、带提升传递依赖的 npm 注册表安装、npm 更新空操作、本地 ClawHub fixture 安装和更新空操作、marketplace 更新行为，以及 Claude bundle 启用/检查。设置 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可使 ClawHub 块保持 hermetic/离线。
- `test:docker:plugin-lifecycle-matrix` 在裸容器中安装候选软件包，让一个 npm 插件依次完成安装、检查、禁用、启用、显式升级、显式降级，以及删除插件代码后的卸载。它会记录每个阶段的 RSS 和 CPU 指标。
- `test:docker:plugins` 验证插件安装冒烟测试、本地文件夹安装、本地文件夹更新跳过行为、带预安装依赖的本地文件夹、`file:` 包安装、带 CLI 执行的 git 安装、git 移动引用更新、带提升传递依赖的 npm 注册表安装、npm 更新空操作、本地 ClawHub fixture 安装和更新空操作、marketplace 更新行为，以及 Claude 包启用/检查。设置 `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 安装到脏旧用户 fixture 上，运行软件包更新和非交互式 doctor，然后启动一个 local loopback Gateway 网关并检查状态保留。
- `test:docker:published-upgrade-survivor` 先安装一个已发布基线，通过内置的 `openclaw config set` 配方配置它，将其更新为候选 tarball，运行 doctor，检查旧版清理，启动 Gateway 网关，并探测 `/healthz`、`/readyz` 和 RPC 状态。
- `test:docker:update-migration` 是清理密集型的已发布更新 lane。它从已配置的 Discord/Telegram 风格用户状态开始，运行基线 doctor，让已配置的插件依赖有机会物化，为已配置的打包插件播种旧版插件依赖残留，更新到候选 tarball，并要求更新后的 doctor 移除旧版依赖根目录。
- `test:docker:upgrade-survivor` 将候选 tarball 安装到脏的旧用户 fixture 之上，运行包更新和非交互式 Doctor，然后启动 local loopback Gateway 网关并检查状态保留情况。
- `test:docker:published-upgrade-survivor` 首先安装一个已发布基线，通过内置的 `openclaw config set` 配方对其进行配置，将其更新到候选 tarball，运行 Doctor，检查旧版清理，启动 Gateway 网关，并探测 `/healthz`、`/readyz` 和 RPC Status。
- `test:docker:update-migration` 是清理密集型的已发布更新通道。它从已配置的 Discord/Telegram 风格用户状态开始，运行基线 Doctor，让已配置的插件依赖有机会落地，为已配置的打包插件植入旧版插件依赖残留，更新到候选 tarball，并要求更新后的 Doctor 移除旧版依赖根目录。
有用的已发布升级 survivor 变体：
有用的已发布升级幸存者变体：
```bash
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
@ -90,9 +90,9 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor
```
可用场景包括 `base`、`feishu-channel`、`bootstrap-persona`、`plugin-deps-cleanup`、`configured-plugin-installs`、`tilde-log-path` 和 `versioned-runtime-deps`。在聚合运行中，`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 会展开为所有已报告问题形态的场景，包括已配置插件安装迁移。
可用场景包括 `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` 会展开为所有呈现为已报告问题形态的场景，包括已配置插件安装迁移。
完整更新迁移有意与 Full Release CI 分离。当发布问题是“从 2026.4.23 起的每个已发布稳定版本是否都能更新到此候选版本并清理插件依赖残留？”时，使用手动 `Update Migration` 工作流：
完整更新迁移有意与完整发布 CI 分离。当发布问题是“从 `2026.4.23` 起每个已发布稳定版本是否都能更新到此候选版本并清理插件依赖残留？”时，请使用手动 `Update Migration` workflow：
```bash
gh workflow run update-migration.yml \
@ -103,20 +103,20 @@ gh workflow run update-migration.yml \
-f scenarios=plugin-deps-cleanup
```
## Package Acceptance
## 包验收
Package Acceptance 是 GitHub 原生的软件包门禁。它将一个候选软件包解析为 `package-under-test` tarball，记录版本和 SHA-256，然后针对这个精确 tarball 运行可复用的 Docker E2E lanes。工作流 harness ref 与软件包源 ref 分离，因此当前测试逻辑可以验证较旧的受信任发布。
包验收是 GitHub 原生包门禁。它会将一个候选包解析为 `package-under-test` tarball，记录版本和 SHA-256，然后针对该精确 tarball 运行可复用 Docker E2E 通道。workflow harness 引用与包源码引用分离，因此当前测试逻辑可以验证较旧的受信任版本。
候选来源：
- `source=npm`：验证 `openclaw@beta`、`openclaw@latest` 或精确的已发布版本。
- `source=ref`：使用所选当前 harness 打包受信任的分支、标签或提交。
- `source=url`：验证需要 `package_sha256` 的 HTTPS tarball。
- `source=ref`：使用选定的当前 harness 打包受信任的分支、标签或提交。
- `source=url`：验证 HTTPS tarball，并要求提供 `package_sha256`。
- `source=artifact`：复用另一个 Actions 运行上传的 tarball。
Full Release Validation 默认使用 `source=artifact`，从解析后的发布 SHA 构建。对于发布后证明，传入 `package_acceptance_package_spec=openclaw@YYYY.M.D`，让同一个升级矩阵目标指向已发布的 npm 软件包。
完整发布验证默认使用 `source=artifact`，基于解析后的发布 SHA 构建。对于发布后证明，传入 `package_acceptance_package_spec=openclaw@YYYY.M.D`，让同一升级矩阵以已发布的 npm 包为目标。
发布检查会使用 package/update/plugin 集合调用 Package Acceptance：
发布检查会用包/更新/插件集合调用包验收：
```text
doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update
@ -130,11 +130,11 @@ published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
```
这会让软件包迁移、更新渠道切换、陈旧插件依赖清理、离线插件覆盖、插件更新行为和 Telegram 软件包 QA 绑定到同一个解析后的构件上。
这会让包迁移、更新渠道切换、过时插件依赖清理、离线插件覆盖、插件更新行为和 Telegram 包 QA 使用同一个解析后的构件。
`all-since-2026.4.23` 是 Full Release CI 升级样本：从 `2026.4.23` 到 `latest` 的每个稳定 npm 已发布版本。要获得详尽的已发布更新迁移覆盖，请在单独的 Update Migration 工作流中使用 `all-since-2026.4.23`，而不是 Full Release CI。`release-history` 仍可用于手动更广泛抽样，适用于你也需要旧版日期前锚点的情况。
`all-since-2026.4.23` 是完整发布 CI 升级样本：从 `2026.4.23` 到 `latest` 的每个已发布到 npm 的稳定版本。对于穷尽式已发布更新迁移覆盖，请在单独的更新迁移 workflow 中使用 `all-since-2026.4.23`，而不是完整发布 CI。`release-history` 仍可用于手动更宽采样，适用于你还想包含旧版日期前锚点的情况。
在发布前验证候选版本时，手动运行软件包 profile：
在发布前验证候选包时，手动运行包 profile：
```bash
gh workflow run package-acceptance.yml \
@ -148,49 +148,49 @@ gh workflow run package-acceptance.yml \
-f telegram_mode=mock-openai
```
当发布问题包含 MCP 渠道、cron/subagent 清理、OpenAI web search 或 OpenWebUI 时，使用 `suite_profile=product`。仅在需要完整 Docker 发布路径覆盖时使用 `suite_profile=full`。
当发布问题包含 MCP 渠道、cron/subagent 清理、OpenAI web search 或 OpenWebUI 时，使用 `suite_profile=product`。只有在需要完整 Docker 发布路径覆盖时，才使用 `suite_profile=full`。
## 发布默认值
对于发布候选版本，默认证明栈是：
对于候选发布版本，默认证明栈是：
1. 用于源代码级回归的 `pnpm check:changed` 和 `pnpm test:changed`。
2. 用于软件包构件完整性的 `pnpm release:check`。
3. 用于安装/更新/插件契约的 Package Acceptance `package` profile 或 release-check 自定义软件包 lanes。
4. 用于特定 OS 安装器、新手引导和平台行为的跨 OS 发布检查。
5. 仅当变更面触及提供商或托管服务行为时运行实时套件。
1. `pnpm check:changed` 和 `pnpm test:changed`，用于源码级回归。
2. `pnpm release:check`，用于包构件完整性。
3. 包验收 `package` profile 或发布检查自定义包通道，用于安装/更新/插件契约。
4. 跨 OS 发布检查，用于特定 OS 的安装器、新手引导和平台行为。
5. 只有当变更表面触及提供商或托管服务行为时，才运行实时套件。
在维护者机器上，广泛门禁和 Docker/软件包产品证明应在 Testbox 中运行，除非明确执行本地证明。
在维护者机器上，宽范围门禁和 Docker/包产品证明应在 Testbox 中运行，除非明确要做本地证明。
## 旧版兼容性
兼容性宽容范围很窄，并且有时间限制：
兼容宽容范围很窄并且有时限：
- 直到 `2026.4.25` 的软件包，包括 `2026.4.25-beta.*`，可以在 Package Acceptance 中容忍已经发布的软件包元数据缺口。
- 已发布的 `2026.4.26` 软件包可以对已经发布的本地构建元数据 stamp 文件发出警告。
- 后续软件包必须满足现代契约。相同缺口会失败，而不是警告或跳过。
- 到 `2026.4.25` 为止的包，包括 `2026.4.25-beta.*`，在包验收中可以容忍已经发布的包元数据缺口。
- 已发布的 `2026.4.26` 包可以对已经发布的本地构建元数据戳文件发出警告。
- 后续包必须满足现代契约。同样的缺口会失败，而不是警告或跳过。
不要为这些旧形态添加新的启动迁移。添加或扩展 doctor 修复，然后用 `upgrade-survivor` 或 `published-upgrade-survivor` 证明它。
不要为这些旧形态添加新的启动迁移。添加或扩展 Doctor 修复，然后用 `upgrade-survivor` 或 `published-upgrade-survivor` 证明它。
## 添加覆盖
更改更新或插件行为时，在能够因正确原因失败的最低层添加覆盖：
更改更新或插件行为时，在能因正确原因失败的最低层添加覆盖：
- 纯路径或元数据逻辑：源代码旁边的单元测试。
- 软件包清单或打包文件行为：`package-dist-inventory` 或 tarball 检查器测试。
- CLI 安装/更新行为：Docker lane 断言或 fixture。
- 纯路径或元数据逻辑：源码旁的单元测试。
- 包清单或打包文件行为：`package-dist-inventory` 或 tarball 检查器测试。
- CLI 安装/更新行为：Docker 通道断言或 fixture。
- 已发布版本迁移行为：`published-upgrade-survivor` 场景。
- 注册表/软件包来源行为：`test:docker:plugins` fixture 或 ClawHub fixture server。
- 依赖布局或清理行为：同时断言运行时执行和文件系统边界。npm 依赖可能被提升到托管 npm 根目录下，所以测试应证明根目录已被扫描/清理，而不是假设存在软件包本地 `node_modules` 树。
- 注册表/包来源行为：`test:docker:plugins` fixture 或 ClawHub fixture 服务器。
- 依赖布局或清理行为：同时断言运行时执行和文件系统边界。npm 依赖可能会被提升到受管理的 npm 根目录下，因此测试应证明该根目录被扫描/清理，而不是假设存在包本地的 `node_modules` 树。
默认保持新的 Docker fixtures hermetic。除非测试重点是实时注册表行为，否则使用本地 fixture 注册表和伪软件包。
默认保持新的 Docker fixture 封闭。除非测试目的就是实时注册表行为，否则使用本地 fixture 注册表和假包。
## 失败分诊
从构件身份开始：
- Package Acceptance `resolve_package` 摘要：来源、版本、SHA-256 和构件名称。
- Docker 构件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志和重新运行命令。
- Upgrade survivor 摘要：`.artifacts/upgrade-survivor/summary.json`，包括基线版本、候选版本、场景、阶段耗时和配方步骤。
- 包验收 `resolve_package` 摘要：来源、版本、SHA-256 和构件名称。
- Docker 构件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志和重新运行命令。
- 升级幸存者摘要：`.artifacts/upgrade-survivor/summary.json`，包括基线版本、候选版本、场景、阶段耗时和配方步骤。
优先使用相同软件包构件重新运行失败的精确 lane，而不是重新运行整个发布总括流程。
优先使用同一个包构件重新运行失败的精确通道，而不是重新运行整个发布总括任务。

50
docs/zh-CN/plugins/manage-plugins.md
View File

@ -4,18 +4,18 @@ read_when:
- 你想在 ClawHub 和 npm 插件分发之间做出选择
- 你正在发布一个插件包
sidebarTitle: Manage plugins
summary: 用于安装、列出、卸载、更新和发布 OpenClaw 插件的快速示例
summary: 安装、列出、卸载、更新和发布 OpenClaw 插件的快速示例
title: 管理插件
x-i18n:
generated_at: "2026-05-02T21:57:54Z"
generated_at: "2026-05-04T20:59:54Z"
model: gpt-5.5
provider: openai
source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
source_path: plugins/manage-plugins.md
workflow: 16
---
大多数插件工作流只需要几个命令：搜索、安装、重启 Gateway 网关、验证，以及在不再需要插件时卸载。
大多数插件工作流只需几个命令：搜索、安装、重启 Gateway 网关、验证，并在不再需要插件时卸载。
## 列出插件
@ -26,35 +26,35 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
脚本请使用 `--json`。当插件包声明了 `dependencies` 或 `optionalDependencies` 时，它会包含注册表诊断信息以及每个插件的静态 `dependencyStatus`。
对脚本使用 `--json`。当插件包声明 `dependencies` 或 `optionalDependencies` 时，它会包含注册表诊断信息和每个插件的静态 `dependencyStatus`。
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` 是一次冷态清单检查。它显示 OpenClaw 能从配置、清单和插件注册表中发现的内容；它不能证明已经运行的 Gateway 网关进程已导入该插件运行时。
`plugins list` 是一次冷清单检查。它显示 OpenClaw 可以从配置、清单和插件注册表中发现的内容；它不能证明已经运行的 Gateway 网关进程导入了插件运行时。
## 安装插件
```bash
# 在 ClawHub 中搜索插件包。
# Search ClawHub for plugin packages.
openclaw plugins search "calendar"
# 裸包规范会先尝试 ClawHub，然后回退到 npm。
# Bare package specs try ClawHub first, then npm fallback.
openclaw plugins install <package>
# 强制使用一个来源。
# Force one source.
openclaw plugins install clawhub:<package>
openclaw plugins install npm:<package>
# 安装特定版本或 dist-tag。
# Install a specific version or dist-tag.
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex
# 从 git 或本地开发检出安装。
# Install from git or a local development checkout.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
@ -67,7 +67,7 @@ openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
当你需要证明插件已注册运行时表面时，请使用 `inspect --runtime`，例如工具、钩子、服务、Gateway 网关方法，或插件拥有的 CLI 命令。
当你需要证明插件注册了运行时表面，例如工具、钩子、服务、Gateway 网关方法或插件拥有的 CLI 命令时，请使用 `inspect --runtime`。
## 更新插件
@ -77,16 +77,16 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
如果插件是从 npm dist-tag（例如 `@beta`）安装的，后续 `update <plugin-id>` 调用会复用该记录的标签。传入显式 npm 规范会将被跟踪的安装切换到该规范，以供后续更新使用。
如果插件是从 npm dist-tag（例如 `@beta`）安装的，之后的 `update <plugin-id>` 调用会复用该记录的标签。传入显式 npm spec 会将跟踪的安装切换到该 spec，供未来更新使用。
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
当插件此前固定到精确版本或标签时，第二个命令会将插件移回注册表的默认发布线。
当插件之前固定到精确版本或标签时，第二个命令会将插件移回注册表的默认发布线。
当 `openclaw update` 在 beta 渠道上运行时，默认线 npm 和 ClawHub 插件记录会先尝试匹配的插件 `@beta` 版本。如果该 beta 版本不存在，OpenClaw 会回退到记录的默认/latest 规范。精确版本和显式标签（例如 `@rc` 或 `@beta`）会被保留。
当 `openclaw update` 在 beta 渠道上运行时，默认线 npm 和 ClawHub 插件记录会先尝试匹配的插件 `@beta` 发布。如果该 beta 发布不存在，OpenClaw 会回退到记录的默认/latest spec。对于 npm 插件，当 beta 包存在但安装验证失败时，OpenClaw 也会回退。精确版本和显式标签（例如 `@rc` 或 `@beta`）会被保留。
## 卸载插件
@ -97,15 +97,15 @@ openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
卸载会移除插件的配置条目、插件索引记录、允许/拒绝列表条目，以及适用时的链接加载路径。除非传入 `--keep-files`，否则托管安装目录会被移除。
卸载会移除插件的配置条目、插件索引记录、允许/拒绝列表条目，以及在适用时移除链接的加载路径。托管安装目录会被移除，除非你传入 `--keep-files`。
## 发布插件
你可以将外部插件发布到 [ClawHub](https://clawhub.ai)、npmjs.com，或同时发布到两者。
你可以将外部插件发布到 [ClawHub](https://clawhub.ai)、npmjs.com，或两者都发布。
### 发布到 ClawHub
ClawHub 是 OpenClaw 插件的主要公开发现表面。它会在安装前向用户提供可搜索的元数据、版本历史和注册表扫描结果。
ClawHub 是 OpenClaw 插件的主要公共发现表面。它让用户在安装前获得可搜索的元数据、版本历史和注册表扫描结果。
```bash
npm i -g clawhub
@ -115,7 +115,7 @@ clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0
```
用户可通过以下方式从 ClawHub 安装：
用户可以通过以下方式从 ClawHub 安装：
```bash
openclaw plugins install clawhub:<package>
@ -143,7 +143,7 @@ openclaw plugins install <package>
npm publish --access public
```
用户可通过以下方式安装仅 npm 的插件：
用户可以通过以下方式仅从 npm 安装：
```bash
openclaw plugins install npm:@acme/openclaw-plugin
@ -151,14 +151,14 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
```
如果同一个包也可在 ClawHub 上获得，`npm:` 会跳过 ClawHub 查找，并强制使用 npm 解析。
如果同一个包也可在 ClawHub 上获得，`npm:` 会跳过 ClawHub 查找并强制使用 npm 解析。
## 来源选择
## 源选择
- **ClawHub**：当你需要 OpenClaw 原生发现、扫描摘要、版本和安装提示时使用。
- **npmjs.com**：当你已经发布 JavaScript 包，或需要 npm dist-tag/私有注册表工作流时使用。
- **ClawHub**：当你想要 OpenClaw 原生发现、扫描摘要、版本和安装提示时使用。
- **npmjs.com**：当你已经发布 JavaScript 包，或需要 npm dist-tag/private registry 工作流时使用。
- **Git**：当你想直接从分支、标签或提交安装时使用。
- **本地路径**：当你正在同一台机器上开发或测试插件时使用。
- **本地路径**：当你在同一台机器上开发或测试插件时使用。
## 相关内容

98
docs/zh-CN/reference/test.md
View File

@ -4,60 +4,60 @@ read_when:
summary: 如何在本地运行测试（vitest），以及何时使用强制/覆盖率模式
title: 测试
x-i18n:
generated_at: "2026-05-02T18:56:59Z"
generated_at: "2026-05-04T20:59:42Z"
model: gpt-5.5
provider: openai
source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
source_path: reference/test.md
workflow: 16
---
- 完整测试工具包（套件、实时、Docker）：[测试](/zh-CN/help/testing)
- 完整测试工具包（套件、实时测试、Docker）：[测试](/zh-CN/help/testing)
- 更新和插件包验证：[更新和插件测试](/zh-CN/help/testing-updates-plugins)
- `pnpm test:force`：终止任何占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整 Vitest 套件，避免服务器测试与正在运行的实例冲突。当先前的 Gateway 网关运行遗留端口 18789 被占用时使用此命令。
- `pnpm test:coverage`：使用 V8 覆盖率运行单元套件（通过 `vitest.unit.config.ts`）。这是已加载文件的单元覆盖率门禁，不是全仓库所有文件覆盖率。阈值为 70% 行/函数/语句和 55% 分支。由于 `coverage.all` 为 false，该门禁测量单元覆盖率套件加载的文件，而不是把每个拆分车道源文件都视为未覆盖。
- `pnpm test:force`：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整 Vitest 套件，避免服务器测试与正在运行的实例冲突。当前一次 Gateway 网关运行留下端口 18789 被占用时使用。
- `pnpm test:coverage`：使用 V8 覆盖率运行单元套件（通过 `vitest.unit.config.ts`）。这是已加载文件的单元覆盖率门禁，不是整个仓库的全文件覆盖率。阈值为行/函数/语句 70%，分支 55%。因为 `coverage.all` 为 false，该门禁衡量单元覆盖率套件加载的文件，而不是把每个分片通道源文件都视为未覆盖。
- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来变更的文件运行单元覆盖率。
- `pnpm test:changed`：廉价的智能变更测试运行。它会从直接测试编辑、同级 `*.test.ts` 文件、显式源映射和本地导入图运行精确目标。宽泛/配置/包变更会被跳过，除非它们映射到精确测试。
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：显式的宽泛变更测试运行。当测试 harness/配置/包编辑应回退到 Vitest 更宽泛的变更测试行为时使用。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的差异触发的架构车道。
- `pnpm check:changed`：针对相对于 `origin/main` 的差异运行智能变更检查门禁。它会为受影响的架构车道运行类型检查、lint 和保护命令，但不会运行 Vitest 测试。使用 `pnpm test:changed` 或显式 `pnpm test <target>` 获取测试证明。
- `pnpm test`：通过有作用域的 Vitest 车道路由显式文件/目录目标。未指定目标的运行使用固定分片组，并展开为叶子配置以便本地并行执行；扩展组始终展开为按扩展划分的分片配置，而不是一个巨大的根项目进程。
- 测试包装器运行结束时会带有简短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自身的耗时行保留为每个分片的详情。
- 共享 OpenClaw 测试状态：当测试需要隔离的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、配置夹具、工作区、智能体目录或认证配置存储时，在 Vitest 中使用 `src/test-utils/openclaw-test-state.ts`。
- 进程 E2E 辅助工具：当 Vitest 进程级 E2E 测试需要把运行中的 Gateway 网关、CLI 环境、日志捕获和清理集中到一处时，使用 `test/helpers/openclaw-test-instance.ts`。
- Docker/Bash E2E 辅助工具：source `scripts/lib/docker-e2e-image.sh` 的车道可以将 `docker_e2e_test_state_shell_b64 <label> <scenario>` 传入容器，并用 `scripts/lib/openclaw-e2e-instance.sh` 解码；多 home 脚本可以传入 `docker_e2e_test_state_function_b64`，并在每个流程中调用 `openclaw_test_state_create <label> <scenario>`。更底层的调用方可以使用 `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` 获取容器内 shell 片段，或使用 `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` 获取可 source 的宿主机环境文件。`create` 前的 `--` 会防止较新的 Node 运行时把 `--env-file` 当作 Node 标志。启动 Gateway 网关的 Docker/Bash 车道可以在容器内 source `scripts/lib/openclaw-e2e-instance.sh`，用于入口点解析、模拟 OpenAI 启动、Gateway 网关前台/后台启动、就绪探针、状态环境导出、日志转储和进程清理。
- 完整、扩展和包含模式分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续整配置运行会使用这些计时来平衡慢分片和快分片。包含模式 CI 分片会把分片名称追加到计时键，这样可以让过滤后的分片计时可见，而不会替换整配置计时数据。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地计时工件。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用轻量车道，这些车道只保留 `test/setup.ts`，同时让运行时较重的用例留在其现有车道上。
- 带有同级测试的源文件会先映射到该同级测试，再回退到更宽泛的目录 glob。`src/channels/plugins/contracts/test-helpers`、`src/plugin-sdk/test-helpers` 和 `src/plugins/contracts` 下的辅助工具编辑会使用本地导入图运行导入它们的测试，而不是在依赖路径精确时宽泛运行每个分片。
- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），因此回复 harness 不会主导较轻量的顶层 Status/token/辅助工具测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在全仓库配置中启用共享的非隔离运行器。
- `pnpm test:changed`：低成本的智能变更测试运行。它会根据直接测试编辑、同级 `*.test.ts` 文件、显式源映射和本地导入图运行精确目标。广泛/config/package 变更会被跳过，除非它们映射到精确测试。
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：显式的广泛变更测试运行。当测试 harness/config/package 编辑应回退到 Vitest 更广泛的变更测试行为时使用。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 触发的架构通道。
- `pnpm check:changed`：对相对于 `origin/main` 的 diff 运行智能变更检查门禁。它会为受影响的架构通道运行类型检查、lint 和守卫命令，但不会运行 Vitest 测试。使用 `pnpm test:changed` 或显式 `pnpm test <target>` 提供测试证明。
- `pnpm test`：将显式文件/目录目标路由到有作用域的 Vitest 通道。无目标运行会使用固定分片组，并展开为叶级配置以进行本地并行执行；扩展组始终展开为每个扩展的分片配置，而不是一个巨大的根项目进程。
- 测试 wrapper 运行会以简短的 `[test] passed|failed|skipped ... in ...` 摘要结束。Vitest 自己的时长行保留为每个分片的详细信息。
- 共享 OpenClaw 测试状态：当测试需要隔离的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、配置 fixture、工作区、智能体目录或 auth-profile 存储时，在 Vitest 中使用 `src/test-utils/openclaw-test-state.ts`。
- 进程 E2E 辅助工具：当 Vitest 进程级 E2E 测试需要在一个位置管理正在运行的 Gateway 网关、CLI 环境、日志捕获和清理时，使用 `test/helpers/openclaw-test-instance.ts`。
- Docker/Bash E2E 辅助工具：source `scripts/lib/docker-e2e-image.sh` 的通道可以将 `docker_e2e_test_state_shell_b64 <label> <scenario>` 传入容器，并用 `scripts/lib/openclaw-e2e-instance.sh` 解码；多 home 脚本可以传入 `docker_e2e_test_state_function_b64`，并在每个流程中调用 `openclaw_test_state_create <label> <scenario>`。较低层调用方可以使用 `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` 获取容器内 shell 片段，或使用 `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` 生成可 source 的宿主环境文件。`create` 前面的 `--` 会阻止较新的 Node 运行时把 `--env-file` 视为 Node 标志。启动 Gateway 网关的 Docker/Bash 通道可以在容器内 source `scripts/lib/openclaw-e2e-instance.sh`，用于入口点解析、模拟 OpenAI 启动、Gateway 网关前台/后台启动、就绪探测、状态环境导出、日志转储和进程清理。
- 完整、扩展和 include-pattern 分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续 whole-config 运行使用这些计时来平衡慢速和快速分片。Include-pattern CI 分片会把分片名称追加到计时键，这会让过滤后的分片计时保持可见，同时不替换 whole-config 计时数据。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地计时 artifact。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用轻量通道，这些通道只保留 `test/setup.ts`，而运行时较重的用例保留在现有通道中。
- 带有同级测试的源文件会先映射到该同级测试，再回退到更宽的目录 glob。`src/channels/plugins/contracts/test-helpers`、`src/plugin-sdk/test-helpers` 和 `src/plugins/contracts` 下的辅助工具编辑会使用本地导入图运行导入它们的测试，而不是在依赖路径精确时广泛运行每个分片。
- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），这样回复 harness 不会压过较轻量的顶层 status/token/helper 测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在仓库配置中启用共享的非隔离 runner。
- `pnpm test:channels` 运行 `vitest.channels.config.ts`。
- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展/插件分片。重型渠道插件、浏览器插件和 OpenAI 会作为专用分片运行；其他插件组保持批处理。使用 `pnpm test extensions/<id>` 运行一个内置插件车道。
- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入分解报告，同时仍然对显式文件/目录目标使用有作用域车道路由。
- `pnpm test:perf:imports:changed`：相同的导入分析，但仅针对自 `origin/main` 以来变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一个已提交的 Git 差异，对路由后的变更模式路径和原生根项目运行进行基准测试。
- `pnpm test:perf:changed:bench -- --worktree`：对当前工作树变更集进行基准测试，无需先提交。
- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展/插件分片。重型渠道插件、浏览器插件和 OpenAI 会作为专用分片运行；其他插件组保持批处理。使用 `pnpm test extensions/<id>` 运行一个内置插件通道。
- `pnpm test:perf:imports`：启用 Vitest 导入时长 + 导入分解报告，同时仍然对显式文件/目录目标使用有作用域的通道路由。
- `pnpm test:perf:imports:changed`：相同的导入 profiling，但仅针对自 `origin/main` 以来变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：基准测试同一已提交 git diff 下，路由后的 changed-mode 路径相对于原生根项目运行的表现。
- `pnpm test:perf:changed:bench -- --worktree`：在无需先提交的情况下，对当前 worktree 变更集进行基准测试。
- `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。
- `pnpm test:perf:profile:runner`：为单元运行器写入 CPU + heap profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整套件 Vitest 叶子配置，并写入分组耗时数据以及每配置 JSON/日志工件。Test Performance Agent 在尝试修复慢测试前使用它作为基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在性能导向变更后比较分组报告。
- `pnpm test:perf:profile:runner`：为单元 runner 写入 CPU + heap profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个 full-suite Vitest 叶级配置，并写入分组时长数据以及每个配置的 JSON/log artifact。Test Performance Agent 使用它作为尝试修复慢测试之前的基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在性能相关变更后比较分组报告。
- Gateway 网关集成：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/node 配对）。默认在 `vitest.e2e.config.ts` 中使用 `threads` + `isolate: false` 和自适应 worker；用 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 获取详细日志。
- `pnpm test:e2e`：运行 Gateway 网关端到端 smoke 测试（多实例 WS/HTTP/node 配对）。默认使用 `threads` + `isolate: false`，并在 `vitest.e2e.config.ts` 中使用自适应 worker；用 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 输出详细日志。
- `pnpm test:live`：运行提供商 live 测试（minimax/zai）。需要 API key 和 `LIVE=1`（或提供商特定的 `*_LIVE_TEST=1`）才能取消跳过。
- `pnpm test:docker:all`：构建共享 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，构建/复用裸 Node/Git 运行器镜像以及把该 tarball 安装到 `/app` 的功能镜像，然后通过加权调度器使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker 冒烟车道。裸镜像（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用于安装器/更新/插件依赖车道；这些车道挂载预构建的 tarball，而不是使用复制的仓库源代码。功能镜像（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用于正常的已构建应用功能车道。`scripts/package-openclaw-for-docker.mjs` 是唯一的本地/CI 包打包器，并在 Docker 使用前验证 tarball 和 `dist/postinstall-inventory.json`。Docker 车道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 执行选定计划。`node scripts/test-docker-all.mjs --plan-json` 会输出由调度器拥有的 CI 计划，包含选定车道、镜像种类、包/live-image 需求、状态场景和凭据检查，而不构建或运行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制进程槽位，默认为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制提供商敏感的尾部池，默认为 10。重型车道上限默认值为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认通过 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4` 为每个提供商设置一个重型车道。对更大的宿主机使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。如果某个车道在低并行度宿主机上超过有效权重或资源上限，它仍可以从空池启动，并会独自运行直到释放容量。车道启动默认错开 2 秒，以避免本地 Docker daemon 出现 create 风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆盖。运行器默认预检 Docker、清理过期的 OpenClaw E2E 容器、每 30 秒输出活动车道 Status、在兼容车道之间共享提供商 CLI 工具缓存、默认重试一次瞬时 live 提供商失败（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），并把车道计时存储在 `.artifacts/docker-tests/lane-timings.json` 中，以便后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 打印车道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 调整 Status 输出，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用计时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 仅运行确定性/本地车道，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 仅运行 live 提供商车道；包别名为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅 live 模式会把主 live 车道和尾部 live 车道合并到一个最长优先池中，让提供商桶可以将 Claude、Codex 和 Gemini 工作一起打包。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则运行器会在第一次失败后停止调度新的池化车道；每个车道都有 120 分钟的后备超时，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/尾部车道使用更严格的每车道上限。CLI 后端 Docker 设置命令有自己的超时，通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS`（默认 180）配置。每车道日志、`summary.json`、`failures.json` 和阶段计时会写入 `.artifacts/docker-tests/<run-id>/` 下；使用 `pnpm test:docker:timings <summary.json>` 检查慢车道，使用 `pnpm test:docker:rerun <run-id|summary.json|failures.json>` 打印廉价的定向重跑命令。
- `pnpm test:docker:browser-cdp-snapshot`：构建基于 Chromium 的源 E2E 容器，启动原始 CDP 和隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP 角色快照包含链接 URL、光标提升的可点击项、iframe 引用和 frame 元数据。
- CLI 后端 live Docker 探针可以作为聚焦车道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 有对应的 `:resume` 和 `:mcp` 别名。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行真实的代理聊天。需要可用的 live 模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并且不像正常单元/e2e 套件那样预期能在 CI 中稳定运行。
- `pnpm test:docker:mcp-channels`：启动一个已播种的 Gateway 网关容器和第二个客户端容器，后者会生成 `openclaw mcp serve`，然后验证路由后的对话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP frames，因此该冒烟测试反映 bridge 实际发出的内容。
- `pnpm test:docker:upgrade-survivor`：将打包的 OpenClaw tarball 安装到一个脏的旧用户 fixture 之上，在没有实时提供商或渠道密钥的情况下运行软件包更新和非交互式 Doctor，然后启动一个回环 Gateway 网关，并检查智能体、渠道配置、插件 allowlist、工作区/会话文件、陈旧的旧版插件依赖状态、启动过程和 RPC 状态是否能保留下来。
- `pnpm test:docker:published-upgrade-survivor`：默认安装 `openclaw@latest`，在没有实时提供商或渠道密钥的情况下播种真实的既有用户文件，用内置的 `openclaw config set` 命令配方配置该基线，将该已发布安装更新到打包的 OpenClaw tarball，运行非交互式 Doctor，写入 `.artifacts/upgrade-survivor/summary.json`，然后启动一个回环 Gateway 网关，并检查已配置的意图、工作区/会话文件、陈旧的插件配置和旧版依赖状态、启动过程、`/healthz`、`/readyz` 以及 RPC 状态是否能保留或干净修复。可用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆盖一个基线，用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 展开精确矩阵，例如 `all-since-2026.4.23`，或用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 添加场景 fixture；reported-issues 集合包含 `configured-plugin-installs`，用于验证已配置的外部 OpenClaw 插件会在升级期间自动安装。软件包验收会将这些公开为 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 和 `published_upgrade_survivor_scenarios`。
- `pnpm test:docker:update-migration`：在清理较重的 `plugin-deps-cleanup` 场景中运行已发布升级存活 harness，默认从 `openclaw@2026.4.23` 开始。单独的 `Update Migration` 工作流会用 `baselines=all-since-2026.4.23` 扩展此 lane，因此从 `.23` 起的每个稳定已发布软件包都会更新到候选版本，并在 Full Release CI 之外证明已配置插件的依赖清理。
- `pnpm test:docker:plugins`：为本地路径、`file:`、带提升依赖的 npm registry 软件包、git 移动引用、ClawHub fixture、市场更新以及 Claude-bundle 启用/检查运行安装/更新冒烟测试。
- `pnpm test:docker:all`：构建共享 live-test 镜像，将 OpenClaw 一次打包为 npm tarball，构建/复用一个裸 Node/Git runner 镜像，以及一个把该 tarball 安装到 `/app` 的功能镜像，然后通过加权调度器以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker smoke 通道。裸镜像（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用于 installer/update/plugin-dependency 通道；这些通道挂载预构建 tarball，而不是使用复制的仓库源。功能镜像（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用于普通 built-app 功能通道。`scripts/package-openclaw-for-docker.mjs` 是唯一的本地/CI package packer，并在 Docker 消费前验证 tarball 和 `dist/postinstall-inventory.json`。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；planner 逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 执行选定计划。`node scripts/test-docker-all.mjs --plan-json` 会输出调度器拥有的 CI 计划，包含选定通道、镜像类型、package/live-image 需求、状态场景和凭据检查，而不会构建或运行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制提供商敏感的 tail pool，默认值为 10。重型通道上限默认是 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认通过 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4` 设置为每个提供商一个重型通道。更大的宿主机可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。如果某个通道在低并行度宿主机上超过有效权重或资源上限，它仍然可以从空池启动，并会独占运行直到释放容量。通道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆盖。runner 默认预检 Docker，清理陈旧的 OpenClaw E2E 容器，每 30 秒输出 active-lane 状态，在兼容通道之间共享提供商 CLI 工具缓存，默认对瞬态 live-provider 失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），并将通道计时存储在 `.artifacts/docker-tests/lane-timings.json` 中，以便后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可打印通道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 可调整状态输出，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用计时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 仅运行确定性/本地通道，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 仅运行 live-provider 通道；package 别名是 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。Live-only 模式会把 main 和 tail live 通道合并到一个最长优先池中，这样提供商 bucket 可以把 Claude、Codex 和 Gemini 工作打包在一起。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，runner 会在第一次失败后停止调度新的 pooled 通道，并且每个通道都有一个 120 分钟的回退超时，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 通道使用更严格的每通道上限。CLI 后端 Docker 设置命令有自己的超时，通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 控制（默认 180）。每通道日志、`summary.json`、`failures.json` 和阶段计时会写入 `.artifacts/docker-tests/<run-id>/` 下；使用 `pnpm test:docker:timings <summary.json>` 检查慢通道，使用 `pnpm test:docker:rerun <run-id|summary.json|failures.json>` 打印低成本的定向重跑命令。
- `pnpm test:docker:browser-cdp-snapshot`：构建基于 Chromium 的 source E2E 容器，启动原始 CDP 加隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP role 快照包含链接 URL、cursor-promoted clickables、iframe refs 和 frame metadata。
- CLI 后端 live Docker 探测可以作为聚焦通道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 有匹配的 `:resume` 和 `:mcp` 别名。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并且不预期像普通 unit/e2e 套件一样在 CI 中稳定。
- `pnpm test:docker:mcp-channels`：启动一个已播种的 Gateway 网关容器和第二个客户端容器，后者会生成 `openclaw mcp serve`，然后验证路由后的对话发现、transcript 读取、附件 metadata、live event queue 行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格 channel + permission notifications。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该 smoke 反映 bridge 实际发出的内容。
- `pnpm test:docker:upgrade-survivor`：将打包后的 OpenClaw tarball 安装到脏的旧用户 fixture 上，运行软件包更新和非交互式 Doctor，不使用实时提供商或渠道密钥，然后启动一个环回 Gateway 网关，并检查智能体、渠道配置、插件允许列表、工作区/会话文件、陈旧的旧版插件依赖状态、启动和 RPC 状态是否保留下来。
- `pnpm test:docker:published-upgrade-survivor`：默认安装 `openclaw@latest`，填充不含实时提供商或渠道密钥的真实既有用户文件，使用内置的 `openclaw config set` 命令配方配置该基线，将该已发布安装更新到打包后的 OpenClaw tarball，运行非交互式 Doctor，写入 `.artifacts/upgrade-survivor/summary.json`，然后启动一个环回 Gateway 网关，并检查已配置的意图、工作区/会话文件、陈旧的插件配置和旧版依赖状态、启动、`/healthz`、`/readyz` 以及 RPC 状态是否保留下来或被干净修复。使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆盖一个基线，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 展开精确矩阵，例如 `all-since-2026.4.23`，或使用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 添加场景 fixture；reported-issues 集合包含 `configured-plugin-installs`，用于验证已配置的外部 OpenClaw 插件会在升级期间自动安装，还包含 `stale-source-plugin-shadow`，用于防止仅源码插件影子破坏启动。Package Acceptance 将这些暴露为 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 和 `published_upgrade_survivor_scenarios`。
- `pnpm test:docker:update-migration`：在清理较重的 `plugin-deps-cleanup` 场景中运行已发布升级幸存者 harness，默认从 `openclaw@2026.4.23` 开始。单独的“更新迁移”工作流会用 `baselines=all-since-2026.4.23` 展开此 lane，使从 `.23` 起的每个稳定已发布软件包都更新到候选版本，并在完整发布 CI 之外证明已配置插件的依赖清理。
- `pnpm test:docker:plugins`：针对本地路径、`file:`、带提升依赖的 npm registry 软件包、git 移动引用、ClawHub fixture、marketplace 更新，以及 Claude bundle 启用/检查运行安装/更新 smoke。
## 本地 PR 门禁
对于本地 PR 合并/门禁检查，运行：
对于本地 PR 合入/门禁检查，运行：
- `pnpm check:changed`
- `pnpm check`
@ -66,7 +66,7 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
如果 `pnpm test` 在负载较高的主机上出现不稳定失败，先重新运行一次，再将其视为回归；然后用 `pnpm test <path/to/test>` 隔离问题。对于内存受限的主机，使用：
如果 `pnpm test` 在负载较高的主机上出现不稳定失败，请先重新运行一次，再将其视为回归问题，然后用 `pnpm test <path/to/test>` 隔离问题。对于内存受限的主机，使用：
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -114,15 +114,15 @@ x-i18n:
- `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`tasks --json`、`tasks list --json`、`tasks audit --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port`
- `all`：两个预设
输出包括每条命令的 `sampleCount`、平均值、p50、p95、最小值/最大值、退出代码/信号分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 配置文件，因此计时和配置文件采集使用同一个 harness。
输出包含每条命令的 `sampleCount`、平均值、p50、p95、最小值/最大值、退出码/信号分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时和 profile 捕获会使用同一个 harness。
已保存输出约定：
保存输出约定：
- `pnpm test:startup:bench:smoke` 会将目标冒烟测试产物写入 `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将全套件产物写入 `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新签入的基线 fixture：`test/fixtures/cli-startup-bench.json`
- `pnpm test:startup:bench:smoke` 将目标 smoke artifact 写入 `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` 使用 `runs=5` 和 `warmup=1` 将全套 artifact 写入 `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:update` 使用 `runs=5` 和 `warmup=1` 刷新已签入的基线 fixture：`test/fixtures/cli-startup-bench.json`
签入的 fixture：
已签入的 fixture：
- `test/fixtures/cli-startup-bench.json`
- 使用 `pnpm test:startup:bench:update` 刷新
@ -130,7 +130,7 @@ x-i18n:
## 新手引导 E2E（Docker）
Docker 是可选的；只有容器化新手引导冒烟测试需要它。
Docker 是可选的；只有容器化的新手引导 smoke 测试才需要它。
在干净的 Linux 容器中执行完整冷启动流程：
@ -138,11 +138,11 @@ Docker 是可选的；只有容器化新手引导冒烟测试需要它。
scripts/e2e/onboard-docker.sh
```
此脚本通过伪 tty 驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 网关并运行 `openclaw health`。
该脚本通过伪 tty 驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 网关并运行 `openclaw health`。
## QR 导入冒烟测试（Docker）
## QR 导入 smoke（Docker）
确保维护中的 QR 运行时辅助工具能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）：
确保维护的 QR 运行时 helper 可以在受支持的 Docker Node 运行时中加载（Node 24 默认，Node 22 兼容）：
```bash
pnpm test:docker:qr