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-04-28 02:01:31 +00:00
parent 14b737b6eb
commit ffab1017ef
4 changed files with 536 additions and 532 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

563
docs/zh-CN/help/testing.md
View File

@ -1,139 +1,113 @@
---
read_when:
- 在本地或 CI 中运行测试
- 在本地或在 CI 中运行测试
- 为模型 / 提供商缺陷添加回归测试
- 调试 Gateway 网关 + 智能体行为
summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及各项测试的覆盖内容
summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每类测试覆盖的内容
title: 测试
x-i18n:
generated_at: "2026-04-27T22:50:29Z"
generated_at: "2026-04-28T01:58:12Z"
model: gpt-5.4
provider: openai
source_hash: f5adf6c223bc489d8c9eceb5a5a5b5b2c0fb774a48f6a71f6b793361e2fd4911
source_hash: d2511d646a4e86fa0b7c17eb94dcc4931b88abb510a67f31e155f7da3f41279d
source_path: help/testing.md
workflow: 15
---
OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是“我们如何测试”的指南：
OpenClaw 有三套 Vitest 测试套件（单元 / 集成、e2e、live）以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南：
- 各个测试套件覆盖什么（以及它刻意**不**覆盖什么）。
- 每个测试套件覆盖什么（以及它刻意**不**覆盖什么）。
- 常见工作流（本地、推送前、调试）应运行哪些命令。
- 实时测试如何发现凭证并选择模型 / 提供商。
- live 测试如何发现凭证并选择模型 / 提供商。
- 如何为真实世界中的模型 / 提供商问题添加回归测试。
<Note>
**QA 栈（qa-lab、qa-channel、实时传输通道）** 另有单独文档说明：
**QA stack（qa-lab、qa-channel、live transport lanes）**另有单独文档说明：
- [QA overview](/zh-CN/concepts/qa-e2e-automation) — 架构、命令入口、场景编写。
- [QA overview](/zh-CN/concepts/qa-e2e-automation) — 架构、命令面、场景编写。
- [Matrix QA](/zh-CN/concepts/qa-matrix) — `pnpm openclaw qa matrix` 的参考文档。
- [QA channel](/zh-CN/channels/qa-channel) — 仓库支持场景所使用的合成传输插件。
本页涵盖常规测试套件以及 Docker / Parallels 运行器的运行方式。下面的 QA 专用运行器部分（[QA 专用运行器](#qa-specific-runners)）列出了具体的 `qa` 调用方式，并回链到上述参考文档。
本页介绍如何运行常规测试套件以及 Docker / Parallels 运行器。下方的 QA 专用运行器部分（[QA-specific runners](#qa-specific-runners)）列出了具体的 `qa` 调用方式，并回链到上面的参考文档。
</Note>
## 快速开始
大多数时候：
- 完整门禁（预期应在推送前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test`
- 在配置充足的机器上更快地本地运行完整测试套件：`pnpm test:max`
- 直接进入 Vitest 监视循环：`pnpm test:watch`
- 直接指定文件现在也会路由扩展 / 渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
- 当你在迭代处理单个失败用例时，优先先跑有针对性的测试。
- 完整闸门（预期应在推送前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test`
- 在配置充足的机器上更快地运行本地全套测试：`pnpm test:max`
- 直接使用 Vitest 监视循环：`pnpm test:watch`
- 现在也支持直接按文件定位 extension / channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
- 当你在迭代单个失败用例时，优先先跑有针对性的测试。
- Docker 支持的 QA 站点：`pnpm qa:lab:up`
- Linux VM 支持的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
- Linux VM 支持的 QA lane：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
当你修改了测试，或想获得更多信心时：
当你改动了测试或想获得更多信心时：
- 覆盖率门禁：`pnpm test:coverage`
- E2E 套件：`pnpm test:e2e`
- 覆盖率闸门：`pnpm test:coverage`
- E2E 测试套件：`pnpm test:e2e`
当你在调试真实提供商 / 模型时（需要真实凭证）：
- 实时套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live`
- 安静地只跑一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
- Docker 实时模型全量扫描：`pnpm test:docker:live-models`
- 现在每个选中的模型都会运行一次文本轮次外加一个小型文件读取式探测。
元数据声明支持 `image` 输入的模型还会运行一个微型图像轮次。
当你要隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或
`OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探测。
- CI 覆盖范围：每日的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的
`OpenClaw Release Checks` 都会调用可复用的实时 / E2E 工作流，并设置
`include_live_suites: true`，其中包括按提供商分片的独立 Docker 实时模型矩阵任务。
- 若要在 CI 中有针对性地重跑，可调度 `OpenClaw Live And E2E Checks (Reusable)`
并设置 `include_live_suites: true` 与 `live_models_only: true`。
- 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`，同时更新 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 及其定时 / 发布调用方。
- live 测试套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live`
- 安静地只跑一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
- Docker live 模型扫描：`pnpm test:docker:live-models`
- 现在，每个选中的模型都会运行一次文本轮次加一个小型文件读取式探测。元数据声明支持 `image` 输入的模型还会再运行一个微型图像轮次。在隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探测。
- CI 覆盖：每日的 `OpenClaw Scheduled Live And E2E Checks` 和手动的 `OpenClaw Release Checks` 都会调用可复用的 live / E2E 工作流，并设置 `include_live_suites: true`，其中包括按提供商分片的独立 Docker live 模型矩阵作业。
- 若要进行聚焦的 CI 重跑，请分发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。
- 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 以及其定时 / 发布调用方中。
- 原生 Codex 绑定聊天冒烟测试：`pnpm test:docker:live-codex-bind`
- 在 Codex app-server 路径上运行 Docker 实时通道，绑定一个合成 Slack 私信，使用 `/codex bind`，执行 `/codex fast` 和
`/codex permissions`，然后验证普通回复和图像附件都通过原生插件绑定路由，而不是 ACP。
- 在 Docker live lane 中针对 Codex app-server 路径运行，将一个合成 Slack 私信通过 `/codex bind` 绑定，执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件都经由原生插件绑定路由，而不是 ACP。
- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`
- 通过插件拥有的 Codex app-server harness 运行 Gateway 网关智能体轮次，验证 `/codex status` 和 `/codex models`，并默认执行图像、
cron MCP、子智能体和 Guardian 探测。隔离其他 Codex
app-server 故障时，可通过 `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`
禁用子智能体探测。若要专注于子智能体检查，请禁用其他探测：
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。
除非设置了 `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`，否则该流程会在子智能体探测后退出。
- 通过插件拥有的 Codex app-server harness 运行 Gateway 网关智能体轮次，验证 `/codex status` 和 `/codex models`，并且默认执行图像、cron MCP、子智能体以及 Guardian 探测。在隔离其他 Codex app-server 故障时，可通过 `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` 禁用子智能体探测。若要进行聚焦的子智能体检查，请禁用其他探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。
除非设置了 `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`，否则该命令会在子智能体探测后退出。
- Crestodian 救援命令冒烟测试：`pnpm test:live:crestodian-rescue-channel`
- 这是消息渠道救援命令入口的可选双重保险检查。它会执行 `/crestodian status`，排队一个持久化模型变更，回复 `/crestodian yes`，并验证审计 / 配置写入路径。
- Crestodian 规划器 Docker 冒烟测试：`pnpm test:docker:crestodian-planner`
- 在无配置容器中运行 Crestodian，并在 `PATH` 上放置假的 Claude CLI，验证模糊规划器回退会被转换为带审计记录的类型化配置写入。
- 对消息渠道救援命令表面进行可选的双保险检查。它会执行 `/crestodian status`，排队一个持久模型变更，回复 `/crestodian yes`，并验证审计 / 配置写入路径。
- Crestodian planner Docker 冒烟测试：`pnpm test:docker:crestodian-planner`
- 在一个无配置容器中运行 Crestodian，并在 `PATH` 上放置一个假的 Claude CLI，验证模糊 planner 回退会转换成带审计记录的类型化配置写入。
- Crestodian 首次运行 Docker 冒烟测试：`pnpm test:docker:crestodian-first-run`
- 从空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到
Crestodian，应用设置 / 模型 / 智能体 / Discord 插件 + SecretRef 写入，验证配置，并核对审计条目。相同的 Ring 0 设置路径也在 QA Lab 中通过
`pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` 覆盖。
- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行
`openclaw models list --provider moonshot --json`，然后对 `moonshot/kimi-k2.6` 运行一个隔离的
`openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`
。验证 JSON 报告的是 Moonshot / K2.6，并且助手转录中存储了规范化的 `usage.cost`。
- 从空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到 Crestodian，应用设置 / 模型 / 智能体 / Discord 插件 + SecretRef 写入，验证配置，并检查审计条目。同一条 Ring 0 设置路径也在 QA Lab 中通过 `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` 覆盖。
- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行独立命令 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`
。验证 JSON 报告的是 Moonshot / K2.6，且助手转录中存储了归一化后的 `usage.cost`。
<Tip>
当你只需要一个失败用例时，优先使用下面描述的允许列表环境变量来缩小实时测试范围。
当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来收窄 live 测试范围。
</Tip>
## QA 专用运行器
当你需要 qa-lab 级别的真实环境时，这些命令与主测试套件配套使用：
当你需要 qa-lab 级别的真实感时，这些命令与主测试套件并列使用：
CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动调度在模拟提供商模式下运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可手动调度；它会并行运行模拟 parity gate、实时 Matrix 通道、Convex 托管的实时 Telegram 通道，以及 Convex 托管的实时 Discord 通道。定时 QA 和发布检查会显式传递 Matrix `--profile fast`，而 Matrix CLI 和手动工作流输入的默认值仍然是 `all`；手动调度可以将 `all` 分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 任务。`OpenClaw Release Checks` 会在发布批准前运行 parity，以及快速 Matrix 和 Telegram 通道。
CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上以及通过手动分发、使用 mock 提供商时运行。`QA-Lab - All Lanes` 会在 `main` 上按夜间计划运行，也可通过手动分发运行；其中 mock parity gate、live Matrix lane、Convex 托管的 live Telegram lane，以及 Convex 托管的 live Discord lane 会作为并行作业执行。定时 QA 和发布检查会显式传入 Matrix `--profile fast`，而 Matrix CLI 和手动工作流输入的默认值仍为 `all`；手动分发可以将 `all` 分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 会在发布批准前运行 parity，以及 fast Matrix 和 Telegram lanes。
- `pnpm openclaw qa suite`
- 直接在宿主机上运行仓库支持的 QA 场景。
- 默认会使用隔离的 Gateway 网关工作进程并行运行多个已选场景。`qa-channel` 默认并发度为 4（受已选场景数量限制）。使用 `--concurrency <count>` 调整工作进程数，或使用 `--concurrency 1` 回到较早的串行通道。
- 任一场景失败时将以非零状态退出。若你想保留制品但不希望退出码失败，可使用 `--allow-failures`。
- 直接在主机上运行由仓库支持的 QA 场景。
- 默认会以隔离的 Gateway 网关 worker 并行运行多个选中的场景。`qa-channel` 默认为并发 4（受所选场景数量限制）。使用 `--concurrency <count>` 调整 worker 数量，或使用 `--concurrency 1` 走旧式串行 lane。
- 当任一场景失败时以非零状态退出。如果你想保留产物但不让退出码失败，请使用 `--allow-failures`。
- 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。
`aimock` 会启动一个本地的 AIMock 支持提供商服务器，用于实验性的 fixture 和协议模拟覆盖，而不会替换具备场景感知能力的 `mock-openai` 通道。
`aimock` 会启动一个本地的 AIMock 支持提供商服务器，用于实验性的 fixture 和协议 mock 覆盖，而不会替代具备场景感知能力的 `mock-openai` lane。
- `pnpm openclaw qa suite --runner multipass`
- 在一次性 Multipass Linux VM 中运行同一套 QA 测试。
- 与宿主机上的 `qa suite` 保持相同的场景选择行为。
- 在一次性 Multipass Linux VM 中运行同样的 QA 测试套件。
- 与主机上的 `qa suite` 保持相同的场景选择行为。
- 复用与 `qa suite` 相同的提供商 / 模型选择标志。
- 实时运行会转发对来宾环境切实可行的受支持 QA 鉴权输入：
基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。
- 输出目录必须保留在仓库根目录下，这样来宾环境才能通过挂载的工作区回写。
- 会将常规 QA 报告 + 摘要，以及 Multipass 日志写入
`.artifacts/qa-e2e/...`。
- live 运行会转发适合访客环境的、受支持的 QA 鉴权输入：基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。
- 输出目录必须保持在仓库根目录下，这样访客环境才能通过挂载的工作区写回。
- 会在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要，以及 Multipass 日志。
- `pnpm qa:lab:up`
- 启动 Docker 支持的 QA 站点，用于偏操作员风格的 QA 工作。
- 启动 Docker 支持的 QA 站点，供偏运维风格的 QA 工作使用。
- `pnpm test:docker:npm-onboard-channel-agent`
- 从当前检出构建一个 npm tarball，在 Docker 中全局安装它，运行非交互式 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件时会按需安装运行时依赖，运行 doctor，并针对模拟的 OpenAI 端点运行一次本地智能体轮次。
- 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。
- 从当前检出构建一个 npm tarball，在 Docker 中全局安装，以非交互方式运行 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件会按需安装运行时依赖，运行 doctor，并对一个模拟的 OpenAI 端点执行一次本地智能体轮次。
- 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装 lane。
- `pnpm test:docker:session-runtime-context`
- 为嵌入式运行时上下文转录运行一个确定性的已构建应用 Docker 冒烟测试。它会验证隐藏的 OpenClaw 运行时上下文被持久化为非显示型自定义消息，而不会泄漏到可见的用户轮次中；然后植入一个受影响的损坏会话 JSONL，并验证
`openclaw doctor --fix` 会将其重写到当前活动分支，并保留备份。
- 针对嵌入式运行时上下文转录运行一个确定性的已构建应用 Docker 冒烟测试。它会验证隐藏的 OpenClaw 运行时上下文以不可显示的自定义消息形式持久化，而不是泄漏到可见的用户轮次中；然后会植入一份受影响的损坏会话 JSONL，并验证 `openclaw doctor --fix` 会将其重写到当前活动分支并保留备份。
- `pnpm test:docker:npm-telegram-live`
- 在 Docker 中安装一个 OpenClaw 候选包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用实时 Telegram QA 通道，并将该已安装包作为被测 Gateway 网关。
- 默认值为 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`；设置
`OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` 或
`OPENCLAW_CURRENT_PACKAGE_TGZ`，即可测试解析后的本地 tarball，而不是从注册表安装。
- 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置
`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，同时配置
`OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在
`OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，Docker 包装器会自动选择 Convex。
- `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为此通道覆盖共享的
`OPENCLAW_QA_CREDENTIAL_ROLE`。
- GitHub Actions 也将该通道暴露为手动维护者工作流
`NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用
`qa-live-shared` 环境和 Convex CI 凭证租约。
- GitHub Actions 还提供 `Package Acceptance`，用于针对单个候选包执行旁路产品验证。它接受可信 ref、已发布的 npm 规格、HTTPS tarball URL 加 SHA-256，或来自另一个运行的 tarball 制品；随后上传规范化的 `openclaw-current.tgz` 作为 `package-under-test`，再运行现有的 Docker E2E 调度器，可选择 smoke、package、product、full 或自定义通道配置。设置 `telegram_mode=mock-openai` 或 `live-frontier`，即可让 Telegram QA 工作流针对同一个 `package-under-test` 制品运行。
- 在 Docker 中安装一个 OpenClaw 包候选版本，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用 live Telegram QA lane，并将这个已安装包作为待测系统 Gateway 网关。
- 默认使用 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`；设置 `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` 或 `OPENCLAW_CURRENT_PACKAGE_TGZ`，即可测试已解析的本地 tarball，而不是从注册表安装。
- 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，并同时设置 `OPENCLAW_QA_CONVEX_SITE_URL` 与角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，则 Docker 包装器会自动选择 Convex。
- `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为此 lane 覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。
- GitHub Actions 还将此 lane 暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。
- GitHub Actions 还暴露了 `Package Acceptance`，用于针对单个候选包执行旁路产品验证。它接受可信 ref、已发布的 npm 规格、带 SHA-256 的 HTTPS tarball URL，或来自其他运行的 tarball 制品；然后将标准化后的 `openclaw-current.tgz` 作为 `package-under-test` 上传，再运行现有 Docker E2E 调度器的 smoke、package、product、full 或 custom lane 配置文件。设置 `telegram_mode=mock-openai` 或 `live-frontier`，即可针对同一个 `package-under-test` 制品运行 Telegram QA 工作流。
- 最新 beta 产品验证：
```bash
@ -165,58 +139,58 @@ gh workflow run package-acceptance.yml --ref main \
```
- `pnpm test:docker:bundled-channel-deps`
- 在 Docker 中打包并安装当前的 OpenClaw 构建，配置 OpenAI 后启动 Gateway 网关，然后通过编辑配置启用内置渠道 / 插件。
- 验证设置发现流程会让未配置插件的运行时依赖保持缺失状态，首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖，而第二次重启不会重新安装已经激活过的依赖。
- 还会安装一个已知的旧版 npm 基线，在运行 `openclaw update --tag <candidate>` 之前启用 Telegram，并验证候选版本在更新后的 doctor 中会修复内置渠道运行时依赖，而无需 harness 侧的 postinstall 修复。
- 在 Docker 中打包并安装当前的 OpenClaw 构建，启动已配置 OpenAI 的 Gateway 网关，然后通过配置编辑启用内置渠道 / 插件。
- 验证设置发现阶段会保持未配置插件的运行时依赖缺失状态；首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重新安装已经激活的依赖。
- 还会安装一个已知的旧 npm 基线版本，在运行 `openclaw update --tag <candidate>` 之前启用 Telegram，并验证候选版本的更新后 doctor 会修复内置渠道的运行时依赖，而无需 harness 侧的 postinstall 修复。
- `pnpm test:parallels:npm-update`
- 在 Parallels 来宾环境中运行原生打包安装更新冒烟测试。每个选定平台都会先安装请求的基线包，然后在同一个来宾环境中运行已安装的 `openclaw update` 命令，并验证已安装版本、更新状态、Gateway 网关就绪情况，以及一次本地智能体轮次。
- 在只迭代单个来宾时，使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 可获取摘要制品路径和各通道状态。
- OpenAI 通道默认使用 `openai/gpt-5.5` 进行实时智能体轮次验证。若要有意验证其他 OpenAI 模型，请传入 `--model <provider/model>` 或设置 `OPENCLAW_PARALLELS_OPENAI_MODEL`。
- 将较长的本地运行包在宿主机超时中，这样 Parallels 传输卡顿就不会耗尽剩余测试窗口：
- 在 Parallels 客户机中运行原生打包安装更新冒烟测试。每个选中的平台都会先安装请求的基线包，然后在同一个客户机中运行已安装的 `openclaw update` 命令，并验证已安装版本、更新状态、Gateway 网关就绪状态以及一次本地智能体轮次。
- 迭代单个客户机时，使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 获取摘要制品路径和每个 lane 的状态。
- OpenAI lane 默认使用 `openai/gpt-5.5` 作为 live 智能体轮次验证模型。若要有意验证其他 OpenAI 模型，请传入 `--model <provider/model>` 或设置 `OPENCLAW_PARALLELS_OPENAI_MODEL`。
- 将较长的本地运行包裹在主机超时中，以免 Parallels 传输停滞耗尽剩余测试窗口：
```bash
timeout --foreground 150m pnpm test:parallels:npm-update -- --json
timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
```
- 该脚本会将嵌套通道日志写入 `/tmp/openclaw-parallels-npm-update.*`。在认定外层包装器卡住之前，请先检查 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。
- 在冷启动来宾环境上，Windows 更新可能会在更新后的 doctor / 运行时依赖修复阶段耗费 10 到 15 分钟；只要嵌套的 npm 调试日志仍在推进，这仍属于正常状态。
- 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享 VM 状态，可能会在快照恢复、包服务或来宾 Gateway 网关状态上发生冲突。
- 更新后的验证会运行常规的内置插件入口，因为语音、图像生成和媒体理解等能力 facade 是通过内置运行时 API 加载的，即使智能体轮次本身只检查简单的文本响应也是如此。
- 该脚本会将嵌套 lane 日志写入 `/tmp/openclaw-parallels-npm-update.*` 下。不要在假定外层包装器卡住之前，先查看 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。
- 在冷启动客户机上，Windows 更新后的 doctor / 运行时依赖修复可能需要 10 到 15 分钟；只要嵌套的 npm 调试日志仍在推进，这仍然是健康状态。
- 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟 lane 并行运行。它们共享 VM 状态，可能会在快照恢复、包服务或客户机 Gateway 网关状态上发生冲突。
- 更新后验证会运行常规的内置插件表面，因为像语音、图像生成和媒体理解这样的能力外观层，即使智能体轮次本身只检查简单文本响应，也仍然会通过内置运行时 API 加载。
- `pnpm openclaw qa aimock`
- 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。
- `pnpm openclaw qa matrix`
- 针对一次性 Docker 支持的 Tuwunel homeserver 运行 Matrix 实时 QA 通道。仅支持源代码检出——打包安装不包含 `qa-lab`。
- 完整的 CLI、配置文件 / 场景目录、环境变量和制品布局：参见 [Matrix QA](/zh-CN/concepts/qa-matrix)。
- 针对一次性 Docker 支持的 Tuwunel homeserver 运行 Matrix live QA lane。仅适用于源码检出 —— 打包安装不附带 `qa-lab`。
- 完整的 CLI、profile / 场景目录、环境变量和制品布局： [Matrix QA](/zh-CN/concepts/qa-matrix)。
- `pnpm openclaw qa telegram`
- 使用环境变量中的驱动机器人和 SUT 机器人令牌，针对真实私有群组运行 Telegram 实时 QA 通道。
- 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram 聊天的数字 id。
- 支持 `--credential-source convex` 以使用共享池化凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。
- 任一场景失败时将以非零状态退出。若你想保留制品但不希望退出码失败，可使用 `--allow-failures`。
- 需要同一私有群组中的两个不同机器人，并且 SUT 机器人需要公开一个 Telegram 用户名。
- 为了实现稳定的机器人到机器人观测，请在 `@BotFather` 中为两个机器人启用 Bot-to-Bot Communication Mode，并确保驱动机器人可以观测群组中的机器人流量。
- 会在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 制品。回复类场景会包含从驱动发送请求到观测到 SUT 回复之间的 RTT。
- 使用来自环境变量的 driver 和待测系统 bot token，在真实私有群组上运行 Telegram live QA lane。
- 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是数字形式的 Telegram chat id。
- 支持 `--credential-source convex` 以使用共享凭证池。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。
- 当任何场景失败时会以非零状态退出。如果你想保留制品但不让退出码失败，请使用 `--allow-failures`。
- 需要在同一个私有群组中的两个不同 bot，且待测系统 bot 必须暴露 Telegram 用户名。
- 为了实现稳定的 bot 对 bot 观察，请在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 能观察到群组内的 bot 流量。
- 会在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 制品。回复类场景会包含从 driver 发送请求到观察到待测系统回复之间的 RTT。
实时传输通道共享一套标准契约，这样新传输不会产生漂移；各通道的覆盖矩阵位于 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 是范围更广的合成测试套件，不属于该矩阵的一部分。
live 传输 lanes 共享一份标准契约，因此新传输不会发生漂移；每个 lane 的覆盖矩阵位于 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 是更广泛的合成测试套件，不属于该矩阵的一部分。
### 通过 Convex 共享 Telegram 凭证（v1）
当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的凭证池中获取独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放该租约。
当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的凭证池中获取一个独占租约，在 lane 运行期间为该租约发送心跳，并在关闭时释放租约。
参考的 Convex 项目脚手架：
参考 Convex 项目脚手架：
- `qa/convex-credential-broker/`
必需的环境变量：
- `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`）
- 为选定角色配置一个密钥：
- `maintainer` 对应 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
- `ci` 对应 `OPENCLAW_QA_CONVEX_SECRET_CI`
- 所选角色对应的一个密钥：
- `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 用于 `maintainer`
- `OPENCLAW_QA_CONVEX_SECRET_CI` 用于 `ci`
- 凭证角色选择：
- CLI：`--credential-role maintainer|ci`
- 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认为 `ci`，否则默认为 `maintainer`）
- 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则默认是 `maintainer`）
可选环境变量：
@ -226,13 +200,13 @@ gh workflow run package-acceptance.yml --ref main \
- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`）
- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`）
- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id）
- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许仅用于本地开发的 loopback `http://` Convex URL。
- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。
在正常运行中，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。
`OPENCLAW_QA_CONVEX_SITE_URL` 在正常运行中应使用 `https://`。
维护者管理命令（池添加 / 移除 / 列表）必须专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。
维护者管理命令（池添加 / 删除 / 列表）明确要求使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。
面向维护者的 CLI 辅助命令：
供维护者使用的 CLI 辅助命令：
```bash
pnpm openclaw qa credentials doctor
@ -241,16 +215,14 @@ pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>
```
在实时运行前使用 `doctor` 来检查 Convex 站点 URL、broker 密钥、
端点前缀、HTTP 超时和管理 / 列表可达性，同时不会打印密钥值。
在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。
在 live 运行之前使用 `doctor`，检查 Convex 站点 URL、broker 密钥、端点前缀、HTTP 超时以及 admin / list 可达性，同时不会打印密钥值。在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。
默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）：
- `POST /acquire`
- 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }`
- 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }`
- 耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }`
- 池已耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }`
- `POST /heartbeat`
- 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }`
- 成功：`{ status: "ok" }`（或空的 `2xx`）
@ -268,97 +240,94 @@ pnpm openclaw qa credentials remove --credential-id <credential-id>
- 请求：`{ kind?, status?, includePayload?, limit? }`
- 成功：`{ status: "ok", credentials, count }`
Telegram 类型的 payload 结构：
Telegram 类型的载荷结构：
- `{ groupId: string, driverToken: string, sutToken: string }`
- `groupId` 必须是 Telegram 聊天数字 id 的字符串。
- `admin/add` 会针对 `kind: "telegram"` 验证此结构，并拒绝格式错误的 payload。
- `groupId` 必须是数字形式的 Telegram chat id 字符串。
- `admin/add` 会对 `kind: "telegram"` 验证该结构，并拒绝格式错误的载荷。
### 向 QA 添加一个渠道
新渠道适配器的架构和场景辅助函数名称位于 [QA overview → Adding a channel](/zh-CN/concepts/qa-e2e-automation#adding-a-channel)。最低门槛是：在共享的 `qa-lab` 宿主接缝上实现传输运行器、在插件清单中声明 `qaRunners`、挂载为 `openclaw qa <runner>`，并在 `qa/scenarios/` 下编写场景。
新渠道适配器的架构和场景辅助函数名称位于 [QA overview → Adding a channel](/zh-CN/concepts/qa-e2e-automation#adding-a-channel)。最低门槛：在共享的 `qa-lab` 主机接缝上实现传输运行器，在插件清单中声明 `qaRunners`，挂载为 `openclaw qa <runner>`，并在 `qa/scenarios/` 下编写场景。
## 测试套件（各自运行位置）
## 测试套件（在哪里运行什么）
可以把这些测试套件理解为“真实性逐级增加”（同时波动性 / 成本也逐级增加）：
可以把这些测试套件理解为“真实度逐步提升”（同时不稳定性 / 成本也逐步提升）：
### 单元 / 集成（默认）
- 命令：`pnpm test`
- 配置：未指定目标的运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度
- 文件：核心 / 单元清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts` 和 `test/**/*.test.ts`；UI 单元测试运行在专用的 `unit-ui` 分片中
- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片扩展为按项目划分的配置，以便并行调度
- 文件：核心 / 单元清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts` 和 `test/**/*.test.ts`；UI 单元测试在专用的 `unit-ui` 分片中运行
- 范围：
- 纯单元测试
- 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
- 进程内集成测试（Gateway 网关鉴权、路由、工具、解析、配置）
- 已知缺陷的确定性回归测试
- 预期：
- 在 CI 中运行
- 不需要真实密钥
- 应当快速且稳定
- 应该快速且稳定
<AccordionGroup>
<Accordion title="项目、分片和作用域通道">
<Accordion title="项目、分片和作用域 lane">
- 未指定目标的 `pnpm test` 会运行十二个较小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个庞大的原生根项目进程。这样可以降低繁忙机器上的峰值 RSS，并避免 auto-reply / 扩展工作拖累无关测试套件。
- 未定向的 `pnpm test` 会运行 12 个较小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply / extension 工作拖慢无关测试套件。
- `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片监视循环并不现实。
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先通过作用域通道来路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可以避免承担完整根项目启动成本。
- `pnpm test:changed` 默认会将变更的 git 路径展开为低成本的作用域通道：直接测试编辑、同级 `*.test.ts` 文件、显式源码映射以及本地导入图依赖项。配置 / setup / 包编辑不会广泛运行测试，除非你显式使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
- `pnpm check:changed` 是窄范围工作时的常规智能本地检查门禁。它会将差异分类为核心、核心测试、扩展、扩展测试、应用、文档、发布元数据、实时 Docker 工具和工具链，然后运行匹配的类型检查、lint 和守卫命令。它不会运行 Vitest 测试；如需测试证明，请调用 `pnpm test:changed` 或显式执行 `pnpm test <target>`。仅发布元数据的版本提升会运行有针对性的版本 / 配置 / 根依赖检查，并带有一个守卫，用于拒绝顶层版本字段之外的包变更。
- 实时 Docker ACP harness 编辑会运行聚焦检查：实时 Docker 认证脚本的 shell 语法检查，以及实时 Docker 调度器 dry-run。只有当差异仅限于 `scripts["test:docker:live-*"]` 时才会包含 `package.json` 变更；依赖、导出、版本和其他包表面编辑仍然使用更广泛的守卫。
- 来自智能体、commands、插件、auto-reply 辅助器、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试会通过 `unit-fast` 通道路由，从而跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件则仍保留在现有通道上。
- 一些选定的 `plugin-sdk` 和 `commands` 辅助源码文件也会将 changed 模式运行映射到这些轻量通道中的显式同级测试，因此辅助器编辑可以避免为该目录重新运行完整的重型测试套件。
- `auto-reply` 为顶层核心辅助器、顶层 `reply.*` 集成测试以及 `src/auto-reply/reply/**` 子树提供了专用分桶。CI 还会将 reply 子树进一步拆分为 agent-runner、dispatch 和 commands / state-routing 分片，这样某一个导入开销很大的分桶就不会拖住整个 Node 尾部运行时间。
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 现在会优先通过作用域 lane 路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不需要承担完整根项目启动成本。
- `pnpm test:changed` 默认会将变更的 git 路径扩展为廉价的作用域 lane：直接的测试编辑、同级 `*.test.ts` 文件、显式源码映射以及本地导入图依赖项。配置 / setup / 包编辑不会广泛运行测试，除非你显式使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
- `pnpm check:changed` 是针对小范围工作的常规智能本地检查闸门。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs、发布元数据、live Docker 工具链以及工具链，然后运行匹配的 typecheck、lint 和 guard 命令。它不会运行 Vitest 测试；测试验证请调用 `pnpm test:changed` 或显式的 `pnpm test <target>`。仅发布元数据的版本提升会运行有针对性的版本 / 配置 / 根依赖检查，并带有一个 guard，用于拒绝顶层 version 字段之外的包变更。
- live Docker ACP harness 编辑会运行聚焦检查：对 live Docker 鉴权脚本进行 shell 语法检查，以及一次 live Docker 调度器 dry-run。只有当 diff 仅限于 `scripts["test:docker:live-*"]` 时，才会包含 `package.json` 变更；依赖、导出、版本以及其他包表面编辑仍然使用更广泛的 guard。
- 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试，会路由到 `unit-fast` lane，该 lane 会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有 lane 中。
- 某些 `plugin-sdk` 和 `commands` 辅助源码文件，在 changed 模式运行时也会映射到这些轻量 lane 中的显式同级测试，因此辅助函数编辑无需为该目录重跑完整的重型测试套件。
- `auto-reply` 为顶层核心辅助函数、顶层 `reply.*` 集成测试以及 `src/auto-reply/reply/**` 子树设置了专用分桶。CI 还会将 reply 子树进一步拆分为 agent-runner、dispatch 和 commands / state-routing 分片，这样某一个导入较重的分桶就不会独占完整的 Node 尾部时间。
</Accordion>
<Accordion title="嵌入式运行器覆盖范围">
<Accordion title="嵌入式运行器覆盖">
- 当你修改消息工具发现输入或 compaction 运行时上下文时，要同时保留这两个层级的覆盖。
- 为纯路由和规范化边界添加聚焦的辅助器回归测试。
- 保持嵌入式运行器集成套件健康：
- 当你修改消息工具发现输入或压缩运行时上下文时，要同时保留这两个层级的覆盖。
- 为纯路由和归一化边界添加聚焦的辅助函数回归测试。
- 保持嵌入式运行器集成测试套件健康：
`src/agents/pi-embedded-runner/compact.hooks.test.ts`、
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。
- 这些套件会验证作用域 id 和 compaction 行为仍然会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助器级测试并不足以替代这些集成路径。
- 这些测试套件会验证作用域 id 和压缩行为仍会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试并不能充分替代这些集成路径。
</Accordion>
<Accordion title="Vitest 池和隔离默认值">
- 基础 Vitest 配置默认使用 `threads`。
- 共享 Vitest 配置将 `isolate: false` 固定下来，并在根项目、e2e 和实时配置中使用非隔离运行器。
- 根 UI 通道保留其 `jsdom` 设置和优化器，但也运行在共享的非隔离运行器上。
- 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。
- 根 UI lane 保留其 `jsdom` 设置和优化器，但也在共享的非隔离运行器上运行。
- 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。
- `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。
设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可对比原生 V8
行为。
- `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行对比。
</Accordion>
<Accordion title="快速本地迭代">
- `pnpm changed:lanes` 会显示某个差异会触发哪些架构通道。
- pre-commit 钩子仅负责格式化。它会重新暂存格式化后的文件，但不会运行 lint、类型检查或测试。
- 在交接或推送前，如果你需要智能本地检查门禁，请显式运行 `pnpm check:changed`。
- `pnpm test:changed` 默认通过低成本的作用域通道路由。仅当智能体判断某个 harness、配置、包或契约编辑确实需要更广泛的 Vitest 覆盖时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
- `pnpm changed:lanes` 会显示某个 diff 会触发哪些架构 lane。
- pre-commit hook 只做格式化。它会重新暂存格式化后的文件，不会运行 lint、typecheck 或测试。
- 在你需要智能本地检查闸门时，交接或推送前请显式运行 `pnpm check:changed`。
- `pnpm test:changed` 默认通过廉价的作用域 lane 路由。只有当智能体判断 harness、配置、包或契约编辑确实需要更广的 Vitest 覆盖时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
- `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的 worker 上限。
- 本地 worker 自动伸缩刻意保持保守；当宿主负载平均值已经较高时，它会主动回退，因此默认情况下多个并发 Vitest 运行造成的影响会更小。
- 基础 Vitest 配置将项目 / 配置文件标记为 `forceRerunTriggers`，这样当测试布线发生变化时，changed 模式的重跑仍然是正确的。
- 该配置会在受支持的宿主上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接分析指定一个显式缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
- 本地 worker 自动缩放刻意设计得较为保守；当主机负载平均值已经很高时，它会回退，因此默认情况下，多路并发 Vitest 运行造成的影响会更小。
- 基础 Vitest 配置会将项目 / 配置文件标记为 `forceRerunTriggers`，以便在测试接线发生变化时，changed 模式的重跑仍然正确。
- 该配置会在受支持主机上保持 `OPENCLAW_VITEST_FS_MODULE_CACHE` 启用；如果你想为直接性能分析指定一个明确的缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
</Accordion>
<Accordion title="性能调试">
- `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入拆分输出。
- `pnpm test:perf:imports:changed` 会将相同的分析视图限定到自 `origin/main` 以来变更的文件。
- 分片耗时数据会写入 `.artifacts/vitest-shard-timings.json`。
整个配置运行使用配置路径作为键；include-pattern CI 分片会追加分片名称，以便单独跟踪过滤后的分片。
- 当某个热点测试仍然把大部分时间耗在启动导入上时，应将重依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了通过 `vi.mock(...)` 传递它们就去深度导入运行时辅助器。
- `pnpm test:perf:changed:bench -- --ref <git-ref>` 会针对该已提交差异，对比路由后的 `test:changed` 与原生根项目路径，并打印墙钟时间以及 macOS 最大 RSS。
- `pnpm test:perf:changed:bench -- --worktree` 会通过 `scripts/test-projects.mjs` 和根 Vitest 配置，将变更文件列表路由出去，从而对当前脏工作树做基准测试。
- `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和 transform 开销写出主线程 CPU profile。
- `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。
- `pnpm test:perf:imports` 会启用 Vitest 导入时长报告以及导入明细输出。
- `pnpm test:perf:imports:changed` 会将同样的性能分析视图限定到自 `origin/main` 以来发生变化的文件。
- 分片计时数据会写入 `.artifacts/vitest-shard-timings.json`。整套配置运行使用配置路径作为键；include-pattern CI 分片会附加分片名称，这样就可以分别跟踪被过滤的分片。
- 当某个热点测试的大部分时间仍消耗在启动导入上时，应将重型依赖放在一个狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了传给 `vi.mock(...)` 就深度导入运行时辅助函数。
- `pnpm test:perf:changed:bench -- --ref <git-ref>` 会针对该已提交 diff，对比路由后的 `test:changed` 与原生根项目路径，并打印墙钟时间和 macOS 最大 RSS。
- `pnpm test:perf:changed:bench -- --worktree` 会通过 `scripts/test-projects.mjs` 和根 Vitest 配置，将当前脏工作树的变更文件列表进行路由并做基准测试。
- `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动与转换开销写出一个主线程 CPU profile。
- `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出 runner CPU + heap profiles。
</Accordion>
</AccordionGroup>
@ -368,14 +337,14 @@ Telegram 类型的 payload 结构：
- 命令：`pnpm test:stability:gateway`
- 配置：`vitest.gateway.config.ts`，强制单 worker
- 范围：
- 默认启用诊断功能，启动一个真实的 loopback Gateway 网关
- 通过诊断事件路径驱动合成的 Gateway 网关消息、内存和大负载抖动
- 启动一个默认启用诊断的真实 loopback Gateway 网关
- 通过诊断事件路径驱动合成的 gateway message、memory 和大载荷抖动
- 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability`
- 覆盖诊断稳定性 bundle 持久化辅助器
- 断言记录器保持有界、合成 RSS 采样保持在压力预算之下，并且每个会话的队列深度最终回落到零
- 覆盖诊断稳定性包持久化辅助函数
- 断言记录器保持有界、合成 RSS 样本保持在压力预算内，且每个会话的队列深度会回落到零
- 预期：
- 对 CI 安全且无须密钥
- 这是用于稳定性回归跟进的窄范围通道，不可替代完整 Gateway 网关测试套件
- 对 CI 安全且无需密钥
- 这是一个用于稳定性回归跟进的窄 lane，不替代完整的 Gateway 网关测试套件
### E2E（Gateway 网关冒烟）
@ -383,163 +352,173 @@ Telegram 类型的 payload 结构：
- 配置：`vitest.e2e.config.ts`
- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置插件 E2E 测试
- 运行时默认值：
- 使用 Vitest `threads`，并设置 `isolate: false`，与仓库其余部分保持一致。
- 使用 Vitest `threads` 和 `isolate: false`，与仓库其他部分保持一致。
- 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。
- 默认以静默模式运行，以减少控制台 I/O 开销。
- 常用覆盖项：
- 使用 `OPENCLAW_E2E_WORKERS=<n>` 强制设置 worker 数量（上限为 16）。
- 使用 `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。
- `OPENCLAW_E2E_WORKERS=<n>` 用于强制指定 worker 数量（上限为 16）。
- `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。
- 范围：
- 多实例 Gateway 网关端到端行为
- WebSocket / HTTP 表面、节点配对以及更重的网络交互
- 预期：
- 会在 CI 中运行（当流水线启用时）
- 不需要真实密钥
- 相比单元测试有更多活动部件（可能更慢）
- 比单元测试涉及更多可变部件（可能更慢）
### E2E：OpenShell 后端冒烟测试
### E2E：OpenShell 后端冒烟
- 命令：`pnpm test:e2e:openshell`
- 文件：`extensions/openshell/src/backend.e2e.test.ts`
- 范围：
- 通过 Docker 在宿主机上启动一个隔离的 OpenShell Gateway 网关
- 通过 Docker 在主机上启动一个隔离的 OpenShell gateway
- 从一个临时本地 Dockerfile 创建沙箱
- 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端
- 通过沙箱 fs bridge 验证远端规范文件系统行为
- 通过真实的 `sandbox ssh-config` + SSH exec 练习 OpenClaw 的 OpenShell 后端
- 通过 sandbox fs bridge 验证远端规范化文件系统行为
- 预期：
- 仅限显式启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 需要本地 `openshell` CLI 和可用的 Docker daemon
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 gateway 和沙箱
- 常用覆盖项：
- 运行更广泛的 e2e 套件时，设置 `OPENCLAW_E2E_OPENSHELL=1` 启用该测试
- 设置 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 以指向非默认 CLI 二进制或包装脚本
- `OPENCLAW_E2E_OPENSHELL=1` 可在手动运行更广泛的 e2e 测试套件时启用该测试
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 可指向非默认 CLI 二进制或包装脚本
### 实时（真实提供商 + 真实模型）
### live（真实提供商 + 真实模型）
- 命令：`pnpm test:live`
- 配置：`vitest.live.config.ts`
- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置插件实时测试
- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置插件 live 测试
- 默认：由 `pnpm test:live` **启用**（会设置 `OPENCLAW_LIVE_TEST=1`）
- 范围：
- “这个提供商 / 模型在 _今天_ 搭配真实凭证是否真的可用？”
- 捕捉提供商格式变更、工具调用怪癖、认证问题以及限流行为
- “这个提供商 / 模型在**今天**配合真实凭证是否真的能工作？”
- 捕获提供商格式变化、工具调用怪癖、鉴权问题和速率限制行为
- 预期：
- 按设计并不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障）
- 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障）
- 会花钱 / 消耗速率限制
- 优先运行收窄后的子集，而不是“全部都跑”
- 实时运行会加载 `~/.profile`，以拾取缺失的 API 密钥。
- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 认证材料复制到一个临时测试 home 中，这样单元测试 fixture 就不会修改你真实的 `~/.openclaw`。
- 仅当你有意让实时测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
- `pnpm test:live` 现在默认采用更安静的模式：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 Gateway 网关引导日志 / Bonjour 噪声。如果你想恢复完整启动日志，可设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
- API 密钥轮换（按提供商区分）：设置 `*_API_KEYS`（逗号 / 分号格式）或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或通过 `OPENCLAW_LIVE_*_KEY` 进行按实时测试覆盖；测试会在收到限流响应时重试。
- 优先运行收窄后的子集，而不是“全部”
- live 运行会 source `~/.profile`，以获取缺失的 API 密钥。
- 默认情况下，live 运行仍会隔离 `HOME`，并将配置 / 鉴权材料复制到一个临时测试 home 中，这样单元测试 fixture 就不会改动你真实的 `~/.openclaw`。
- 仅当你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
- `pnpm test:live` 现在默认采用更安静的模式：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 gateway 启动日志 / Bonjour 杂音。若要恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
- API 密钥轮换（按提供商）：设置逗号 / 分号格式的 `*_API_KEYS`，或设置 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行单次 live 覆盖；测试会在收到速率限制响应时重试。
- 进度 / 心跳输出：
- 实时套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获很安静，长时间的提供商调用也能显示仍在活动。
- `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此提供商 / Gateway 网关进度行会在实时运行期间立即流出。
- live 测试套件现在会把进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能明显显示仍在活动。
- `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此在 live 运行期间，提供商 / gateway 进度行会立即流出。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。
- 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。
## 我应该运行哪个测试套件？
使用这个决策表：
使用这张决策表：
- 编辑逻辑 / 测试：运行 `pnpm test`（如果改动较多，再加上 `pnpm test:coverage`）
- 触及 Gateway 网关网络 / WS 协议 / 配对：再加上 `pnpm test:e2e`
- 调试“我的机器人挂了” / 提供商特定故障 / 工具调用：运行收窄后的 `pnpm test:live`
- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，再加上 `pnpm test:coverage`）
- 触及 Gateway 网关网络 / WS 协议 / 配对：加跑 `pnpm test:e2e`
- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行收窄后的 `pnpm test:live`
## 实时（触网）测试
## live（接触网络的）测试
关于实时模型矩阵、CLI 后端冒烟测试、ACP 冒烟测试、Codex app-server
harness，以及所有媒体提供商实时测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、
音乐、视频、媒体 harness）——以及实时运行的凭证处理——请参见
对于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server
harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、
音乐、视频、媒体 harness）—— 以及 live 运行的凭证处理 —— 请参阅
[Testing — live suites](/zh-CN/help/testing-live)。
## Docker 运行器（可选的“在 Linux 中可用”检查）
## Docker 运行器（可选的“在 Linux 中可运行”检查）
这些 Docker 运行器分为两类：
- 实时模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像内运行与其匹配的 profile-key 实时文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），挂载你的本地配置目录和工作区（如果已挂载，也会加载 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
- Docker 实时运行器默认采用较小的冒烟上限，以便完整的 Docker 扫描保持可行：
- live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 仅在仓库 Docker 镜像内运行与各自 profile-key 匹配的 live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果已挂载，也会 source `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
- Docker live 运行器默认采用更小的冒烟上限，以便完整的 Docker 扫描仍然可行：
`test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，而
`test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确希望进行更大范围的穷举扫描时，可覆盖这些环境变量。
- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，再通过 `scripts/package-openclaw-for-docker.mjs` 将 OpenClaw 打包一次为 npm tarball，然后构建 / 复用两个 `scripts/e2e/Dockerfile` 镜像。裸镜像仅包含用于安装 / 更新 / 插件依赖通道的 Node / Git 运行器；这些通道会挂载预构建的 tarball。功能镜像则将同一个 tarball 安装到 `/app` 中，用于已构建应用的功能通道。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 负责执行选定计划。这个聚合运行器使用带权重的本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限会阻止高负载的实时、npm 安装和多服务通道同时全部启动。如果某个单独通道比当前启用的上限还重，调度器仍然会在池为空时启动它，然后在容量再次可用之前让它单独运行。默认值是 10 个槽位、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有当 Docker 宿主有更多余量时，才调整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。该运行器默认执行 Docker 预检、移除陈旧的 OpenClaw E2E 容器、每 30 秒打印一次状态、将成功通道的耗时存入 `.artifacts/docker-tests/lane-timings.json`，并在后续运行中利用这些耗时优先启动较长的通道。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可以只打印带权重的通道清单而不构建或运行 Docker，或者使用 `node scripts/test-docker-all.mjs --plan-json` 打印所选通道、包 / 镜像需求和凭证的 CI 计划。
- `Package Acceptance` 是 GitHub 原生的包门禁，用于回答“这个可安装的 tarball 作为产品是否可用？”这个问题。它会从 `source=npm`、`source=ref`、`source=url` 或 `source=artifact` 中解析出一个候选包，将其作为 `package-under-test` 上传，然后针对这个精确 tarball 运行可复用的 Docker E2E 通道，而不是重新打包所选 ref。`workflow_ref` 选择可信的工作流 / harness 脚本，而 `package_ref` 在 `source=ref` 时选择要打包的源提交 / 分支 / 标签；这样当前的 acceptance 逻辑就能验证较早但可信的提交。各个配置文件按覆盖广度排序：`smoke` 是快速的安装 / 渠道 / 智能体加 Gateway 网关 / 配置检查，`package` 覆盖包 / 更新 / 插件契约，并且是大多数 Parallels 包 / 更新覆盖的默认原生替代方案，`product` 会加入 MCP 渠道、cron / 子智能体清理、OpenAI Web 搜索和 OpenWebUI，而 `full` 会运行带 OpenWebUI 的发布路径 Docker 分块。发布验证会运行自定义的 package delta（`bundled-channel-deps-compat plugins-offline`）加 Telegram package QA，因为发布路径 Docker 分块已经覆盖了重叠的包 / 更新 / 插件通道。根据制品生成的定向 GitHub Docker 重跑命令，在可用时会包含先前的包制品和已准备好的镜像输入，因此失败通道可以避免重新构建包和镜像。
- 构建和发布检查会在 tsdown 之后运行 `scripts/check-cli-bootstrap-imports.mjs`。该守卫会从 `dist/entry.js` 和 `dist/cli/run-main.js` 遍历静态构建图，并在命令分发之前的启动导入阶段，如果发现导入了 Commander、提示 UI、undici 或日志记录等包依赖，就会失败。打包后的 CLI 冒烟测试还覆盖根 help、onboard help、doctor help、status、config schema 和 model-list 命令。
- `Package Acceptance` 旧版兼容性上限为 `2026.4.25`（包含 `2026.4.25-beta.*`）。在这个截止点之前，harness 仅容忍已发布包中的元数据缺口：省略的私有 QA 清单条目、缺失的 `gateway install --wrapper`、从 tarball 派生的 git fixture 中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件 install-record 位置、缺失的 marketplace install-record 持久化，以及在 `plugins update` 期间发生的配置元数据迁移。对于 `2026.4.25` 之后的包，这些路径都会被视为严格失败。
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想进行更大范围的穷尽扫描时，再覆盖这些环境变量。
- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，再通过 `scripts/package-openclaw-for-docker.mjs` 将 OpenClaw 打包为一个 npm tarball，然后构建 / 复用两个 `scripts/e2e/Dockerfile` 镜像。裸镜像只包含用于安装 / 更新 / 插件依赖 lane 的 Node / Git 运行器；这些 lane 会挂载预构建 tarball。功能镜像则会将同一个 tarball 安装到 `/app` 中，用于已构建应用功能 lane。Docker lane 定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 会执行所选计划。这个聚合器使用带权重的本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限会阻止重型 live、npm 安装和多服务 lane 同时全部启动。如果某个单独 lane 比当前活动上限更重，调度器仍可在池为空时启动它，然后在容量再次可用之前让它单独运行。默认值为 10 个槽位、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有当 Docker 主机有更多余量时，才调整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。该运行器默认会执行 Docker 预检，移除陈旧的 OpenClaw E2E 容器，每 30 秒打印一次状态，将成功 lane 的耗时存储到 `.artifacts/docker-tests/lane-timings.json`，并在后续运行中利用这些耗时优先启动较长的 lane。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可打印带权重的 lane 清单而不构建或运行 Docker，或使用 `node scripts/test-docker-all.mjs --plan-json` 打印所选 lane、包 / 镜像需求和凭证的 CI 计划。
- `Package Acceptance` 是 GitHub 原生的包闸门，用于回答“这个可安装 tarball 作为产品是否可用？”。它会从 `source=npm`、`source=ref`、`source=url` 或 `source=artifact` 解析一个候选包，将其作为 `package-under-test` 上传，然后针对这个精确 tarball 运行可复用的 Docker E2E lanes，而不是重新打包所选 ref。`workflow_ref` 选择可信的工作流 / harness 脚本，而 `package_ref` 则在 `source=ref` 时选择要打包的源码提交 / 分支 / 标签；这样当前的验收逻辑就可以验证较早的可信提交。各个 profile 按覆盖广度排序：`smoke` 是快速安装 / 渠道 / 智能体加 gateway / 配置检查，`package` 覆盖包 / 更新 / 插件契约，并且是大多数 Parallels 包 / 更新覆盖的默认原生替代方案，`product` 会额外加入 MCP 渠道、cron / 子智能体清理、OpenAI Web 搜索以及 OpenWebUI，`full` 则会运行包含 OpenWebUI 的发布路径 Docker 分块。发布验证会运行一个自定义 package 增量（`bundled-channel-deps-compat plugins-offline`）以及 Telegram package QA，因为发布路径 Docker 分块已经覆盖了重叠的包 / 更新 / 插件 lanes。由制品生成的定向 GitHub Docker 重跑命令，在可用时会包含先前的包制品和已准备镜像输入，因此失败的 lane 可以避免重新构建包和镜像。
- 构建和发布检查会在 tsdown 之后运行 `scripts/check-cli-bootstrap-imports.mjs`。这个 guard 会从 `dist/entry.js` 和 `dist/cli/run-main.js` 开始遍历静态构建图，并在命令分发之前若启动导入了 Commander、prompt UI、undici 或 logging 等包依赖时失败；它还会将内置 gateway 运行分块控制在预算之内，并拒绝静态导入已知的冷 gateway 路径。打包 CLI 冒烟测试还覆盖根 help、onboard help、doctor help、status、config schema 以及一个 model-list 命令。
- `Package Acceptance` 的旧版兼容性上限是 `2026.4.25`（包含 `2026.4.25-beta.*`）。在该截止版本及之前，harness 只容忍已发布包中的元数据缺口：省略的私有 QA inventory 条目、缺失的 `gateway install --wrapper`、tarball 派生 git fixture 中缺失的 patch 文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。对于 `2026.4.25` 之后的包，这些路径都会被视为严格失败。
- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层级的集成路径。
实时模型 Docker 运行器还会只绑定挂载所需的 CLI 认证 home 目录（如果运行未收窄，则挂载所有受支持的目录），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改宿主机认证存储：
live 模型 Docker 运行器还会只绑定挂载所需的 CLI 鉴权 home（如果运行未收窄，则挂载所有受支持的 home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会改动主机鉴权存储：
- 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
- ACP 绑定冒烟测试：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`；默认覆盖 Claude、Codex 和 Gemini，通过 `pnpm test:docker:live-acp-bind:droid` 和 `pnpm test:docker:live-acp-bind:opencode` 提供严格的 Droid / OpenCode 覆盖）
- ACP 绑定冒烟测试：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`；默认覆盖 Claude、Codex 和 Gemini，对 Droid / OpenCode 的严格覆盖可通过 `pnpm test:docker:live-acp-bind:droid` 和 `pnpm test:docker:live-acp-bind:opencode` 运行）
- CLI 后端冒烟测试：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`）
- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`）
- Gateway 网关 + 开发智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
- 可观测性冒烟测试：`pnpm qa:otel:smoke` 是一个私有 QA 源代码检出通道。它有意不属于 package Docker 发布通道的一部分，因为 npm tarball 不包含 QA Lab。
- Open WebUI 实时冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- 新手引导向导（TTY、完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
- Npm tarball 新手引导 / 渠道 / 智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，默认通过 env-ref 新手引导配置 OpenAI 并配置 Telegram，验证 doctor 会修复已激活插件的运行时依赖，并运行一次模拟的 OpenAI 智能体轮次。使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 可复用预构建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 可跳过宿主机构建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。
- 更新渠道切换冒烟测试：`pnpm test:docker:update-channel-switch` 会在 Docker 中全局安装打包后的 OpenClaw tarball，从 package `stable` 切换到 git `dev`，验证持久化渠道和插件在更新后仍然可用，然后再切回 package `stable` 并检查更新状态。
- Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
- 可观测性冒烟测试：`pnpm qa:otel:smoke` 是一个私有 QA 源码检出 lane。它刻意不属于包 Docker 发布 lanes，因为 npm tarball 不包含 QA Lab。
- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- 新手引导 wizard（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
- npm tarball 新手引导 / 渠道 / 智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装已打包的 OpenClaw tarball，通过 env-ref 新手引导配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活插件的运行时依赖，然后运行一次模拟的 OpenAI 智能体轮次。使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 可复用预构建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 可跳过主机构建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。
- 更新渠道切换冒烟测试：`pnpm test:docker:update-channel-switch` 会在 Docker 中全局安装已打包的 OpenClaw tarball，从包 `stable` 切换到 git `dev`，验证持久化的渠道和插件在更新后仍可工作，然后再切回包 `stable` 并检查更新状态。
- 会话运行时上下文冒烟测试：`pnpm test:docker:session-runtime-context` 会验证隐藏运行时上下文转录的持久化，以及 doctor 对受影响的重复 prompt-rewrite 分支的修复。
- Bun 全局安装冒烟测试：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装它，并验证 `openclaw infer image providers --json` 返回的是内置图像提供商，而不是卡住。使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 可复用预构建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 可跳过宿主机构建，或使用 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像中复制 `dist/`。
- 安装器 Docker 冒烟测试：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟测试默认使用 npm `latest` 作为稳定基线，然后升级到候选 tarball。在本地可用 `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` 覆盖，或在 GitHub 上通过 Install Smoke 工作流的 `update_baseline_version` 输入覆盖。非 root 安装器检查会保留独立的 npm 缓存，这样 root 拥有的缓存条目就不会掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重跑之间复用 root / update / direct-npm 缓存。
- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；如果需要直接 `npm install -g` 覆盖，请在本地运行该脚本时不要设置这个环境变量。
- Agents 删除共享工作区 CLI 冒烟测试：`pnpm test:docker:agents-delete-shared-workspace`（脚本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）默认构建根 Dockerfile 镜像，在隔离的容器 home 中植入两个共享同一工作区的智能体，运行 `agents delete --json`，并验证 JSON 合法且共享工作区保留行为正确。可使用 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 复用 install-smoke 镜像。
- Gateway 网关网络（两个容器、WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- 浏览器 CDP 快照冒烟测试：`pnpm test:docker:browser-cdp-snapshot`（脚本：`scripts/e2e/browser-cdp-snapshot-docker.sh`）会构建源码 E2E 镜像加一个 Chromium 层，使用原始 CDP 启动 Chromium，运行 `browser doctor --deep`，并验证 CDP 角色快照覆盖链接 URL、游标提升的可点击元素、iframe 引用和 frame 元数据。
- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个模拟的 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制提供商 schema 拒绝，并检查原始细节出现在 Gateway 网关日志中。
- MCP 渠道 bridge（植入的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile allow / deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`）
- Cron / 子智能体 MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性子智能体运行后清理 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`）
- 插件（安装冒烟测试、ClawHub 安装 / 卸载、marketplace 更新，以及 Claude bundle 启用 / 检查）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
设置 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可跳过实时 ClawHub 部分，或使用 `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` 和 `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` 覆盖默认包。
- 插件更新未变化冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`）
- Bun 全局安装冒烟测试：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装它，并验证 `openclaw infer image providers --json` 返回的是内置图像提供商，而不是卡住。使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 可复用预构建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 可跳过主机构建，或者使用 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。
- 安装器 Docker 冒烟测试：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟测试默认使用 npm `latest` 作为稳定基线，然后升级到候选 tarball。你可以在本地用 `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` 覆盖，或在 GitHub 上通过 Install Smoke 工作流的 `update_baseline_version` 输入覆盖。非 root 安装器检查会保持隔离的 npm 缓存，这样 root 拥有的缓存条目就不会掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重复运行之间复用 root / update / direct-npm 缓存。
- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；若需要 direct `npm install -g` 覆盖，请在本地运行该脚本且不要设置这个环境变量。
- Agents 删除共享工作区 CLI 冒烟测试：`pnpm test:docker:agents-delete-shared-workspace`（脚本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）默认构建根 Dockerfile 镜像，在隔离的容器 home 中为两个 Agents 预置一个工作区，运行 `agents delete --json`，并验证 JSON 合法以及工作区保留行为。使用 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 可复用 install-smoke 镜像。
- Gateway 网关网络（两个容器，WS 鉴权 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- 浏览器 CDP 快照冒烟测试：`pnpm test:docker:browser-cdp-snapshot`（脚本：`scripts/e2e/browser-cdp-snapshot-docker.sh`）会构建源码 E2E 镜像以及 Chromium 层，使用原始 CDP 启动 Chromium，运行 `browser doctor --deep`，并验证 CDP 角色快照覆盖链接 URL、光标提升的可点击元素、iframe 引用以及 frame 元数据。
- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个模拟的 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制提供商 schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。
- MCP 渠道桥接（已预置的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- Pi 内置 MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi 配置文件 allow / deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`）
- cron / 子智能体 MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性子智能体运行后清理 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`）
- 插件（安装冒烟测试、ClawHub 安装 / 卸载、marketplace 更新，以及 Claude 内置包启用 / 检查）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
设置 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可跳过 live ClawHub 代码块，或通过 `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` 和 `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` 覆盖默认包。
- 插件更新无变更冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`）
- 配置热重载元数据冒烟测试：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`）
- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在宿主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，在完成一次新的本地构建后使用 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过宿主机构建，或使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整的 Docker 聚合运行器和发布路径内置渠道分块会先统一预打包这个 tarball，然后将内置渠道检查分片为独立通道，其中包括针对 Telegram、Discord、Slack、Feishu、memory-lancedb 和 ACPX 的独立更新通道。发布分块会将渠道冒烟测试、更新目标和设置 / 运行时契约拆分为 `bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`；聚合的 `bundled-channels` 分块仍可用于手动重跑。发布工作流还会拆分提供商安装器分块和内置插件安装 / 卸载分块；旧版的 `package-update`、`plugins-runtime` 和 `plugins-integrations` 分块仍保留为手动重跑时的聚合别名。直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 缩小渠道矩阵，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 缩小更新场景。该通道还会验证 `channels.<id>.enabled=false` 和 `plugins.entries.<id>.enabled=false` 会抑制 doctor / 运行时依赖修复。
- 迭代时若要缩小内置插件运行时依赖范围，可禁用无关场景，例如：
- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 可复用镜像，使用 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 可在刚完成本地构建后跳过主机重建，或者使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整的 Docker 聚合器和发布路径 bundled-channel 分块会先统一预打包这个 tarball，然后将内置渠道检查分片为独立 lanes，包括 Telegram、Discord、Slack、Feishu、memory-lancedb 和 ACPX 的单独更新 lanes。发布分块会将渠道冒烟测试、更新目标以及设置 / 运行时契约拆分为 `bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`；聚合的 `bundled-channels` 分块仍可用于手动重跑。发布工作流还会拆分提供商安装器分块以及内置插件安装 / 卸载分块；旧版的 `package-update`、`plugins-runtime` 和 `plugins-integrations` 分块仍保留为手动重跑的聚合别名。直接运行内置 lane 时，使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 可收窄渠道矩阵，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 可收窄更新场景。该 lane 还会验证 `channels.<id>.enabled=false` 和 `plugins.entries.<id>.enabled=false` 会抑制 doctor / 运行时依赖修复。
- 迭代时若想收窄内置插件运行时依赖范围，可禁用无关场景，例如：
`OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`。
如需手动预构建并复用共享功能镜像：
若要手动预构建并复用共享功能镜像：
```bash
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels
```
诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 之类的套件专用镜像覆盖项在设置时仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果它尚未存在于本地，这些脚本会先拉取它。QR 和安装器 Docker 测试保留各自的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的已构建应用运行时。
像 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这样的测试套件专用镜像覆盖项在设置时仍然优先。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果镜像尚未存在于本地，这些脚本会先拉取它。QR 和安装器 Docker 测试保留各自独立的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的已构建应用运行时。
实时模型 Docker 运行器还会以只读方式绑定挂载当前检出内容，并将其暂存到容器内的临时工作目录中。这样既能让运行时镜像保持精简，又能让 Vitest 针对你精确的本地源码 / 配置运行。暂存步骤会跳过大型的本地专用缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或 Gradle 输出目录，因此 Docker 实时运行不会花费数分钟去复制机器专属制品。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探测就不会在容器内启动真实的 Telegram / Discord / 等渠道工作进程。
`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 Gateway 网关实时覆盖时，也要透传 `OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是一个更高层的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，再针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过 Open WebUI 登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。
首次运行可能会明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自己的冷启动设置。
这个通道需要一个可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`
（默认为 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
成功运行会打印一个小型 JSON 负载，例如 `{ "ok": true, "model":
live 模型 Docker 运行器还会以只读方式绑定挂载当前检出，并将其暂存到容器内的临时工作目录中。这样可以让运行时镜像保持精简，同时仍能针对你当前精确的本地源码 / 配置运行 Vitest。暂存步骤会跳过大型本地专用缓存和应用构建输出，如
`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或
Gradle 输出目录，因此 Docker live 运行不会花费数分钟复制机器专属制品。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关 live 探测就不会在容器内启动真实的 Telegram / Discord / 等渠道 worker。
`test:docker:live-models` 仍会运行 `pnpm test:live`，因此当你需要从该 Docker lane 中收窄或排除 Gateway 网关 live 覆盖时，也要透传
`OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw gateway 容器，再启动一个固定版本的 Open WebUI 容器连接到该 gateway，通过 Open WebUI 完成登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一次真实聊天请求。
首次运行可能会明显更慢，因为 Docker 可能需要拉取
Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置。
这个 lane 需要一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`
（默认是 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
成功运行会打印一小段 JSON 载荷，例如 `{ "ok": true, "model":
"openclaw/default", ... }`。
`test:docker:mcp-channels` 刻意保持确定性，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个植入好的 Gateway 网关容器，再启动第二个容器来拉起 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio MCP bridge 发送的 Claude 风格渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。
`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要实时模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP 探测服务器，通过嵌入式 Pi bundle MCP 运行时实例化该服务器，执行工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会过滤掉它们。
`test:docker:cron-mcp-cleanup` 是确定性的，不需要实时模型密钥。它会启动一个带有真实 stdio MCP 探测服务器的植入式 Gateway 网关，运行一次隔离的 cron 轮次和一次 `/subagents spawn` 一次性子进程轮次，然后验证 MCP 子进程会在每次运行后退出。
`test:docker:mcp-channels` 刻意设计为确定性测试，不需要真实的
Telegram、Discord 或 iMessage 账户。它会启动一个已预置的 Gateway 网关
容器，再启动第二个容器来生成 `openclaw mcp serve`，然后通过真实的 stdio MCP bridge 验证路由对话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 +
权限通知。通知检查会直接检查原始 stdio MCP 帧，因此这个冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。
`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要 live
模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP probe server，通过嵌入式 Pi 内置 MCP 运行时实例化该服务器，执行该工具，然后验证 `coding` 和 `messaging` 会保留
`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。
`test:docker:cron-mcp-cleanup` 是确定性的，不需要 live 模型
密钥。它会启动一个带真实 stdio MCP probe server 的已预置 Gateway 网关，运行一次隔离的 cron 轮次和一次 `/subagents spawn` 一次性子轮次，然后验证 MCP 子进程会在每次运行后退出。
手动 ACP 自然语言线程冒烟测试（非 CI）：
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...`
- 保留这个脚本用于回归 / 调试工作流。将来它可能还需要用于 ACP 线程路由验证，因此不要删除它。
- 为回归 / 调试工作流保留此脚本。它未来可能还会再次用于 ACP 线程路由验证，因此不要删除它。
常用环境变量：
- `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw`
- `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace`
- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前加载
- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于仅验证从 `OPENCLAW_PROFILE_FILE` 加载的环境变量，使用临时配置 / 工作区目录，并且不挂载外部 CLI 认证目录
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存的 CLI 安装
- `$HOME` 下的外部 CLI 认证目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...`
- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前 source
- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于只验证从 `OPENCLAW_PROFILE_FILE` source 的环境变量，同时使用临时配置 / 工作区目录且不挂载外部 CLI 鉴权
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装
- `$HOME` 下的外部 CLI 鉴权目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...`
- 默认目录：`.minimax`
- 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json`
- 收窄后的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件
- 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或逗号列表（如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`）手动覆盖
- 收窄的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件
- 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`，或像 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 这样的逗号列表手动覆盖
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于收窄运行范围
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内筛选提供商
- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用现有的 `openclaw:local-live` 镜像，以便在不需要重建时重跑
@ -550,72 +529,72 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOC
## 文档完整性检查
在修改文档后运行文档检查：`pnpm check:docs`。
当你还需要检查页内标题时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。
文档编辑后运行文档检查：`pnpm check:docs`。
当你还需要检查页内标题时，运行完整的 Mintlify 锚点验证：`pnpm docs:check-links:anchors`。
## 离线回归测试（对 CI 安全）
这些是在没有真实提供商的情况下运行的“真实流水线”回归测试：
- Gateway 网关工具调用（模拟 OpenAI、真实 Gateway 网关 + Agent loop）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
- Gateway 网关向导（WS `wizard.start` / `wizard.next`，强制写入配置 + 认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
- Gateway 网关工具调用（模拟 OpenAI，真实 gateway + Agent loop）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
- Gateway 网关向导（WS `wizard.start` / `wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
## 智能体可靠性评估（Skills）
我们已经有一些对 CI 安全的测试，它们的行为类似“智能体可靠性评估”：
我们已经有一些对 CI 安全的测试，其行为类似“智能体可靠性评估”：
- 通过真实 Gateway 网关 + Agent loop 的模拟工具调用（`src/gateway/gateway.test.ts`）。
- 验证会话布线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。
- 通过真实 gateway + Agent loop 的模拟工具调用（`src/gateway/gateway.test.ts`）。
- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。
Skills 方面仍然缺少的内容（参见 [Skills](/zh-CN/tools/skills)）：
针对 Skills（参见 [Skills](/zh-CN/tools/skills)）目前仍然缺失的内容：
- **决策**：当提示词中列出 Skills 时，智能体是否会选择正确的 Skills（或避免选择无关的 Skills）？
- **合规性**：智能体是否会在使用前读取 `SKILL.md` 并遵循所需步骤 / 参数？
- **工作流契约**：断言工具顺序、会话历史延续和沙箱边界的多轮场景。
- **决策能力：** 当提示中列出 Skills 时，智能体是否会选择正确的 Skill（或避免选择无关的 Skill）？
- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循必需的步骤 / 参数？
- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。
未来的评估应当优先保持确定性：
未来的评估应首先保持确定性：
- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、技能文件读取和会话布线。
- 一小组以 Skills 为重点的场景（使用 vs 避免、门控、提示注入）。
- 仅在对 CI 安全的套件就绪之后，才添加可选的实时评估（显式启用、由环境变量控制）。
- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话接线。
- 一小套以 Skill 为中心的场景（使用 vs 避免、闸门控制、提示注入）。
- 只有在对 CI 安全的测试套件就位后，才添加可选的 live 评估（显式启用、受环境变量控制）。
## 契约测试（插件和渠道形状）
契约测试会验证每个已注册的插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组形状和行为断言。默认的 `pnpm test` 单元测试通道会有意跳过这些共享接缝和冒烟测试文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。
契约测试用于验证每个已注册的插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组形状和行为断言。默认的 `pnpm test` 单元 lane 会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行这些契约命令。
### 命令
- 所有契约测试：`pnpm test:contracts`
- 仅渠道契约测试：`pnpm test:contracts:channels`
- 仅提供商契约测试：`pnpm test:contracts:plugins`
- 所有契约：`pnpm test:contracts`
- 仅渠道契约：`pnpm test:contracts:channels`
- 仅提供商契约：`pnpm test:contracts:plugins`
### 渠道契约测试
### 渠道契约
位于 `src/channels/plugins/contracts/*.contract.test.ts`：
- **plugin** - 基础插件形状（id、名称、能力）
- **plugin** - 基本插件形状（id、name、capabilities）
- **setup** - 设置向导契约
- **session-binding** - 会话绑定行为
- **outbound-payload** - 消息负载结构
- **outbound-payload** - 消息载荷结构
- **inbound** - 入站消息处理
- **actions** - 渠道动作处理器
- **actions** - 渠道操作处理器
- **threading** - 线程 ID 处理
- **directory** - 目录 / roster API
- **group-policy** - 群组策略执行
### 提供商 Status 契约测试
### 提供商 Status 契约
位于 `src/plugins/contracts/*.contract.test.ts`。
- **status** - 渠道 Status 探测
- **registry** - 插件注册表形状
### 提供商契约测试
### 提供商契约
位于 `src/plugins/contracts/*.contract.test.ts`：
- **auth** - 认证流程契约
- **auth-choice** - 认证方式 / 选择
- **auth** - 鉴权流程契约
- **auth-choice** - 鉴权选择 / 选取
- **catalog** - 模型目录 API
- **discovery** - 插件发现
- **loader** - 插件加载
@ -625,24 +604,24 @@ Skills 方面仍然缺少的内容（参见 [Skills](/zh-CN/tools/skills)）：
### 何时运行
- 在更改 plugin-sdk 导出或子路径之后
- 在添加或修改渠道或提供商插件之后
- 在重构插件注册或发现逻辑之后
- 修改 `plugin-sdk` 导出或子路径之后
- 添加或修改渠道或提供商插件之后
- 重构插件注册或发现之后
契约测试会在 CI 中运行，并且不需要真实 API 密钥。
契约测试会在 CI 中运行，不需要真实 API 密钥。
## 添加回归测试（指南）
当你修复一个在实时环境中发现的提供商 / 模型问题时：
当你修复在 live 中发现的提供商 / 模型问题时：
- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换）
- 如果它本质上只能在实时环境中复现（限流、认证策略），则让该实时测试保持收窄，并通过环境变量显式启用
- 优先定位到能捕捉该缺陷的最小层级：
- 如果它本质上只能是 live 测试（速率限制、鉴权策略），就让该 live 测试保持收窄，并通过环境变量显式启用
- 优先针对能捕获该缺陷的最小层级：
- 提供商请求转换 / 重放缺陷 → 直接模型测试
- Gateway 网关会话 / 历史 / 工具流水线缺陷 → Gateway 网关实时冒烟测试或对 CI 安全的 Gateway 网关模拟测试
- SecretRef 遍历防护：
- `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。
- 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会有意在未分类目标 id 上失败，这样新类别就不会被悄悄跳过。
- gateway 会话 / 历史 / 工具流水线缺陷 → Gateway 网关 live 冒烟测试或对 CI 安全的 Gateway 网关模拟测试
- SecretRef 遍历护栏：
- `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段执行 id 会被拒绝。
- 如果你在 `src/secrets/target-registry-data.ts` 中新增了一个 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在目标 id 未分类时有意失败，因此新类别无法被静默跳过。
## 相关内容

104
docs/zh-CN/plugins/compatibility.md
View File

@ -1,45 +1,45 @@
---
read_when:
- 你维护一个 OpenClaw 插件
- 你看到一条插件兼容性警告
- 你正在规划一次插件 SDK 或清单迁移
- 你负责维护一个 OpenClaw 插件
- 你看到一个插件兼容性警告
- 你正在规划一个插件 SDK 或清单迁移
summary: 插件兼容性契约、弃用元数据和迁移预期
title: 插件兼容性
x-i18n:
generated_at: "2026-04-28T01:06:39Z"
generated_at: "2026-04-28T01:58:12Z"
model: gpt-5.4
provider: openai
source_hash: 9cb004d9959f1892f3bebcdfb9bee3fd78fc3322a2cbee4e8078c41a3f6706c6
source_hash: eecf94743cf34c5b773bfa8066164f90b7c8a75667c43f3f1002d32ec1d04902
source_path: plugins/compatibility.md
workflow: 15
---
OpenClaw 会在移除旧版插件契约之前，通过具名兼容性适配器继续接入这些旧契约。这样可以在 SDK、清单、设置、配置和智能体运行时契约不断演进时，保护现有的内置插件和外部插件。
OpenClaw 会在移除旧版插件契约之前，继续通过具名兼容性适配器接通这些旧契约。这样可以在 SDK、清单、设置、配置和智能体运行时契约演进期间，保护现有的内置插件和外部插件。
## 兼容性注册表
插件兼容性契约会在核心注册表 `src/plugins/compat/registry.ts` 中跟踪。
每条记录都包含：
每条记录包含：
- 一个稳定的兼容性代码
- 稳定的兼容性代码
- 状态：`active`、`deprecated`、`removal-pending` 或 `removed`
- 所属方：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心
- 归属方：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心
- 适用时的引入日期和弃用日期
- 替代方案指引
- 覆盖旧行为和新行为的文档、诊断和测试
- 替代指引
- 覆盖旧行为和新行为的文档、诊断信息和测试
该注册表是维护者规划和未来插件检查器检查的来源。如果某个面向插件的行为发生变化，请在添加适配器的同一变更中新增或更新对应的兼容性记录。
该注册表是维护者规划和未来插件检查器检查的来源。如果某个面向插件的行为发生变化，请在添加适配器的同一次变更中，新增或更新对应的兼容性记录。
Doctor 修复和迁移兼容性会在 `src/commands/doctor/shared/deprecation-compat.ts` 中单独跟踪。这些记录涵盖旧版配置结构、安装台账布局以及修复垫片；即使运行时兼容路径被移除，它们也可能仍需继续保留。
Doctor 修复和迁移兼容性会单独在 `src/commands/doctor/shared/deprecation-compat.ts` 中跟踪。这些记录涵盖旧配置结构、安装账本布局以及修复垫片；即使运行时兼容路径被移除之后，它们也可能仍需保留。
发布前的全面检查应同时检查这两个注册表。不要仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认不存在仍然需要该修复的受支持升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道移出核心，插件归属和配置范围可能会发生变化。
发布前的全面检查应同时检查这两个注册表。不要仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认是否仍存在需要该修复的受支持升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道移出核心，插件归属关系和配置范围可能会变化。
## 插件检查器包
插件检查器应作为独立的包或仓库，存放在 OpenClaw 核心仓库之外，并以带版本的兼容性契约和清单契约为基础。
插件检查器应当位于核心 OpenClaw 仓库之外，作为一个独立的包或仓库，并以已版本化的兼容性契约和清单契约为基础。
首个版本的 CLI 应该是：
首个版本的 CLI 应为：
```sh
openclaw-plugin-inspector ./my-plugin
@ -47,57 +47,71 @@ openclaw-plugin-inspector ./my-plugin
它应输出：
- 清单 / 模式验证
- 正在检查的契约兼容性版本
- 清单 / schema 验证
- 正在检查的契约兼容版本
- 安装 / 来源元数据检查
- 冷路径导入检查
- 弃用和兼容性警告
在 CI 注释中，如果需要稳定的机器可读输出，请使用 `--json`。OpenClaw 核心应暴露检查器可消费的契约和夹具，但不应从主 `openclaw` 包发布该检查器二进制文件。
在 CI 注解中，使用 `--json` 获取稳定的机器可读输出。OpenClaw 核心应暴露检查器可消费的契约和夹具，但不应从主 `openclaw` 包发布检查器二进制文件。
### 维护者验收通道
在针对 OpenClaw 插件包验证外部检查器时，应使用 Blacksmith Testbox 作为可安装包验收通道。在包构建完成后，从一个干净的 OpenClaw 检出目录运行：
```sh
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>
```
请将此通道保持为维护者选择启用，因为它会安装外部 npm 包，并且可能检查在仓库外克隆的插件包。本地仓库防护涵盖 SDK 导出映射、兼容性注册表元数据、已弃用 SDK 导入的清理进度，以及内置扩展导入边界；而 Testbox 中的检查器验证则覆盖外部插件作者实际使用该包的场景。
## 弃用策略
OpenClaw 不应在引入某个插件契约替代方案的同一版本中移除已文档化的原契约。
OpenClaw 不应在引入某个插件契约替代方案的同一个版本中，就移除该已文档化的插件契约。
迁移顺序如下：
1. 添加新契约。
2. 通过具名兼容性适配器继续接入旧行为。
3. 当插件作者可以采取行动时，发出诊断或警告。
2. 继续通过具名兼容性适配器接通旧行为。
3. 在插件作者可以采取行动时发出诊断或警告。
4. 记录替代方案和时间线。
5. 测试旧路径和新路径。
6. 等待已宣布的迁移窗口结束。
7. 只有在获得明确的破坏性发布批准后才移除。
5. 为旧路径和新路径都编写测试。
6. 等待已公告的迁移窗口结束。
7. 仅在获得明确的破坏性版本批准后再移除。
已弃用记录必须包含警告开始日期、替代方案、文档链接，以及不晚于警告开始后三个月的最终移除日期。除非维护者明确决定它应作为永久兼容性保留并将其标记为 `active`，否则不要添加一个移除窗口不明确的已弃用兼容路径。
已弃用记录必须包含警告开始日期、替代方案、文档链接，以及最晚不超过警告开始后三个月的最终移除日期。不要添加一个移除窗口无限期开放的已弃用兼容路径，除非维护者明确决定它是永久兼容性，并将其标记为 `active`。
## 当前兼容性领域
## 当前兼容性范围
当前的兼容性记录包括：
当前兼容性记录包括：
- 旧版宽泛 SDK 导入，例如 `openclaw/plugin-sdk/compat`
- 旧版仅钩子插件结构和 `before_agent_start`
- 旧版 `activate(api)` 插件入口点，在插件迁移到 `register(api)` 期间继续支持
- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth` Status 构建器、`openclaw/plugin-sdk/test-utils`（由更聚焦的 `openclaw/plugin-sdk/*` 测试子路径替代），以及 `ClawdbotConfig` / `OpenClawSchemaType` 类型别名
- 旧版仅钩子插件形态和 `before_agent_start`
- 旧版 `activate(api)` 插件入口点，同时插件正迁移到 `register(api)`
- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth` 状态构建器、`openclaw/plugin-sdk/test-utils`（已由更聚焦的 `openclaw/plugin-sdk/*` 测试子路径替代），以及 `ClawdbotConfig` / `OpenClawSchemaType` 类型别名
- 内置插件允许列表和启用行为
- 旧版提供商 / 渠道环境变量清单元数据
- 旧版提供商插件钩子和类型别名，在提供商迁移到显式目录、认证、思考、回放和传输钩子期间继续支持
- 旧版提供商插件钩子和类型别名，同时提供商正迁移到显式目录、凭证、思考、回放和传输钩子
- 旧版运行时别名，例如 `api.runtime.taskFlow`、`api.runtime.subagent.getSession`、`api.runtime.stt`，以及已弃用的 `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
- 旧版 memory 插件拆分注册方式，在 memory 插件迁移到 `registerMemoryCapability` 期间继续支持
- 旧版渠道 SDK 辅助方法，用于原生消息模式、提及门控、入站信封格式化和审批能力嵌套
- 旧版渠道路由键和可比较目标辅助别名，在插件迁移到 `openclaw/plugin-sdk/channel-route` 期间继续支持
- 旧版 Memory 插件拆分注册，同时 Memory 插件正迁移到 `registerMemoryCapability`
- 旧版渠道 SDK 辅助工具，用于原生消息 schema、提及门控、入站信封格式化和审批能力嵌套
- 旧版渠道路由键和可比较目标辅助别名，同时插件正迁移到 `openclaw/plugin-sdk/channel-route`
- 正在被清单贡献归属替代的激活提示
- `setup-api` 运行时回退，在设置描述符迁移到冷路径 `setup.requiresRuntime: false` 元数据期间继续支持
- 提供商 `discovery` 钩子，在提供商目录钩子迁移到 `catalog.run(...)` 期间继续支持
- 渠道 `showConfigured` / `showInSetup` 元数据，在渠道包迁移到 `openclaw.channel.exposure` 期间继续支持
- 旧版运行时策略配置键，在 Doctor 将操作员迁移到 `agentRuntime` 期间继续支持
- 生成的内置渠道配置元数据回退，在注册表优先的 `channelConfigs` 元数据落地期间继续支持
- 持久化插件注册表禁用和安装迁移环境变量标志，在修复流程将操作员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix` 期间继续支持
- 旧版插件自有的 web search、web fetch 和 x_search 配置路径，在 Doctor 将它们迁移到 `plugins.entries.<plugin>.config` 期间继续支持
- 旧版 `plugins.installs` 手写配置和内置插件加载路径别名，在安装元数据迁移到状态管理的插件台账期间继续支持
- `setup-api` 运行时回退，同时设置描述符正迁移到冷路径 `setup.requiresRuntime: false` 元数据
- 提供商 `discovery` 钩子，同时提供商目录钩子正迁移到 `catalog.run(...)`
- 渠道 `showConfigured` / `showInSetup` 元数据，同时渠道包正迁移到 `openclaw.channel.exposure`
- 旧版运行时策略配置键，同时 Doctor 正将操作员迁移到 `agentRuntime`
- 生成的内置渠道配置元数据回退，同时以注册表优先的 `channelConfigs` 元数据正在落地
- 持久化插件注册表禁用和安装迁移环境变量标志，同时修复流程正将操作员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix`
- 旧版插件自有 web search、web fetch 和 x_search 配置路径，同时 Doctor 正将它们迁移到 `plugins.entries.<plugin>.config`
- 旧版 `plugins.installs` 手写配置和内置插件加载路径别名，同时安装元数据正迁移到状态管理的插件账本中
新插件代码应优先使用注册表和特定迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断和发布说明宣布移除窗口。
新的插件代码应优先使用注册表和对应迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断信息和发布说明公布移除窗口。
## 发布说明
发布说明应包含即将到来的插件弃用信息，并附上目标日期和迁移文档链接。必须先发出这类警告，兼容路径才能转为 `removal-pending` 或 `removed`。
发布说明应包含即将到来的插件弃用项、目标日期以及迁移文档链接。这个警告必须先发生，然后兼容路径才能进入 `removal-pending` 或 `removed`。

243
docs/zh-CN/plugins/sdk-subpaths.md
View File

@ -1,43 +1,43 @@
---
read_when:
- 为插件导入选择合适的 plugin-sdk 子路径
- 审查 bundled-plugin 子路径和辅助接口
- 审计 bundled-plugin 子路径和辅助接口
summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-28T01:47:20Z"
generated_at: "2026-04-28T01:58:12Z"
model: gpt-5.4
provider: openai
source_hash: 67de782db5ef5a60ffe104ba67749590e70acb31f615e8c6e5049f688a3c2422
source_hash: c56a83c4cf89a40286328bd58079af21a1f5fcf2392c5f6a1e08f873c65e49d6
source_path: plugins/sdk-subpaths.md
workflow: 15
---
plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。
本页按用途分组，汇总常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也包含预留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为推荐接口，否则它们都属于实现细节。
插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径公开。
本页按用途分组整理了常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会出现为 bundled-plugin 保留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。
关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
## 插件入口
| 子路径 | 关键导出 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/testing` | 面向旧版插件测试的广泛兼容 barrel；新扩展测试优先使用聚焦的测试子路径 |
| `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 |
| `plugin-sdk/channel-test-helpers` | 渠道账户生命周期、目录、发送配置、运行时 mock、钩子，以及通用渠道契约测试辅助工具 |
| `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 |
| `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公共产物、运行时 API、导入副作用以及直接导入契约辅助工具 |
| `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导以及运行时任务流夹具 |
| `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、Web 搜索/抓取以及向导契约辅助工具 |
| `plugin-sdk/test-env` | 测试环境、抓取/网络、实时测试、临时文件系统以及时间控制夹具 |
| `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、Skill、智能体消息、系统事件、终端、分块处理、认证令牌以及类型化用例测试夹具 |
| `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` |
| `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/testing` | 面向旧版插件测试的宽泛兼容 barrel；对于新的扩展测试，优先使用更聚焦的测试子路径 |
| `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 |
| `plugin-sdk/channel-test-helpers` | 渠道账户生命周期、目录、发送配置、运行时 mock、钩子，以及通用渠道契约测试辅助工具 |
| `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 |
| `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公开产物、运行时 API、导入副作用以及直接导入契约辅助工具 |
| `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流 fixture |
| `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、媒体能力、网页搜索/抓取以及向导契约辅助工具 |
| `plugin-sdk/provider-http-test-mocks` | 供提供商测试选择启用的 Vitest HTTP/认证 mocks，用于覆盖调用 `plugin-sdk/provider-http` 的场景 |
| `plugin-sdk/test-env` | 测试环境、fetch/网络、实时测试、临时文件系统和时间控制 fixture |
| `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、Skill、智能体消息、系统事件、终端、分块、认证令牌和类型化测试用例 fixture |
| `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` |
| `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` |
<AccordionGroup>
<Accordion title="渠道子路径">
@ -46,7 +46,7 @@ x-i18n:
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享设置向导辅助工具、允许列表提示、设置状态构建器 |
| `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
@ -57,54 +57,54 @@ x-i18n:
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 基元和通用构建器 |
| `plugin-sdk/bundled-channel-config-schema` | 仅供受维护的内置插件使用的内置 OpenClaw 渠道配置 schema |
| `plugin-sdk/channel-config-schema-legacy` | 针对内置渠道配置 schema 的已弃用兼容别名 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带内置契约回退 |
| `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 |
| `plugin-sdk/bundled-channel-config-schema` | 仅供受维护的内置插件使用的 OpenClaw 内置渠道配置 schema |
| `plugin-sdk/channel-config-schema-legacy` | 针对内置渠道配置 schemas 的已弃用兼容别名 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，并带有内置契约回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
| `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量级出站发送依赖查找 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化以及负载规划辅助工具 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和负载规划辅助工具 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对以及已配置绑定辅助工具 |
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道 Status 快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置编辑/读取辅助工具 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信认证/守卫辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 面向入站去抖动、提及匹配、提及策略辅助工具以及 envelope 辅助工具的兼容 barrel |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖动辅助工具 |
| `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时接口的精简提及策略、提及标记和提及文本辅助工具 |
| `plugin-sdk/direct-dm` | 共享私信认证/保护辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 面向入站防抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容 barrel |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站防抖辅助工具 |
| `plugin-sdk/channel-mention-gating` | 精简的提及策略、提及标记和提及文本辅助工具，不包含更广泛的入站运行时接口 |
| `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃以及输入中/确认失败的渠道日志辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃以及正在输入/确认失败的渠道日志辅助工具 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
| `plugin-sdk/channel-route` | 共享路由规范化、基于解析器的目标解析、线程 ID 字符串化、去重/紧凑路由键、已解析目标类型，以及路由/目标比较辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` |
| `plugin-sdk/channel-targets` | 目标解析辅助工具；需要进行路由比较的调用方应使用 `plugin-sdk/channel-route` |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-secret-runtime` | 精简的秘密契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及 secret target 类型 |
| `plugin-sdk/channel-secret-runtime` | 精简的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及密钥目标类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 |
| `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具 |
| `plugin-sdk/lmstudio` | 用于设置、目录发现和运行时模型准备的受支持 LM Studio 提供商门面 |
| `plugin-sdk/lmstudio-runtime` | 用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具的受支持 LM Studio 运行时门面 |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助工具 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
@ -115,24 +115,24 @@ x-i18n:
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay 策略构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助工具 |
| `plugin-sdk/provider-catalog-runtime` | 用于契约测试的提供商目录增强运行时钩子和插件提供商注册表接口 |
| `plugin-sdk/provider-catalog-runtime` | 提供商目录增强运行时钩子，以及用于契约测试的插件提供商注册表接口 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart 表单辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 Web 抓取配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Web 抓取提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 Web 搜索配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精简的 Web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter |
| `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的网页抓取配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | 网页抓取提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简网页搜索配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精简的网页搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter |
| `plugin-sdk/provider-web-search` | 网页搜索提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似接口 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似导出 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的抓取、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写的传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地单例/map/缓存辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
| `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 |
</Accordion>
<Accordion title="认证和安全子路径">
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具（包括动态参数菜单格式化）、发送者授权辅助工具 |
@ -141,87 +141,87 @@ x-i18n:
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向热点渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter/gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
| `plugin-sdk/approval-runtime` | exec/插件审批负载辅助工具、原生审批路由/运行时辅助工具，以及诸如 `formatApprovalDisplayPath` 之类的结构化审批显示辅助工具 |
| `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 |
| `plugin-sdk/channel-contract-testing` | 不含宽泛 testing barrel 的精简渠道契约测试辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助工具 |
| `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的精简渠道契约测试辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化和原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 面向热点渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表层辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的精简秘密契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 面向秘密契约/配置解析的精简 `coerceSecretRef` 和 `SecretRef` 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间秘密比较以及秘密收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时接口的精简 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的抓取、SSRF 错误和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 秘密输入解析辅助工具 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表层的精简密钥契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 面向密钥契约/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较和密钥收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时接口的精简 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF 保护 fetch、SSRF 错误和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具，以及原始 websocket/body 强制转换 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
</Accordion>
<Accordion title="运行时和存储子路径">
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、日志器、超时、重试和退避辅助工具 |
| `plugin-sdk/runtime` | 宽泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、日志记录器、超时、重试和退避辅助工具 |
| `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制认证辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/HTTP/交互式辅助工具 |
| `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/HTTP/交互辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子流水线辅助工具 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用以及惰性命令组辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误以及渠道 Status 补丁辅助工具 |
| `plugin-sdk/config-types` | 面向插件配置形状的纯类型配置接口，例如 `OpenClawConfig` 以及渠道/提供商配置类型 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助工具 |
| `plugin-sdk/config-types` | 仅类型配置接口，用于插件配置形状，例如 `OpenClawConfig` 以及渠道/提供商配置类型 |
| `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助工具，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` |
| `plugin-sdk/config-mutation` | 事务性配置变更辅助工具，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` |
| `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助工具，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照 setter |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化，以及重复项/冲突检查，即使内置 Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/完成以及会话标签辅助工具 |
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助工具和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/最终化和会话标签辅助工具 |
| `plugin-sdk/reply-history` | 共享的短时间窗口回复历史辅助工具和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间以及存储变更辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助工具 |
| `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助工具 |
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道/账户 Status 摘要辅助工具、运行时状态默认值以及问题元数据辅助工具 |
| `plugin-sdk/status-helpers` | 共享渠道/账户 Status 摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 从类似 fetch/request 的输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 |
| `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带计时功能的命令运行器，输出经规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助工具 |
| `plugin-sdk/logging-core` | 子系统日志记录器和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 |
| `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助工具，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` |
| `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 原语 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助基元 |
| `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性可信插件接口：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/细节辅助工具，以及尝试结果工具函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性可信插件接口：harness 类型、活跃运行引导/中止辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/细节辅助工具，以及尝试结果工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助工具 |
| `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助工具 |
| `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助工具 |
| `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助工具 |
@ -233,32 +233,32 @@ x-i18n:
| `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助工具 |
| `plugin-sdk/system-event-runtime` | 系统事件队列辅助工具 |
| `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助工具 |
| `plugin-sdk/infra-runtime` | 已弃用兼容垫片；请使用上面更聚焦的运行时子路径 |
| `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请改用上面更聚焦的运行时子路径 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和跟踪上下文辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入的、感知 dispatcher 的运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不依赖宽泛 media runtime 接口的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不含宽泛配置写入/维护导入的会话存储辅助工具 |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入 proxy/guarded-fetch 导入 |
| `plugin-sdk/response-limit-runtime` | 不依赖宽泛媒体运行时接口的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 不引入宽泛配置写入/维护导入的会话存储辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不引入宽泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不引入 markdown/日志导入的精简原始记录/字符串强制转换和规范化辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="能力和测试子路径">
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体抓取/转换/存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如对助手可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如去除对助手可见的文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、校验、OpenAI 兼容 TTS 构建器和语音辅助导出 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助导出 |
@ -273,51 +273,52 @@ x-i18n:
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 |
| `plugin-sdk/zod` | 为 plugin SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | 面向旧版插件测试的广泛兼容 barrel。新的扩展测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` |
| `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，而无需导入仓库测试辅助桥接 |
| `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作/设置/Status 契约、目录断言、账户启动生命周期、发送配置线程化、运行时 mock、Status 问题、出站投递和钩子注册 |
| `plugin-sdk/channel-target-testing` | 面向渠道测试的共享目标解析错误场景套件 |
| `plugin-sdk/plugin-test-contracts` | 插件包、注册、公共产物、直接导入、运行时 API 和导入副作用契约辅助工具 |
| `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、向导、Web 搜索/抓取和流契约辅助工具 |
| `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skill 编写器、智能体消息、系统事件、终端文本、分块处理、认证令牌和类型化用例夹具 |
| `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
| `plugin-sdk/testing` | 面向旧版插件测试的宽泛兼容 barrel。新的扩展测试应改为导入更聚焦的 SDK 子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` |
| `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，无需导入仓库测试辅助桥接 |
| `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用 actions/setup/status 契约、目录断言、账户启动生命周期、发送配置线程化、运行时 mocks、Status 问题、出站投递和钩子注册 |
| `plugin-sdk/channel-target-testing` | 面向渠道测试的共享目标解析错误场景测试套件 |
| `plugin-sdk/plugin-test-contracts` | 插件包、注册、公开产物、直接导入、运行时 API 和导入副作用契约辅助工具 |
| `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、向导、媒体能力、网页搜索/抓取和流契约辅助工具 |
| `plugin-sdk/provider-http-test-mocks` | 供提供商测试选择启用的 Vitest HTTP/认证 mocks，用于覆盖调用 `plugin-sdk/provider-http` 的场景 |
| `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skill 写入器、智能体消息、系统事件、终端文本、分块、认证令牌和类型化测试用例 fixtures |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/配置/文件/CLI 辅助工具 |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商和通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory host Status 辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 面向 Memory 邻接插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 面向搜索管理器访问的活动 Memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host Status 辅助工具别名 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 memory host 事件日志辅助工具 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-markdown` | 面向 Memory 相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活跃 Memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory host Status 辅助工具 |
| `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助接口 |
</Accordion>
<Accordion title="预留的内置辅助子路径">
<Accordion title="保留的 bundled-helper 子路径">
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 形状。`browser-support` 仍然是兼容 barrel。 |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
| 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容/辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 |
| 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容/辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrels。 |
| 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>

158
docs/zh-CN/plugins/sdk-testing.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 你正在为一个插件编写测试
- 你需要来自插件 SDK 的测试工具
- 你需要使用来自插件 SDK 的测试工具
- 你想了解内置插件的契约测试
sidebarTitle: Testing
summary: OpenClaw 插件的测试工具与模式
title: 插件测试
x-i18n:
generated_at: "2026-04-28T01:18:58Z"
generated_at: "2026-04-28T01:58:13Z"
model: gpt-5.4
provider: openai
source_hash: dcc9f0340a651ab742150101ceb78b65ea450b90720bc06e96bb19535db3d83d
source_hash: 264c652d0a857a4e5b570d177011b04318757d30c5169bbcf432c038e6b8b7d5
source_path: plugins/sdk-testing.md
workflow: 15
---
@ -18,14 +18,14 @@ x-i18n:
OpenClaw 插件的测试工具、模式以及 lint 强制规则参考。
<Tip>
**在找测试示例吗？** 操作指南包含已完成的测试示例：
**在找测试示例？** 操作指南中包含了完整的测试示例：
[渠道插件测试](/zh-CN/plugins/sdk-channel-plugins#step-6-test) 和
[提供商插件测试](/zh-CN/plugins/sdk-provider-plugins#step-6-test)。
</Tip>
## 测试工具
**插件 API 模拟导入：** `openclaw/plugin-sdk/plugin-test-api`
**插件 API mock 导入：** `openclaw/plugin-sdk/plugin-test-api`
**渠道契约导入：** `openclaw/plugin-sdk/channel-contract-testing`
@ -39,12 +39,14 @@ OpenClaw 插件的测试工具、模式以及 lint 强制规则参考。
**提供商契约导入：** `openclaw/plugin-sdk/provider-test-contracts`
**环境 / 网络测试导入：** `openclaw/plugin-sdk/test-env`
**提供商 HTTP mock 导入：** `openclaw/plugin-sdk/provider-http-test-mocks`
**环境/网络测试导入：** `openclaw/plugin-sdk/test-env`
**通用夹具导入：** `openclaw/plugin-sdk/test-fixtures`
对于新的插件测试，优先使用下面这些更聚焦的子路径。宽泛的
`openclaw/plugin-sdk/testing` barrel 仅用于兼容旧版。
新插件测试应优先使用下面这些更聚焦的子路径。较宽泛的
`openclaw/plugin-sdk/testing` barrel 仅用于旧版兼容。
```typescript
import {
@ -58,71 +60,78 @@ import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-help
import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks";
import { withEnv, withFetchPreconnect } from "openclaw/plugin-sdk/test-env";
import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fixtures";
```
### 可用导出
| Export | 用途 |
| ----------------------------------------------- | -------------------------------------------------------------------- |
| `createTestPluginApi` | 为直接注册单元测试构建一个最小化的插件 API 模拟。从 `plugin-sdk/plugin-test-api` 导入 |
| `expectChannelInboundContextContract` | 断言渠道入站上下文的结构。从 `plugin-sdk/channel-contract-testing` 导入 |
| `installChannelOutboundPayloadContractSuite` | 安装渠道出站负载契约测试用例。从 `plugin-sdk/channel-contract-testing` 导入 |
| `createStartAccountContext` | 构建渠道账户生命周期上下文。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelActionsContractSuite` | 安装通用渠道消息动作契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelSetupContractSuite` | 安装通用渠道设置契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelStatusContractSuite` | 安装通用渠道 Status 契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `expectDirectoryIds` | 从目录列表函数中断言渠道目录 id。从 `plugin-sdk/channel-test-helpers` 导入 |
| `describePluginRegistrationContract` | 安装插件注册契约检查。从 `plugin-sdk/plugin-test-contracts` 导入 |
| `registerSingleProviderPlugin` | 在加载器冒烟测试中注册一个提供商插件。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `registerProviderPlugin` | 从单个插件中捕获所有提供商类型。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `registerProviderPlugins` | 在多个插件之间捕获提供商注册。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `requireRegisteredProvider` | 断言一个提供商集合包含某个 id。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `createRuntimeEnv` | 构建一个模拟的 CLI / 插件运行时环境。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `createPluginSetupWizardStatus` | 为渠道插件构建设置向导 Status 辅助工具。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `describeOpenAIProviderRuntimeContract` | 安装提供商家族运行时契约检查。从 `plugin-sdk/provider-test-contracts` 导入 |
| `installCommonResolveTargetErrorCases` | 目标解析错误处理的共享测试用例。从 `plugin-sdk/channel-target-testing` 导入 |
| `shouldAckReaction` | 检查渠道是否应添加 ack reaction。从 `plugin-sdk/channel-feedback` 导入 |
| `removeAckReactionAfterReply` | 在回复发送后移除 ack reaction。从 `plugin-sdk/channel-feedback` 导入 |
| `createTestRegistry` | 构建一个渠道插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `createEmptyPluginRegistry` | 构建一个空的插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `setActivePluginRegistry` | 为插件运行时测试安装一个注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `createRequestCaptureJsonFetch` | 在媒体辅助测试中捕获 JSON fetch 请求。从 `plugin-sdk/test-env` 导入 |
| `withFetchPreconnect` | 在安装 preconnect 钩子的情况下运行 fetch 测试。从 `plugin-sdk/test-env` 导入 |
| `withEnv` / `withEnvAsync` | 临时修改环境变量。从 `plugin-sdk/test-env` 导入 |
| `createTempHomeEnv` / `withTempDir` | 创建隔离的文件系统测试夹具。从 `plugin-sdk/test-env` 导入 |
| `createMockServerResponse` | 创建一个最小化的 HTTP 服务器响应模拟。从 `plugin-sdk/test-env` 导入 |
| `createCliRuntimeCapture` | 在测试中捕获 CLI 运行时输出。从 `plugin-sdk/test-fixtures` 导入 |
| `createSandboxTestContext` | 构建沙箱测试上下文。从 `plugin-sdk/test-fixtures` 导入 |
| `writeSkill` | 写入 Skills 夹具。从 `plugin-sdk/test-fixtures` 导入 |
| `makeAgentAssistantMessage` | 构建智能体转录消息夹具。从 `plugin-sdk/test-fixtures` 导入 |
| 导出 | 用途 |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `createTestPluginApi` | 为直接注册单元测试构建最小化的插件 API mock。从 `plugin-sdk/plugin-test-api` 导入 |
| `expectChannelInboundContextContract` | 断言渠道入站上下文的结构。从 `plugin-sdk/channel-contract-testing` 导入 |
| `installChannelOutboundPayloadContractSuite` | 安装渠道出站负载契约测试用例。从 `plugin-sdk/channel-contract-testing` 导入 |
| `createStartAccountContext` | 构建渠道账户生命周期上下文。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelActionsContractSuite` | 安装通用渠道消息动作契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelSetupContractSuite` | 安装通用渠道设置契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `installChannelStatusContractSuite` | 安装通用渠道 Status 契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 |
| `expectDirectoryIds` | 从目录列表函数中断言渠道目录 id。从 `plugin-sdk/channel-test-helpers` 导入 |
| `describePluginRegistrationContract` | 安装插件注册契约检查。从 `plugin-sdk/plugin-test-contracts` 导入 |
| `registerSingleProviderPlugin` | 在加载器冒烟测试中注册一个提供商插件。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `registerProviderPlugin` | 从一个插件中捕获所有提供商类型。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `registerProviderPlugins` | 跨多个插件捕获提供商注册。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `requireRegisteredProvider` | 断言提供商集合中包含某个 id。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `createRuntimeEnv` | 构建一个 mock 的 CLI/插件运行时环境。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `createPluginSetupWizardStatus` | 为渠道插件构建设置向导 Status 辅助工具。从 `plugin-sdk/plugin-test-runtime` 导入 |
| `describeOpenAIProviderRuntimeContract` | 安装提供商家族运行时契约检查。从 `plugin-sdk/provider-test-contracts` 导入 |
| `expectExplicitVideoGenerationCapabilities` | 断言视频提供商声明了显式的生成模式能力。从 `plugin-sdk/provider-test-contracts` 导入 |
| `expectExplicitMusicGenerationCapabilities` | 断言音乐提供商声明了显式的生成/编辑能力。从 `plugin-sdk/provider-test-contracts` 导入 |
| `mockSuccessfulDashscopeVideoTask` | 安装一个成功的、兼容 DashScope 的视频任务响应。从 `plugin-sdk/provider-test-contracts` 导入 |
| `getProviderHttpMocks` | 访问按需启用的提供商 HTTP/认证 Vitest mocks。从 `plugin-sdk/provider-http-test-mocks` 导入 |
| `installProviderHttpMockCleanup` | 在每个测试后重置提供商 HTTP/认证 mocks。从 `plugin-sdk/provider-http-test-mocks` 导入 |
| `installCommonResolveTargetErrorCases` | 目标解析错误处理的共享测试用例。从 `plugin-sdk/channel-target-testing` 导入 |
| `shouldAckReaction` | 检查渠道是否应添加 ack reaction。从 `plugin-sdk/channel-feedback` 导入 |
| `removeAckReactionAfterReply` | 在回复发送后移除 ack reaction。从 `plugin-sdk/channel-feedback` 导入 |
| `createTestRegistry` | 构建一个渠道插件 registry 夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `createEmptyPluginRegistry` | 构建一个空的插件 registry 夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `setActivePluginRegistry` | 为插件运行时测试安装一个 registry 夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 |
| `createRequestCaptureJsonFetch` | 在媒体辅助工具测试中捕获 JSON fetch 请求。从 `plugin-sdk/test-env` 导入 |
| `withFetchPreconnect` | 在安装了 preconnect hooks 的情况下运行 fetch 测试。从 `plugin-sdk/test-env` 导入 |
| `withEnv` / `withEnvAsync` | 临时修补环境变量。从 `plugin-sdk/test-env` 导入 |
| `createTempHomeEnv` / `withTempDir` | 创建隔离的文件系统测试夹具。从 `plugin-sdk/test-env` 导入 |
| `createMockServerResponse` | 创建一个最小化的 HTTP 服务器响应 mock。从 `plugin-sdk/test-env` 导入 |
| `createCliRuntimeCapture` | 在测试中捕获 CLI 运行时输出。从 `plugin-sdk/test-fixtures` 导入 |
| `createSandboxTestContext` | 构建沙箱测试上下文。从 `plugin-sdk/test-fixtures` 导入 |
| `writeSkill` | 写入 Skills 夹具。从 `plugin-sdk/test-fixtures` 导入 |
| `makeAgentAssistantMessage` | 构建智能体转录消息夹具。从 `plugin-sdk/test-fixtures` 导入 |
| `peekSystemEvents` / `resetSystemEventsForTest` | 检查并重置系统事件夹具。从 `plugin-sdk/test-fixtures` 导入 |
| `sanitizeTerminalText` | 清理终端输出以便断言。从 `plugin-sdk/test-fixtures` 导入 |
| `countLines` / `hasBalancedFences` | 断言分块输出的结构。从 `plugin-sdk/test-fixtures` 导入 |
| `runProviderCatalog` | 使用测试依赖执行提供商目录钩子 |
| `resolveProviderWizardOptions` | 在契约测试中解析提供商设置向导选项 |
| `resolveProviderModelPickerEntries` | 在契约测试中解析提供商模型选择器条目 |
| `buildProviderPluginMethodChoice` | 为断言构建提供商向导选项 id |
| `setProviderWizardProvidersResolverForTest` | 为隔离测试注入提供商向导提供商 |
| `createProviderUsageFetch` | 构建提供商用量 fetch 夹具 |
| `useFrozenTime` / `useRealTime` | 冻结并恢复计时器，用于时间敏感测试。从 `plugin-sdk/test-env` 导入 |
| `createTestWizardPrompter` | 构建一个模拟的设置向导提示器 |
| `createRuntimeTaskFlow` | 创建隔离的运行时任务流状态 |
| `typedCases` | 为表驱动测试保留字面量类型。从 `plugin-sdk/test-fixtures` 导入 |
| `sanitizeTerminalText` | 清理终端输出以便断言。从 `plugin-sdk/test-fixtures` 导入 |
| `countLines` / `hasBalancedFences` | 断言分块输出形状。从 `plugin-sdk/test-fixtures` 导入 |
| `runProviderCatalog` | 使用测试依赖执行提供商目录钩子 |
| `resolveProviderWizardOptions` | 在契约测试中解析提供商设置向导选项 |
| `resolveProviderModelPickerEntries` | 在契约测试中解析提供商模型选择器条目 |
| `buildProviderPluginMethodChoice` | 为断言构建提供商向导选项 id |
| `setProviderWizardProvidersResolverForTest` | 为隔离测试注入提供商向导提供商 |
| `createProviderUsageFetch` | 构建提供商用量 fetch 夹具 |
| `useFrozenTime` / `useRealTime` | 为时间敏感测试冻结和恢复定时器。从 `plugin-sdk/test-env` 导入 |
| `createTestWizardPrompter` | 构建一个 mock 的设置向导提示器 |
| `createRuntimeTaskFlow` | 创建隔离的运行时任务流状态 |
| `typedCases` | 为表驱动测试保留字面量类型。从 `plugin-sdk/test-fixtures` 导入 |
内置插件契约测试套件也会使用 SDK 测试子路径中的仅测试用注册表、manifest、公开产物和运行时夹具辅助工具。依赖内置 OpenClaw 清单的仅核心测试套件仍保留在 `src/plugins/contracts` 下。
新的扩展测试应保持使用已记录的聚焦 SDK 子路径，例如
内置插件契约测试套件也会使用 SDK 测试子路径中的仅测试用 registry、manifest、公共产物以及运行时夹具辅助工具。依赖内置 OpenClaw 清单的仅核心测试套件仍保留在 `src/plugins/contracts` 下。
新的扩展测试应使用已文档化的聚焦型 SDK 子路径，例如
`plugin-sdk/plugin-test-api`、`plugin-sdk/channel-contract-testing`、
`plugin-sdk/channel-test-helpers`、`plugin-sdk/plugin-test-contracts`、
`plugin-sdk/plugin-test-runtime`、`plugin-sdk/provider-test-contracts`、
`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures`，而不是导入宽泛的
`plugin-sdk/testing` 兼容 barrel、仓库中的 `src/**` 文件，或直接导入仓库
`test/helpers/plugins/*` 桥接层。
`plugin-sdk/provider-http-test-mocks`、`plugin-sdk/test-env` 或
`plugin-sdk/test-fixtures`，而不是导入宽泛的 `plugin-sdk/testing`
兼容性 barrel、仓库中的 `src/**` 文件，或直接导入仓库中的 `test/helpers/plugins/*`
桥接层。
### 类型
聚焦的测试子路径也会重新导出测试文件中有用的类型：
聚焦型测试子路径也会重新导出在测试文件中有用的类型：
```typescript
import type {
@ -161,17 +170,18 @@ describe("my-channel target resolution", () => {
### 测试注册契约
将手写的 `api` mock 传给 `register(api)` 的单元测试，并不会覆盖 OpenClaw 加载器的接受门禁。对于你的插件所依赖的每个注册入口，至少添加一个由加载器驱动的冒烟测试，尤其是钩子和诸如 memory 之类的独占能力。
把手写的 `api` mock 传给 `register(api)` 的单元测试，并不会覆盖
OpenClaw 加载器的验收门禁。对于你的插件所依赖的每个注册入口面，至少添加一个由加载器支持的冒烟测试，尤其是 hooks 和内存这类独占能力。
真实加载器会在缺少必需元数据，或者插件调用了自己并不拥有的能力 API 时拒绝插件注册。例如，
`api.registerHook(...)` 需要一个 hook 名称，而
真实加载器会在缺少必需元数据，或插件调用了自己并不拥有的能力 API 时使插件注册失败。例如，
`api.registerHook(...)` 需要提供 hook 名称，而
`api.registerMemoryCapability(...)` 则要求插件 manifest 或导出的入口声明 `kind: "memory"`。
### 测试运行时配置访问
在测试内置渠道插件时，优先使用来自 `openclaw/plugin-sdk/channel-test-helpers`
为内置渠道插件编写测试时，优先使用来自 `openclaw/plugin-sdk/channel-test-helpers`
的共享插件运行时 mock。它的已弃用 `runtime.config.loadConfig()` 和
`runtime.config.writeConfigFile(...)` mock 默认会抛出错误，这样测试就能捕获对兼容性 API 的新使用。只有当测试明确覆盖旧版兼容行为时，才重写这些 mock。
`runtime.config.writeConfigFile(...)` mocks 默认会抛错，从而让测试能够捕获对兼容性 API 的新使用。只有当测试明确覆盖旧版兼容行为时，才重写这些 mocks。
### 渠道插件的单元测试
@ -237,9 +247,9 @@ describe("my-provider plugin", () => {
});
```
### 模拟插件运行时
### Mock 插件运行时
对于使用 `createPluginRuntimeStore` 的代码，在测试中应模拟运行时：
对于使用 `createPluginRuntimeStore` 的代码，在测试中应 mock 运行时：
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
@ -270,9 +280,9 @@ store.setRuntime(mockRuntime);
store.clearRuntime();
```
### 使用按实例 stub 进行测试
### 使用实例级 stub 进行测试
优先使用按实例 stub，而不是修改原型：
优先使用实例级 stub，而不是修改原型：
```typescript
// Preferred: per-instance stub
@ -285,7 +295,7 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
## 契约测试（仓库内插件）
内置插件有契约测试，用于验证注册归属：
内置插件带有用于验证注册归属的契约测试：
```bash
pnpm test -- src/plugins/contracts/
@ -295,12 +305,12 @@ pnpm test -- src/plugins/contracts/
- 哪些插件注册了哪些提供商
- 哪些插件注册了哪些语音提供商
- 注册结构是否正确
- 运行时契约是否合规
- 注册形状的正确性
- 运行时契约合规性
### 运行限定范围测试
### 运行作用域测试
针对特定插件：
针对某个特定插件：
```bash
pnpm test -- <bundled-plugin-root>/my-channel/
@ -326,7 +336,7 @@ pnpm test -- src/plugins/contracts/runtime.contract.test.ts
## 测试配置
OpenClaw 使用 Vitest，并启用 V8 覆盖率阈值。对于插件测试：
OpenClaw 使用带有 V8 覆盖率阈值的 Vitest。对于插件测试：
```bash
# Run all tests