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-26 23:12:32 +00:00
parent 6fe4560ba3
commit 76b4cdad60
6 changed files with 582 additions and 583 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/zh-CN/automation/hooks.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你希望为 `/new`、`/reset`、`/stop` 以及智能体生命周期事件提供事件驱动自动化
- 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件提供事件驱动的自动化功能
- 你想要构建、安装或调试钩子
summary: 钩子：用于命令和生命周期事件的事件驱动自动化
title: 钩子
x-i18n:
generated_at: "2026-04-26T00:28:47Z"
generated_at: "2026-04-26T23:09:30Z"
model: gpt-5.4
provider: openai
source_hash: cf40a64449347ef750b4b0e0a83b80e2e8fdef87d92daa71f028d2bf6a3d3d22
source_hash: f1f9b1dc0c470502f782758e1542435f1e593750ff69a39f7f966c7d42e29c1e
source_path: automation/hooks.md
workflow: 15
---
钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中发现，并可通过 `openclaw hooks` 进行检查。只有在你启用钩子，或至少配置了一个 hook 条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。
钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可通过 `openclaw hooks` 进行检查。只有在你启用钩子，或至少配置了一个钩子条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。
OpenClaw 中有两种钩子：
- **内部钩子**（本页）：当智能体事件触发时，在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。
- **Webhooks**：外部 HTTP 端点，让其他系统在 OpenClaw 中触发工作。请参阅 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。
- **内部钩子**（本页）：当智能体事件触发时在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。
- **Webhooks**：外部 HTTP 端点，让其他系统可以在 OpenClaw 中触发工作。参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。
钩子也可以打包在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。
钩子也可以内置在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。
## 快速开始
@ -46,11 +46,11 @@ openclaw hooks info session-memory
| `command:reset` | 发出 `/reset` 命令时 |
| `command:stop` | 发出 `/stop` 命令时 |
| `command` | 任意命令事件（通用监听器） |
| `session:compact:before` | 压缩总结历史记录之前 |
| `session:compact:before` | 压缩开始汇总历史记录之前 |
| `session:compact:after` | 压缩完成之后 |
| `session:patch` | 修改会话属性时 |
| `agent:bootstrap` | 注入工作区引导文件之前 |
| `gateway:startup` | 渠道启动并加载钩子之后 |
| `agent:bootstrap` | 注入工作区 bootstrap 文件之前 |
| `gateway:startup` | 渠道启动且钩子加载完成之后 |
| `message:received` | 从任意渠道收到入站消息 |
| `message:transcribed` | 音频转录完成之后 |
| `message:preprocessed` | 所有媒体和链接理解完成之后 |
@ -62,7 +62,7 @@ openclaw hooks info session-memory
每个钩子都是一个包含两个文件的目录：
```text
```
my-hook/
├── HOOK.md # 元数据 + 文档
└── handler.ts # 处理器实现
@ -73,14 +73,14 @@ my-hook/
```markdown
---
name: my-hook
description: "此钩子的功能简短描述"
description: "这个钩子的简短说明"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
详细文档写在这里。
这里填写详细文档。
```
**元数据字段**（`metadata.openclaw`）：
@ -89,10 +89,10 @@ metadata:
| ---------- | ---------------------------------------------------- |
| `emoji` | CLI 中显示的 emoji |
| `events` | 要监听的事件数组 |
| `export` | 要使用的命名导出（默认为 `"default"`） |
| `export` | 要使用的命名导出（默认是 `"default"`） |
| `os` | 所需平台（例如 `["darwin", "linux"]`） |
| `requires` | 所需的 `bins`、`anyBins`、`env` 或 `config` 路径 |
| `always` | 绕过资格检查（布尔值） |
| `always` | 跳过资格检查（布尔值） |
| `install` | 安装方式 |
### 处理器实现
@ -104,18 +104,18 @@ const handler = async (event) => {
}
console.log(`[my-hook] New command triggered`);
// Your logic here
// 你的逻辑写在这里
// Optionally send message to user
// 可选：向用户发送消息
event.messages.push("Hook executed!");
};
export default handler;
```
每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 `push` 以向用户发送消息）以及 `context`（特定于事件的数据）。智能体和工具插件的钩子上下文还可能包含 `trace`，这是一个只读的、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以进行 OTEL 关联。
每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 push 以发送给用户）以及 `context`（事件特定数据）。智能体和工具插件的钩子上下文还可以包含 `trace`，这是一个只读、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以便与 OTEL 进行关联。
### 事件上下文要点
### 事件上下文重点
**命令事件**（`command:new`、`command:reset`）：`context.sessionEntry`、`context.previousSessionEntry`、`context.commandSource`、`context.workspaceDir`、`context.cfg`。
@ -127,26 +127,26 @@ export default handler;
**消息事件**（`message:preprocessed`）：`context.bodyForAgent`（最终增强后的正文）、`context.from`、`context.channelId`。
**引导事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。
**Bootstrap 事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。
**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端才能触发 patch 事件。
**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端可以触发补丁事件。
**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 会额外包含 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。
**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 还会增加 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。
`command:stop` 观察的是用户发出 `/stop`；它属于取消/命令生命周期，而不是智能体最终完成的关卡。需要检查自然结束答案并要求智能体再执行一轮的插件，应改用类型化插件钩子 `before_agent_finalize`。请参阅 [Plugin hooks](/zh-CN/plugins/hooks)。
`command:stop` 观察的是用户发出 `/stop`；它属于取消/命令生命周期，而不是智能体最终完成的关卡。需要检查自然结束答案并让智能体再进行一轮处理的插件，应改用类型化插件钩子 `before_agent_finalize`。参见 [Plugin hooks](/zh-CN/plugins/hooks)。
## 钩子发现
钩子会从以下目录中发现，优先级依次升高：
钩子会按以下目录进行发现，覆盖优先级依次递增：
1. **内置钩子**：随 OpenClaw 一起发布
2. **插件钩子**：打包在已安装插件中的钩子
3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与其具有相同优先级。
4. **工作区钩子**：`<workspace>/hooks/`（按智能体区分，默认禁用，需显式启用）
2. **插件钩子**：内置在已安装插件中的钩子
3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与此具有相同优先级。
4. **工作区钩子**：`<workspace>/hooks/`（每个智能体单独使用，默认禁用，需显式启用）
工作区钩子可以添加新的钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。
工作区钩子可以新增钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。
在内部钩子完成配置之前，Gateway 网关启动时会跳过内部钩子发现。可通过 `openclaw hooks enable <name>` 启用一个内置或托管钩子、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个命名钩子时，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器会启用广泛发现。
在配置内部钩子之前，Gateway 网关会在启动时跳过内部钩子发现。你可以通过 `openclaw hooks enable <name>` 启用一个内置或托管钩子，安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来主动启用。启用某个具名钩子后，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器则会启用更广泛的发现机制。
### Hook packs
@ -156,14 +156,14 @@ Hook pack 是通过 `package.json` 中的 `openclaw.hooks` 导出钩子的 npm
openclaw plugins install <path-or-spec>
```
npm 规格仅支持 registry（包名 + 可选精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围会被拒绝。
npm spec 仅支持注册表来源（包名 + 可选精确版本或 dist-tag）。Git/URL/file spec 和 semver 范围都会被拒绝。
## 内置钩子
| 钩子 | 事件 | 功能 |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的引导文件 |
| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的 bootstrap 文件 |
| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | 在网关启动时运行 `BOOT.md` |
@ -177,7 +177,7 @@ openclaw hooks enable <hook-name>
### `session-memory` 详情
提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并保存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。
提取最近 15 条用户/assistant 消息，通过 LLM 生成描述性文件名 slug，并使用主机本地日期保存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。要求配置 `workspace.dir`。
<a id="bootstrap-extra-files"></a>
@ -198,7 +198,7 @@ openclaw hooks enable <hook-name>
}
```
路径相对于工作区解析。只会加载已识别的引导 basename（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。
路径相对于工作区解析。仅会加载已识别的 bootstrap 基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。
<a id="command-logger"></a>
@ -214,11 +214,10 @@ openclaw hooks enable <hook-name>
## 插件钩子
插件可以通过 插件 SDK 注册类型化钩子，以实现更深层的集成：
拦截工具调用、修改提示词、控制消息流等。
插件可以通过插件 SDK 注册类型化钩子，以实现更深层的集成：拦截工具调用、修改提示词、控制消息流等。
当你需要 `before_tool_call`、`before_agent_reply`、`before_install` 或其他进程内生命周期钩子时，请使用插件钩子。
完整的插件钩子参考请参阅 [Plugin hooks](/zh-CN/plugins/hooks)。
完整的插件钩子参考请参见 [Plugin hooks](/zh-CN/plugins/hooks)。
## 配置
@ -268,7 +267,7 @@ openclaw hooks enable <hook-name>
```
<Note>
旧版的 `hooks.internal.handlers` 数组配置格式仍受支持，以保持向后兼容，但新钩子应使用基于发现的系统。
旧版 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新钩子应使用基于发现的系统。
</Note>
## CLI 参考
@ -290,9 +289,9 @@ openclaw hooks disable <hook-name>
## 最佳实践
- **保持处理器快速。** 钩子会在命令处理期间运行。对重型工作使用 `void processInBackground(event)` 方式即发即忘。
- **优雅地处理错误。** 用 try/catch 包裹有风险的操作；不要抛出异常，以便其他处理器继续运行。
- **尽早过滤事件。** 如果事件类型/动作无关，立即返回。
- **保持处理器快速。** 钩子会在命令处理期间运行。对较重的工作请使用 `void processInBackground(event)` 以即发即忘方式处理。
- **优雅地处理错误。** 用 try/catch 包裹高风险操作；不要抛出异常，以便其他处理器继续运行。
- **尽早过滤事件。** 如果事件类型/动作无关，请立即返回。
- **使用具体事件键。** 优先使用 `"events": ["command:new"]`，而不是 `"events": ["command"]`，以减少开销。
## 故障排除
@ -308,7 +307,7 @@ ls -la ~/.openclaw/hooks/my-hook/
openclaw hooks list
```
### 钩子不符合资格
### 钩子不符合条件
```bash
openclaw hooks info my-hook

127
docs/zh-CN/ci.md
View File

File diff suppressed because one or more lines are too long

157
docs/zh-CN/gateway/bonjour.md
View File

@ -5,38 +5,38 @@ read_when:
summary: Bonjour/mDNS 发现 + 调试（Gateway 网关信标、客户端和常见故障模式）
title: Bonjour 发现
x-i18n:
generated_at: "2026-04-26T04:59:41Z"
generated_at: "2026-04-26T23:09:30Z"
model: gpt-5.4
provider: openai
source_hash: b055021bdcd92740934823dea2acf758c6ec991a15c0a315426dc359a7eea093
source_hash: abaec96c53233e697155fd62a2fa6af972ab039cb480af8246f96359b5036e1f
source_path: gateway/bonjour.md
workflow: 15
---
# Bonjour / mDNS 发现
OpenClaw 使用 Bonjour（mDNS / DNS‑SD）来发现活动中的 Gateway 网关（WebSocket 端点）。
OpenClaw 使用 Bonjour（mDNS / DNS-SD）来发现活动中的 Gateway 网关（WebSocket 端点）。
多播 `local.` 浏览是**仅限局域网的便利功能**。内置的 `bonjour`
插件负责局域网广播，且默认启用。对于跨网络发现，
插件负责局域网广播，并且默认启用。对于跨网络发现，
同一个信标也可以通过已配置的广域 DNS-SD 域发布。
发现机制仍然是尽力而为，**不能**替代 SSH 或基于 Tailnet 的连接方式。
发现机制仍然是尽力而为，并**不能**替代 SSH 或基于 Tailnet 的连接方式。
## 通过 Tailscale 使用广域 Bonjour（单播 DNS-SD）
如果节点和网关位于不同网络，多播 mDNS 无法跨越
网络边界。你可以通过在 Tailscale 上切换到**单播 DNS‑SD**
如果节点和网关位于不同网络，多播 mDNS 无法跨越该
边界。你可以通过在 Tailscale 上切换到**单播 DNS-SD**
（“广域 Bonjour”）来保留相同的发现 UX。
高级步骤：
1. 在网关主机上运行一个 DNS 服务器（可通过 Tailnet 访问）。
2. 在专用区域下为 `_openclaw-gw._tcp` 发布 DNS‑SD 记录
（示例：`openclaw.internal.`）。
3. 配置 Tailscale **split DNS**，使你的所选域通过该
DNS 服务器为客户端解析（包括 iOS）。
2. 在专用区域下为 `_openclaw-gw._tcp` 发布 DNS-SD 记录
（例如：`openclaw.internal.`）。
3. 配置 Tailscale **split DNS**，让客户端（包括 iOS）
通过该 DNS 服务器解析你选择的域名。
OpenClaw 支持任何发现域；`openclaw.internal.` 只是一个示例。
iOS/Android 节点会同时浏览 `local.` 和你配置的广域域。
iOS/Android 节点会同时浏览 `local.` 和你配置的广域域名。
### Gateway 网关配置（推荐）
@ -56,9 +56,9 @@ openclaw dns setup --apply
这会安装 CoreDNS 并将其配置为：
- 仅在网关的 Tailscale 接口上的 53 端口监听
- 从 `~/.openclaw/dns/<domain>.db` 为你选择的域（示例：`openclaw.internal.`）提供服务
- 从 `~/.openclaw/dns/<domain>.db` 为你选择的域提供服务（例如：`openclaw.internal.`）
在连接到 tailnet 的机器上验证：
从已连接 Tailnet 的机器验证：
```bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.
@ -72,13 +72,13 @@ dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
- 添加一个指向网关 tailnet IP 的名称服务器（UDP/TCP 53）。
- 添加 split DNS，使你的发现域使用该名称服务器。
一旦客户端接受 tailnet DNS，iOS 节点和 CLI 发现就可以在你的发现域中
浏览 `_openclaw-gw._tcp`，而无需使用多播。
一旦客户端接受 Tailnet DNS，iOS 节点和 CLI 发现就可以在不使用多播的情况下
浏览你的发现域中的 `_openclaw-gw._tcp`。
### Gateway 网关监听器安全性（推荐）
Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网 / tailnet
访问，请显式绑定并保持启用认证。
Gateway 网关的 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网 / tailnet
访问，请显式绑定并保持启用身份验证。
对于仅 tailnet 的设置：
@ -88,8 +88,8 @@ Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局
## 广播内容
只有 Gateway 网关会广播 `_openclaw-gw._tcp`。局域网多播广播
由内置的 `bonjour` 插件提供；广域 DNS-SD 发布仍由
Gateway 网关负责。
由内置的 `bonjour` 插件提供；广域 DNS-SD 发布仍然由
Gateway 网关自身负责。
## 服务类型
@ -97,27 +97,27 @@ Gateway 网关负责。
## TXT 键（非机密提示）
Gateway 网关会广播一些小型、非机密提示，以方便 UI 流程：
Gateway 网关会广播少量非机密提示，以便让 UI 流程更方便：
- `role=gateway`
- `displayName=<friendly name>`
- `lanHost=<hostname>.local`
- `gatewayPort=<port>`（Gateway 网关 WS + HTTP）
- `gatewayTls=1`（仅当启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅当启用 TLS 且指纹可用时）
- `canvasPort=<port>`（仅当启用 canvas host 时；当前与 `gatewayPort` 相同）
- `gatewayTls=1`（仅在启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
- `canvasPort=<port>`（仅在启用 canvas host 时；目前与 `gatewayPort` 相同）
- `transport=gateway`
- `tailnetDns=<magicdns>`（仅在 mDNS 完整模式下；当 Tailnet 可用时的可选提示）
- `sshPort=<port>`（仅在 mDNS 完整模式下；广域 DNS-SD 可能省略它）
- `cliPath=<path>`（仅在 mDNS 完整模式下；广域 DNS-SD 仍会将其写入为远程安装提示）
- `tailnetDns=<magicdns>`（仅在 mDNS full mode 中；当 Tailnet 可用时的可选提示）
- `sshPort=<port>`（仅在 mDNS full mode 中；广域 DNS-SD 可能省略它）
- `cliPath=<path>`（仅在 mDNS full mode 中；广域 DNS-SD 仍会将其写入作为远程安装提示）
安全说明：
- Bonjour/mDNS TXT 记录是**未经身份验证的**。客户端不得将 TXT 视为权威路由信息。
- Bonjour/mDNS TXT 记录是**未经认证的**。客户端不得将 TXT 视为权威路由信息。
- 客户端应使用已解析的服务端点（SRV + A/AAAA）进行路由。仅将 `lanHost`、`tailnetDns`、`gatewayPort` 和 `gatewayTlsSha256` 视为提示信息。
- SSH 自动定向同样应使用已解析的服务主机，而不是仅使用 TXT 提示。
- TLS pinning 绝不能允许已广播的 `gatewayTlsSha256` 覆盖先前已存储的 pin。
- iOS/Android 节点应将基于发现的直接连接视为**仅限 TLS**，并在信任首次出现的指纹之前要求用户明确确认。
- SSH 自动目标选择同样应使用已解析的服务主机，而不是仅依赖 TXT 提示。
- TLS pinning 绝不能允许广播的 `gatewayTlsSha256` 覆盖先前已存储的 pin。
- iOS/Android 节点应将基于发现的直接连接视为**仅 TLS**，并且在信任首次出现的指纹之前需要用户明确确认。
## 在 macOS 上调试
@ -129,19 +129,19 @@ Gateway 网关会广播一些小型、非机密提示，以方便 UI 流程：
dns-sd -B _openclaw-gw._tcp local.
```
- 解析一个实例（替换 `<instance>`）：
- 解析单个实例（替换 `<instance>`）：
```bash
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```
如果浏览正常但解析失败，通常说明你遇到了局域网策略或
如果浏览可用但解析失败，通常说明你遇到了局域网策略或
mDNS 解析器问题。
## 在 Gateway 网关日志中调试
Gateway 网关会写入滚动日志文件（启动时会打印为
`gateway log file: ...`）。查找 `bonjour:` 行，尤其是：
Gateway 网关会写入一个滚动日志文件（启动时会打印为
`gateway log file: ...`）。请查找 `bonjour:` 行，尤其是：
- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
@ -154,30 +154,30 @@ iOS 节点使用 `NWBrowser` 发现 `_openclaw-gw._tcp`。
要捕获日志：
- 设置 → Gateway 网关 → 高级 → **Discovery 调试日志**
- 设置 → Gateway 网关 → 高级 → **Discovery 日志** → 复现问题 → **复制**
- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs**
- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现问题 → **Copy**
日志包含浏览器状态转换和结果集变化。
## 何时禁用 Bonjour
仅当局域网多播广播不可用或有害时，才禁用 Bonjour。
常见情况是 Gateway 网关运行在 Docker bridge 网络、WSL 后面，或处于
会丢弃 mDNS 多播的网络策略中。在这些环境中，Gateway 网关
仍可通过其已发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问，
只有当局域网多播广播不可用或有害时，才应禁用 Bonjour。
常见情况是 Gateway 网关运行在 Docker bridge networking、WSL 后面，或者处于
会丢弃 mDNS 多播的网络策略下。在这些环境中，Gateway 网关
仍然可以通过其发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问，
但局域网自动发现并不可靠。
如果问题仅限于部署范围，优先使用现有的环境变量覆盖：
当问题仅限于部署范围时，优先使用现有的环境变量覆盖：
```bash
OPENCLAW_DISABLE_BONJOUR=1
```
这会禁用局域网多播广播，而不会更改插件配置。
这会禁用局域网多播广播，而不更改插件配置。
它适用于 Docker 镜像、服务文件、启动脚本和一次性
调试，因为环境变量移除后该设置也会消失。
调试，因为当环境消失时该设置也会随之消失。
仅当你有意要为该 OpenClaw 配置关闭
只有当你明确想为该 OpenClaw 配置关闭
内置局域网发现插件时，才使用插件配置：
```bash
@ -186,93 +186,94 @@ openclaw plugins disable bonjour
## Docker 注意事项
内置 Docker Compose 默认会为 Gateway 网关服务设置 `OPENCLAW_DISABLE_BONJOUR=1`。
Docker bridge 网络通常不会在容器与局域网之间转发 mDNS 多播
（`224.0.0.251:5353`），因此保持 Bonjour 启用可能会
产生反复的 ciao `probing` 或 `announcing` 失败，而不会让发现真正生效。
内置 Bonjour 插件会在检测到的容器中且未设置 `OPENCLAW_DISABLE_BONJOUR` 时，
自动禁用局域网多播广播。Docker bridge networks
通常不会在容器与局域网之间转发 mDNS 多播（`224.0.0.251:5353`），
因此从容器中广播通常无法让发现正常工作。
重要注意事项：
- 禁用 Bonjour 不会停止 Gateway 网关。它只会停止局域网多播
广播。
- 禁用 Bonjour 不会更改 `gateway.bind`；Docker 仍默认使用
`OPENCLAW_GATEWAY_BIND=lan`，以便已发布的主机端口能够工作。
`OPENCLAW_GATEWAY_BIND=lan`，这样发布的主机端口才能工作。
- 禁用 Bonjour 不会禁用广域 DNS-SD。当 Gateway 网关和节点不在同一局域网时，
请使用广域发现或 Tailnet。
- 在 Docker 外重用相同的 `OPENCLAW_CONFIG_DIR` 不会继承
Compose 默认值，除非环境中仍设置了 `OPENCLAW_DISABLE_BONJOUR`。
- 仅当已知 mDNS 多播可通过 host networking、macvlan 或其他
网络时，才设置 `OPENCLAW_DISABLE_BONJOUR=0`。
- 在 Docker 外重用相同的 `OPENCLAW_CONFIG_DIR` 并不会持久保留
容器自动禁用策略。
- 仅在 host networking、macvlan 或其他已知可传递 mDNS 多播的
网络中，将 `OPENCLAW_DISABLE_BONJOUR=0` 设置为强制启用；设置为 `1` 可强制禁用。
## 已禁用 Bonjour 的故障排除
如果在 Docker 设置后节点不再自动发现 Gateway 网关：
如果节点在 Docker 设置后不再自动发现 Gateway 网关：
1. 确认 Gateway 网关是否有意抑制局域网广播：
1. 确认 Gateway 网关当前运行于自动、强制开启还是强制关闭模式：
```bash
docker compose config | grep OPENCLAW_DISABLE_BONJOUR
```
2. 确认 Gateway 网关本身可通过已发布端口访问：
2. 确认 Gateway 网关本身可通过发布的端口访问：
```bash
curl -fsS http://127.0.0.1:18789/healthz
```
3. 在 Bonjour 被禁用时使用直接目标：
3. 当 Bonjour 被禁用时，使用直接目标：
- Control UI 或本地工具：`http://127.0.0.1:18789`
- 局域网客户端：`http://<gateway-host>:18789`
- 跨网络客户端：Tailnet MagicDNS、Tailnet IP、SSH 隧道或
- 跨网络客户端：Tailnet MagicDNS、Tailnet IP、SSH 隧道，或
广域 DNS-SD
4. 如果你有意在 Docker 中通过
4. 如果你在 Docker 中有意通过
`OPENCLAW_DISABLE_BONJOUR=0` 启用了 Bonjour，请从主机测试多播：
```bash
dns-sd -B _openclaw-gw._tcp local.
```
如果浏览结果为空，或 Gateway 网关日志显示反复出现 ciao watchdog
取消，请恢复 `OPENCLAW_DISABLE_BONJOUR=1` 并使用直接或
如果浏览为空，或者 Gateway 网关日志显示重复的 ciao watchdog
取消操作，请恢复 `OPENCLAW_DISABLE_BONJOUR=1`，并使用直接连接或
Tailnet 路径。
## 常见故障模式
- **Bonjour 无法跨网络工作**：请使用 Tailnet 或 SSH。
- **多播被阻止**：某些 Wi‑Fi 网络会禁用 mDNS。
- **广播器卡在 probing/announcing**：多播被阻止的主机、
容器桥接网络、WSL 或接口频繁变化，可能会让 ciao 广播器处于
- **广播器卡在 probing/announcing**：在多播被阻止的主机、
容器桥接、WSL 或接口频繁变更的情况下，ciao 广播器可能停留在
未广播状态。OpenClaw 会重试几次，然后为当前 Gateway 网关进程禁用 Bonjour，
而不是无限重启广播器。
- **Docker bridge 网络**：内置 Docker Compose 默认通过
`OPENCLAW_DISABLE_BONJOUR=1` 禁用 Bonjour。仅对 host、
macvlan 或其他支持 mDNS 的网络将其设置为 `0`。
- **休眠 / 接口频繁变化**：macOS 可能会暂时丢失 mDNS 结果；请重试。
- **浏览正常但解析失败**：保持机器名简洁（避免使用表情符号或
标点符号），然后重启 Gateway 网关。服务实例名派生自
- **Docker bridge networking**：Bonjour 会在检测到的容器中自动禁用。
仅在 host、macvlan 或其他
支持 mDNS 的网络上，将 `OPENCLAW_DISABLE_BONJOUR=0` 设置为启用。
- **休眠 / 接口频繁变更**：macOS 可能会暂时丢失 mDNS 结果；请重试。
- **浏览可用但解析失败**：保持机器名称简单（避免使用表情符号或
标点符号），然后重启 Gateway 网关。服务实例名称派生自
主机名，因此过于复杂的名称可能会让某些解析器混淆。
## 转义的实例名称（`\032`）
Bonjour/DNS‑SD 通常会将服务实例名称中的字节转义为十进制 `\DDD`
Bonjour/DNS-SD 通常会将服务实例名称中的字节转义为十进制 `\DDD`
序列（例如空格会变成 `\032`）。
- 这在协议层面是正常的。
- 这是协议层面的正常现象。
- UI 应为显示目的进行解码（iOS 使用 `BonjourEscapes.decode`）。
## 禁用 / 配置
- `openclaw plugins disable bonjour` 通过禁用内置插件来禁用局域网多播广播。
- `openclaw plugins enable bonjour` 恢复默认的局域网发现插件。
- `OPENCLAW_DISABLE_BONJOUR=1` 在不更改插件配置的情况下禁用局域网多播广播；接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。
- Docker Compose 默认会为 bridge 网络设置 `OPENCLAW_DISABLE_BONJOUR=1`；仅在 mDNS 多播可用时，才用 `OPENCLAW_DISABLE_BONJOUR=0` 覆盖。
- `gateway.bind` 在 `~/.openclaw/openclaw.json` 中控制 Gateway 网关绑定模式。
- `OPENCLAW_DISABLE_BONJOUR=1` 可在不更改插件配置的情况下禁用局域网多播广播；接受的真值包括 `1`、`true`、`yes` 和 `on`（旧版：`OPENCLAW_DISABLE_BONJOUR`）。
- `OPENCLAW_DISABLE_BONJOUR=0` 可强制启用局域网多播广播，包括在检测到的容器内部；接受的假值包括 `0`、`false`、`no` 和 `off`。
- 当 `OPENCLAW_DISABLE_BONJOUR` 未设置时，Bonjour 会在普通主机上广播，并在检测到的容器内部自动禁用。
- `gateway.bind`（位于 `~/.openclaw/openclaw.json`）控制 Gateway 网关绑定模式。
- `OPENCLAW_SSH_PORT` 会在广播 `sshPort` 时覆盖 SSH 端口（旧版：`OPENCLAW_SSH_PORT`）。
- `OPENCLAW_TAILNET_DNS` 会在启用 mDNS 完整模式时于 TXT 中发布 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。
- `OPENCLAW_TAILNET_DNS` 会在启用 mDNS full mode 时于 TXT 中发布一个 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。
- `OPENCLAW_CLI_PATH` 会覆盖广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。
## 相关文档
- 设备发现策略和传输选择：[设备发现](/zh-CN/gateway/discovery)
- 节点配对 + 批准：[Gateway pairing](/zh-CN/gateway/pairing)
- 发现策略和传输选择：[设备发现](/zh-CN/gateway/discovery)
- 节点配对 + 审批：[Gateway pairing](/zh-CN/gateway/pairing)

127
docs/zh-CN/gateway/discovery.md
View File

@ -1,66 +1,65 @@
---
read_when:
- 实现或更改 Bonjour 设备发现/通告
- 实现或更改 Bonjour 设备发现/广播
- 调整远程连接模式（直连与 SSH）
- 为远程节点设计设备发现 + 配对机制
- 为远程节点设计设备发现 + 配对
summary: 用于查找 Gateway 网关的节点发现和传输协议（Bonjour、Tailscale、SSH）
title: 设备发现 + 传输协议
title: 设备发现和传输协议
x-i18n:
generated_at: "2026-04-26T04:54:49Z"
generated_at: "2026-04-26T23:09:31Z"
model: gpt-5.4
provider: openai
source_hash: 615be0f501470772c257beb8e798c522c108b09081a603f44218404277fdf269
source_hash: c396e6e07808e2571c6d7f539922b94443adbf39339027e6e962596c6f13deaa
source_path: gateway/discovery.md
workflow: 15
---
# 设备发现 + 传输协议
# 设备发现和传输协议
OpenClaw 有两个表面看起来相似、但本质上不同的问题：
OpenClaw 有两个彼此不同、但表面上看起来相似的问题：
1. **操作端远程控制**：macOS 菜单栏应用控制运行在其他地方的 Gateway 网关。
2. **节点配对**：iOS/Android（以及未来的节点）查找 Gateway 网关并进行安全配对。
1. **操作员远程控制**：macOS 菜单栏应用控制运行在其他位置的 Gateway 网关。
2. **节点配对**：iOS/Android（以及未来的节点）发现 Gateway 网关并进行安全配对。
设计目标是将所有网络设备发现/通告都保留在 **Node Gateway**（`openclaw gateway`）中，并让客户端（mac 应用、iOS）作为使用方。
设计目标是将所有网络发现/广播都保留在 **Node Gateway**（`openclaw gateway`）中，并让客户端（mac 应用、iOS）作为消费者。
## 术语
- **Gateway 网关**：单个长期运行的 Gateway 网关进程，负责状态（会话、配对、节点注册表）并运行渠道。大多数部署在每台主机上使用一个；也支持隔离的多 Gateway 网关部署。
- **Gateway WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到局域网 / tailnet。
- **直连 WS 传输**：面向局域网 / tailnet 的 Gateway WS 端点（不使用 SSH）。
- **SSH 传输（回退方案）**：通过 SSH 转发 `127.0.0.1:18789` 来实现远程控制。
- **旧版 TCP 桥接（已移除）**：较早的节点传输方式（参见
[Bridge protocol](/zh-CN/gateway/bridge-protocol)）；不再用于设备发现通告，也不再属于当前构建的一部分。
- **Gateway 网关**：单个长期运行的 Gateway 网关进程，负责管理状态（会话、配对、节点注册表）并运行渠道。大多数部署在每台主机上使用一个；也可以进行隔离的多 Gateway 网关部署。
- **Gateway WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到 LAN/tailnet。
- **直连 WS 传输**：面向 LAN/tailnet 的 Gateway WS 端点（不使用 SSH）。
- **SSH 传输（回退方案）**：通过 SSH 转发 `127.0.0.1:18789` 实现远程控制。
- **旧版 TCP bridge（已移除）**：较早的节点传输方式（参见 [Bridge protocol（旧版节点，历史参考）](/zh-CN/gateway/bridge-protocol)）；不再用于设备发现广播，也不再包含在当前构建中。
协议详情：
- [Gateway protocol](/zh-CN/gateway/protocol)
- [Bridge protocol（旧版）](/zh-CN/gateway/bridge-protocol)
- [Bridge protocol（旧版节点，历史参考）](/zh-CN/gateway/bridge-protocol)
## 为什么我们同时保留“直连”和 SSH
- **直连 WS** 在同一网络以及 tailnet 内提供最佳体验：
- 通过 Bonjour 在局域网内自动发现
- **直连 WS** 在同一网络和 tailnet 内提供最佳体验：
- 通过 Bonjour 在局域网中自动发现
- 配对令牌和 ACL 由 Gateway 网关管理
- 无需 shell 访问；协议暴露面可以保持精简且可审计
- 无需 shell 访问；协议暴露面可以保持紧凑且便于审计
- **SSH** 仍然是通用的回退方案：
- 只要你有 SSH 访问权限，就几乎可以在任何地方使用（即使跨越互不相关的网络）
- 能避开多播 / mDNS 问题
- 除 SSH 外无需开放新的入站端口
- 只要你有 SSH 访问权限，就可以在任何地方使用（即使跨越互不关联的网络）
- 能够应对组播/mDNS 问题
- 除 SSH 外无需新增入站端口
## 设备发现输入（客户端如何获知 Gateway 网关位置）
### 1) Bonjour / DNS-SD 设备发现
### 1) Bonjour / DNS-SD 发现
多播 Bonjour 是尽力而为的，并且不会跨网络。OpenClaw 也可以通过已配置的广域 DNS-SD 域浏览同一个 Gateway 网关信标，因此设备发现范围可以覆盖：
组播 Bonjour 是尽力而为的，并且不会跨网络。OpenClaw 也可以通过已配置的广域 DNS-SD 域浏览同一个 Gateway 网关信标，因此设备发现可以覆盖：
- 同一局域网中的 `local.`
- 用于跨网络设备发现的已配置单播 DNS-SD 域
- 用于跨网络发现的已配置单播 DNS-SD 域
目标方向：
- **Gateway 网关** 通过 Bonjour 通告它的 WS 端点。
- 客户端负责浏览并显示“选择一个 Gateway 网关”的列表，然后保存所选端点。
- **Gateway 网关** 通过 Bonjour 广播其 WS 端点。
- 客户端进行浏览并显示“选择一个 Gateway 网关”列表，然后保存所选端点。
故障排除和信标详情： [Bonjour](/zh-CN/gateway/bonjour)。
@ -68,55 +67,55 @@ OpenClaw 有两个表面看起来相似、但本质上不同的问题：
- 服务类型：
- `_openclaw-gw._tcp`（Gateway 网关传输信标）
- TXT 键名（非机密）：
- TXT 键（非机密）：
- `role=gateway`
- `transport=gateway`
- `displayName=<friendly name>`（操作端配置的显示名称）
- `displayName=<friendly name>`（由操作员配置的显示名称）
- `lanHost=<hostname>.local`
- `gatewayPort=18789`（Gateway WS + HTTP）
- `gatewayTls=1`（仅在启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且可获得指纹时）
- `canvasPort=<port>`（canvas host 端口；当前在启用 canvas host 时与 `gatewayPort` 相同）
- `tailnetDns=<magicdns>`（可选提示；当 Tailscale 可用时自动检测）
- `sshPort=<port>`（仅 mDNS 完整模式；广域 DNS-SD 可能省略该项，此时 SSH 默认端口保持为 `22`）
- `cliPath=<path>`（仅 mDNS 完整模式；广域 DNS-SD 仍会将其写入，作为远程安装提示）
- `sshPort=<port>`（仅限 mDNS 完整模式；广域 DNS-SD 可能省略它，此时 SSH 默认端口仍为 `22`）
- `cliPath=<path>`（仅限 mDNS 完整模式；广域 DNS-SD 仍会将其写入为远程安装提示）
安全说明：
- Bonjour/mDNS TXT 记录是**未经认证的**。客户端必须仅将 TXT 值视为用户体验提示。
- 路由（主机 / 端口）应优先使用**已解析的服务端点**（SRV + A/AAAA），而不是 TXT 中提供的 `lanHost`、`tailnetDns` 或 `gatewayPort`。
- TLS 固定必须绝不允许通告的 `gatewayTlsSha256` 覆盖先前存储的 pin。
- iOS/Android 节点在所选路由为安全 / 基于 TLS 的情况下，在存储首次 pin 之前，应要求显式确认“信任此指纹”（带外验证）。
- Bonjour/mDNS TXT 记录**未经身份验证**。客户端必须仅将 TXT 值视为用户体验提示。
- 路由（主机/端口）应优先使用**已解析的服务端点**（SRV + A/AAAA），而不是 TXT 提供的 `lanHost`、`tailnetDns` 或 `gatewayPort`。
- TLS pinning 绝不能允许广播的 `gatewayTlsSha256` 覆盖先前已存储的 pin。
- iOS/Android 节点在所选路由为安全/TLS 路由时，应要求用户明确确认“信任此指纹”后，才存储首次 pin（带外验证）。
禁用 / 覆盖：
禁用/覆盖：
- `OPENCLAW_DISABLE_BONJOUR=1` 禁用通告。
- Docker Compose 默认使用 `OPENCLAW_DISABLE_BONJOUR=1`，因为 bridge 网络通常无法可靠承载 mDNS 多播；仅在 host、macvlan 或其他支持 mDNS 的网络上使用 `0`。
- `OPENCLAW_DISABLE_BONJOUR=1` 可禁用广播。
- 当未设置 `OPENCLAW_DISABLE_BONJOUR` 时，Bonjour 会在普通主机上广播，并在检测到的容器内自动禁用。仅在 host、macvlan 或其他支持 mDNS 的网络中使用 `0`；使用 `1` 可强制禁用。
- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
- `OPENCLAW_SSH_PORT` 会在发出 `sshPort` 时覆盖所通告的 SSH 端口。
- `OPENCLAW_TAILNET_DNS` 发布 `tailnetDns` 提示（MagicDNS）。
- `OPENCLAW_CLI_PATH` 覆盖所通告的 CLI 路径。
- `OPENCLAW_SSH_PORT` 会覆盖在发出 `sshPort` 时广播的 SSH 端口。
- `OPENCLAW_TAILNET_DNS` 会发布 `tailnetDns` 提示（MagicDNS）。
- `OPENCLAW_CLI_PATH` 会覆盖广播的 CLI 路径。
### 2) Tailnet（跨网络）
### 2) tailnet（跨网络）
对于 London/Vienna 这类部署，Bonjour 不会有帮助。推荐的“直连”目标是：
对于 London/Vienna 风格的部署，Bonjour 没有帮助。推荐的“直连”目标是：
- Tailscale MagicDNS 名称（优先），或稳定的 tailnet IP。
- Tailscale MagicDNS 名称（优先）或稳定的 tailnet IP。
如果 Gateway 网关能够检测到自己运行在 Tailscale 环境下，它会将 `tailnetDns` 作为客户端的可选提示发布（包括广域信标）。
如果 Gateway 网关能够检测到自己运行在 Tailscale 下，它会发布 `tailnetDns` 作为给客户端的可选提示（包括广域信标）。
macOS 应用现在在 Gateway 网关设备发现中优先使用 MagicDNS 名称，而不是原始 Tailscale IP。这样在 tailnet IP 发生变化时（例如节点重启后或 CGNAT 重新分配后）可靠性更高，因为 MagicDNS 名称会自动解析到当前 IP。
macOS 应用现在在 Gateway 网关发现中优先使用 MagicDNS 名称，而不是原始 Tailscale IP。这在 tailnet IP 发生变化时（例如节点重启后或 CGNAT 重新分配后）可以提高可靠性，因为 MagicDNS 名称会自动解析到当前 IP。
对于移动节点配对，设备发现提示不会放宽 tailnet / 公网路由上的传输安全要求：
对于移动节点配对，发现提示不会放宽 tailnet/公网路由上的传输安全要求：
- iOS/Android 仍然要求首次通过安全的 tailnet / 公网连接路径进行连接（`wss://` 或 Tailscale Serve/Funnel）。
- 发现到的原始 tailnet IP 只是路由提示，并不意味着允许使用明文远程 `ws://`。
- iOS/Android 仍然要求首次通过 tailnet/公网连接时使用安全路径（`wss://` 或 Tailscale Serve/Funnel）。
- 发现到的原始 tailnet IP 只是路由提示，并不意味着可以使用明文远程 `ws://`。
- 私有局域网直连 `ws://` 仍然受支持。
- 如果你希望为移动节点提供最简单的 Tailscale 路径，请使用 Tailscale Serve，这样设备发现和设置代码都会解析到同一个安全的 MagicDNS 端点。
- 如果你希望移动节点通过 Tailscale 使用最简单的路径，请使用 Tailscale Serve，这样设备发现和设置代码都会解析到同一个安全的 MagicDNS 端点。
### 3) 手动 / SSH 目标
当没有直连路径（或直连被禁用）时，客户端始终可以通过转发 loopback Gateway 网关端口来使用 SSH 连接。
当没有直连路由（或直连被禁用）时，客户端始终可以通过 SSH 转发 loopback Gateway 网关端口进行连接。
参见 [Remote access](/zh-CN/gateway/remote)。
@ -124,26 +123,26 @@ macOS 应用现在在 Gateway 网关设备发现中优先使用 MagicDNS 名称
推荐的客户端行为：
1. 如果已配置并且可达的已配对直连端点存在，则使用它。
2. 否则，如果设备发现在 `local.` 或已配置的广域域名中找到 Gateway 网关，则提供一键“使用此 Gateway 网关”的选项，并将其保存为直连端点。
3. 否则，如果已配置 tailnet DNS / IP，则尝试直连。
对于位于 tailnet / 公网路由上的移动节点，直连意味着安全端点，而不是明文远程 `ws://`。
1. 如果已配置且可达的配对直连端点存在，则使用它。
2. 否则，如果设备发现找到了 `local.` 或已配置广域域中的 Gateway 网关，则提供“一键使用此 Gateway 网关”的选项，并将其保存为直连端点。
3. 否则，如果已配置 tailnet DNS/IP，则尝试直连。
对于位于 tailnet/公网路由上的移动节点，“直连”意味着安全端点，而不是明文远程 `ws://`。
4. 否则，回退到 SSH。
## 配对 + 认证（直连传输）
Gateway 网关是节点 / 客户端接入的唯一真实来源。
Gateway 网关是节点/客户端准入的事实来源。
- 配对请求由 Gateway 网关创建 / 批准 / 拒绝（参见 [Gateway pairing](/zh-CN/gateway/pairing)）。
- Gateway 网关负责执行：
- 认证（令牌 / 密钥对）
- 作用域 / ACL（Gateway 网关不是通往所有方法的原始代理）
- 配对请求在 Gateway 网关中创建/批准/拒绝（参见 [Gateway pairing](/zh-CN/gateway/pairing)）。
- Gateway 网关负责强制执行：
- 认证（token / keypair）
- 作用域/ACL（Gateway 网关并不是通往每个方法的原始代理）
- 速率限制
## 各组件职责
- **Gateway 网关**：通告设备发现信标，负责配对决策，并托管 WS 端点。
- **macOS 应用**：帮助你选择 Gateway 网关，显示配对提示，并仅将 SSH 作为回退方案使用。
- **Gateway 网关**：广播发现信标、负责配对决策并托管 WS 端点。
- **macOS 应用**：帮助你选择一个 Gateway 网关、显示配对提示，并且仅将 SSH 作为回退方案使用。
- **iOS/Android 节点**：将 Bonjour 浏览作为便利功能，并连接到已配对的 Gateway WS。
## 相关内容

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

@ -3,162 +3,162 @@ read_when:
- 在本地或 CI 中运行测试
- 为模型 / 提供商缺陷添加回归测试
- 调试 Gateway 网关 + 智能体行为
summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每类测试覆盖的内容
summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每项测试覆盖的内容
title: 测试
x-i18n:
generated_at: "2026-04-26T22:39:47Z"
generated_at: "2026-04-26T23:09:33Z"
model: gpt-5.4
provider: openai
source_hash: 4499f5092819a250971610ce3e31191b871cd2a1d2915bb7479f9439cea94dcd
source_hash: 7e23cc382a48b372aa5273b16f2831e37c870df265b3f30fe06f8b2b97909814
source_path: help/testing.md
workflow: 15
---
OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、live）以及一小组 Docker 运行器。本文档是关于“我们如何测试”的指南：
OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南：
- 每个测试套件覆盖什么内容（以及它刻意 _不_ 覆盖什么）。
- 常见工作流（本地、推送前、调试）应运行哪些命令。
- live 测试如何发现凭证并选择模型 / 提供商。
- 每个测试套件覆盖什么（以及它刻意**不**覆盖什么）。
- 常见工作流应运行哪些命令（本地、推送前、调试）。
- 实时测试如何发现凭证并选择模型 / 提供商。
- 如何为真实世界中的模型 / 提供商问题添加回归测试。
## 快速开始
大多数情况下：
大多数时候：
- 完整门禁（预期在推送前执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test`
- 在配置宽裕的机器上更快地运行本地完整测试套件：`pnpm test:max`
- 完整门禁（预期在推送前运行）：`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`
- 当你在迭代修复单个失败用例时，优先先运行有针对性的测试。
- 现在可直接将文件定位路由到 extension / 渠道路径：`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`
当你修改了测试或想获得更高信心时：
当你修改了测试，或者想获得更多信心时：
- 覆盖率门禁：`pnpm test:coverage`
- E2E 测试套件：`pnpm test:e2e`
当你在调试真实提供商 / 模型时（需要真实凭证）：
- 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`。
- 将新的高信号提供商 secrets 添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 以及其定时 / 发布调用方中。
- 实时测试套件（模型 + 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` 和它的 scheduled / release 调用方中。
- 原生 Codex 绑定聊天冒烟测试：`pnpm test:docker:live-codex-bind`
- 在 Codex app-server 路径上运行一个 Docker live 通道，绑定一个合成的 Slack 私信并执行 `/codex bind`，运行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件都是通过原生插件绑定而不是 ACP 路由的。
- 在针对 Codex app-server 路径的 Docker 实时通道中运行，将一个合成的 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`，否则该命令会在子智能体探测后退出。
- Crestodian rescue command 冒烟测试：`pnpm test:live:crestodian-rescue-channel`
- 针对消息渠道 rescue command 表面的可选加固检查。它会执行 `/crestodian status`，排队一个持久模型变更，回复 `/crestodian yes`，并验证审计 / 配置写入路径。
- 通过插件自有的 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 planner Docker 冒烟测试：`pnpm test:docker:crestodian-planner`
- 在一个无配置容器中运行 Crestodian，并在 `PATH` 中放置一个伪造的 Claude CLI，验证模糊 planner 回退会转换为一条带审计记录的类型化配置写入。
- 在一个无配置容器中运行 Crestodian，并在 `PATH` 上放置一个假的 Claude CLI，验证模糊 planner 回退会转换为带审计记录的类型化配置写入。
- Crestodian 首次运行 Docker 冒烟测试：`pnpm test:docker:crestodian-first-run`
- 从空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到 Crestodian，应用 setup / model / agent / 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，且 assistant transcript 中存储了标准化的 `usage.cost`。
- 从空的 OpenClaw 状态目录启动，将裸 `openclaw` 路由到 Crestodian，应用 setup / model / agent / 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，且 assistant transcript 存储了规范化的 `usage.cost`。
提示：当你只需要一个失败用例时，优先使用下文描述的 allowlist 环境变量来收窄 live 测试范围。
提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小实时测试范围。
## QA 专用运行器
当你需要 QA-lab 级别的真实性时，这些命令位于主测试套件旁边：
当你需要 QA-lab 级别的真实性时，这些命令与主测试套件并列存在：
CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上以及通过手动调度运行，使用 mock 提供商。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，并可通过手动调度运行，其中 mock parity gate、live Matrix 通道和由 Convex 管理的 live Telegram 通道作为并行任务执行。`OpenClaw Release Checks` 会在发布批准前运行同样的通道。
CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动分发使用 mock 提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可通过手动分发并行运行 mock parity gate、实时 Matrix 通道以及由 Convex 管理的实时 Telegram 通道。`OpenClaw Release Checks` 会在发布批准前运行同样的通道。
- `pnpm openclaw qa suite`
- 直接在主机上运行基于仓库的 QA 场景。
- 默认情况下，会使用隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency <count>` 可调整工作进程数量，或使用 `--concurrency 1` 以采用较早的串行通道。
- 当任一场景失败时会以非零状态退出。如果你想保留工件但不希望以失败退出码结束，可使用 `--allow-failures`。
- 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地的、由 AIMock 支持的提供商服务器，用于实验性的夹具和协议 mock 覆盖，而不会替代具备场景感知能力的 `mock-openai` 通道。
- 默认使用隔离的 Gateway 网关 worker 并行运行多个选中场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency <count>` 调整 worker 数量，或使用 `--concurrency 1` 启用旧的串行通道。
- 任一场景失败时以非零状态退出。若你想保留产物但不希望以失败退出码结束，可使用 `--allow-failures`。
- 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地的 AIMock 支持的提供商服务器，用于实验性 fixture 和协议 mock 覆盖，而不替代具备场景感知能力的 `mock-openai` 通道。
- `pnpm openclaw qa suite --runner multipass`
- 在一次性 Multipass Linux VM 中运行同一个 QA 测试套件。
- 在一次性 Multipass Linux VM 内运行相同的 QA 测试套件。
- 与主机上的 `qa suite` 保持相同的场景选择行为。
- 复用与 `qa suite` 相同的提供商 / 模型选择标志。
- live 运行会转发对 guest 来说实际可用的受支持 QA 认证输入：基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。
- 输出目录必须保持在仓库根目录下，以便 guest 能通过挂载的工作区写回内容。
- 会将常规 QA 报告 + 摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。
- 实时运行会转发对来宾机实际可用的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。
- 输出目录必须保持在仓库根目录下，以便来宾机能够通过挂载的工作区回写内容。
- 将常规 QA 报告 + 摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。
- `pnpm qa:lab:up`
- 启动基于 Docker 的 QA 站点，用于偏操作员风格的 QA 工作。
- `pnpm test:docker:npm-onboard-channel-agent`
- 从当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，以非交互方式运行 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件会按需安装运行时依赖，运行 doctor，并针对一个 mock 的 OpenAI 端点执行一次本地智能体轮次。
- 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。
- 从当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，运行非交互式 OpenAI API-key onboarding，默认配置 Telegram，验证启用插件会按需安装运行时依赖，运行 doctor，并针对一个模拟的 OpenAI 端点执行一次本地智能体轮次。
- 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行同样的打包安装通道。
- `pnpm test:docker:session-runtime-context`
- 运行一个确定性的已构建应用 Docker 冒烟测试，用于嵌入式运行时上下文 transcript。它会验证隐藏的 OpenClaw 运行时上下文会以非展示型自定义消息持久化，而不会泄漏到可见的用户轮次中；随后会植入一个受影响的损坏会话 JSONL，并验证 `openclaw doctor --fix` 会将其重写到当前活动分支并保留备份。
- 运行一个确定性的、基于已构建应用的 Docker 冒烟测试，用于嵌入式运行时上下文 transcript。它会验证隐藏的 OpenClaw 运行时上下文作为非显示型自定义消息被持久化，而不是泄漏到可见的用户轮次中；随后会注入一个受影响的损坏会话 JSONL，并验证 `openclaw doctor --fix` 会将其重写为当前分支并生成备份。
- `pnpm test:docker:npm-telegram-live`
- 在 Docker 中安装一个已发布的 OpenClaw 软件包，运行已安装软件包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用 live Telegram QA 通道，并将该已安装软件包作为被测 Gateway 网关。
- 默认为 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。
- 与 `pnpm openclaw qa telegram` 使用相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，并同时设置 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色 secret。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和一个 Convex 角色 secret，Docker 包装器会自动选择 Convex。
- `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 可仅为这一通道覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。
- GitHub Actions 将这个通道作为手动维护者工作流 `NPM Telegram Beta E2E` 暴露。它不会在合并时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。
- 在 Docker 中安装一个已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用实时 Telegram QA 通道，将该已安装包作为被测 Gateway 网关。
- 默认使用 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。
- 使用与 `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 凭证租约。
- `pnpm test:docker:bundled-channel-deps`
- 在 Docker 中打包并安装当前 OpenClaw 构建版本，配置 OpenAI 后启动 Gateway 网关，然后通过配置编辑启用内置的渠道 / 插件。
- 验证 setup 发现流程不会安装未配置插件的运行时依赖；首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重新安装已激活的依赖。
- 还会安装一个已知较旧的 npm 基线版本，在运行 `openclaw update --tag <candidate>` 前启用 Telegram，并验证候选版本在更新后的 doctor 中会修复内置渠道的运行时依赖，而无需 harness 侧的 postinstall 修复。
- 在 Docker 中打包并安装当前 OpenClaw 构建，使用已配置的 OpenAI 启动 Gateway 网关，然后通过配置编辑启用内置的渠道 / 插件。
- 验证 setup discovery 不会提前安装未配置插件的运行时依赖；首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重新安装已激活的依赖。
- 还会安装一个已知的旧 npm 基线，在运行 `openclaw update --tag <candidate>` 之前启用 Telegram，并验证候选版本在更新后的 doctor 中会修复内置渠道运行时依赖，而无需依赖 harness 侧的 postinstall 修复。
- `pnpm test:parallels:npm-update`
- 在 Parallels guest 上运行原生打包安装更新冒烟测试。每个选中的平台会先安装请求的基线软件包，然后在同一个 guest 中运行已安装的 `openclaw update` 命令，并验证安装版本、更新状态、网关可用性以及一次本地智能体轮次。
- 在迭代单个 guest 时，使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 获取摘要工件路径和各通道状态。
- 默认情况下，OpenAI 通道使用 `openai/gpt-5.5` 作为 live 智能体轮次验证模型。若你有意验证其他 OpenAI 模型，可传入 `--model <provider/model>` 或设置 `OPENCLAW_PARALLELS_OPENAI_MODEL`。
- 请为长时间本地运行包裹主机超时，以防 Parallels 传输停顿耗尽剩余测试窗口：
- 在 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 传输停滞耗尽剩余测试时间窗口：
```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 更新在冷 guest 上可能会花费 10 到 15 分钟执行更新后 doctor / 运行时依赖修复；只要嵌套的 npm 调试日志仍在推进，这仍属于健康状态。
- 不要将这个聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享 VM 状态，可能会在快照恢复、软件包分发或 guest Gateway 网关状态上发生冲突。
- 更新后的验证会运行常规的内置插件表面，因为语音、图像生成和媒体理解等能力外观层即使在智能体轮次本身只检查简单文本响应时，也仍通过内置运行时 API 加载。
- 该脚本会将嵌套通道日志写入 `/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 加载。
- `pnpm openclaw qa aimock`
- 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。
- 仅启动本地 AIMock 提供商服务器，用于直接的协议冒烟测试。
- `pnpm openclaw qa matrix`
- 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix live QA 通道。
- 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix 实时 QA 通道。
- 这个 QA 主机目前仅供仓库 / 开发使用。打包后的 OpenClaw 安装不包含 `qa-lab`，因此不会暴露 `openclaw qa`。
- 仓库 checkout 会直接加载内置运行器；不需要单独的插件安装步骤。
- 会预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA Gateway 网关子进程，并使用真实的 Matrix 插件作为 SUT 传输层。
- 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。
- Matrix 不暴露共享凭证来源标志，因为该通道会在本地预配一次性用户。
- 会将 Matrix QA 报告、摘要、observed-events 工件以及合并后的 stdout / stderr 输出日志写入 `.artifacts/qa-e2e/...`。
- 默认会输出进度，并通过 `OPENCLAW_QA_MATRIX_TIMEOUT_MS`（默认 30 分钟）强制执行硬性运行超时。清理由 `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 限制，失败信息中会包含恢复命令 `docker compose ... down --remove-orphans`。
- 仓库 checkout 会直接加载内置运行器；无需单独安装插件。
- 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）和一个私有房间，然后以真实 Matrix 插件作为 SUT 传输层启动一个 QA gateway 子进程。
- 默认使用固定稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。
- 由于该通道会在本地预配一次性用户，因此 Matrix 不暴露共享凭证来源标志。
- 将 Matrix QA 报告、摘要、observed-events 产物以及合并后的 stdout / stderr 输出日志写入 `.artifacts/qa-e2e/...`。
- 默认输出进度，并通过 `OPENCLAW_QA_MATRIX_TIMEOUT_MS` 强制执行硬性运行超时（默认 30 分钟）。清理由 `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 限制，失败时会包含用于恢复的 `docker compose ... down --remove-orphans` 命令。
- `pnpm openclaw qa telegram`
- 使用环境变量中的 driver 和 SUT bot token，针对一个真实私有群组运行 Telegram live QA 通道。
- 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。group id 必须是数字形式的 Telegram chat id。
- 使用环境变量中的 driver 和 SUT bot token，针对真实私有群组运行 Telegram 实时 QA 通道。
- 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。group id 必须是 Telegram 聊天的数字 id。
- 支持 `--credential-source convex` 以使用共享凭证池。默认使用环境变量模式，或者设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。
- 当任一场景失败时会以非零状态退出。如果你想保留工件但不希望以失败退出码结束，可使用 `--allow-failures`。
- 要求在同一个私有群组中使用两个不同的 bot，并且 SUT bot 必须暴露一个 Telegram 用户名。
- 为了获得稳定的 bot 对 bot 观测，请在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 能观察群组中的 bot 流量。
- 会将 Telegram QA 报告、摘要以及 observed-messages 工件写入 `.artifacts/qa-e2e/...`。回复类场景会包含从 driver 发送请求到观测到 SUT 回复之间的 RTT。
- 任一场景失败时以非零状态退出。若你想保留产物但不希望以失败退出码结束，可使用 `--allow-failures`。
- 需要同一个私有群组中的两个不同 bot，且 SUT bot 必须暴露 Telegram 用户名。
- 为了实现稳定的 bot 对 bot 观察，请在 `@BotFather` 中为两个 bot 都启用 Bot-to-Bot Communication Mode，并确保 driver bot 能够观察群组中的 bot 流量。
- 将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。回复类场景会包含从 driver 发送请求到观察到 SUT 回复的 RTT。
live 传输通道共享一个标准契约，因此新增传输方式时不会发生漂移：
实时传输通道共享一个标准契约，这样新传输层就不会发生漂移：
`qa-channel` 仍然是宽泛的合成 QA 测试套件，不属于 live 传输覆盖矩阵的一部分。
`qa-channel` 仍然是广义的合成 QA 测试套件，不属于实时传输覆盖矩阵的一部分。
| 通道 | Canary | 提及门控 | Allowlist 阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | Reaction 观测 | 帮助命令 |
| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | ------------- | -------- |
| 通道 | Canary | Mention gating | Allowlist block | 顶层回复 | 重启恢复 | 线程后续回复 | 线程隔离 | 观察反应 | 帮助命令 |
| ---- | ------ | -------------- | --------------- | -------- | -------- | ------------ | -------- | -------- | -------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
### 通过 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 的凭证池获取独占租约，在通道运行期间对该租约发送心跳，并在关闭时释放租约。
参考 Convex 项目脚手架：
参考的 Convex 项目脚手架：
- `qa/convex-credential-broker/`
必需的环境变量：
必需环境变量：
- `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`）
- 所选角色对应的一个 secret：
- `maintainer` 使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
- `ci` 使用 `OPENCLAW_QA_CONVEX_SECRET_CI`
- 所选角色对应的一个密钥：
- `maintainer` 对应 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
- `ci` 对应 `OPENCLAW_QA_CONVEX_SECRET_CI`
- 凭证角色选择：
- CLI：`--credential-role maintainer|ci`
- 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则为 `maintainer`）
- 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则默认是 `maintainer`）
可选环境变量：
@ -167,14 +167,14 @@ live 传输通道共享一个标准契约，因此新增传输方式时不会发
- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`）
- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`）
- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`）
- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选的追踪 id）
- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选跟踪 id）
- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。
正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。
维护者管理命令（池添加 / 删除 / 列表）必须专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。
维护者管理命令（池添加 / 删除 / 列表）必须显式使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。
供维护者使用的 CLI 辅助命令：
面向维护者的 CLI 辅助命令：
```bash
pnpm openclaw qa credentials doctor
@ -183,87 +183,87 @@ pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>
```
在 live 运行前使用 `doctor`，可检查 Convex site URL、broker secrets、endpoint prefix、HTTP 超时以及 admin / list 可达性，同时不会打印 secret 值。在脚本和 CI 工具中可使用 `--json` 获取机器可读输出。
在实时运行前使用 `doctor` 检查 Convex 站点 URL、broker 密钥、endpoint 前缀、HTTP 超时和管理 / 列表可达性，同时不打印密钥值。在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。
默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）：
默认 endpoint 契约（`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`）
- `POST /release`
- 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken }`
- 成功：`{ status: "ok" }`（或空的 `2xx`）
- `POST /admin/add`（仅限 maintainer secret）
- `POST /admin/add`（仅 maintainer 密钥）
- 请求：`{ kind, actorId, payload, note?, status? }`
- 成功：`{ status: "ok", credential }`
- `POST /admin/remove`（仅限 maintainer secret）
- `POST /admin/remove`（仅 maintainer 密钥）
- 请求：`{ credentialId, actorId }`
- 成功：`{ status: "ok", changed, credential }`
- 活跃租约保护：`{ status: "error", code: "LEASE_ACTIVE", ... }`
- `POST /admin/list`（仅限 maintainer secret）
- `POST /admin/list`（仅 maintainer 密钥）
- 请求：`{ kind?, status?, includePayload?, limit? }`
- 成功：`{ status: "ok", credentials, count }`
Telegram 类型的负载结构：
- `{ groupId: string, driverToken: string, sutToken: string }`
- `groupId` 必须是数字形式的 Telegram chat id 字符串。
- 对于 `kind: "telegram"`，`admin/add` 会验证此结构，并拒绝格式错误的负载。
- `groupId` 必须是 Telegram 聊天数字 id 的字符串形式。
- `admin/add` 会对 `kind: "telegram"` 校验此结构，并拒绝格式错误的负载。
### 向 QA 添加一个渠道
向 Markdown QA 系统添加一个渠道，严格来说只需要两样东西：
将一个渠道添加到 markdown QA 系统中，严格来说只需要两样东西：
1. 该渠道的传输适配器。
2. 一个用于验证渠道契约的场景包。
2. 用于验证该渠道契约的场景包。
当共享的 `qa-lab` 主机可以承载该流程时，不要添加新的顶层 QA 命令根。
如果共享的 `qa-lab` 主机可以承载整个流程，就不要添加新的顶层 QA 命令根。
`qa-lab` 负责共享主机机制：
- `openclaw qa` 命令根
- 测试套件启动和拆除
- 工作进程并发
- 工件写入
- 测试套件启动与关闭
- worker 并发
- 产物写入
- 报告生成
- 场景执行
- 对旧版 `qa-channel` 场景的兼容别名
- 对旧 `qa-channel` 场景的兼容别名
运行器插件负责传输契约：
- `openclaw qa <runner>` 如何挂载到共享的 `qa` 根命令下
- 如何为该传输配置网关
- 如何将 `openclaw qa <runner>` 挂载到共享 `qa` 根之下
- 如何为该传输层配置 gateway
- 如何检查就绪状态
- 如何注入入站事件
- 如何观测出站消息
- 如何暴露 transcript 和标准化传输状态
- 如何观察出站消息
- 如何暴露 transcript 和规范化的传输状态
- 如何执行基于传输的操作
- 如何处理传输特定的重置或清理
新渠道的最低采用门槛是：
新渠道的最低接入门槛是：
1. 保持由 `qa-lab` 负责共享的 `qa` 根命令。
1. 继续让 `qa-lab` 拥有共享 `qa` 根。
2. 在共享的 `qa-lab` 主机接缝上实现传输运行器。
3. 将传输特定机制保留在运行器插件或渠道 harness 内部。
4. 将运行器挂载为 `openclaw qa <runner>`，而不是注册一个相互竞争的根命令。
运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。
保持 `runtime-api.ts` 轻量；惰性 CLI 和运行器执行应留在独立入口点之后。
5. 在具有主题划分的 `qa/scenarios/` 目录下编写或改造 Markdown 场景。
4. 将运行器挂载为 `openclaw qa <runner>`，而不是注册一个竞争性的根命令。
运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并在 `runtime-api.ts` 中导出匹配的 `qaRunnerCliRegistrations` 数组。
保持 `runtime-api.ts` 轻量；惰性 CLI 和运行器执行应保留在单独的入口点之后。
5. 在按主题划分的 `qa/scenarios/` 目录下编写或改造 markdown 场景。
6. 为新场景使用通用场景辅助函数。
7. 除非仓库正在执行有意迁移，否则保持现有兼容别名继续可用。
7. 保持现有兼容别名继续工作，除非仓库正在进行有意的迁移。
决策规则很严格：
决策规则是严格的：
- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放进 `qa-lab`。
- 如果某个行为依赖于单一渠道传输，就把它保留在该运行器插件或插件 harness 中。
- 如果某个场景需要多个渠道都可使用的新能力，应添加通用辅助函数，而不是在 `suite.ts` 中增加渠道特定分支。
- 如果某个行为只对单一传输有意义，就保持该场景是传输特定的，并在场景契约中明确说明。
- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放在 `qa-lab`。
- 如果某个行为依赖单一渠道传输层，就把它保留在该运行器插件或插件 harness 中。
- 如果一个场景需要一个以上渠道都能使用的新能力，就添加一个通用辅助函数，而不是在 `suite.ts` 中加入渠道特定分支。
- 如果某个行为仅对一种传输层有意义，就将该场景保留为传输层特定，并在场景契约中明确说明。
新场景优先使用的通用辅助函数名称是：
新场景推荐使用的通用辅助函数名称是：
- `waitForTransportReady`
- `waitForChannelReady`
@ -278,7 +278,7 @@ Telegram 类型的负载结构：
- `formatTransportTranscript`
- `resetTransport`
现有场景仍可使用的兼容别名包括：
现有场景仍可使用兼容别名，包括：
- `waitForQaChannelReady`
- `waitForOutboundMessage`
@ -287,87 +287,87 @@ Telegram 类型的负载结构：
- `resetBus`
新的渠道工作应使用通用辅助函数名称。
兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。
兼容别名的存在是为了避免一次性迁移日，而不是作为新场景编写的模板。
## 测试套件（分别在哪里运行）
## 测试套件（哪些内容在哪里运行）
可以把这些测试套件理解为“真实性逐步提升”（同时不稳定性 / 成本也逐步增加）：
可以把这些测试套件理解为“真实性逐步增加”（同时不稳定性 / 成本也逐步增加）：
### 单元 / 集成（默认）
- 命令：`pnpm test`
- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度
- 文件：核心 / 单元测试清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试
- 配置：未指定目标的运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度
- 文件：由 `vitest.unit.config.ts` 覆盖的核心 / 单元清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及白名单中的 `ui` node 测试
- 范围：
- 纯单元测试
- 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
- 针对已知缺陷的确定性回归测试
- 进程内集成测试（gateway 凭证、路由、工具、解析、配置）
- 已知缺陷的确定性回归测试
- 预期：
- 在 CI 中运行
- 不需要真实密钥
- 应该快速且稳定
<AccordionGroup>
<Accordion title="项目、分片和定向通道">
<Accordion title="项目、分片和作用域通道">
- 未定向的 `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 / extension 工作拖慢无关测试套件。
- `pnpm test --watch` 仍使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不现实。
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先通过定向通道处理显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可以避免承担完整根项目启动成本。
- `pnpm test:changed` 会在差异仅涉及可路由的源文件 / 测试文件时，将变更的 git 路径展开到相同的定向通道；配置 / setup 编辑仍会回退到更宽泛的根项目重跑。
- `pnpm check:changed` 是针对小范围工作的常规智能本地门禁。它会将差异归类为 core、core tests、extensions、extension tests、apps、docs、发布元数据、live Docker 工具以及工具链，然后运行匹配的类型检查 / lint / 测试通道。公共 Plugin SDK 和插件契约变更会额外包含一次 extension 验证，因为 extensions 依赖这些核心契约。仅涉及发布元数据的版本升级会运行定向的版本 / 配置 / 根依赖检查，而不是完整测试套件，并通过一个保护机制拒绝顶层版本字段之外的 package 变更。
- live Docker ACP harness 编辑会运行一个聚焦型本地门禁：对 live Docker 认证脚本做 shell 语法检查、执行 live Docker 调度器 dry-run、运行 ACP bind 单元测试以及 ACPX extension 测试。只有当差异仅限于 `scripts["test:docker:live-*"]` 时，才会包含 `package.json` 变更；依赖、导出、版本和其他 package 表面编辑仍会使用更宽泛的保护措施。
- 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试，会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道中。
- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会将 changed 模式运行映射到这些轻量通道中的显式同级测试，因此辅助函数编辑无需为该目录重跑完整的重型测试套件。
- `auto-reply` 为顶层 core 辅助函数、顶层 `reply.*` 集成测试以及 `src/auto-reply/reply/**` 子树提供了专用分桶。CI 还会进一步将 reply 子树拆分为 agent-runner、dispatch 和 commands / state-routing 分片，这样导入较重的单个分桶就不会独占整个 Node 收尾阶段。
- 未指定目标的 `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 / 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` 是窄范围工作时常规的智能本地检查门禁。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs、发布元数据、实时 Docker 工具和工具链，然后运行匹配的类型检查、lint 和保护命令。它不会运行 Vitest 测试；如需测试证明，请调用 `pnpm test:changed` 或显式运行 `pnpm test <target>`。仅发布元数据的版本升级会运行定向的版本 / 配置 / 根依赖检查，并带有一个保护机制，拒绝顶层 version 字段之外的 package 变更。
- 实时 Docker ACP harness 编辑会运行聚焦检查：实时 Docker 认证脚本的 shell 语法检查，以及实时 Docker 调度器 dry-run。仅当 diff 限定在 `scripts["test:docker:live-*"]` 时，才会包含 `package.json` 变更；依赖、导出、版本和其他包表面编辑仍会使用更广泛的保护检查。
- 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时负载较重的文件仍保留在现有通道上。
- 选定的 `plugin-sdk` 和 `commands` 辅助源码文件也会将 changed-mode 运行映射到这些轻量通道中的显式同级测试，因此辅助函数编辑不必为该目录重跑完整的重型测试套件。
- `auto-reply` 为顶层 core 辅助函数、顶层 `reply.*` 集成测试以及 `src/auto-reply/reply/**` 子树设置了专用分桶。CI 还会将 reply 子树进一步拆分为 agent-runner、dispatch 和 commands / state-routing 分片，这样单个导入开销大的分桶就不会占据完整的 Node 尾部时间。
</Accordion>
<Accordion title="嵌入式运行器覆盖">
- 当你修改消息工具发现输入或压缩运行时上下文时，请同时保留两个层级的覆盖。
- 为纯路由和标准化边界添加聚焦型辅助函数回归测试。
- 当你更改消息工具发现输入或压缩运行时上下文时，要同时保留两个层级的覆盖。
- 为纯路由和规范化边界添加聚焦的辅助函数回归测试。
- 保持嵌入式运行器集成测试套件健康：
`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 和压缩行为仍会通过真实的 `run.ts` / `compact.ts` 路径流转；仅辅助函数测试不足以替代这些集成路径。
- 这些测试套件会验证作用域 id 和压缩行为仍然通过真实的 `run.ts` / `compact.ts` 路径流转；仅有辅助函数测试并不足以替代这些集成路径。
</Accordion>
<Accordion title="Vitest 池和隔离默认值">
- 基础 Vitest 配置默认使用 `threads`。
- 共享 Vitest 配置固定为 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。
- 根 UI 通道保留其 `jsdom` setup 和优化器，但也运行在共享的非隔离运行器上。
- 每个 `pnpm test` 分片都继承共享 Vitest 配置中的相同 `threads` + `isolate: false` 默认值。
- `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可对比原生 V8 行为。
- 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。
- 根 UI 通道保留其 `jsdom` setup 和 optimizer，但也运行在共享的非隔离运行器上。
- 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。
- `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行比较。
</Accordion>
<Accordion title="快速本地迭代">
- `pnpm changed:lanes` 会显示某个差异会触发哪些架构通道。
- pre-commit hook 只负责格式化。它会重新暂存格式化后的文件，不会运行 lint、类型检查或测试。
- 在交接或 push 前，当你需要智能本地门禁时，请显式运行 `pnpm check:changed`。公共 Plugin SDK 和插件契约变更会额外包含一次 extension 验证。
- `pnpm test:changed` 会在变更路径能够清晰映射到较小测试套件时，通过定向通道运行。
- `pnpm changed:lanes` 会显示一个 diff 触发了哪些架构通道。
- pre-commit hook 仅负责格式化。它会重新暂存已格式化文件，但不会运行 lint、类型检查或测试。
- 当你需要智能本地检查门禁时，在交接或推送前显式运行 `pnpm check:changed`。
- `pnpm test:changed` 默认通过低成本作用域通道进行路由。只有当智能体判断 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-mode 重跑仍然正确。
- 该配置会在受支持主机上保持 `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` 以来发生变化的文件。
- `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。
整体配置运行以配置路径作为键；include-pattern CI 分片会附加分片名称，以便单独跟踪被过滤的分片。
- 当某个热点测试的大部分时间仍然耗在启动导入上时，应将重型依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了通过 `vi.mock(...)` 传递运行时辅助函数而深度导入它们。
- `pnpm test:perf:changed:bench -- --ref <git-ref>` 会将已路由的 `test:changed` 与该已提交 diff 的原生根项目路径进行比较，并打印总耗时以及 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` 会在禁用文件级并行的情况下，为单元测试套件写入运行器 CPU + heap profile。
</Accordion>
</AccordionGroup>
@ -377,73 +377,73 @@ Telegram 类型的负载结构：
- 命令：`pnpm test:stability:gateway`
- 配置：`vitest.gateway.config.ts`，强制单 worker
- 范围：
- 默认启动一个启用了诊断功能的真实 loopback Gateway 网关
- 通过诊断事件路径驱动合成的网关消息、内存和大负载抖动
- 启动一个真实的 loopback Gateway 网关，并默认启用诊断
- 通过诊断事件路径驱动合成的 gateway 消息、内存和大负载 churn
- 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability`
- 覆盖诊断稳定性 bundle 持久化辅助函数
- 断言记录器保持有界、合成 RSS 样本保持在压力预算之下，且每个会话的队列深度会回落到零
- 断言记录器保持有界、合成 RSS 样本保持在压力预算之下，并且每个会话的队列深度都会回落到零
- 预期：
- 可安全用于 CI，且无需密钥
- 这是用于稳定性回归跟进的窄通道，不可替代完整的 Gateway 网关测试套件
- 对 CI 安全且无需密钥
- 这是用于稳定性回归跟进的窄范围通道，不可替代完整 Gateway 网关测试套件
### E2E（Gateway 网关冒烟）
### E2E（Gateway 网关冒烟测试）
- 命令：`pnpm test:e2e`
- 配置：`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` 重新启用详细控制台输出。
- 默认以静默模式运行，以降低控制台 I/O 开销。
- 常用覆盖：
- `OPENCLAW_E2E_WORKERS=<n>` 用于强制指定 worker 数量（上限为 16）。
- `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。
- 范围：
- 多实例网关端到端行为
- WebSocket / HTTP 表面、节点配对以及更重的网络行为
- 多实例 gateway 端到端行为
- WebSocket / HTTP 表面、节点配对和更重的网络交互
- 预期：
- 会在 CI 中运行（当在流水线中启用时）
- 在 CI 中运行（当流水线启用时）
- 不需要真实密钥
- 比单元测试有更多可变因素（可能更慢）
- 比单元测试包含更多活动部件（可能更慢）
### E2E：OpenShell 后端冒烟
### E2E：OpenShell 后端冒烟测试
- 命令：`pnpm test:e2e:openshell`
- 文件：`extensions/openshell/src/backend.e2e.test.ts`
- 范围：
- 通过 Docker 在主机上启动一个隔离的 OpenShell 网关
- 从一个临时本地 Dockerfile 创建一个沙箱
- 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端
- 通过沙箱文件系统桥验证远端规范文件系统行为
- 通过 Docker 在主机上启动一个隔离的 OpenShell gateway
- 从临时本地 Dockerfile 创建一个沙箱
- 通过真实的 `sandbox ssh-config` + SSH exec 调用 OpenClaw 的 OpenShell 后端
- 通过沙箱 fs bridge 验证远端规范文件系统行为
- 预期：
- 仅按需启用；不属于默认的 `pnpm test:e2e` 运行
- 仅限选择性启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 需要本地 `openshell` CLI 和可用的 Docker daemon
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，之后会销毁测试网关和沙箱
- 常用覆盖项：
- 在手动运行更宽泛的 e2e 测试套件时，设置 `OPENCLAW_E2E_OPENSHELL=1` 可启用该测试
- 设置 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 可指向非默认的 CLI 二进制或包装脚本
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 gateway 和沙箱
- 常用覆盖：
- `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/` 下内置插件的 live 测试
- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下内置插件的实时测试
- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`）
- 范围：
- “这个提供商 / 模型 _今天_ 是否真的能在真实凭证下工作？”
- 捕获提供商格式变化、工具调用怪癖、认证问题和速率限制行为
- “这个提供商 / 模型在**今天**使用真实凭证时是否真的能工作？”
- 捕捉提供商格式变化、工具调用怪癖、认证问题和速率限制行为
- 预期：
- 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障）
- 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、中断）
- 会花钱 / 消耗速率限制
- 优先运行收窄后的子集，而不是“全部”
- live 运行会加载 `~/.profile` 以获取缺失的 API 密钥。
- 默认情况下，live 运行仍会隔离 `HOME`，并将配置 / 认证材料复制到一个临时测试 home 中，这样单元测试夹具就不会修改你真实的 `~/.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 运行覆盖；测试会在遇到速率限制响应时重试。
- 优先运行缩小范围的子集，而不是“全部”
- 实时运行会读取 `~/.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 测试套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也仍能显示为活跃状态。
- `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此提供商 / 网关进度行会在 live 运行期间立即流式输出。
- 实时测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获较安静，较长的提供商调用也能可见地显示为正在运行。
- `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此提供商 / gateway 进度行会在实时运行期间立即流式输出。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。
- 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。
@ -451,147 +451,145 @@ Telegram 类型的负载结构：
使用这个决策表：
- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，再加上 `pnpm test:coverage`）
- 触及 Gateway 网关网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e`
- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行收窄后的 `pnpm test:live`
- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，再运行 `pnpm test:coverage`）
- 修改 gateway 网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e`
- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live`
## live（触网）测试
## 实时（触网）测试
关于 live 模型矩阵、CLI 后端冒烟测试、ACP 冒烟测试、Codex app-server harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、音乐、视频、媒体 harness）——以及 live 运行的凭证处理——请参阅 [Testing — live suites](/zh-CN/help/testing-live)。
关于实时模型矩阵、CLI 后端冒烟测试、ACP 冒烟测试、Codex app-server harness，以及所有媒体提供商实时测试（Deepgram、BytePlus（国际版）、ComfyUI、image、music、video、media harness）——以及实时运行的凭证处理——请参阅 [测试 — 实时测试套件](/zh-CN/help/testing-live)。
## Docker 运行器（可选的“在 Linux 中可用”检查）
## Docker 运行器（可选的“在 Linux 中可运行”检查）
这些 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`），同时挂载你的本地配置目录和工作区（如果已挂载，也会加载 `~/.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`、
- 实时模型运行器：`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 扫描仍然可行：
`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` 构建一次 live Docker 镜像，再通过 `scripts/package-openclaw-for-docker.mjs` 将 OpenClaw 打包一次为 npm tarball，然后构建 / 复用两个 `scripts/e2e/Dockerfile` 镜像。裸镜像仅作为 Node / Git 运行器，用于 install / update / plugin-dependency 通道；这些通道会挂载预构建的 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` 控制进程槽位，而资源上限会防止重型 live、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` 打印所选通道、package / 镜像需求以及凭证的 CI 计划。
`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` 镜像。裸镜像仅作为 install / update / plugin-dependency 通道的 Node / Git 运行器；这些通道会挂载预构建的 tarball。功能镜像会将同一个 tarball 安装到 `/app` 中，供基于已构建应用的功能通道使用。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；planner 逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 会执行所选计划。该聚合运行器使用加权本地调度器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制进程槽位，而资源上限会阻止高负载的实时、npm-install 和多服务通道同时启动过多。默认值为 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` 输出所选通道、package / image 需求以及凭证的 CI 计划。
- 容器冒烟运行器：`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` 会启动一个或多个真实容器，并验证更高层级的集成路径。
live 模型 Docker 运行器还会仅绑定挂载所需的 CLI 认证 home 目录（如果运行未收窄，则挂载所有受支持的目录），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改宿主机的认证存储：
实时模型 Docker 运行器还会只 bind-mount 所需的 CLI 认证 home 目录（或者在运行未缩小范围时挂载所有受支持的目录），然后在运行前将它们复制到容器 home 中，以便外部 CLI OAuth 可以刷新 token，而不会修改主机认证存储：
- 直接模型：`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，对 Droid / OpenCode 的严格覆盖可使用 `pnpm test:docker:live-acp-bind:droid` 和 `pnpm test:docker:live-acp-bind: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 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- 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 会修复已激活插件的运行时依赖，并运行一次 mocked 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` 并检查更新状态。
- 会话运行时上下文冒烟测试：`pnpm test:docker:session-runtime-context` 会验证隐藏运行时上下文 transcript 的持久化，以及 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/`。
- Installer Docker 冒烟测试：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享同一个 npm 缓存。更新冒烟测试默认使用 npm `latest` 作为稳定基线，然后升级到候选 tarball。非 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` 覆盖时，请在本地运行脚本且不要设置该环境变量。
- 智能体删除共享工作区 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 镜像。
- Npm tarball onboarding / 渠道 / 智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装已打包的 OpenClaw tarball，通过 env-ref onboarding 配置 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` 并检查更新状态。
- 会话运行时上下文冒烟测试：`pnpm test:docker:session-runtime-context` 会验证隐藏运行时上下文 transcript 的持久化，以及对受影响的重复 prompt-rewrite 分支进行 doctor 修复。
- Bun 全局安装冒烟测试：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中通过 `bun install -g` 安装它，并验证 `openclaw infer image providers --json` 返回的是内置 image 提供商，而不是挂起。可使用 `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。非 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 网关运行一个 mocked OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始细节出现在 Gateway 网关日志中。
- MCP 渠道桥接（已植入的 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟测试）：`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 / subagent MCP 清理（真实 Gateway 网关 + 在隔离的 cron 和一次性 subagent 运行后拆除 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` 可跳过 live ClawHub 区块，或通过 `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` 和 `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` 覆盖默认 package。
- 插件更新未变化冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-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`）会让一个模拟的 OpenAI 服务器通过 Gateway 网关运行，验证 `web_search` 将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。
- MCP 渠道桥接（预置 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi 配置文件 allow / deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`）
- Cron / 子智能体 MCP 清理（真实 Gateway 网关 + stdio MCP 子进程在隔离的 cron 和一次性子智能体运行后被拆除）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`）
- 插件（安装冒烟测试、ClawHub 安装 / 卸载、市场更新，以及 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` 覆盖默认 package。
- 插件更新未变更冒烟测试：`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 的独立更新通道。直接运行内置通道时，可使用 `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 聚合运行器会先预打包此 tarball 一次，然后将内置渠道检查分片为独立通道，包括 Telegram、Discord、Slack、Feishu、memory-lancedb 和 ACPX 的独立更新通道。直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 缩小渠道矩阵，或使用 `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` 缩小更新场景。该通道还会验证 `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 和 installer Docker 测试仍保留各自的 Dockerfile，因为它们验证的是 package / install 行为，而不是共享的已构建应用运行时。
设置后，像 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这样的特定测试套件镜像覆盖仍然具有更高优先级。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未存在于本地，脚本会先拉取它。QR 和安装器 Docker 测试保留它们各自的 Dockerfile，因为它们验证的是 package / install 行为，而不是共享的已构建应用运行时。
live 模型 Docker 运行器还会以只读方式绑定挂载当前 checkout，并将其暂存到容器内的临时工作目录中。这样可以保持运行时镜像精简，同时仍然让 Vitest 针对你本地精确的源码 / 配置运行。
暂存步骤会跳过大型的本地专用缓存和应用构建输出，例如
`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或 Gradle 输出目录，这样 Docker live 运行就不会花上数分钟复制机器特定的工件。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关 live 探测就不会在容器内启动真实的 Telegram / Discord / 等渠道工作进程。
`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要从该 Docker 通道中收窄或排除 Gateway 网关 live 覆盖时，也要一并传递 `OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw 网关容器，针对该网关启动一个固定版本的 Open WebUI 容器，通过 Open WebUI 登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。
实时模型 Docker 运行器还会以只读方式 bind-mount 当前 checkout，并在容器内将其暂存到一个临时工作目录中。这样可以让运行时镜像保持精简，同时仍然针对你精确的本地源码 / 配置运行 Vitest。暂存步骤会跳过大型本地专用缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或 Gradle 输出目录，这样 Docker 实时运行就不会花上几分钟去复制机器特定的产物。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway 实时探测就不会在容器内启动真实的 Telegram / Discord / 等渠道 worker。
`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 可能需要完成自身的冷启动设置。
该通道要求提供可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`（默认为 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
成功运行会打印一个小型 JSON 负载，例如 `{ "ok": true, "model": "openclaw/default", ... }`。
`test:docker:mcp-channels` 被刻意设计为确定性的，不需要真实的 Telegram、Discord 或 iMessage 账户。它会启动一个已植入的 Gateway 网关容器，启动第二个容器来运行 `openclaw mcp serve`，然后验证路由后的会话发现、transcript 读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio MCP bridge 传输的 Claude 风格渠道 + 权限通知。通知检查会直接检查原始 stdio MCP frame，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。
`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要 live 模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP probe 服务器，通过嵌入式 Pi 内置 MCP 运行时将该服务器实体化，执行该工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。
`test:docker:cron-mcp-cleanup` 是确定性的，不需要 live 模型密钥。它会启动一个已植入的 Gateway 网关和一个真实的 stdio MCP probe 服务器，运行一个隔离的 cron 轮次和一个 `/subagents spawn` 一次性子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。
这个通道需要一个可用的实时模型密钥，而 `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 验证路由后的会话发现、transcript 读取、附件元数据、实时事件队列行为、出站发送路由，以及 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 子进程会在每次运行后退出。
手动 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_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/...`
- 默认目录：`.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_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于收窄运行范围
- 缩小范围后的提供商运行只会挂载从 `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` 镜像
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而非环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择在 Open WebUI 冒烟测试中由网关暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试中使用的 nonce 检查提示词
- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用已有的 `openclaw:local-live` 镜像，以便在无需重建时重跑
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而不是环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 Gateway 网关向 Open WebUI 冒烟测试暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试所用的 nonce 检查提示词
- `OPENWEBUI_IMAGE=...` 用于覆盖固定的 Open WebUI 镜像标签
## 文档完整性检查
在修改文档后运行文档检查：`pnpm check:docs`。
当你还需要检查页内标题时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。
文档修改后运行文档检查：`pnpm check:docs`。
当你还需要检查页面内标题锚点时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。
## 离线回归测试（CI 安全）
## 离线回归测试（对 CI 安全）
这些是在没有真实提供商的情况下运行的“真实流水线”回归测试：
这些是“不依赖真实提供商的真实流水线”回归测试：
- Gateway 网关工具调用（mock OpenAI，真实网关 + 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`，强制写入配置 + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
## 智能体可靠性评估（Skills）
我们已经有一些可安全用于 CI 的测试，其行为类似“智能体可靠性评估”：
我们已经有一些对 CI 安全的测试，它们的行为类似“智能体可靠性评估”：
- 通过真实 Gateway 网关 + Agent loop 的 mock 工具调用（`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)），目前仍缺少的是：
- **决策能力：** 当 prompt 中列出 Skills 时，智能体是否会选择正确的 Skills（或避开无关的 Skills）？
- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循所需步骤 / 参数？
- **决策能力：** 当 Skills 列在提示词中时，智能体是否会选择正确的 Skill（或者避免选择无关 Skill）？
- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循要求的步骤 / 参数？
- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。
未来的评估应首先保持确定性：
- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、Skills 文件读取以及会话接线。
- 一小组以 Skills 为中心的场景（使用 vs 避免、门控、提示注入）。
- 仅在 CI 安全测试套件就位后，才添加可选的 live 评估（按需启用、受环境变量门控）。
- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话接线。
- 一小组聚焦 Skill 的场景（使用与避免、门控、提示注入）。
- 只有在对 CI 安全的测试套件落地之后，才添加可选的实时评估（选择性启用、受环境变量门控）。
## 契约测试（插件和渠道形状）
契约测试用于验证每个已注册的插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元测试通道会有意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。
契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组形状和行为断言。默认的 `pnpm test` 单元测试通道会有意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。
### 命令
- 所有契约测试：`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`：
@ -600,24 +598,24 @@ live 模型 Docker 运行器还会以只读方式绑定挂载当前 checkout，
- **session-binding** - 会话绑定行为
- **outbound-payload** - 消息负载结构
- **inbound** - 入站消息处理
- **actions** - 渠道 action 处理器
- **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** - 插件加载
@ -627,26 +625,26 @@ live 模型 Docker 运行器还会以只读方式绑定挂载当前 checkout，
### 何时运行
- 修改 plugin-sdk 导出或子路径后
- 添加或修改渠道或提供商插件后
- 重构插件注册或发现逻辑后
- 修改 plugin-sdk 导出或子路径之后
- 添加或修改渠道或提供商插件之后
- 重构插件注册或发现逻辑之后
契约测试会在 CI 中运行，并且不需要真实 API 密钥。
契约测试会在 CI 中运行，不需要真实 API 密钥。
## 添加回归测试（指南）
当你修复了在 live 中发现的提供商 / 模型问题时：
当你修复一个在实时环境中发现的提供商 / 模型问题时：
- 如果可能，添加一个对 CI 安全的回归测试（mock / stub 提供商，或捕获精确的请求形状转换）
- 如果它本质上只能通过 live 测试验证（速率限制、认证策略），就保持 live 测试足够收窄，并通过环境变量按需启用
- 优先瞄准能捕获该缺陷的最小层级：
- 提供商请求转换 / 重放缺陷 → 直接模型测试
- Gateway 网关会话 / 历史 / 工具流水线缺陷 → Gateway 网关 live 冒烟测试或对 CI 安全的 Gateway 网关 mock 测试
- SecretRef 遍历保护栏：
- `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。
- 如果你在 `src/secrets/target-registry-data.ts` 中新增了一个 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类的目标 id 时有意失败，以确保新类别不会被静默跳过。
- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换）
- 如果它天然只能在实时环境中复现（速率限制、认证策略），就让实时测试保持范围狭窄，并通过环境变量选择性启用
- 优先瞄准能够捕获此缺陷的最小层级：
- 提供商请求转换 / 回放缺陷 → 直接模型测试
- gateway 会话 / 历史 / 工具流水线缺陷 → gateway 实时冒烟测试或对 CI 安全的 gateway mock 测试
- SecretRef 遍历防护：
- `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历分段 exec id 会被拒绝。
- 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。这个测试会在目标 id 未被分类时故意失败，这样新的类别就无法被悄悄跳过。
## 相关内容
- [Testing live](/zh-CN/help/testing-live)
- [测试实时环境](/zh-CN/help/testing-live)
- [CI](/zh-CN/ci)

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

@ -1,54 +1,55 @@
---
read_when:
- 运行或修复测试
summary: 如何在本地运行测试（`vitest`），以及何时使用 `force` / `coverage` 模式
summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式
title: 测试
x-i18n:
generated_at: "2026-04-26T22:39:43Z"
generated_at: "2026-04-26T23:09:31Z"
model: gpt-5.4
provider: openai
source_hash: 57a5eff6e46662960a9b06a1f6883bb22b3fd8598de6338b4e7da3fa1b90b492
source_hash: ac57661d94c1d83195f63c342356c44130b4c3c459dd3965caad8ae3826266e3
source_path: reference/test.md
workflow: 15
---
- 完整测试工具包（测试套件、live、Docker）：[测试](/zh-CN/help/testing)
- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务器测试与正在运行的实例发生冲突。当先前的 Gateway 网关运行导致端口 `18789` 仍被占用时，使用此命令。
- `pnpm test:coverage`：通过 `vitest.unit.config.ts` 使用 V8 coverage 运行单元测试套件。这是一个基于已加载文件的单元 coverage 检查，而不是覆盖整个仓库所有文件的 coverage。阈值为：行数 / 函数 / 语句 70%，分支 55%。由于 `coverage.all` 为 false，该检查只统计被单元 coverage 套件加载的文件，而不会把所有拆分测试通道中的源文件都视为未覆盖。
- `pnpm test:coverage:changed`：只针对相对于 `origin/main` 发生变更的文件运行单元 coverage。
- `pnpm test:changed`：当 diff 只涉及可路由的源文件 / 测试文件时，将 Git 变更路径展开为有范围限制的 Vitest 测试通道。配置 / setup 变更仍会回退到原生根项目运行方式，因此接线类修改在需要时会更广泛地重新运行测试。
- `pnpm test:changed:focused`：用于内循环的变更测试运行。它只会基于直接修改的测试文件、同级 `*.test.ts` 文件、显式源文件映射以及本地导入图来运行精确目标。广泛的 / 配置 / package 变更会被跳过，而不是扩展为完整的变更测试回退运行。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构测试通道。
- `pnpm check:changed`：对相对于 `origin/main` 的 diff 运行智能变更检查。它会将核心代码与核心测试通道一起运行，将扩展代码与扩展测试通道一起运行，仅测试变更则只运行测试类型检查 / 测试；对于公开的 插件 SDK 或插件契约变更，会额外扩展一次扩展校验；对于仅包含发布元数据的版本号提升，则保持在有针对性的版本 / 配置 / 根依赖检查范围内。
- `pnpm test`：将显式传入的文件 / 目录目标路由到有范围限制的 Vitest 测试通道。未指定目标时，会使用固定的分片组，并展开到叶子配置以便在本地并行执行；扩展组始终会展开为各个扩展 / 插件的分片配置，而不是使用一个巨大的根项目进程。
- 完整测试、扩展测试和 include-pattern 分片运行会把本地耗时数据更新到 `.artifacts/vitest-shard-timings.json`；后续整套配置运行会利用这些耗时数据来平衡慢分片和快分片。include-pattern CI 分片会把分片名称附加到耗时键名中，因此筛选后的分片耗时仍可见，而不会覆盖整套配置的耗时数据。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时产物。
- 部分 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用的轻量测试通道，只保留 `test/setup.ts`，而运行时负担较重的用例仍保留在原有测试通道中。
- 带有同级测试的源文件会优先映射到该同级测试，然后才会回退到更宽泛的目录 glob。`test/helpers/channels` 和 `test/helpers/plugins` 下的辅助文件变更会使用本地导入图来运行导入它们的测试，而不是在依赖路径明确时广泛运行所有分片。
- `auto-reply` 现在还拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply harness 就不会主导较轻量的顶层 Status / token / helper 测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用共享的非隔离运行器。
- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，这样服务器测试就不会与正在运行的实例发生冲突。当之前的 Gateway 网关运行遗留并占用了端口 `18789` 时，请使用它。
- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库的所有文件覆盖率。阈值为 70% 的行数/函数/语句覆盖率，以及 55% 的分支覆盖率。由于 `coverage.all` 为 false，该门禁衡量的是被单元覆盖率套件加载的文件，而不是把每个拆分 lane 中的源文件都视为未覆盖。
- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来发生变更的文件运行单元覆盖率。
- `pnpm test:changed`：低成本的智能变更测试运行。它会根据直接修改的测试文件、同级 `*.test.ts` 文件、显式源码映射以及本地导入图，运行精确目标。宽泛的变更、配置或 package 变更会被跳过，除非它们能映射到精确的测试。
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：显式的宽范围变更测试运行。当测试 harness、配置或 package 编辑需要回退到 Vitest 更宽泛的变更测试行为时，请使用它。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的差异所触发的架构 lanes。
- `pnpm check:changed`：对相对于 `origin/main` 的差异运行智能变更检查门禁。它会为受影响的架构 lanes 运行 typecheck、lint 和 guard 命令，但不会运行 Vitest 测试。需要测试证明时，请使用 `pnpm test:changed` 或显式的 `pnpm test <target>`。
- `pnpm test`：通过带作用域的 Vitest lanes 路由显式的文件/目录目标。未指定目标的运行会使用固定的分片组，并展开为叶子配置以便本地并行执行；extension 组始终会展开为按 extension 划分的分片配置，而不是一个巨大的根项目进程。
- 测试包装器运行结束时会输出一个简短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自身的耗时行仍然保留为每个分片的详细信息。
- 完整、extension 和 include-pattern 分片运行会把本地耗时数据更新到 `.artifacts/vitest-shard-timings.json`；后续的整配置运行会使用这些耗时数据来平衡慢分片和快分片。include-pattern CI 分片会把分片名称附加到耗时键上，这样筛选后的分片耗时仍然可见，而不会替换整配置的耗时数据。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时产物。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量 lanes 路由，这些 lanes 仅保留 `test/setup.ts`，而运行时较重的用例仍保留在原有 lanes 中。
- 带有同级测试的源文件会优先映射到该同级测试，然后才回退到更宽的目录 glob。`test/helpers/channels` 和 `test/helpers/plugins` 下的辅助代码编辑会使用本地导入图来运行导入它们的测试，而不是在依赖路径明确时宽泛地运行每个分片。
- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），因此 reply harness 不会再主导更轻量的顶层 status/token/helper 测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并且整个仓库配置中启用了共享的非隔离 runner。
- `pnpm test:channels` 运行 `vitest.channels.config.ts`。
- `pnpm test:extensions` 和 `pnpm test extensions` 会运行所有扩展 / 插件分片。重量级渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组保持批量运行。对单个内置插件测试通道，使用 `pnpm test extensions/<id>`。
- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入拆解报告，同时对显式文件 / 目录目标仍使用有范围限制的测试通道路由。
- `pnpm test:perf:imports:changed`：与上面相同的导入性能分析，但仅针对相对于 `origin/main` 发生变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一份已提交的 Git diff，对路由后的 changed 模式路径与原生根项目运行做基准对比。
- `pnpm test:perf:changed:bench -- --worktree`：先不提交，直接对当前 worktree 的变更集做基准对比。
- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有 extension/plugin 分片。较重的渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组则继续保持批量运行。对单个内置插件 lane，请使用 `pnpm test extensions/<id>`。
- `pnpm test:perf:imports`：启用 Vitest 的导入耗时和导入明细报告，同时对显式文件/目录目标继续使用带作用域的 lane 路由。
- `pnpm test:perf:imports:changed`：同样进行导入性能分析，但仅针对自 `origin/main` 以来变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一组已提交的 git diff，对比带路由的 changed 模式路径与原生根项目运行的基准表现。
- `pnpm test:perf:changed:bench -- --worktree`：对当前 worktree 的变更集进行基准测试，无需先提交。
- `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。
- `pnpm test:perf:profile:runner`：为 unit runner 写入 CPU + heap profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行完整测试套件中的每个 Vitest 叶子配置，并写出分组耗时数据以及每个配置的 JSON / 日志产物。测试性能智能体会将其作为尝试修复慢测试之前的基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：对比性能优化变更前后的分组报告。
- `pnpm test:perf:profile:runner`：为单元 runner 写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组耗时数据以及每个配置对应的 JSON/日志产物。Test Performance Agent 会在尝试修复慢测试之前，把它作为基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在性能优化相关变更之后比较分组报告。
- Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 显式启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端 smoke 测试（多实例 WS / HTTP / 节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 和自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 输出详细日志。
- `pnpm test:live`：运行提供商 live 测试（minimax / zai）。需要 API key，并设置 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）才能取消跳过。
- `pnpm test:docker:all`：构建共享的 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，构建 / 复用一个裸 Node / Git runner 镜像以及一个功能镜像，后者会把该 tarball 安装到 `/app`，然后通过加权调度器在设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下运行 Docker smoke 测试通道。裸镜像（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用于安装器 / 更新 / 插件依赖测试通道；这些通道会挂载预构建 tarball，而不是使用复制的仓库源码。功能镜像（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用于正常的已构建应用功能测试通道。`scripts/package-openclaw-for-docker.mjs` 是本地 / CI 唯一的 package 打包器。Docker 测试通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 负责执行所选计划。`node scripts/test-docker-all.mjs --plan-json` 会输出由调度器拥有的 CI 计划，其中包括所选测试通道、镜像类型、package / live-image 需求以及凭证检查，而不会实际构建或运行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制对提供商敏感的尾部池，默认值也为 10。重量级测试通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认是每个提供商一个重量级测试通道，通过 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4` 控制。对于更大的主机，可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。为避免本地 Docker daemon 在创建时出现风暴，测试通道启动默认错开 2 秒；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆盖。运行器默认会对 Docker 做预检，清理陈旧的 OpenClaw E2E 容器，每 30 秒输出一次活跃测试通道状态，在兼容测试通道之间共享提供商 CLI 工具缓存，对临时性的 live 提供商失败默认重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），并将测试通道耗时存储到 `.artifacts/docker-tests/lane-timings.json`，供后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可只打印测试通道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 调整状态输出频率，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用耗时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 只运行确定性的 / 本地测试通道，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 只运行 live 提供商测试通道；对应的 package 别名为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅 live 模式会把 main 和 tail 的 live 测试通道合并为一个按最长优先排序的池，这样提供商桶就可以一起打包 Claude、Codex 和 Gemini 的工作。运行器在首次失败后会停止调度新的池化测试通道，除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`；每个测试通道都有一个 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分选定的 live / tail 测试通道使用更紧的单通道上限。CLI 后端 Docker 设置命令有单独的超时控制，通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS`（默认 180）。每个测试通道的日志和 `summary.json` 阶段耗时会写入 `.artifacts/docker-tests/<run-id>/`。
- `pnpm test:docker:browser-cdp-snapshot`：构建一个基于 Chromium 的源码 E2E 容器，启动原始 CDP 和一个隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP 角色快照包含链接 URL、由光标提升的可点击元素、iframe 引用以及 frame 元数据。
- CLI 后端 live Docker 探测可以作为聚焦测试通道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 和 `:mcp` 别名。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规 unit / e2e 测试套件那样以 CI 稳定性为预期。
- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由后的会话发现、transcript 读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该 smoke 测试能反映 bridge 实际发出的内容。
- `pnpm test:e2e`：运行 Gateway 网关端到端 smoke 测试（多实例 WS/HTTP/node 配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 和自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。
- `pnpm test:live`：运行提供商 live 测试（minimax/zai）。需要 API keys，并设置 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）才能取消跳过。
- `pnpm test:docker:all`：构建共享的 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，构建或复用一个裸 Node/Git runner 镜像以及一个功能镜像，后者会把该 tarball 安装到 `/app`，然后通过加权调度器以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker smoke lanes。裸镜像（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用于 installer/update/plugin-dependency lanes；这些 lanes 会挂载预构建的 tarball，而不是使用复制的仓库源码。功能镜像（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用于普通的已构建应用功能 lanes。`scripts/package-openclaw-for-docker.mjs` 是本地/CI 共用的唯一 package 打包器，并会在 Docker 使用前校验 tarball 以及 `dist/postinstall-inventory.json`。Docker lane 定义位于 `scripts/lib/docker-e2e-scenarios.mjs`；规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 执行选定的计划。`node scripts/test-docker-all.mjs --plan-json` 会输出由调度器拥有的 CI 计划，其中包含已选 lanes、镜像类型、package/live-image 需求和凭证检查，而不会构建或运行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制对提供商敏感的尾部池，默认值也为 10。重型 lane 上限默认值为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认是每个提供商一个重型 lane，通过 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4` 控制。对于更大的主机，请使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。默认情况下，lane 启动会错开 2 秒，以避免本地 Docker daemon 出现创建风暴；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆盖。runner 默认会对 Docker 做预检，清理陈旧的 OpenClaw E2E 容器，每 30 秒输出一次活动 lane 状态，在兼容 lanes 之间共享提供商 CLI 工具缓存，默认对瞬时 live-provider 失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），并把 lane 耗时存储到 `.artifacts/docker-tests/lane-timings.json`，以便后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可打印 lane 清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 可调整状态输出频率，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用耗时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 可仅运行确定性/本地 lanes，使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 可仅运行 live-provider lanes；对应的 package 别名分别是 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅 live 模式会把主 live lanes 和尾部 live lanes 合并到一个按最长优先的池中，这样提供商桶就能把 Claude、Codex 和 Gemini 的任务一起打包。除非设置了 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则 runner 会在首次失败后停止调度新的池化 lanes，并且每个 lane 都有一个 120 分钟的回退超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分选定的 live/tail lanes 使用更严格的单 lane 上限。CLI 后端 Docker 设置命令有自己的超时，通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 控制（默认 180）。每个 lane 的日志、`summary.json`、`failures.json` 和阶段耗时都会写入 `.artifacts/docker-tests/<run-id>/`；使用 `pnpm test:docker:timings <summary.json>` 可查看慢 lanes，使用 `pnpm test:docker:rerun <run-id|summary.json|failures.json>` 可输出低成本的定向重跑命令。
- `pnpm test:docker:browser-cdp-snapshot`：构建一个由 Chromium 驱动的源码 E2E 容器，启动原始 CDP 和一个隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP 角色快照包含链接 URL、通过光标提升的可点击元素、iframe 引用以及 frame 元数据。
- CLI 后端 live Docker 探测可以作为聚焦 lanes 运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 和 `:mcp` 别名。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw 和 Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。它需要可用的 live 模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不期望像常规 unit/e2e 测试套件那样具备 CI 稳定性。
- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格渠道和权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该 smoke 能反映 bridge 实际发出的内容。
## 本地 PR 检查门槛
## 本地 PR 门禁
对于本地 PR 提交 / 合入前检查，运行：
对于本地 PR 落地/门禁检查，请运行：
- `pnpm check:changed`
- `pnpm check`
@ -57,7 +58,7 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
如果 `pnpm test` 在负载较高的主机上出现偶发失败，在将其视为回归之前先重跑一次，然后用 `pnpm test <path/to/test>` 进行隔离。对于内存受限的主机，使用：
如果 `pnpm test` 在负载较高的主机上出现偶发失败，请先重跑一次，再将其视为回归；然后使用 `pnpm test <path/to/test>` 进行隔离。对于内存受限的主机，请使用：
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -70,9 +71,9 @@ x-i18n:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY`
- 默认提示词：“用一个单词回复：ok。不要使用标点或额外文本。”
- 默认提示词：“Reply with a single word: ok. No punctuation or extra text.”
上次运行（2025-12-31，20 次运行）：
上次运行（2025-12-31，20 次）：
- minimax 中位数 1279ms（最小 1114，最大 2431）
- opus 中位数 2454ms（最小 1224，最大 3170）
@ -102,37 +103,37 @@ x-i18n:
- `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status`
- `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port`
- `all`：同时包含两个预设
- `all`：上述两个预设
输出内容包括每个命令的 `sampleCount`、avg、p50、p95、min/max、exit-code / signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此耗时采集和 profile 捕获使用同一个 harness。
输出内容包括每个命令的 `sampleCount`、平均值、p50、p95、最小值/最大值、退出码/信号分布以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，这样计时和 profile 采集会使用同一个 harness。
保存输出约定：
- `pnpm test:startup:bench:smoke` 会将定向 smoke 产物写入 `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1`，将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1`，刷新已检入的基线 fixture：`test/fixtures/cli-startup-bench.json`
- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已纳入版本控制的基线夹具 `test/fixtures/cli-startup-bench.json`
已检入的 fixture：
已纳入版本控制的夹具：
- `test/fixtures/cli-startup-bench.json`
- 使用 `pnpm test:startup:bench:update` 刷新
- 使用 `pnpm test:startup:bench:check` 将当前结果与该 fixture 进行比较
- 使用 `pnpm test:startup:bench:check` 将当前结果与该夹具进行比较
## 新手引导 E2E（Docker）
Docker 是可选的；只有在进行容器化的新手引导 smoke 测试时才需要。
Docker 是可选的；只有在进行容器化新手引导 smoke 测试时才需要它。
在一个干净的 Linux 容器中运行完整的冷启动流程：
在干净的 Linux 容器中运行完整的冷启动流程：
```bash
scripts/e2e/onboard-docker.sh
```
该脚本会通过 pseudo-tty 驱动交互式向导，验证配置 / workspace / session 文件，然后启动 Gateway 网关并运行 `openclaw health`。
该脚本会通过伪终端驱动交互式向导，验证配置/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。
## QR 导入 smoke 测试（Docker）
## QR 导入 smoke（Docker）
确保维护中的 QR 运行时 helper 能在受支持的 Docker Node 运行时下正确加载（默认 Node 24，兼容 Node 22）：
确保受支持的 Docker Node 运行时（默认 Node 24，兼容 Node 22）下可以加载受维护的 QR 运行时辅助工具：
```bash
pnpm test:docker:qr
@ -141,4 +142,4 @@ pnpm test:docker:qr
## 相关内容
- [测试](/zh-CN/help/testing)
- [测试 live](/zh-CN/help/testing-live)
- [实时测试](/zh-CN/help/testing-live)