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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 00:44:57 +00:00
parent 2346ee4cb4
commit ea4ea4e9bd
2 changed files with 427 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
docs/zh-CN/cli/gateway.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 从 CLI 运行 Gateway 网关（开发环境或服务器）
- 通过 CLI 运行 Gateway 网关（开发环境或服务器）
- 调试 Gateway 网关身份验证、绑定模式和连接性
- 通过 Bonjour 发现 Gateway 网关（本地 + 广域 DNS-SD）
sidebarTitle: Gateway
summary: OpenClaw Gateway 网关 CLI（`openclaw gateway`）— 运行、查询和发现 Gateway 网关
summary: OpenClaw Gateway 网关 CLI (`openclaw gateway`) — 运行、查询和发现 Gateway 网关
title: Gateway 网关
x-i18n:
generated_at: "2026-05-04T18:03:39Z"
generated_at: "2026-05-05T00:43:18Z"
model: gpt-5.5
provider: openai
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_path: cli/gateway.md
workflow: 16
---
@ -18,11 +18,11 @@ x-i18n:
Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。本页中的子命令位于 `openclaw gateway …` 下。
<CardGroup cols={3}>
<Card title="Bonjour 设备发现" href="/zh-CN/gateway/bonjour">
<Card title="Bonjour 发现" href="/zh-CN/gateway/bonjour">
本地 mDNS + 广域 DNS-SD 设置。
</Card>
<Card title="设备发现概览" href="/zh-CN/gateway/discovery">
OpenClaw 如何广播和查找 Gateway 网关。
OpenClaw 如何通告并发现 Gateway 网关。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration">
顶层 Gateway 网关配置键。
@ -46,11 +46,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="启动行为">
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。对临时/开发运行使用 `--allow-unconfigured`。
- `openclaw onboard --mode local` 和 `openclaw setup` 预期会写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，请将其视为损坏或被覆盖的配置并修复，而不是隐式假设为 local 模式。
- 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测 local”。
- 未启用认证时禁止绑定到 loopback 之外的地址（安全护栏）。
- 在授权时，`SIGUSR1` 会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，同时仍允许 Gateway 网关工具/配置应用/更新）。
- `SIGINT`/`SIGTERM` 处理器会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
- `openclaw onboard --mode local` 和 `openclaw setup` 预期会写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置并修复，而不是隐式假定为本地模式。
- 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测为本地”。
- 未启用认证时，禁止绑定到 loopback 之外的地址（安全防护）。
- `SIGUSR1` 会在获得授权时触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，同时仍允许 Gateway 网关工具/配置 apply/update）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
</Accordion>
</AccordionGroup>
@ -79,10 +79,10 @@ openclaw gateway run
通过 Tailscale 暴露 Gateway 网关。
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
在关闭时重置 Tailscale serve/funnel 配置。
关闭时重置 Tailscale serve/funnel 配置。
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
允许在配置中没有 `gateway.mode=local` 时启动 Gateway 网关。仅为临时/开发引导绕过启动保护；不会写入或修复配置文件。
允许在配置中没有 `gateway.mode=local` 时启动 Gateway 网关。仅为临时/开发引导绕过启动防护；不会写入或修复配置文件。
</ParamField>
<ParamField path="--dev" type="boolean">
如果缺失，则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
@ -120,7 +120,7 @@ openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` 会要求正在运行的 Gateway 网关在重启前预检活跃的 OpenClaw 工作。如果队列操作、回复投递、嵌入式运行或任务运行处于活跃状态，Gateway 网关会报告阻塞项，合并重复的安全重启请求，并在活跃工作排空后重启。普通 `restart` 会保留现有的服务管理器行为以保持兼容性。仅当你明确需要立即覆盖路径时才使用 `--force`。
`openclaw gateway restart --safe` 会要求正在运行的 Gateway 网关在重启前对活跃的 OpenClaw 工作进行预检。如果存在排队操作、回复投递、嵌入式运行或任务运行，Gateway 网关会报告阻塞项，合并重复的安全重启请求，并在活跃工作排空后重启。普通 `restart` 会保留现有的服务管理器行为以保持兼容性。仅当你明确需要立即覆盖路径时才使用 `--force`。
<Warning>
内联 `--password` 可能会暴露在本地进程列表中。优先使用 `--password-file`、环境变量，或由 SecretRef 支持的 `gateway.auth.password`。
@ -128,9 +128,9 @@ openclaw gateway restart --force
### 启动性能分析
- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 以在 Gateway 网关启动期间记录阶段耗时，包括每阶段的 `eventLoopMax` 延迟，以及 installed-index、manifest registry、启动规划和 owner-map 工作的插件查找表耗时。
- 设置 `OPENCLAW_DIAGNOSTICS=timeline` 并配合 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，为外部 QA harness 写入尽力而为的 JSONL 启动诊断时间线。你也可以在配置中用 `diagnostics.flags: ["timeline"]` 启用该标志；路径仍由环境变量提供。添加 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 以包含事件循环采样。
- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 对 Gateway 网关启动进行基准测试。该基准会记录首个进程输出、`/healthz`、`/readyz`、启动跟踪耗时、事件循环延迟，以及插件查找表耗时详情。
- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 可在 Gateway 网关启动期间记录各阶段耗时，包括每阶段的 `eventLoopMax` 延迟，以及已安装索引、插件清单注册表、启动规划和 owner-map 工作的插件查找表耗时。
- 设置 `OPENCLAW_DIAGNOSTICS=timeline` 并配合 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，可为外部 QA harness 写入尽力而为的 JSONL 启动诊断时间线。你也可以在配置中用 `diagnostics.flags: ["timeline"]` 启用该标志；路径仍由环境提供。添加 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件循环样本。
- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 可基准测试 Gateway 网关启动。基准测试会记录首次进程输出、`/healthz`、`/readyz`、启动跟踪耗时、事件循环延迟，以及插件查找表耗时详情。
## 查询正在运行的 Gateway 网关
@ -138,8 +138,8 @@ openclaw gateway restart --force
<Tabs>
<Tab title="输出模式">
- 默认：人类可读（在 TTY 中着色）。
- `--json`：机器可读 JSON（无样式/微调器）。
- 默认：人类可读（TTY 中带颜色）。
- `--json`：机器可读 JSON（无样式/spinner）。
- `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI，同时保留人类可读布局。
</Tab>
@ -154,7 +154,7 @@ openclaw gateway restart --force
</Tabs>
<Note>
当你设置 `--url` 时，CLI 不会回退到配置或环境凭证。请显式传入 `--token` 或 `--password`。缺少显式凭证是错误。
设置 `--url` 时，CLI 不会回退到配置或环境凭证。请显式传入 `--token` 或 `--password`。缺少显式凭证会报错。
</Note>
### `gateway health`
@ -163,11 +163,11 @@ openclaw gateway restart --force
openclaw gateway health --url ws://127.0.0.1:18789
```
HTTP `/healthz` 端点是存活探针：只要服务器能响应 HTTP，它就会返回。HTTP `/readyz` 端点更严格，在启动插件 sidecar、渠道或已配置钩子仍在稳定时会保持红色。本地或已认证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包含事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
HTTP `/healthz` 端点是存活探针：服务器可以响应 HTTP 后即返回。HTTP `/readyz` 端点更严格，会在启动插件 sidecar、渠道或已配置钩子仍在收敛时保持红色。本地或已认证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包含事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
### `gateway usage-cost`
从会话日志获取用量成本摘要。
从会话日志获取使用成本摘要。
```bash
openclaw gateway usage-cost
@ -195,13 +195,13 @@ openclaw gateway stability --json
要包含的最近事件最大数量（最大 `1000`）。
</ParamField>
<ParamField path="--type <type>" type="string">
按诊断事件类型过滤，例如 `payload.large` 或 `diagnostic.memory.pressure`。
按诊断事件类型筛选，例如 `payload.large` 或 `diagnostic.memory.pressure`。
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
仅包含诊断序列号之后的事件。
仅包含某个诊断序列号之后的事件。
</ParamField>
<ParamField path="--bundle [path]" type="string">
读取持久化稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅 `--bundle`）读取状态目录下的最新包，或直接传入包 JSON 路径。
读取已持久化的稳定性 bundle，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅 `--bundle`）读取状态目录下最新的 bundle，或直接传入 bundle JSON 路径。
</ParamField>
<ParamField path="--export" type="boolean">
写入可共享的支持诊断 zip，而不是打印稳定性详情。
@ -211,16 +211,16 @@ openclaw gateway stability --json
</ParamField>
<AccordionGroup>
<Accordion title="隐私和包行为">
- 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie、秘密值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
- 在致命 Gateway 网关退出、关闭超时和重启启动失败时，如果记录器中有事件，OpenClaw 会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 检查最新包；`--limit`、`--type` 和 `--since-seq` 也适用于包输出。
<Accordion title="隐私和 bundle 行为">
- 记录会保留运维元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie、秘密值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
- 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器有事件，OpenClaw 会将同一份诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。用 `openclaw gateway stability --bundle latest` 检查最新 bundle；`--limit`、`--type` 和 `--since-seq` 也适用于 bundle 输出。
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
写入一个本地诊断 zip，设计用于附加到 bug 报告。有关隐私模型和包内容，请参见 [诊断导出](/zh-CN/gateway/diagnostics)。
写入本地诊断 zip，设计用于附加到 bug 报告。关于隐私模型和 bundle 内容，请参见 [诊断导出](/zh-CN/gateway/diagnostics)。
```bash
openclaw gateway diagnostics export
@ -229,10 +229,10 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
输出 zip 路径。默认是状态目录下的支持导出。
输出 zip 路径。默认写入状态目录下的支持导出。
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
要包含的最大已清理日志行数。
要包含的已清理日志行最大数量。
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
要检查的最大日志字节数。
@ -250,19 +250,19 @@ openclaw gateway diagnostics export --json
Status/健康快照超时。
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
跳过持久化稳定性包查找。
跳过已持久化稳定性 bundle 查找。
</ParamField>
<ParamField path="--json" type="boolean">
以 JSON 打印写入的路径、大小和清单。
</ParamField>
该导出包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关 Status/健康快照，以及存在时的最新稳定性包。
导出包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关 Status/健康快照，以及在存在时最新的稳定性 bundle。
它旨在用于共享。它会保留有助于调试的运行细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非秘密功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭证、cookie、账号/消息标识符、提示/指令文本、主机名和秘密值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留有消息被省略以及其字节数。
它旨在共享。它会保留有助于调试的运维详情，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非秘密功能设置，以及已脱敏的运维日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭证、cookie、账号/消息标识符、提示词/指令文本、主机名和秘密值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留该消息已被省略以及它的字节数。
### `gateway status`
`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/认证能力探测。
`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），并可选探测连接性/认证能力。
```bash
openclaw gateway status
@ -271,7 +271,7 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
添加显式探测目标。已配置的远程 + localhost 仍会被探测。
添加一个显式探测目标。已配置的远程目标 + localhost 仍会被探测。
</ParamField>
<ParamField path="--token <token>" type="string">
探测使用的令牌认证。
@ -280,7 +280,7 @@ openclaw gateway status --require-rpc
探测使用的密码认证。
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
探测超时时间。
探测超时。
</ParamField>
<ParamField path="--no-probe" type="boolean">
跳过连通性探测（仅服务视图）。
@ -293,41 +293,41 @@ openclaw gateway status --require-rpc
</ParamField>
<AccordionGroup>
<Accordion title="Status 语义">
- `gateway status` 即使在本地 CLI 配置缺失或无效时，也仍可用于诊断。
- 默认 `gateway status` 会证明服务状态、WebSocket 连接，以及握手时可见的认证能力。它不证明读/写/管理员操作。
- 诊断探测对于首次设备认证不会进行变更：如果存在已缓存的设备令牌，它们会复用该令牌，但不会仅为检查状态而创建新的 CLI 设备身份或只读设备配对记录。
- `gateway status` 会尽可能解析已配置的认证 SecretRef，用于探测认证。
- 如果此命令路径中必需的认证 SecretRef 未解析，且探测连通性/认证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
- 如果探测成功，未解析认证引用的警告会被抑制，以避免误报。
- 当监听中的服务还不够，并且你还需要读取范围的 RPC 调用也保持健康时，请在脚本和自动化中使用 `--require-rpc`。
- `--deep` 会尽力额外扫描 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
- 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务配置路径/有效性快照，以帮助诊断配置文件或状态目录漂移。
<Accordion title="Status semantics">
- 即使本地 CLI 配置缺失或无效，`gateway status` 仍可用于诊断。
- 默认的 `gateway status` 会验证服务状态、WebSocket 连接，以及握手时可见的认证能力。它不会验证读/写/管理员操作。
- 诊断探测对于首次设备认证是非变更性的：如果已有缓存的设备令牌，它们会复用该令牌，但不会仅为了检查状态而创建新的 CLI 设备身份或只读设备配对记录。
- `gateway status` 会在可能时解析已配置的认证 SecretRefs，用于探测认证。
- 如果此命令路径中必需的认证 SecretRef 未解析，并且探测连通性/认证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
- 如果探测成功，未解析的 auth-ref 警告会被抑制，以避免误报。
- 在脚本和自动化中，如果仅有正在监听的服务还不够，并且你还需要读取范围的 RPC 调用也保持健康，请使用 `--require-rpc`。
- `--deep` 会额外尽力扫描 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
- 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务配置路径/有效性的快照，用于帮助诊断 profile 或 state-dir 偏移。
</Accordion>
<Accordion title="Linux systemd 认证漂移检查">
- 在 Linux systemd 安装中，服务认证漂移检查会从 unit 读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件，以及可选的 `-` 文件）。
- 漂移检查会使用合并后的运行时 env 解析 `gateway.auth.token` SecretRef（先使用服务命令 env，再回退到进程 env）。
- 如果令牌认证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或 mode 未设置且密码可能胜出并且没有令牌候选可胜出），令牌漂移检查会跳过配置令牌解析。
<Accordion title="Linux systemd auth-drift checks">
- 在 Linux systemd 安装中，服务认证漂移检查会从 unit 中读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件和可选的 `-` 文件）。
- 漂移检查会使用合并后的运行时环境变量解析 `gateway.auth.token` SecretRefs（先使用服务命令环境变量，然后回退到进程环境变量）。
- 如果令牌认证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或模式未设置且密码可胜出、没有令牌候选可胜出），令牌漂移检查会跳过配置令牌解析。
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` 是“调试所有内容”的命令。它始终会探测：
`gateway probe` 是“调试一切”的命令。它始终会探测：
- 你配置的远程 Gateway 网关（如果已设置），以及
- 你已配置的远程 Gateway 网关（如果已设置），以及
- localhost（loopback），**即使已配置远程目标**。
如果传入 `--url`，该显式目标会添加到两者之前。人类可读输出会将目标标记为：
如果你传入 `--url`，该显式目标会被添加到二者之前。人类可读输出会将目标标记为：
- `URL（显式）`
- `远程（已配置）` 或 `远程（已配置，未启用）`
- `URL (explicit)`
- `Remote (configured)` 或 `Remote (configured, inactive)`
- `Local loopback`
<Note>
如果多个 Gateway 网关可达，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援机器人）时，支持多个 Gateway 网关，但大多数安装仍只运行一个 Gateway 网关。
如果多个 Gateway 网关可达，它会打印所有 Gateway 网关。当你使用隔离的 profile/端口时（例如救援机器人），支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。
</Note>
```bash
@ -336,24 +336,24 @@ openclaw gateway probe --json
```
<AccordionGroup>
<Accordion title="解释">
<Accordion title="Interpretation">
- `Reachable: yes` 表示至少一个目标接受了 WebSocket 连接。
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探测能够证明的认证能力。它与可达性是分开的。
- `Read probe: ok` 表示读取范围的详细 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功。
- `Read probe: ok` 表示读取范围的详细 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也已成功。
- `Read probe: limited - missing scope: operator.read` 表示连接成功，但读取范围的 RPC 受限。这会报告为**降级**可达性，而不是完全失败。
- `Connect: ok` 之后的 `Read probe: failed` 表示 Gateway 网关接受了 WebSocket 连接，但后续读取诊断超时或失败。这同样是**降级**可达性，而不是不可达的 Gateway 网关。
- 与 `gateway status` 一样，probe 会复用现有缓存的设备认证，但不会创建首次设备身份或配对状态。
- 只有在没有任何被探测目标可达时，退出码才为非零。
- `Connect: ok` 之后出现 `Read probe: failed` 表示 Gateway 网关接受了 WebSocket 连接，但后续读取诊断超时或失败。这也属于**降级**可达性，而不是 Gateway 网关不可达。
- 与 `gateway status` 一样，探测会复用现有缓存的设备认证，但不会创建首次设备身份或配对状态。
- 只有在所有被探测目标都不可达时，退出码才为非零。
</Accordion>
<Accordion title="JSON 输出">
<Accordion title="JSON output">
顶层：
- `ok`：至少一个目标可达。
- `degraded`：至少一个目标接受了连接，但未完成完整的详细 RPC 诊断。
- `capability`：在可达目标中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
- `primaryTargetId`：按以下顺序作为活动胜出者处理的最佳目标：显式 URL、SSH 隧道、已配置远程，然后是 local loopback。
- `warnings[]`：尽力提供的警告记录，包含 `code`、`message` 和可选的 `targetIds`。
- `primaryTargetId`：按以下顺序作为活跃胜出者的最佳目标：显式 URL、SSH 隧道、已配置的远程目标，然后是 local loopback。
- `warnings[]`：尽力生成的警告记录，包含 `code`、`message` 和可选的 `targetIds`。
- `network`：从当前配置和主机网络派生的 local loopback/tailnet URL 提示。
- `discovery.timeoutMs` 和 `discovery.count`：此次探测实际使用的设备发现预算/结果数量。
@ -365,23 +365,23 @@ openclaw gateway probe --json
每个目标（`targets[].auth`）：
- `role`：可用时，`hello-ok` 中报告的认证角色。
- `scopes`：可用时，`hello-ok` 中报告的已授予 scopes。
- `role`：可用时在 `hello-ok` 中报告的认证角色。
- `scopes`：可用时在 `hello-ok` 中报告的已授予 scope。
- `capability`：该目标暴露的认证能力分类。
</Accordion>
<Accordion title="常见警告代码">
<Accordion title="Common warning codes">
- `ssh_tunnel_failed`：SSH 隧道设置失败；命令回退到直接探测。
- `multiple_gateways`：多个目标可达；除非你有意运行隔离配置文件（例如救援机器人），否则这并不常见。
- `auth_secretref_unresolved`：无法为失败目标解析已配置的认证 SecretRef。
- `multiple_gateways`：多个目标可达；除非你有意运行隔离的 profile（例如救援机器人），否则这种情况并不常见。
- `auth_secretref_unresolved`：已配置的认证 SecretRef 无法为失败目标解析。
- `probe_scope_limited`：WebSocket 连接成功，但读取探测因缺少 `operator.read` 而受限。
</Accordion>
</AccordionGroup>
#### 通过 SSH 访问远程（与 Mac 应用一致）
#### 通过 SSH 访问远程目标（Mac 应用对齐）
macOS 应用的“通过 SSH 访问远程”模式使用本地端口转发，使远程 Gateway 网关（可能仅绑定到 loopback）可在 `ws://127.0.0.1:<port>` 访问。
macOS 应用的“Remote over SSH”模式使用本地端口转发，因此远程 Gateway 网关（可能仅绑定到 loopback）可通过 `ws://127.0.0.1:<port>` 访问。
CLI 等效命令：
@ -396,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host
身份文件。
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
从已解析的设备发现端点（`local.` 加上已配置的广域网域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 的提示会被忽略。
从已解析的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 提示会被忽略。
</ParamField>
配置（可选，用作默认值）：
@ -429,14 +429,14 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
超时预算。
</ParamField>
<ParamField path="--expect-final" type="boolean">
主要用于在最终 payload 之前会流式传输中间事件的智能体式 RPC。
主要用于 agent 风格的 RPC，这类 RPC 会在最终 payload 之前流式传输中间事件。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读的 JSON 输出。
机器可读 JSON 输出。
</ParamField>
<Note>
`--params` 必须是有效的 JSON。
`--params` 必须是有效 JSON。
</Note>
## 管理 Gateway 网关服务
@ -449,11 +449,9 @@ openclaw gateway restart
openclaw gateway uninstall
```
### 使用包装器安装
### 使用 wrapper 安装
当托管服务必须通过另一个可执行文件启动时，请使用 `--wrapper`，例如
密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 网关参数，并
负责最终 exec `openclaw` 或带有这些参数的 Node。
当托管服务必须通过另一个可执行文件启动时，请使用 `--wrapper`，例如密钥管理器 shim 或 run-as 辅助工具。wrapper 会接收正常的 Gateway 网关参数，并负责最终用这些参数 exec `openclaw` 或 Node。
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -467,17 +465,14 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
你也可以通过环境设置包装器。`gateway install` 会验证路径是
可执行文件，将包装器写入服务 `ProgramArguments`，并在服务环境中持久化
`OPENCLAW_WRAPPER`，供后续强制重新安装、更新和 Doctor
修复使用。
你也可以通过环境变量设置 wrapper。`gateway install` 会验证该路径是可执行文件，将 wrapper 写入服务 `ProgramArguments`，并在服务环境中持久化 `OPENCLAW_WRAPPER`，供后续强制重新安装、更新和 Doctor 修复使用。
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
```
要移除已持久化的包装器，请在重新安装时清空 `OPENCLAW_WRAPPER`：
要移除已持久化的 wrapper，请在重新安装时清空 `OPENCLAW_WRAPPER`：
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -485,26 +480,27 @@ openclaw gateway restart
```
<AccordionGroup>
<Accordion title="命令选项">
<Accordion title="Command options">
- `gateway status`：`--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json`
- `gateway install`：`--port`、`--runtime <node|bun>`、`--token`、`--wrapper <path>`、`--force`、`--json`
- `gateway restart`：`--force`、`--wait <duration>`、`--json`
- `gateway restart`：`--safe`、`--force`、`--wait <duration>`、`--json`
- `gateway uninstall|start|stop`：`--json`
</Accordion>
<Accordion title="生命周期行为">
- 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来作为重启替代；在 macOS 上，`gateway stop` 会有意在停止 LaunchAgent 之前禁用它。
<Accordion title="Lifecycle behavior">
- 使用 `gateway restart` 重启托管服务。不要串联 `gateway stop` 和 `gateway start` 来替代重启；在 macOS 上，`gateway stop` 会有意在停止 LaunchAgent 之前禁用它。
- `gateway restart --safe` 会要求正在运行的 Gateway 网关预检活跃的 OpenClaw 工作，并推迟重启，直到回复投递、嵌入式运行和任务运行全部清空。`--safe` 不能与 `--force` 或 `--wait` 组合使用。
- `gateway restart --wait 30s` 会覆盖该次重启配置的重启排空预算。裸数字表示毫秒；也接受 `s`、`m` 和 `h` 等单位。`--wait 0` 会无限期等待。
- `gateway restart --force` 会跳过活跃工作排空并立即重启。当操作员已经检查过列出的任务阻塞项，并希望 Gateway 网关立即恢复时使用它。
- 生命周期命令接受 `--json`，以便脚本使用。
- `gateway restart --force` 会跳过活跃工作排空并立即重启。当操作员已经检查过列出的任务阻塞项，并希望 Gateway 网关现在恢复时使用它。
- 生命周期命令接受 `--json` 以用于脚本。
</Accordion>
<Accordion title="安装时的认证和 SecretRefs">
- 当令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将已解析的令牌持久化到服务环境元数据中。
- 如果令牌认证需要令牌，而已配置的令牌 SecretRef 未解析，安装会关闭式失败，而不是持久化回退明文。
- 对于 `gateway run` 上的密码认证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支持的 `gateway.auth.password`，而不是内联 `--password`。
- 在推断认证模式下，仅 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时，请使用持久配置（`gateway.auth.password` 或配置 `env`）。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，安装会被阻止，直到显式设置 mode。
<Accordion title="安装时的身份验证和 SecretRefs">
- 当令牌身份验证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将解析出的令牌持久化到服务环境元数据中。
- 如果令牌身份验证需要令牌，而配置的令牌 SecretRef 未解析，则安装会关闭失败，而不是持久化回退的明文。
- 对于 `gateway run` 上的密码身份验证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file` 或由 SecretRef 支持的 `gateway.auth.password`，而不是内联 `--password`。
- 在推断的身份验证模式下，仅存在于 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时请使用持久配置（`gateway.auth.password` 或配置 `env`）。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且未设置 `gateway.auth.mode`，则安装会被阻止，直到显式设置模式。
</Accordion>
</AccordionGroup>
@ -513,20 +509,20 @@ openclaw gateway restart
`gateway discover` 会扫描 Gateway 网关信标（`_openclaw-gw._tcp`）。
- 组播 DNS-SD：`local.`
- 单播 DNS-SD（Wide-Area Bonjour）：选择一个域（示例：`openclaw.internal.`），并设置拆分 DNS + 一个 DNS 服务器；参见 [Bonjour](/zh-CN/gateway/bonjour)。
- 多播 DNS-SD：`local.`
- 单播 DNS-SD（广域 Bonjour）：选择一个域（例如：`openclaw.internal.`），并设置拆分 DNS + DNS 服务器；参见 [Bonjour](/zh-CN/gateway/bonjour)。
只有启用 Bonjour 设备发现的 Gateway 网关（默认）才会通告信标。
只有启用了 Bonjour 发现（默认）的 Gateway 网关才会通告该信标。
Wide-Area 设备发现记录包含（TXT）：
广域发现记录包含（TXT）：
- `role`（Gateway 网关角色提示）
- `transport`（传输协议提示，例如 `gateway`）
- `transport`（传输提示，例如 `gateway`）
- `gatewayPort`（WebSocket 端口，通常为 `18789`）
- `sshPort`（可选；缺失时，客户端默认使用 `22` 作为 SSH 目标端口）
- `sshPort`（可选；缺失时，客户端默认 SSH 目标为 `22`）
- `tailnetDns`（MagicDNS 主机名，可用时）
- `gatewayTls` / `gatewayTlsSha256`（已启用 TLS + 证书指纹）
- `cliPath`（写入 Wide-Area 区域的远程安装提示）
- `cliPath`（写入广域区域的远程安装提示）
### `gateway discover`
@ -538,7 +534,7 @@ openclaw gateway discover
每条命令的超时时间（浏览/解析）。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读输出（也会禁用样式/加载指示器）。
机器可读输出（同时禁用样式/微调器）。
</ParamField>
示例：
@ -549,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- CLI 会扫描 `local.` 以及已启用的已配置 Wide-Area 域。
- JSON 输出中的 `wsUrl` 派生自解析后的服务端点，而不是来自仅 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
- 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时，才会广播 `sshPort` 和 `cliPath`。Wide-Area DNS-SD 仍会写入 `cliPath`；`sshPort` 在那里也仍然是可选的。
- CLI 会扫描 `local.` 以及启用后配置的广域域。
- JSON 输出中的 `wsUrl` 派生自解析出的服务端点，而不是来自 `lanHost` 或 `tailnetDns` 等仅 TXT 的提示。
- 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时，才会广播 `sshPort` 和 `cliPath`。广域 DNS-SD 仍会写入 `cliPath`；`sshPort` 在那里也保持可选。
</Note>

469
docs/zh-CN/concepts/qa-e2e-automation.md
View File

@ -3,59 +3,59 @@ read_when:
- 了解 QA 栈如何协同工作
- 扩展 qa-lab、qa-channel 或传输适配器
- 添加基于仓库的 QA 场景
- 围绕 Gateway 网关仪表盘构建更高真实度的 QA 自动化
summary: QA stack 概览：qa-lab、qa-channel、由仓库支持的场景、实时传输通道、传输适配器和报告。
- 围绕 Gateway 网关仪表板构建更高真实度的 QA 自动化
summary: QA 堆栈概览：qa-lab、qa-channel、仓库支持的场景、实时传输通道、传输适配器和报告。
title: QA overview
x-i18n:
generated_at: "2026-05-04T02:52:01Z"
generated_at: "2026-05-05T00:43:19Z"
model: gpt-5.5
provider: openai
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_hash: 01cc3543a10a8ea3a7ea3a135e95ae0ea0c6e983e6b30c35aab1f74c13d7f4a3
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
私有 QA 栈旨在以比单个单元测试更贴近真实、类似渠道形态的方式来测试 OpenClaw。
私有 QA 栈旨在以比单个单元测试更真实、更贴近渠道形态的方式测试 OpenClaw。
当前组成部分：
- `extensions/qa-channel`：合成消息渠道，包含私信、渠道、线程、反应、编辑和删除界面。
- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录记录、注入入站消息，并导出 Markdown 报告。
- `extensions/qa-matrix`、未来的运行器插件：实时传输适配器，用于在子 QA Gateway 网关内驱动真实渠道。
- `qa/`：由仓库托管的种子资源，用于启动任务和基线 QA 场景。
- [Mantis](/zh-CN/concepts/mantis)：针对需要真实传输、浏览器截图、VM 状态和 PR 证据的 bug，进行修复前后实时验证。
- `extensions/qa-channel`：合成消息渠道，包含私信、渠道、线程、表情回应、编辑和删除界面。
- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录、注入入站消息，以及导出 Markdown 报告。
- `extensions/qa-matrix`、未来的运行器插件：实时传输适配器，在子 QA Gateway 网关内驱动真实渠道。
- `qa/`：由仓库提供的启动任务种子资源和基线 QA 场景。
- [Mantis](/zh-CN/concepts/mantis)：针对需要真实传输、浏览器截图、VM 状态和 PR 证据的错误进行前后实时验证。
## 命令界面
## 命令接口
每个 QA 流程都在 `pnpm openclaw qa <subcommand>` 下运行。许多流程都有 `pnpm qa:*` 脚本别名；两种形式都受支持。
每个 QA 流程都在 `pnpm openclaw qa <subcommand>` 下运行。许多命令有 `pnpm qa:*` 脚本别名；两种形式都受支持。
| 命令 | 用途 |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | 内置 QA 自检；写入 Markdown 报告。 |
| `qa suite` | 针对 QA Gateway 网关运行通道运行仓库托管的场景。别名：`pnpm openclaw qa suite --runner multipass`，用于一次性 Linux VM。 |
| `qa coverage` | 打印 Markdown 场景覆盖清单（使用 `--json` 输出机器可读内容）。 |
| `qa parity-report` | 比较两个 `qa-suite-summary.json` 文件并写入智能体一致性报告。 |
| `qa character-eval` | 在多个实时模型上运行角色 QA 场景，并生成带评审的报告。参见[报告](#reporting)。 |
| `qa manual` | 针对所选提供商/模型运行通道运行一次性提示。 |
| `qa ui` | 启动 QA 调试器 UI 和本地 QA 总线（别名：`pnpm qa:lab:ui`）。 |
| `qa docker-build-image` | 构建预制 QA Docker 镜像。 |
| `qa docker-scaffold` | 写入 QA 仪表板 + Gateway 网关运行通道的 docker-compose 脚手架。 |
| `qa up` | 构建 QA 站点，启动 Docker 支撑的栈，并打印 URL（别名：`pnpm qa:lab:up`；`:fast` 变体会添加 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。 |
| `qa aimock` | 仅启动 AIMock 提供商服务器。 |
| `qa mock-openai` | 仅启动感知场景的 `mock-openai` 提供商服务器。 |
| `qa credentials doctor` / `add` / `list` / `remove` | 管理共享 Convex 凭据池。 |
| `qa matrix` | 针对一次性 Tuwunel homeserver 的实时传输运行通道。参见 [Matrix QA](/zh-CN/concepts/qa-matrix)。 |
| `qa telegram` | 针对真实私有 Telegram 群组的实时传输运行通道。 |
| `qa discord` | 针对真实私有 Discord guild 渠道的实时传输运行通道。 |
| `qa slack` | 针对真实私有 Slack 渠道的实时传输运行通道。 |
| `qa mantis` | 面向实时传输 bug 的修复前后验证运行器，包含 Discord 状态反应证据、Crabbox 桌面/浏览器冒烟测试，以及 Slack-in-VNC 冒烟测试。参见 [Mantis](/zh-CN/concepts/mantis)。 |
| 命令 | 用途 |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | 内置 QA 自检；写入 Markdown 报告。 |
| `qa suite` | 针对 QA Gateway 网关通道运行仓库支持的场景。别名：`pnpm openclaw qa suite --runner multipass`，用于一次性 Linux VM。 |
| `qa coverage` | 打印 Markdown 场景覆盖清单（`--json` 用于机器输出）。 |
| `qa parity-report` | 比较两个 `qa-suite-summary.json` 文件并写入智能体一致性报告。 |
| `qa character-eval` | 跨多个实时模型运行角色 QA 场景，并生成评审报告。参见[报告](#reporting)。 |
| `qa manual` | 针对所选提供商/模型通道运行一次性提示。 |
| `qa ui` | 启动 QA 调试器 UI 和本地 QA 总线（别名：`pnpm qa:lab:ui`）。 |
| `qa docker-build-image` | 构建预烘焙的 QA Docker 镜像。 |
| `qa docker-scaffold` | 为 QA 仪表盘 + Gateway 网关通道写入 docker-compose 脚手架。 |
| `qa up` | 构建 QA 站点，启动 Docker 支持的栈，并打印 URL（别名：`pnpm qa:lab:up`；`:fast` 变体会添加 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。 |
| `qa aimock` | 仅启动 AIMock provider 服务器。 |
| `qa mock-openai` | 仅启动感知场景的 `mock-openai` provider 服务器。 |
| `qa credentials doctor` / `add` / `list` / `remove` | 管理共享 Convex 凭证池。 |
| `qa matrix` | 针对一次性 Tuwunel homeserver 的实时传输通道。参见 [Matrix QA](/zh-CN/concepts/qa-matrix)。 |
| `qa telegram` | 针对真实私有 Telegram 群组的实时传输通道。 |
| `qa discord` | 针对真实私有 Discord guild 渠道的实时传输通道。 |
| `qa slack` | 针对真实私有 Slack 渠道的实时传输通道。 |
| `qa mantis` | 用于实时传输错误的前后验证运行器，包含 Discord 状态表情回应证据、Crabbox 桌面/浏览器冒烟测试，以及 VNC 中的 Slack 冒烟测试。参见 [Mantis](/zh-CN/concepts/mantis)。 |
## 操作员流程
当前 QA 操作员流程是一个双面板 QA 站点：
当前 QA 操作员流程是一个双栏 QA 站点：
- 左侧：带有智能体的 Gateway 网关仪表板（Control UI）。
- 右侧：QA Lab，显示类似 Slack 的转录记录和场景计划。
- 左侧：包含智能体的 Gateway 网关仪表盘（Control UI）。
- 右侧：QA Lab，显示类似 Slack 的转录和场景计划。
运行方式：
@ -63,9 +63,9 @@ x-i18n:
pnpm qa:lab:up
```
该命令会构建 QA 站点，启动 Docker 支撑的 Gateway 网关运行通道，并公开 QA Lab 页面，操作员或自动化循环可以在其中给智能体下发 QA 任务、观察真实渠道行为，并记录哪些内容有效、失败或仍被阻塞。
这会构建 QA 站点，启动 Docker 支持的 Gateway 网关通道，并公开 QA Lab 页面，操作员或自动化循环可以在其中向智能体交付 QA 任务、观察真实渠道行为，并记录哪些有效、失败或仍被阻塞。
若要更快地迭代 QA Lab UI，而无需每次重建 Docker 镜像，请使用绑定挂载的 QA Lab 包启动栈：
为了在不每次重建 Docker 镜像的情况下更快迭代 QA Lab UI，可以使用绑定挂载的 QA Lab 包启动栈：
```bash
pnpm openclaw qa docker-build-image
@ -74,27 +74,27 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` 会让 Docker 服务使用预制镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该包，并且浏览器会在 QA Lab 资源哈希变更时自动重新加载。
`qa:lab:up:fast` 会让 Docker 服务使用预构建镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该包，浏览器会在 QA Lab 资源哈希变化时自动重新加载。
如需进行本地 OpenTelemetry 跟踪冒烟测试，请运行：
要进行本地 OpenTelemetry trace 冒烟测试，运行：
```bash
pnpm qa:otel:smoke
```
该脚本会启动本地 OTLP/HTTP 跟踪接收器，在启用 `diagnostics-otel` 插件的情况下运行 `otel-trace-smoke` QA 场景，然后解码导出的 protobuf span，并断言发布关键形态：必须存在 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 和 `openclaw.message.delivery`；成功轮次中的模型调用不得导出 `StreamAbandoned`；原始诊断 ID 和 `openclaw.content.*` 属性必须保留在跟踪之外。它会在 QA suite 产物旁写入 `otel-smoke-summary.json`。
该脚本会启动本地 OTLP/HTTP trace 接收器，在启用 `diagnostics-otel` 插件的情况下运行 `otel-trace-smoke` QA 场景，然后解码导出的 protobuf spans，并断言发布关键形态：必须存在 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 和 `openclaw.message.delivery`；模型调用在成功轮次中不得导出 `StreamAbandoned`；原始诊断 ID 和 `openclaw.content.*` 属性必须保留在 trace 之外。它会在 QA suite 工件旁写入 `otel-smoke-summary.json`。
可观测性 QA 仅保留在源码检出中。npm tarball 会有意省略 QA Lab，因此包 Docker 发布运行通道不会运行 `qa` 命令。更改诊断插桩时，请从已构建的源码检出运行 `pnpm qa:otel:smoke`。
可观测性 QA 仅限源代码检出。npm tarball 会有意省略 QA Lab，因此包 Docker 发布通道不会运行 `qa` 命令。更改诊断 instrumentation 时，请从构建后的源代码检出中使用 `pnpm qa:otel:smoke`。
对于真实传输的 Matrix 冒烟测试运行通道，请运行：
要运行真实传输的 Matrix 冒烟通道，运行：
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
此运行通道的完整 CLI 参考、profile/场景目录、环境变量和产物布局位于 [Matrix QA](/zh-CN/concepts/qa-matrix)。概览：它会在 Docker 中预配一次性 Tuwunel homeserver，注册临时 driver/SUT/observer 用户，在限定到该传输的子 QA Gateway 网关内运行真实 Matrix 插件（无 `qa-channel`），然后在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下写入 Markdown 报告、JSON 摘要、observed-events 产物和合并输出日志。
此通道的完整 CLI 参考、profile/场景目录、环境变量和工件布局位于 [Matrix QA](/zh-CN/concepts/qa-matrix)。概览：它会在 Docker 中配置一次性 Tuwunel homeserver，注册临时 driver/SUT/observer 用户，在限定到该传输的子 QA Gateway 网关内运行真实 Matrix 插件（没有 `qa-channel`），然后在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下写入 Markdown 报告、JSON 摘要、observed-events 工件和合并输出日志。
对于真实传输的 Telegram、Discord 和 Slack 冒烟测试运行通道：
要运行真实传输的 Telegram、Discord 和 Slack 冒烟通道：
```bash
pnpm openclaw qa telegram
@ -102,9 +102,9 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
它们面向一个预先存在的真实渠道，使用两个机器人（driver + SUT）。所需环境变量、场景列表、输出产物和 Convex 凭据池记录在下方的 [Telegram、Discord 和 Slack QA 参考](#telegram-discord-and-slack-qa-reference)中。
它们面向一个预先存在的真实渠道，使用两个 bot（driver + SUT）。所需环境变量、场景列表、输出工件和 Convex 凭证池记录在下面的 [Telegram、Discord 和 Slack QA 参考](#telegram-discord-and-slack-qa-reference)中。
如需运行带 VNC 救援的完整 Slack 桌面 VM，请运行：
要运行带 VNC 救援的完整 Slack 桌面 VM：
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
@ -113,62 +113,62 @@ pnpm openclaw qa mantis slack-desktop-smoke \
--keep-lease
```
该命令会租用一台 Crabbox 桌面/浏览器机器，在 VM 内运行 Slack 实时运行通道，在 VNC 浏览器中打开 Slack Web，捕获桌面，并将 `slack-qa/` 以及 `slack-desktop-smoke.png` 复制回 Mantis 产物目录。通过 VNC 手动登录 Slack Web 后，可复用 `--lease-id <cbx_...>`。使用 `--gateway-setup` 时，Mantis 会在 VM 内保留一个持久的 OpenClaw Slack Gateway 网关，在端口 `38973` 上运行；若不使用该选项，命令会运行普通的 bot-to-bot Slack QA 运行通道，并在产物捕获后退出。
该命令会租用一台 Crabbox 桌面/浏览器机器，在 VM 内运行 Slack 实时通道，在 VNC 浏览器中打开 Slack Web，捕获桌面，并将 `slack-qa/` 和 `slack-desktop-smoke.png` 复制回 Mantis 工件目录。通过 VNC 手动登录 Slack Web 后，可复用 `--lease-id <cbx_...>`。使用 `--gateway-setup` 时，Mantis 会在 VM 内的 `38973` 端口保留一个持久运行的 OpenClaw Slack Gateway 网关；不使用它时，该命令会运行普通的 bot 到 bot Slack QA 通道，并在捕获工件后退出。
使用池化实时凭据之前，请运行：
使用池化实时凭证前，运行：
```bash
pnpm openclaw qa credentials doctor
```
Doctor 会检查 Convex broker 环境，验证端点设置，并在维护者密钥存在时验证 admin/list 可达性。它只报告密钥的已设置/缺失状态。
Doctor 会检查 Convex broker 环境，验证端点设置，并在 maintainer secret 存在时验证 admin/list 可达性。它只报告 secret 的已设置/缺失状态。
## 实时传输覆盖范围
实时传输运行通道共享同一个契约，而不是各自发明自己的场景列表形态。`qa-channel` 是覆盖面广的合成产品行为 suite，并不是实时传输覆盖矩阵的一部分。
实时传输通道共享一个契约，而不是各自发明自己的场景列表形态。`qa-channel` 是覆盖面较广的合成产品行为套件，不属于实时传输覆盖矩阵。
| 运行通道 | 金丝雀 | 提及门控 | Bot-to-bot | 允许列表阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 反应观察 | 帮助命令 | 原生命令注册 |
| -------- | ------ | -------- | ---------- | ------------ | -------- | -------- | -------- | -------- | -------- | -------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
| 通道 | Canary | 提及门控 | Bot 到 bot | Allowlist block | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 表情回应观察 | 帮助命令 | 原生命令注册 |
| -------- | ------ | -------- | ---------- | --------------- | -------- | -------- | -------- | -------- | ------------ | -------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
这会让 `qa-channel` 保持为覆盖面广的产品行为 suite，同时让 Matrix、Telegram 和未来的实时传输共享一份明确的传输契约检查清单。
这会让 `qa-channel` 保持为覆盖面较广的产品行为套件，同时 Matrix、Telegram 和未来的实时传输共享一个明确的传输契约检查清单。
如需运行不把 Docker 带入 QA 路径的一次性 Linux VM 运行通道，请运行：
要运行不把 Docker 带入 QA 路径的一次性 Linux VM 通道，运行：
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
这会启动一个新的 Multipass 虚拟机，安装依赖，在虚拟机内构建 OpenClaw，运行 `qa suite`，然后把常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。
这会启动一个全新的 Multipass 客户机，安装依赖，在客户机内构建 OpenClaw，运行 `qa suite`，然后把常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。
它复用与主机上 `qa suite` 相同的场景选择行为。
主机和 Multipass suite 运行默认会使用隔离的 Gateway 网关工作进程并行执行多个已选场景。`qa-channel` 默认并发数为 4，并受所选场景数量限制。使用 `--concurrency <count>` 调整工作进程数量，或使用 `--concurrency 1` 进行串行执行。
当任何场景失败时，该命令会以非零状态退出。如果你想要产物但不想产生失败退出码，请使用 `--allow-failures`。
实时运行会转发对虚拟机而言可行的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便虚拟机可以通过挂载的工作区写回。
默认情况下，主机和 Multipass 套件运行会通过隔离的 Gateway 网关工作进程并行执行多个选中的场景。`qa-channel` 默认并发数为 4，并受选中场景数量限制。使用 `--concurrency <count>` 调整工作进程数量，或使用 `--concurrency 1` 进行串行执行。
当任何场景失败时，该命令会以非零状态退出。如果你想生成产物但不希望退出码失败，请使用 `--allow-failures`。
实时运行会转发客户机可实际使用的受支持 QA 身份验证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，这样客户机就能通过挂载的工作区写回。
## Telegram、Discord 和 Slack QA 参考
Matrix 有一个[专用页面](/zh-CN/concepts/qa-matrix)，因为它的场景数量较多，并且需要基于 Docker 的 homeserver 配置。Telegram、Discord 和 Slack 规模较小——每个只有少量场景，没有配置档案系统，面向预先存在的真实渠道——因此它们的参考内容放在这里。
Matrix 因场景数量和基于 Docker 的 homeserver 预配而有一个[专用页面](/zh-CN/concepts/qa-matrix)。Telegram、Discord 和 Slack 较小，每个只有少量场景，没有配置文件系统，并针对预先存在的真实渠道，因此其参考内容放在这里。
### 共享 CLI 标志
这些通道通过 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 注册，并接受相同的标志：
| 标志 | 默认值 | 描述 |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | 仅运行此场景。可重复。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 写入报告、摘要、观察到的消息和输出日志的位置。相对路径会相对于 `--repo-root` 解析。 |
| `--repo-root <path>` | `process.cwd()` | 从中立 cwd 调用时的仓库根目录。 |
| `--sut-account <id>` | `sut` | QA Gateway 网关配置内的临时账号 id。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 或 `live-frontier`（旧版 `live-openai` 仍然可用）。 |
| `--model <ref>` / `--alt-model <ref>` | 提供商默认值 | 主模型/备用模型引用。 |
| `--fast` | 关闭 | 在受支持位置启用提供商快速模式。 |
| `--credential-source <env\|convex>` | `env` | 参见 [Convex 凭证池](#convex-credential-pool)。 |
| `--credential-role <maintainer\|ci>` | CI 中为 `ci`，否则为 `maintainer` | 使用 `--credential-source convex` 时使用的角色。 |
| 标志 | 默认值 | 描述 |
| ------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | 只运行此场景。可重复使用。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 写入报告、摘要、观测到的消息和输出日志的位置。相对路径会基于 `--repo-root` 解析。 |
| `--repo-root <path>` | `process.cwd()` | 从中立 cwd 调用时使用的仓库根目录。 |
| `--sut-account <id>` | `sut` | QA Gateway 网关配置中的临时账号 id。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 或 `live-frontier`（旧版 `live-openai` 仍可使用）。 |
| `--model <ref>` / `--alt-model <ref>` | 提供商默认值 | 主模型/备用模型引用。 |
| `--fast` | 关闭 | 在受支持的位置启用提供商快速模式。 |
| `--credential-source <env\|convex>` | `env` | 参见 [Convex 凭据池](#convex-credential-pool)。 |
| `--credential-role <maintainer\|ci>` | CI 中为 `ci`，否则为 `maintainer` | 使用 `--credential-source convex` 时采用的角色。 |
每个通道在任何场景失败时都会以非零状态退出。`--allow-failures` 会写入产物，但不会设置失败退出码。
任何场景失败时，每个通道都会以非零状态退出。`--allow-failures` 会写入产物，但不会设置失败退出码。
### Telegram QA
@ -176,9 +176,9 @@ Matrix 有一个[专用页面](/zh-CN/concepts/qa-matrix)，因为它的场景
pnpm openclaw qa telegram
```
目标是一个真实的私有 Telegram 群组，使用两个不同的 bot（driver + SUT）。SUT bot 必须拥有 Telegram 用户名；当两个 bot 都在 `@BotFather` 中启用 **Bot-to-Bot Communication Mode** 时，bot 到 bot 的观察效果最佳。
目标是一个真实的私有 Telegram 群组，其中包含两个不同的 bot（驱动 + SUT）。SUT bot 必须有 Telegram 用户名；当两个 bot 都在 `@BotFather` 中启用 **Bot-to-Bot Communication Mode** 时，bot 到 bot 的观测效果最好。
当 `--credential-source env` 时需要的环境变量：
使用 `--credential-source env` 时所需的环境变量：
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — 数字聊天 id（字符串）。
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
@ -186,7 +186,7 @@ pnpm openclaw qa telegram
可选：
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 会在观察消息产物中保留消息正文（默认会编辑隐藏）。
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 会在观测消息产物中保留消息正文（默认会脱敏）。
场景（`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`）：
@ -202,8 +202,8 @@ pnpm openclaw qa telegram
输出产物：
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — 从 canary 开始包含每条回复的 RTT（driver 发送 → 观察到 SUT 回复）。
- `telegram-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否则正文会被编辑隐藏。
- `telegram-qa-summary.json` — 从 canary 开始，包含每条回复的 RTT（驱动发送 → 观测到 SUT 回复）。
- `telegram-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否则正文会被脱敏。
### Discord QA
@ -211,26 +211,26 @@ pnpm openclaw qa telegram
pnpm openclaw qa discord
```
目标是一个真实的私有 Discord guild 渠道，使用两个 bot：一个由 harness 控制的 driver bot，以及一个由子 OpenClaw Gateway 网关通过内置 Discord 插件启动的 SUT bot。验证渠道提及处理、SUT bot 已向 Discord 注册原生 `/help` 命令，以及选择加入的 Mantis 证据场景。
目标是一个真实的私有 Discord guild 频道，其中包含两个 bot：由 harness 控制的驱动 bot，以及由子 OpenClaw Gateway 网关通过内置 Discord 插件启动的 SUT bot。它会验证频道提及处理、SUT bot 已向 Discord 注册原生 `/help` 命令，以及可选择启用的 Mantis 证据场景。
当 `--credential-source env` 时需要的环境变量：
使用 `--credential-source env` 时所需的环境变量：
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必须与 Discord 返回的 SUT bot 用户 id 匹配（否则该通道会快速失败）。
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必须匹配 Discord 返回的 SUT bot 用户 id（否则该通道会快速失败）。
可选：
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 会在观察消息产物中保留消息正文。
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 会在观测消息产物中保留消息正文。
场景（`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`）：
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — 选择加入的 Mantis 场景。它会单独运行，因为它会将 SUT 切换为始终开启、仅工具的 guild 回复，并设置 `messages.statusReactions.enabled=true`，然后捕获 REST reaction 时间线以及 HTML/PNG 可视产物。
- `discord-status-reactions-tool-only` — 可选择启用的 Mantis 场景。它会单独运行，因为它会将 SUT 切换为始终开启、仅工具的 guild 回复，并设置 `messages.statusReactions.enabled=true`，然后捕获 REST reaction 时间线以及 HTML/PNG 可视化产物。
显式运行 Mantis 状态 reaction 场景：
@ -247,8 +247,8 @@ pnpm openclaw qa discord \
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`，否则正文会被编辑隐藏。
- 运行状态 reaction 场景时会生成 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
- `discord-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`，否则正文会被脱敏。
- 运行状态 reaction 场景时，会生成 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
### Slack QA
@ -256,9 +256,9 @@ pnpm openclaw qa discord \
pnpm openclaw qa slack
```
目标是一个真实的私有 Slack 渠道，使用两个不同的 bot：一个由 harness 控制的 driver bot，以及一个由子 OpenClaw Gateway 网关通过内置 Slack 插件启动的 SUT bot。
目标是一个真实的私有 Slack 频道，其中包含两个不同的 bot：由 harness 控制的驱动 bot，以及由子 OpenClaw Gateway 网关通过内置 Slack 插件启动的 SUT bot。
当 `--credential-source env` 时需要的环境变量：
使用 `--credential-source env` 时所需的环境变量：
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
@ -267,7 +267,7 @@ pnpm openclaw qa slack
可选：
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` 会在观察消息产物中保留消息正文。
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` 会在观测消息产物中保留消息正文。
场景（`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`）：
@ -278,18 +278,191 @@ pnpm openclaw qa slack
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`，否则正文会被编辑隐藏。
- `slack-qa-observed-messages.json` — 除非设置 `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`，否则正文会被脱敏。
#### 设置 Slack 工作区
该通道需要在一个工作区中有两个不同的 Slack 应用，外加一个两个 bot 都是成员的频道：
- `channelId` — 两个 bot 都已受邀加入的频道的 `Cxxxxxxxxxx` id。请使用专用频道；该通道每次运行都会发帖。
- `driverBotToken` — **Driver** 应用的 bot token（`xoxb-...`）。
- `sutBotToken` — **SUT** 应用的 bot token（`xoxb-...`），它必须是不同于驱动的单独 Slack 应用，以确保其 bot 用户 id 不同。
- `sutAppToken` — SUT 应用的应用级 token（`xapp-...`），带有 `connections:write`，Socket Mode 会使用它让 SUT 应用接收事件。
建议使用专门用于 QA 的 Slack 工作区，而不是复用生产工作区。
**1. 创建 Driver 应用**
前往 [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → 选择 QA 工作区，粘贴以下清单，然后执行 _Install to Workspace_：
```json
{
"display_information": {
"name": "OpenClaw QA Driver",
"description": "Test driver bot for OpenClaw QA Slack live lane"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA Driver",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "channels:history", "groups:history", "users:read"]
}
},
"settings": {
"socket_mode_enabled": false
}
}
```
复制 _Bot User OAuth Token_（`xoxb-...`）—— 它就是 `driverBotToken`。驱动只需要发消息并识别自己；不需要事件，也不需要 Socket Mode。
**2. 创建 SUT 应用**
在同一工作区中重复 _Create New App → From a manifest_。scope 集合与内置 Slack 插件的生产安装一致（`extensions/slack/src/setup-shared.ts:10`）：
```json
{
"display_information": {
"name": "OpenClaw QA SUT",
"description": "OpenClaw QA SUT connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA SUT",
"always_online": true
},
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_home_opened",
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
Slack 创建应用后，在其设置页面完成两件事：
- _Install to Workspace_ → 复制 _Bot User OAuth Token_ → 它就是 `sutBotToken`。
- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → 添加 scope `connections:write` → 保存 → 复制 `xapp-...` 值 → 它就是 `sutAppToken`。
通过分别对每个 token 调用 `auth.test`，验证两个 bot 的用户 id 不同。运行时会通过用户 id 区分驱动和 SUT；将一个应用同时用于两者会导致 mention-gating 立即失败。
**3. 创建频道**
在 QA 工作区中创建一个频道（例如 `#openclaw-qa`），并从频道内邀请两个 bot：
```
/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT
```
从 _channel info → About → Channel ID_ 复制 `Cxxxxxxxxxx` ID，它会成为 `channelId`。公共频道可以使用；如果你使用私有频道，两个应用都已经有 `groups:history`，因此 harness 的历史读取仍会成功。
**4. 注册凭证**
有两种选项。单机调试使用环境变量（设置四个 `OPENCLAW_QA_SLACK_*` 变量并传入 `--credential-source env`），或者填充共享的 Convex 池，让 CI 和其他维护者可以租用它们。
对于 Convex 池，将四个字段写入 JSON 文件：
```json
{
"channelId": "Cxxxxxxxxxx",
"driverBotToken": "xoxb-...",
"sutBotToken": "xoxb-...",
"sutAppToken": "xapp-..."
}
```
在你的 shell 中导出 `OPENCLAW_QA_CONVEX_SITE_URL` 和 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 后，注册并验证：
```bash
pnpm openclaw qa credentials add \
--kind slack \
--payload-file slack-creds.json \
--note "QA Slack pool seed"
pnpm openclaw qa credentials list --kind slack --status all --json
```
预期 `count: 1`、`status: "active"`，且没有 `lease` 字段。
**5. 端到端验证**
在本地运行该 lane，以确认两个机器人都能通过 broker 相互通信：
```bash
pnpm openclaw qa slack \
--credential-source convex \
--credential-role maintainer \
--output-dir .artifacts/qa-e2e/slack-local
```
绿色运行会在远少于 30 秒内完成，且 `slack-qa-report.md` 显示 `slack-canary` 和 `slack-mention-gating` 的 Status 都是 `pass`。如果 lane 挂起约 90 秒并以 `Convex credential pool exhausted for kind "slack"` 退出，说明池为空或每一行都已被租用，`qa credentials list --kind slack --status all --json` 会告诉你是哪一种情况。
### Convex 凭证池
Telegram、Discord 和 Slack 通道可以从共享 Convex 池租用凭证，而不是读取上面的环境变量。传入 `--credential-source convex`（或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 会获取独占租约，在运行期间对其发送 Heartbeat，并在关闭时释放它。池类型为 `"telegram"`、`"discord"` 和 `"slack"`。
Telegram、Discord 和 Slack lane 可以从共享 Convex 池租用凭证，而不是读取上面的环境变量。传入 `--credential-source convex`（或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 会获取一个独占租约，在运行期间发送 Heartbeat，并在关闭时释放它。池类型是 `"telegram"`、`"discord"` 和 `"slack"`。
broker 会在 `admin/add` 上校验的 payload 形状：
broker 在 `admin/add` 上验证的 payload 形状：
- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必须是数字聊天 id 字符串。
- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }`，`groupId` 必须是数字 chat-id 字符串。
- Discord（`kind: "discord"`）：`{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。
- Slack（`kind: "slack"`）：`{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }`，`channelId` 必须匹配 `^[A-Z][A-Z0-9]+$`（例如 `Cxxxxxxxxxx` 这样的 Slack ID）。有关应用和 scope 配置，请参阅[设置 Slack 工作区](#setting-up-the-slack-workspace)。
操作环境变量和 Convex broker 端点契约位于[测试 → 通过 Convex 共享 Telegram 凭证](/zh-CN/help/testing#shared-telegram-credentials-via-convex-v1)（该章节名称早于 Discord 支持；broker 语义对两种类型都相同）。
操作环境变量和 Convex broker 端点契约位于[测试 → 通过 Convex 共享 Telegram 凭证](/zh-CN/help/testing#shared-telegram-credentials-via-convex-v1)（该章节名称早于 Discord 支持；两种类型的 broker 语义相同）。
## 仓库支持的种子
@ -300,18 +473,18 @@ broker 会在 `admin/add` 上校验的 payload 形状：
这些内容有意放在 git 中，这样 QA 计划对人类和智能体都可见。
`qa-lab` 应保持为通用 markdown runner。每个场景 markdown 文件都是一次测试运行的事实来源，并应定义：
`qa-lab` 应保持为通用的 Markdown runner。每个场景 Markdown 文件都是一次测试运行的事实来源，并应定义：
- 场景元数据
- 可选的类别、能力、通道和风险元数据
- 可选的 category、capability、lane 和 risk 元数据
- 文档和代码引用
- 可选的插件要求
- 可选的 Gateway 网关配置补丁
- 可执行的 `qa-flow`
支持 `qa-flow` 的可复用运行时表面允许保持通用且跨领域。例如，markdown 场景可以组合传输侧 helper 和浏览器侧 helper，后者通过 Gateway 网关 `browser.request` 接缝驱动嵌入式 Control UI，而无需添加特殊情况 runner。
支持 `qa-flow` 的可复用运行时表面允许保持通用且跨领域。例如，Markdown 场景可以把传输侧 helper 与浏览器侧 helper 结合起来，通过 Gateway 网关 `browser.request` seam 驱动嵌入式 Control UI，而无需添加特殊情况 runner。
场景文件应按产品能力而不是源码树文件夹分组。文件移动时请保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 进行实现可追溯。
场景文件应按产品能力分组，而不是按源码树文件夹分组。文件移动时保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 进行实现可追溯性。
基线列表应保持足够广，以覆盖：
@ -321,75 +494,75 @@ broker 会在 `admin/add` 上校验的 payload 形状：
- cron 回调
- 记忆召回
- 模型切换
- subagent handoff
- subagent 移交
- 仓库读取和文档读取
- 一个小型构建任务，例如 Lobster Invaders
## 提供商 mock 通道
## 提供商 mock lane
`qa suite` 有两个本地提供商 mock 通道：
`qa suite` 有两个本地提供商 mock lane：
- `mock-openai` 是可感知场景的 OpenClaw mock。它仍然是仓库支持 QA 和 parity gate 的默认确定性 mock 通道。
- `aimock` 会启动一个 AIMock 支持的提供商服务器，用于实验性协议、fixture、record/replay 和 chaos 覆盖。它是增量能力，不会替代 `mock-openai` 场景分派器。
- `mock-openai` 是感知场景的 OpenClaw mock。它仍然是仓库支持 QA 和 parity gate 的默认确定性 mock lane。
- `aimock` 会启动一个由 AIMock 支持的提供商服务器，用于实验性协议、fixture、record/replay 和 chaos 覆盖。它是增量能力，不会替代 `mock-openai` 场景 dispatcher。
提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商拥有自己的默认值、本地服务器启动、Gateway 网关模型配置、认证档案 staging 需求，以及实时/mock 能力标志。共享 suite 和 Gateway 网关代码应通过提供商注册表路由，而不是基于提供商名称分支。
提供商 lane 实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商拥有自己的默认值、本地服务器启动、Gateway 网关模型配置、auth-profile 暂存需求以及 live/mock 能力标志。共享 suite 和 Gateway 网关代码应通过提供商 registry 路由，而不是按提供商名称分支。
## 传输适配器
`qa-lab` 拥有面向 markdown QA 场景的通用传输接缝。`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道应接入同一个 suite runner，而不是添加特定传输的 QA runner。
`qa-lab` 为 Markdown QA 场景拥有一个通用传输 seam。`qa-channel` 是该 seam 上的第一个适配器，但设计目标更广：未来的真实或合成渠道应接入同一个 suite runner，而不是添加传输专用的 QA runner。
在架构层面，拆分为：
在架构层面，拆分如下：
- `qa-lab` 拥有通用场景执行、工作进程并发、产物写入和报告。
- 传输适配器拥有 Gateway 网关配置、就绪状态、入站和出站观察、传输操作，以及规范化的传输状态。
- `qa/scenarios/` 下的 markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。
- `qa-lab` 拥有通用场景执行、worker 并发、工件写入和报告。
- 传输适配器拥有 Gateway 网关配置、就绪状态、入站和出站观测、传输操作以及规范化传输状态。
- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。
### 添加渠道
向 markdown QA 系统添加渠道只需要两件事：
向 Markdown QA 系统添加渠道只需要两件事：
1. 该渠道的传输适配器。
2. 覆盖该渠道契约的场景包。
当共享 `qa-lab` 主机可以拥有流程时，不要添加新的顶层 QA 命令根。
当共享 `qa-lab` host 可以拥有该流程时，不要添加新的顶层 QA command root。
`qa-lab` 拥有共享主机机制：
`qa-lab` 拥有共享 host 机制：
- `openclaw qa` 命令根
- 套件启动和清理
- `openclaw qa` command root
- suite 启动和 teardown
- worker 并发
- artifact 写入
- 工件写入
- 报告生成
- 场景执行
- 旧版 `qa-channel` 场景的兼容性别名
- 旧版 `qa-channel` 场景的兼容别名
运行器插件拥有传输协议契约：
Runner 插件拥有传输契约：
- `openclaw qa <runner>` 如何挂载到共享 `qa` 根下
- 如何为该传输协议配置 Gateway 网关
- `openclaw qa <runner>` 如何挂载到共享 `qa` root 下
- 如何为该传输配置 Gateway 网关
- 如何检查就绪状态
- 如何注入入站事件
- 如何观察出站消息
- 如何暴露 transcript 和规范化后的传输协议状态
- 如何执行由传输协议支持的操作
- 如何处理传输协议专属的重置或清理
- 如何观测出站消息
- 如何暴露 transcript 和规范化传输状态
- 如何执行传输支持的操作
- 如何处理传输专用 reset 或 cleanup
新渠道的最低采用门槛：
1. 保持 `qa-lab` 作为共享 `qa` 根的所有者。
2. 在共享 `qa-lab` 主机 seam 上实现传输协议运行器。
3. 将传输协议专属机制保留在运行器插件或渠道 harness 内。
4. 将运行器挂载为 `openclaw qa <runner>`，而不是注册竞争性的根命令。运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。保持 `runtime-api.ts` 轻量；延迟 CLI 和运行器执行应保留在单独入口点之后。
5. 在主题化的 `qa/scenarios/` 目录下编写或改编 Markdown 场景。
1. 保持 `qa-lab` 作为共享 `qa` root 的所有者。
2. 在共享 `qa-lab` host seam 上实现传输 runner。
3. 将传输专用机制保留在 runner 插件或渠道 harness 内。
4. 将 runner 挂载为 `openclaw qa <runner>`，而不是注册竞争性的 root command。Runner 插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。保持 `runtime-api.ts` 轻量；惰性 CLI 和 runner 执行应保留在单独入口点之后。
5. 在按主题组织的 `qa/scenarios/` 目录下编写或适配 Markdown 场景。
6. 对新场景使用通用场景 helper。
7. 除非仓库正在进行有意的迁移，否则保持现有兼容性别名可用。
7. 保持现有兼容别名可用，除非仓库正在进行有意的迁移。
决策规则是严格的：
决策规则很严格：
- 如果行为可以在 `qa-lab` 中只表达一次，就把它放在 `qa-lab` 中。
- 如果行为依赖某一个渠道传输协议，就把它保留在该运行器插件或插件 harness 中。
- 如果某个场景需要一个多个渠道都能使用的新能力，就添加通用 helper，而不是在 `suite.ts` 中添加渠道专属分支。
- 如果某个行为只对一种传输协议有意义，就保持该场景为传输协议专属，并在场景契约中明确说明。
- 如果行为可以在 `qa-lab` 中表达一次，就把它放在 `qa-lab` 中。
- 如果行为依赖一个渠道传输，就把它保留在该 runner 插件或插件 harness 中。
- 如果某个场景需要多个渠道都可使用的新能力，就添加通用 helper，而不是在 `suite.ts` 中添加渠道专用分支。
- 如果某个行为只对一个传输有意义，就保持场景传输专用，并在场景契约中明确说明。
### 场景 helper 名称
@ -408,21 +581,20 @@ broker 会在 `admin/add` 上校验的 payload 形状：
- `formatTransportTranscript`
- `resetTransport`
现有场景仍可使用兼容性别名：`waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus`，但新场景编写应使用通用名称。这些别名存在是为了避免一次性迁移，而不是未来的模型。
兼容别名仍可用于现有场景：`waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus`，但新场景编写应使用通用名称。这些别名用于避免一次性强制迁移，不代表未来的模型。
## 报告
`qa-lab` 会从观察到的总线时间线导出 Markdown 协议报告。
报告应回答：
`qa-lab` 会从观测到的 bus timeline 导出 Markdown 协议报告。报告应回答：
- 哪些有效
- 哪些失败
- 哪些仍被阻塞
- 哪些后续场景值得添加
如需查看可用场景清单（在评估后续工作规模或接入新传输协议时很有用），运行 `pnpm openclaw qa coverage`（添加 `--json` 可获得机器可读输出）。
要查看可用场景清单（在评估后续工作规模或接入新传输时很有用），运行 `pnpm openclaw qa coverage`（添加 `--json` 可获得机器可读输出）。
对于角色和风格检查，请跨多个实时模型 refs 运行同一场景，并编写一个经过评判的 Markdown 报告：
对于角色和风格检查，在多个 live 模型 ref 上运行同一个场景，并写入经过评审的 Markdown 报告：
```bash
pnpm openclaw qa character-eval \
@ -441,16 +613,21 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
该命令运行本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。不应告知候选模型它正在被评估。该命令会保留每个完整 transcript，记录基础运行统计，然后以 fast mode 请求评审模型，并在受支持时使用 `xhigh` reasoning，按自然度、氛围和幽默感对运行结果排序。比较提供商时使用 `--blind-judge-models`：评审提示仍会获得每个 transcript 和运行状态，但候选 refs 会被替换为中性标签，例如 `candidate-01`；报告在解析后会将排名映射回真实 refs。
候选运行默认使用 `high` thinking；GPT-5.5 使用 `medium`，支持该级别的旧版 OpenAI 评估 refs 使用 `xhigh`。使用 `--model provider/model,thinking=<level>` 内联覆盖特定候选。`--thinking <level>` 仍会设置全局 fallback，旧版 `--model-thinking <provider/model=level>` 形式保留用于兼容。
OpenAI 候选 refs 默认使用 fast mode，以便在提供商支持时使用 priority processing。当单个候选或评审需要覆盖时，内联添加 `,fast`、`,no-fast` 或 `,fast=false`。仅当你想为每个候选模型强制开启 fast mode 时，才传递 `--fast`。候选和评审耗时会记录在报告中以供基准分析，但评审提示会明确说明不要按速度排序。
候选和评审模型运行都默认并发数为 16。当提供商限制或本地 Gateway 网关压力导致运行过于嘈杂时，降低 `--concurrency` 或 `--judge-concurrency`。
该命令运行本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。不应告诉候选模型它正在被评估。该命令会保留每个完整 transcript，记录基本运行统计，然后要求 judge 模型使用 fast mode，并在支持时使用 `xhigh` reasoning，按自然度、vibe 和幽默感对运行结果排名。比较提供商时使用 `--blind-judge-models`：judge prompt 仍会获得每个 transcript 和运行状态，但候选 ref 会替换为 `candidate-01` 等中性标签；报告会在解析后将排名映射回真实 ref。
候选运行默认使用 `high` thinking，GPT-5.5 使用 `medium`，支持它的旧版 OpenAI eval ref 使用 `xhigh`。使用 `--model provider/model,thinking=<level>` 内联覆盖特定候选。`--thinking <level>` 仍会设置全局 fallback，旧的 `--model-thinking <provider/model=level>` 形式保留用于兼容。
OpenAI 候选 ref 默认启用 fast mode，因此在提供商支持时会使用 priority processing。当单个候选或 judge 需要覆盖时，内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你想为每个候选模型强制开启 fast mode 时，才传入 `--fast`。候选和 judge 的持续时间会记录在报告中用于 benchmark 分析，但 judge prompt 会明确说明不要按速度排名。
候选和 judge 模型运行的默认并发均为 16。当提供商限制或本地 Gateway 网关压力使运行噪声过大时，降低 `--concurrency` 或 `--judge-concurrency`。
未传入候选 `--model` 时，角色评估默认使用 `openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5` 和 `google/gemini-3.1-pro-preview`。
未传入 `--judge-model` 时，评审默认使用 `openai/gpt-5.5,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。
未传入 `--judge-model` 时，judge 默认使用 `openai/gpt-5.5,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。
## 相关文档
- [Matrix QA](/zh-CN/concepts/qa-matrix)
- [QA Channel](/zh-CN/channels/qa-channel)
- [QA channel](/zh-CN/channels/qa-channel)
- [测试](/zh-CN/help/testing)
- [仪表板](/zh-CN/web/dashboard)