操作员流程

操作员流程¶

当前 QA 操作员流程采用双栏 QA 站点：

左侧：Gateway 仪表盘（控制 UI），包含 agent。
右侧：QA Lab，展示类 Slack 的对话记录和场景计划。

运行方式：

pnpm qa:lab:up

该命令会构建 QA 站点，启动基于 Docker 的 gateway 通道，并暴露 QA Lab 页面，供操作员或自动化循环为 agent 分配 QA 任务、观察真实通道行为，并记录成功、失败或保持阻塞的内容。

请从匹配的当前源码检出目录运行 QA Lab。Lab 加载完成后，capture 请求会检查异步代理捕获支持，如果缺失则报告升级错误；与 Lab 无关的其他操作不要求具备该捕获能力。此操作检查并不代表与较旧主机完全兼容：当前 QA 源码还需要 SDK 导入（例如 sqlite-runtime-testing），而已发布的 2026.9.6 包不包含这些导入，因此其 QA CLI 可能在捕获检查运行之前就失败。

Runner 的 Scenarios 面板可以同时启动 flow、Playwright、Vitest 和 script 目录条目。Profile 使用 taxonomy 拥有的成员计划；勾选场景会创建显式覆盖，而 Scenarios 面板中的 Profile 则返回服务器解析的 profile 成员关系。

Config 还暴露 Provider lane、主要和备用模型、Execution channel、Channel driver、Evidence mode、Runtime pair 和 Runtime-pair lane（core、extended 或 soak）。Provider/模型、runtime 和 channel-driver 的选择保持独立：例如，Real frontier 提供商可以使用 Crabline channel driver，而 Synthetic（mock）可以使用 Real channels。服务器会在启动前解析 taxonomy 成员关系、provider/model 资格、声明的 execution.channel、runtime-pair-lane 成员关系以及受支持的 execution 类型。Run 面板显示所选 execution 类型以及显式排除项或错误。未知、空的显式选择、与 profile 不兼容或与 lane 不兼容的选择都会关闭失败，而不会替换为默认套件。

为了在每次迭代时无需重建 Docker 镜像即可更快地迭代 QA Lab UI，可以使用 bind-mount 的 QA Lab bundle 启动整个技术栈：

pnpm openclaw qa docker-build-image
pnpm qa:lab:build
pnpm qa:lab:up:fast
pnpm qa:lab:watch

qa:lab:up:fast 让 Docker 服务保持在使用预构建镜像的状态，并将 extensions/qa-lab/web/dist bind-mount 到 qa-lab 容器中。qa:lab:watch 会在 bundle 发生变化时重新构建，当 QA Lab 资源哈希变化时浏览器会自动重新加载。

可观测性冒烟测试¶

Note

可观测性 QA 仅限源码检出目录使用。npm tarball 有意省略 QA Lab（以及 qa-channel），因此包 Docker 发布通道不会运行 qa 命令。在修改诊断插桩时，请从构建好的源码检出目录运行这些命令。

别名	运行内容
`pnpm qa:otel:smoke`	本地 OpenTelemetry receiver，再加上启用了 `diagnostics-otel` 的 `otel-trace-smoke` 场景。
`pnpm qa:otel:collector-smoke`	相同的 lane，但位于真实的 OpenTelemetry Collector Docker 容器之后。在修改端点接线或 collector/OTLP 兼容性时使用。
`pnpm qa:prometheus:smoke`	`docker-prometheus-smoke` 场景，启用了 `diagnostics-prometheus`。
`pnpm qa:observability:smoke`	先运行 `qa:otel:smoke`，再运行 `qa:prometheus:smoke`。
`pnpm qa:observability:collector-smoke`	先运行 `qa:otel:collector-smoke`，再运行 `qa:prometheus:smoke`。

qa:otel:smoke 会启动一个本地 OTLP/HTTP receiver，运行一轮最小的 QA-channel agent 对话，然后断言 traces、metrics 和 logs 已被导出。它会解码导出的 protobuf trace spans，并检查发布关键形状：openclaw.run、openclaw.harness.run、一个最新的 GenAI 语义约定 model-call span、openclaw.context.assembled 和 openclaw.message.delivery 都必须存在。该 smoke 会强制设置 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental，因此 model-call span 必须使用 {gen_ai.operation.name} {gen_ai.request.model} 名称；模型调用在成功轮次中不得导出 StreamAbandoned；原始诊断 ID 和 openclaw.content.* 属性必须保留在 trace 之外。场景提示要求模型回复一个固定标记并保留一个固定秘密字符串；原始 OTLP 负载不得包含其中任何一个，也不得包含从场景 id 派生的 QA 会话密钥。它会在 QA 套件产物旁边写入 otel-smoke-summary.json。

qa:prometheus:smoke 会验证未认证的抓取被拒绝，然后检查认证后的抓取是否包含发布关键的 metric 族，且不包含 prompt 内容、响应内容、原始诊断标识符、auth token 或本地路径。

Matrix 实时 lane¶

对于不需要模型提供商凭据的传输层真实 Matrix lane，请使用确定性 mock OpenAI 提供商：

pnpm openclaw qa matrix --provider-mode mock-openai

对于实时前沿提供商 lane，请显式提供 OpenAI 兼容凭据：

OPENCLAW_LIVE_OPENAI_KEY="${OPENAI_API_KEY}" \
  pnpm openclaw qa matrix --provider-mode live-frontier

直接运行 pnpm openclaw qa matrix 会运行所有通过 execution.channel 或 execution.channels 显式声明 Matrix 资格的 flow 场景，并且会在场景失败后继续执行。使用 --fail-fast 可缩短反馈循环，或重复使用 --scenario <id> 来运行显式子集，包括无通道限制的可移植场景。

Matrix 实时实现位于 extensions/qa-lab/src/live-transports/matrix/scenarios/。

适配器在 Docker 中提供一个一次性的 Tuwunel homeserver（默认镜像 ghcr.io/matrix-construct/tuwunel:v1.8.3，固定到其多架构 OCI 索引摘要；服务器名称为 matrix-qa.test，主机端口由 Docker 分配），注册临时的 driver、SUT 和 observer 用户，初始化所需房间，并记录经脱敏处理的请求/响应边界。随后它在该传输专用的子 QA 网关（无 qa-channel）中运行真实的 Matrix 插件，并在最后拆除整个环境。

v1.8.3 的 GHCR 索引解析为 sha256:699fa9971c174e01c884abad8d1a3cfb2fe518e1a71f1fa16ea9dedf11873d74。 docker buildx imagetools inspect ghcr.io/matrix-construct/tuwunel:v1.8.3 报告的清单包含 linux/arm64、linux/amd64、linux/amd64/v2 和 linux/amd64/v3。

常见选项：

Flag	Default	Purpose
`--scenario <id>`	-	选择一个场景；可重复指定。
`--fail-fast`	off	在第一个失败的检查或场景后停止。
`--allow-failures`	off	在场景失败时仍写入产物，但不返回失败的退出码。
`--provider-mode <mode>`	`live-frontier`	使用 `mock-openai` 进行确定性调度，或使用 `live-frontier` 连接真实提供商。
`--model <ref>`	provider default	设置主要的 `provider/model` 引用。
`--alt-model <ref>`	provider default	设置场景在切换模型时使用的备用模型。
`--fast`	off	在支持的情况下启用提供商的快速模式。
`--output-dir <path>`	generated	选择报告目录；相对路径将相对于 `--repo-root` 解析。
`--repo-root <path>`	current directory	从一个中立的工作目录运行。
`--sut-account <id>`	`sut`	选择子网关配置中的 Matrix 账户 ID。

Matrix QA 不会租用共享的 Matrix 凭据：适配器在本地创建一次性用户，因此它不接受 --credential-source 或 --credential-role。可通过 OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE 覆盖 homeserver 镜像；通过 OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS 调整负向的“无回复”断言（默认 8000，并会被限制在当前场景超时范围内）。单次执行命令通常会在产物刷新后强制干净退出，因为 Matrix 加密的原生句柄可能比清理过程存活更久；只有需要命令直接返回的测试框架中，才应设置 OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1。

每次运行都会在所选输出目录下写入常规的 QA Lab 产物：qa-suite-report.md、 qa-suite-summary.json 和 qa-evidence.json。如果清理失败，请运行打印出的 docker compose ... down --remove-orphans 恢复命令。在较慢的运行环境中，请增大 no-reply 窗口；在较快的 CI 上，较小的窗口可以缩短负向断言时间。

该场景目录涵盖了单元测试无法端到端验证的传输行为：提及门控、allow-bot 策略、允许列表、顶层回复和线程回复、DM 路由、表情回应处理、入站编辑抑制、重启重放去重、homeserver 中断恢复、审批元数据传递、媒体处理，以及 Matrix E2EE 引导/恢复/验证流程。E2EE CLI 场景还会在检查网关回复之前，先通过同一次性 homeserver 驱动 openclaw matrix encryption setup 和验证命令。

CI 在 .github/workflows/qa-live-transports-convex.yml 中使用相同的命令接口。定时、发布和手动运行会在一个作业中执行由场景目录派生的选择，最多使用四个隔离的主机 worker。每个 worker 拥有自己的一次性 homeserver、Gateway、状态和产物。场景成员资格仍由目录统一维护； --fail-fast 保持串行执行，并在第一次失败后停止。使用 openclaw qa matrix --concurrency <count> 可请求更少的 worker；超过传输上限的值仍会保持封顶。

Discord Mantis 场景¶

Discord 还有一些仅限 Mantis、可选启用的场景，用于缺陷复现。使用 --scenario discord-status-reactions-tool-only 可执行显式的状态 reaction 时间线；使用 --scenario discord-thread-reply-filepath-attachment 可创建真实的 Discord 线程，并验证 message.thread-reply 是否保留 filePath 附件。这些场景不会进入默认的真实 Discord 通道，因为它们是复现前后对照探针，而非广泛的冒烟覆盖。当 QA 环境中配置了 MANTIS_DISCORD_VIEWER_CHROME_PROFILE_DIR 或 MANTIS_DISCORD_VIEWER_CHROME_PROFILE_TGZ_B64 时，线程附件 Mantis 工作流还可以添加一段已登录的 Discord Web 见证视频。该查看者配置仅用于视觉捕获；通过/失败判定仍来自 Discord REST oracle。

对于其他真实传输冒烟通道：

pnpm openclaw qa buzz
pnpm openclaw qa discord
pnpm openclaw qa slack
pnpm openclaw qa telegram
pnpm openclaw qa whatsapp

它们使用两个机器人或账户（driver + SUT）针对预先存在的真实频道。这五种传输所需的环境变量、场景列表、输出产物以及 Convex 凭据池记录在 Buzz、Discord、Slack、Telegram 和 WhatsApp QA 参考中。

Mantis Slack 桌面与可视化任务运行器¶

若要使用 VNC 救援进行完整的 Slack 桌面虚拟机运行，请执行：

pnpm openclaw qa mantis slack-desktop-smoke \
  --gateway-setup \
  --scenario slack-canary \
  --keep-lease

该命令会租用一台 Crabbox 桌面/浏览器机器，在 VM 内运行 Slack 实时泳道，在 VNC 浏览器中打开 Slack Web，捕获桌面，并将 slack-qa/、slack-desktop-smoke.png 和 slack-desktop-smoke.mp4（当视频捕获可用时）复制回 Mantis 工件目录。Crabbox 桌面/浏览器租约会预先提供捕获工具和浏览器/原生构建辅助包，因此该场景应只在较旧的租约上安装回退项。Mantis 会在 mantis-slack-desktop-smoke-report.md 中报告总耗时和各阶段耗时，以便慢速运行能够显示时间花在了租约预热、凭据获取、远程设置还是工件复制上。在通过 VNC 手动登录 Slack Web 后，复用 --lease-id <cbx_...>；复用的租约还能保持 Crabbox 的 pnpm store 缓存处于热状态。默认 --hydrate-mode source 会从源码检出进行验证，并在 VM 内运行安装/构建。仅当复用的远程工作区已有 node_modules 和已构建的 dist/ 时，才使用 --hydrate-mode prehydrated；该模式会跳过耗时的安装/构建步骤，并且在工作区未就绪时失败关闭。使用 --gateway-setup 时，Mantis 会在 VM 内的端口 38973 上保留一个持久运行的 OpenClaw Slack 网关；不使用它时，该命令会运行常规的机器人到机器人 Slack QA 泳道，并在工件捕获后退出。

为了用桌面证据证明原生 Slack 审批 UI，请运行 Mantis 审批检查点模式：

pnpm openclaw qa mantis slack-desktop-smoke \
  --approval-checkpoints \
  --credential-source convex \
  --credential-role maintainer

该模式与 --gateway-setup 互斥。它会运行 Slack 审批场景，拒绝非审批场景 ID，在每个待处理和已解决的审批状态处等待，将观察到的 Slack API 消息渲染为 approval-checkpoints/<scenario>-pending.png 和 approval-checkpoints/<scenario>-resolved.png，然后如果任何检查点、消息证据、确认或渲染截图缺失或为空，则失败。冷 CI 租约可能仍会在 slack-desktop-smoke.png 中显示 Slack 登录；审批检查点图像是该泳道的视觉证据。

默认检查点运行保留两个标准 Slack 审批场景。若要捕获任一可选加入的 Codex 审批路由，请显式使用 --scenario slack-codex-approval-exec-native 或 --scenario slack-codex-approval-plugin-native 进行选择；Mantis 接受两者，并输出相同的待处理/已解决截图对。运行器会为每个选定的 Codex 路由扩展其检查点和远程命令截止时间，以便完整的审批、代理完成和已解决更新序列能够完成。

操作员检查清单、GitHub 工作流分发命令、证据注释契约、hydrate-mode 决策表、耗时解读以及故障处理步骤位于 Mantis Slack 桌面运行手册。

对于代理/CV 风格的桌面任务，运行：

pnpm openclaw qa mantis visual-task \
  --browser-url https://example.net \
  --expect-text "Example Domain" \
  --vision-model openai/gpt-5.6-luna

visual-task 会租用或复用一台 Crabbox 桌面/浏览器机器，启动 crabbox record --while，通过嵌套的 visual-driver 驱动可见浏览器，捕获 visual-task.png，当选择 --vision-mode image-describe 时，针对截图运行 openclaw infer image describe，并写入 visual-task.mp4、mantis-visual-task-summary.json、mantis-visual-task-driver-result.json 和 mantis-visual-task-report.md。当设置 --expect-text 时，视觉提示会要求一个结构化 JSON 判定（visible、evidence、reason），并且只有当模型报告 visible: true 且证据引用了预期文本时才通过；仅引用目标文本的 visible: false 响应仍会使断言失败。使用 --vision-mode metadata 可执行无模型冒烟测试，以证明桌面、浏览器、截图和视频管道可用，而无需调用图像理解提供商。录制是 visual-task 的必需工件；如果 Crabbox 没有录制到非空的 visual-task.mp4，即使视觉驱动通过，任务也会失败。失败时，除非任务已经通过且未设置 --keep-lease，否则 Mantis 会保留租约以供 VNC 使用。

凭据池健康检查¶

在使用池化的实时凭据之前，运行：

pnpm openclaw qa credentials doctor

doctor 会检查 Convex broker 环境变量（OPENCLAW_QA_CONVEX_SITE_URL、OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX），验证端点设置，仅报告 OPENCLAW_QA_CONVEX_SECRET_CI 和 OPENCLAW_QA_CONVEX_SECRET_MAINTAINER 的已设置/缺失状态，并在存在 maintainer secret 时验证 admin/list 可达性。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw