Operator 流程
操作员流程¶
当前 QA 操作员流程是一个双窗格 QA 站点:
- 左侧:Gateway 仪表盘(Control UI),包含 agent。
- 右侧:QA Lab,显示类似 Slack 的转录记录和场景计划。
通过以下命令运行:
该命令会构建 QA 站点,启动 Docker 支撑的 gateway 通道,并提供 QA Lab 页面,操作员或自动化循环可在其中为 agent 分配 QA 任务、观察真实渠道行为,并记录哪些成功、失败或保持阻塞。
请从与当前源代码匹配的检出运行 QA Lab。Lab 加载后,捕获请求会检查异步代理捕获支持,若缺失则报告升级错误;不相关的 Lab 操作不需要该捕获能力。此操作检查并不表示与旧主机完全兼容:当前 QA 源代码还要求 SDK 导入(例如 sqlite-runtime-testing),而已发布的 2026.9.6 包并不包含这些导入,因此其 QA CLI 可能在捕获检查运行之前就失败。
Runner 的 Scenarios 面板可以同时启动 flow、Playwright、Vitest 和脚本目录条目。Profile 使用 taxonomy 拥有的成员计划;勾选场景会创建显式覆盖,而 Scenarios 面板中的 Profile 会恢复为服务器解析的 profile 成员身份。
配置还提供 Provider 通道、主要和备用模型、执行渠道、渠道驱动、证据模式、运行时配对 和 运行时配对通道(core、extended 或 soak)。Provider/模型、运行时和渠道驱动的选择保持独立:例如,真实前沿提供商可以使用 Crabline 渠道驱动,而合成(模拟)提供商可以使用真实渠道。服务器在启动前解析 taxonomy 成员身份、provider/模型资格、声明的 execution.channel、运行时配对通道成员身份以及受支持的执行种类。Run 面板显示选定的执行种类以及显式排除项或错误。未知、空显式、与 profile 不兼容或与通道不兼容的选择会失败关闭,而不会被默认套件替换。
为了更快地迭代 QA Lab UI,而无需每次重新构建 Docker 镜像,可通过绑定挂载的 QA Lab bundle 启动该堆栈:
qa:lab:up:fast 将 Docker 服务保留在预构建镜像上,并将 extensions/qa-lab/web/dist 绑定挂载到 qa-lab 容器中。qa:lab:watch 会在变更时重新构建该 bundle,并且当 QA Lab 资源哈希变更时,浏览器会自动重新加载。
可观测性冒烟测试¶
Note
可观测性 QA 仅限源代码检出。npm tarball 有意省略 QA Lab(和 qa-channel),因此包的 Docker 发布通道不会运行 qa 命令。更改诊断插桩时,请从构建好的源代码检出运行这些命令。
| 别名 | 运行内容 |
|---|---|
pnpm qa:otel:smoke |
本地 OpenTelemetry 接收器,外加启用了 diagnostics-otel 的 otel-trace-smoke 场景。 |
pnpm qa:otel:collector-smoke |
同一个通道,但位于真实的 OpenTelemetry Collector Docker 容器之后。在更改端点接线或 collector/OTLP 兼容性时使用。 |
pnpm qa:prometheus:smoke |
启用了 diagnostics-prometheus 的 docker-prometheus-smoke 场景。 |
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 接收器,运行一次最小的 QA-channel agent 轮次,然后断言 trace、指标和日志均已导出。它解码导出的 protobuf trace spans,并检查发布关键结构:openclaw.run、openclaw.harness.run、最新的 GenAI 语义约定模型调用 span、openclaw.context.assembled 和 openclaw.message.delivery 必须全部存在。该冒烟测试强制设置 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,因此模型调用 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 验证未认证的抓取被拒绝,然后检查认证抓取包含发布关键指标族,且不含提示内容、响应内容、原始诊断标识符、认证令牌或本地路径。
Matrix 实时通道¶
对于使用真实传输、且不需要模型提供商凭据的 Matrix 通道,请使用确定性 mock OpenAI 提供商:
对于实时前沿提供商通道,请显式提供 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 网关中运行真实的 Matrix 插件(不使用 qa-channel),然后拆除环境。
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 的清单。
常用选项:
| 标志 | 默认值 | 用途 |
|---|---|---|
--scenario <id> |
- | 选择一个场景;可重复。 |
--fail-fast |
关闭 | 在第一个失败的检查或场景后停止。 |
--allow-failures |
关闭 | 写入产物,但场景失败时不返回失败的退出码。 |
--provider-mode <mode> |
live-frontier |
使用 mock-openai 进行确定性调度,或使用 live-frontier 连接实时提供商。 |
--model <ref> |
提供商默认 | 设置主 provider/model 引用。 |
--alt-model <ref> |
提供商默认 | 设置切换模型的场景所使用的备用模型。 |
--fast |
关闭 | 在受支持时启用提供商快速模式。 |
--output-dir <path> |
生成 | 选择报告目录;相对路径相对于 --repo-root 解析。 |
--repo-root <path> |
当前目录 | 从中立的工作目录运行。 |
--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 恢复命令。在慢速运行器上,
请增大无回复窗口;在快速 CI 上,较小的窗口可以缩短负面
断言。
目录涵盖单元测试无法端到端证明的传输行为:提及门控、允许机器人策略、允许列表、顶层和线程
回复、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 的可选场景,用于 bug 复现。使用
--scenario discord-status-reactions-tool-only 获取明确的状态
表情回应时间线,或使用 --scenario discord-thread-reply-filepath-attachment
创建真实的 Discord 线程,并验证 message.thread-reply
是否保留 filePath 附件。这些场景不会包含在默认
实时 Discord 通道中,因为它们是前后复现检查,而不是
广泛的冒烟覆盖。线程附件 Mantis 工作流还可以在
MANTIS_DISCORD_VIEWER_CHROME_PROFILE_DIR 或
MANTIS_DISCORD_VIEWER_CHROME_PROFILE_TGZ_B64 在 QA
环境中配置时,添加已登录的 Discord Web 见证视频。
该 viewer 配置文件仅用于视觉捕获;通过/失败
判定仍来自 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 桌面 VM 运行,请运行:
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 网关;不使用它时,该命令会运行常规的 bot-to-bot 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 workflow 分发命令、证据注释契约、hydrate-mode 决策表、计时解释和故障处理步骤位于 Mantis Slack 桌面运行手册。
对于 agent/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。
凭证池健康检查¶
在使用池化的实时凭据之前,请运行:
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