跳转至

QA 专用运行器

面向 QA 的专用运行器

当你需要 QA 实验室真实感时,这些命令与主测试套件并列使用。

CI 在专用工作流中运行 QA Lab。Agentic 对等性(parity)测试嵌套在 QA-Lab - All Lanes 和发布验证之下,并非独立的 PR 工作流。广泛验证应使用 Full Release Validation,通过 rerun_group=qa-parity 进行对等性测试,或通过 rerun_group=qa-live 进行实时 QA。单独的 OpenClaw Release Checks 子项可以使用 rerun_group=qa 作为两个分组的手动聚合。稳定版/完整版、启用浸泡测试(soak)以及显式 qa-live 发布检查包含 QA-live Matrix 和 Telegram 通道。有界的 beta 发布 all(不含浸泡测试)运行对等性测试,但将那些实时通道推迟到发布后置信度(postpublish-confidence)阶段。QA-Lab - All Lanes 在 main 分支上每晚运行,也可通过手动调度运行,包含 mock 对等性通道、实时 Matrix 通道、Convex 管理的实时 Telegram 通道以及 Convex 管理的实时 Discord 通道作为并行任务。定时 QA 和选定的发布检查通过共享实时适配器运行从目录派生的 Matrix 选择。发布传输检查使用 mock-openai/gpt-5.6-luna,以保持确定性并避免常规提供方插件启动。这些实时传输网关禁用记忆搜索;记忆行为仍由 QA 对等性测试套件覆盖。

完整发布的实时媒体分片使用 ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04,该镜像已包含 ffmpeg 和 ffprobe。Docker 实时模型/后端分片使用共享的 ghcr.io/openclaw/openclaw-live-test:<sha> 镜像,该镜像为每个选定提交构建一次,然后通过 OPENCLAW_SKIP_DOCKER_BUILD=1 拉取,而不是在每个分片内重新构建。

  • pnpm openclaw qa suite
  • 直接在宿主机上运行仓库支持的 QA 场景。
  • 为所选场景集写入顶层 qa-evidence.json、qa-suite-summary.json 和 qa-suite-report.md 工件,包括混合流程、Vitest 和 Playwright 场景选择。
  • 当通过 pnpm openclaw qa run --qa-profile <profile> 调度时,会在同一个 qa-evidence.json 中嵌入所选分类法配置文件记分卡。smoke-ci 写入精简证据(evidenceMode: "slim",不包含逐条 execution)。release 覆盖精选的发布就绪切片;all 选择所有活跃的成熟度类别,并在需要完整记分卡工件时针对显式 QA Profile Evidence 工作流调度。
  • 默认使用隔离的网关工作器并行运行多个所选场景。qa-channel 默认并发数为 4(受所选场景数量限制)。使用 --concurrency <count> 调整工作器数量,或使用 --concurrency 1 启用旧的串行通道。每个工作器拥有稳定的命名配置文件以及独立的 home、state 和 config 路径,因此其 CLI 引导程序无法选择操作员已安装的 Gateway 服务。父级配置文件和运行时环境补丁不会覆盖该工作器身份。子临时文件和默认编译缓存保留在工作器的临时根目录中,并在其进程停止后被移除。父临时路径和运行时环境补丁不会重定向此临时存储。OPENCLAW_QA_KEEP_TEMP=1 保留该根目录用于调试。如果控制器终止,当前 Gateway 的父级看门狗会退出,而不会删除后代进程可能仍在使用的运行时文件。幸存的属主或宿主机维护人员必须先确认这些写入进程已停止,然后才能移除保留的根目录。
  • 当任何场景失败时以非零状态退出。使用 --allow-failures 可在不产生失败退出码的情况下生成工件。
  • 支持提供方模式 live-frontier、mock-openai 和 aimock。aimock 启动一个由 AIMock 支持的本地提供方服务器,用于实验性夹具和协议模拟覆盖,而不会取代场景感知的 mock-openai 通道。
  • pnpm openclaw qa coverage --match <query>
  • 搜索场景 ID、标题、界面(surface)、覆盖 ID、文档引用、代码引用、插件和提供方要求,然后打印匹配的套件目标。
  • 在运行 QA Lab 之前,当你已知受影响的 behavior 或文件路径但不确定最小的场景时,请使用此命令。仅供建议参考——仍然要根据被更改的行为选择 mock、live、Multipass、Matrix 或 transport 证明。
  • pnpm test:plugins:kitchen-sink-live
  • 通过 QA Lab 运行实时 OpenAI Kitchen Sink 插件严苛测试。安装外部 Kitchen Sink 包,验证插件 SDK 界面清单,检查 /healthz 和 /readyz,记录网关 CPU/RSS 证据,运行一次实时 OpenAI 对话,并检查对抗性诊断。需要实时 OpenAI 认证,例如 OPENAI_API_KEY。在已初始化的 Testbox 会话中,当存在 openclaw-testbox-env 辅助工具时,它会自动加载 Testbox 实时认证配置文件。
  • pnpm test:gateway:cpu-scenarios
  • 运行网关启动基准测试以及一个小型 mock QA Lab 场景包(channel-chat-baseline、memory-failure-fallback、gateway-restart-inflight-run),并在 .artifacts/gateway-cpu-scenarios/ 下写入合并的 CPU 观测摘要。
  • 默认仅标记持续的高 CPU 观测(--cpu-core-warn,默认 0.9;--hot-wall-warn-ms,默认 30000),因此短暂的启动突发会作为指标记录,而不会看起来像持续数分钟的网关占用回归。
  • 针对构建后的 dist 工件运行;如果检出目录中尚无最新的运行时输出,请先运行构建。
  • pnpm openclaw qa suite --runner multipass
  • 在一次性 Multipass Linux 虚拟机中运行相同的 QA 套件,保持与 qa suite 相同的场景选择和提供方/模型标志。
  • 实时运行会转发适用于 guest 的 QA 认证输入:基于环境变量的提供方密钥、QA 实时提供方配置路径,以及 CODEX_HOME(如果存在)。
  • 输出目录必须保持在仓库根目录下,以便 guest 可以通过挂载的工作区写回。
  • 在 .artifacts/qa-e2e/... 下写入正常的 QA 报告 + 摘要以及 Multipass 日志。
  • pnpm qa:lab:up
  • 启动 Docker 支持的 QA 站点,用于操作员风格的 QA 工作。
  • pnpm test:docker:npm-onboard-channel-agent
  • 从当前检出目录构建 npm tarball,在 Docker 中全局安装,运行非交互式 OpenAI API 密钥初始化,默认配置 Telegram,验证打包的插件运行时无需启动依赖修复即可加载,运行 doctor,并针对模拟的 OpenAI 端点运行一次本地 agent 对话。
  • 使用 OPENCLAW_NPM_ONBOARD_CHANNEL=discord 可通过 Discord 运行相同的打包安装通道。
  • pnpm test:docker:session-runtime-context
  • 针对嵌入式运行时上下文记录运行确定性的已构建应用 Docker 冒烟测试。验证隐藏的 OpenClaw 运行时上下文以非显示的定制消息形式持久化,而不会泄漏到可见的用户对话中,然后植入一个受影响损坏的会话 JSONL,并验证 openclaw doctor --fix 将其重写为带有备份的活动分支。
  • pnpm test:docker:npm-telegram-live
  • 在 Docker 中安装 OpenClaw 候选包,运行已安装包的初始化,通过已安装的 CLI 配置 Telegram,然后以该已安装包作为被测系统(SUT)Gateway 重用实时 Telegram QA 通道。
  • 受信任的检出目录拥有 QA 测试框架源码、分类法、场景、依赖项和私有 SDK 构建。已安装包仍然是测试中的绝对 CLI、Gateway 和捆绑插件运行时,其 CLI 会写入候选包的持久化认证状态。
  • 默认使用 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta;设置 OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz 或 OPENCLAW_CURRENT_PACKAGE_TGZ 可测试已解析的本地 tarball,而不是从注册表安装。
  • 默认通过 OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20 在 qa-evidence.json 中输出重复 RTT 计时。覆盖 OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES、OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS 或 OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES 可调整运行参数。OPENCLAW_NPM_TELEGRAM_RTT_CHECKS 接受零个或恰好一个规范的 Telegram QA 场景 ID。省略时,正常通道采样 channel-canary;专注于非 RTT 场景的运行保持无检查。显式 RTT 场景会自动包含在场景选择中,因此调用者无需在 OPENCLAW_NPM_TELEGRAM_SCENARIOS 中重复指定。多个 ID 会立即失败,而未知或不适用的 ID 会导致规范场景验证失败。包运行器会将选定的 RTT 场景提升到首位,然后运行其余基于分类法的快速失败发布场景。检查在其最近观察到的对话和线程中继续进行,使用已租用的主要参与者。第一个样本启动一条新消息;后续样本链式生成自己的回复,而不是使用其他场景参与者观察到的回复。仅投递场景使用其观察到的出站路由,不需要额外的目录元数据。
  • 使用与 pnpm openclaw qa telegram 相同的 Convex 租用 Test Server userbot 凭据。设置 OPENCLAW_QA_CONVEX_SITE_URL 以及所选角色的密钥。Docker 包装器默认选择 Convex。
  • 包装器在 Docker 构建/安装工作之前验证宿主机上的 Convex 凭据环境变量。仅在有意调试凭据前设置时才设置 OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1。
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer 仅为此通道覆盖共享的 OPENCLAW_QA_CREDENTIAL_ROLE。未指定角色时,包装器在 CI 中使用 ci,在 CI 之外使用 maintainer。
  • GitHub Actions 将此通道作为手动维护者工作流 NPM Telegram Beta E2E 公开。它不会在合并时运行。该工作流使用 qa-live-shared 环境和 Convex CI 凭据租约。设置其可选的 rtt_scenario 输入以选择重复 RTT 场景,或留空以使用上述默认行为。仅在有意的历史降级或恢复验证时启用 allow_older_binary_destructive_actions;它默认保持为 false。
  • GitHub Actions 还公开了 Package Acceptance,用于针对一个候选包进行并行产品验证。它接受 Git ref、已发布的 npm spec、HTTPS tarball URL 加 SHA-256、可信 URL 策略,或来自另一次运行的 tarball 工件(source=ref|npm|url|trusted-url|artifact),将规范化后的 openclaw-current.tgz 上传为 package-under-test,然后使用 smoke、package、product、full 或 custom 通道配置文件运行现有的 Docker E2E 调度器。设置 telegram_mode=mock-openai 或 live-frontier 可针对同一个 package-under-test 工件运行 Telegram QA 工作流。
  • 对于跨已发布驱动程序更新的旧版 Telegram 话题绑定,选择 suite_profile=telegram、telegram_mode=mock-openai 和单一场景 telegram-published-upgrade-bindings。将 package_spec 作为精确的已发布基线提供,例如 openclaw@2026.9.6,并通过 source=ref 或经过验证的 tarball 工件解析候选包。该场景在租用 Test Server 凭据之前安装基线,让其生成一个绑定线程的子进程接管论坛话题,并针对候选包运行该安装的正常 openclaw update。它检查话题在激活后以及另一次 Gateway 重启后是否路由回父会话,同时子会话保持完整,包括全部三次有序关闭。原始凭据、会话和传输状态保留在容器临时存储中;上传的证据仅包含包标识和脱敏后的结果。
  • 最新 beta 产品验证:
gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai
  • 精确的 tarball URL 验证需要提供摘要,并使用公共 URL 安全策略:
gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package
  • 企业/私有 tarball 镜像使用明确的受信任来源策略:
gh workflow run package-acceptance.yml --ref main \
  -f source=trusted-url \
  -f trusted_source_id=enterprise-artifactory \
  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

source=trusted-url 从受信任的工作流 ref 中读取 .github/package-trusted-sources.json,既不接受 URL 凭据,也不接受通过工作流输入绕过专用网络的方式。如果指定的策略声明了 bearer 认证,请配置固定的 OPENCLAW_TRUSTED_PACKAGE_TOKEN 密钥。

  • 构件验证会从另一个 Actions 运行中下载 tarball 构件:
gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke
  • pnpm test:docker:plugins
  • 在 Docker 中打包并安装当前 OpenClaw 构建,启动配置了 OpenAI 的 Gateway,然后通过编辑配置启用捆绑的渠道/插件。
  • 验证设置发现不会包含未配置的可下载插件,首次配置的 doctor 修复会显式安装每个缺失的可下载插件,并且第二次重启不会运行隐藏的依赖修复。
  • 还会安装一个已知较旧的 npm 基线,在运行 openclaw update --tag <candidate> 之前启用 Telegram,并验证候选版本的更新后 doctor 会清理旧版插件依赖残留,而无需测试框架侧的 postinstall 修复。
  • pnpm test:parallels:npm-update
  • 在多个 Parallels 虚拟机中运行原生打包安装的更新冒烟测试。每个选定的平台首先安装请求的基线包,然后在同一虚拟机中运行已安装的 openclaw update 命令,并验证安装版本、更新状态、网关就绪状态以及一次本地 agent 轮次。
  • 在单台虚拟机上迭代时使用 --platform macos、--platform windows 或 --platform linux。使用 --json 获取摘要构件路径和每个通道的状态。
  • OpenAI 通道默认使用 openai/gpt-5.6-luna 进行实时 agent 轮次验证。传入 --model <provider/model> 或设置 OPENCLAW_PARALLELS_OPENAI_MODEL 来验证其他 OpenAI 模型。
  • 在主机超时内运行较长的本地测试,以免 Parallels 传输停滞消耗剩余测试窗口:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    
  • 脚本会在 /tmp/openclaw-parallels-npm-update.* 下写入嵌套的通道日志。在断定外层包装器挂起之前,请先检查 windows-update.log、macos-update.log 或 linux-update.log。

  • 在冷虚拟机上,Windows 更新可能在更新后 doctor 和包更新工作中花费 10 到 15 分钟;只要嵌套的 npm 调试日志仍在推进,就属于正常情况。
  • 不要将此聚合包装器与单独的 Parallels macOS、Windows 或 Linux 冒烟通道并行运行。它们共享虚拟机状态,可能在快照恢复、包服务或虚拟机网关状态上发生冲突。
  • 更新后的验证运行的是常规的捆绑插件表面,因为即使 agent 轮次本身只检查简单的文本响应,语音、图像生成和媒体理解等功能外观也会通过捆绑的运行时 API 加载。

  • pnpm openclaw qa aimock

  • 仅启动本地 AIMock 提供者服务器,用于直接协议冒烟测试。
  • pnpm openclaw qa buzz
  • 使用专用 driver 和 SUT 身份,针对真实的 relay 房间运行 Buzz 实时 QA 通道。
  • 本地运行使用 --credential-file <path>,包含 relayUrl、roomId、driverPrivateKey 和 sutPrivateKey。封闭的 relay 可能还需要 driverAuthTag 和 sutAuthTag。托管的 relay 要求 wss://;ws:// 仅接受用于回环开发 relay。
  • 默认使用 mock-openai,并通过真实的 Buzz 插件路径运行 canary 和提及门控场景。
  • 支持 --credential-source convex,使用池化的 kind: "buzz" 行。两个公钥都必须是 relay/room 成员,并且 SUT 必须具有 Bot 房间角色。切勿使用人类所有者或管理员私钥。
  • pnpm openclaw qa matrix
  • 针对一次性的 Docker 后端 Tuwunel homeserver 运行 Matrix 实时 QA 通道。仅限源码检出 - 打包安装不附带 qa-lab。
  • 完整的 CLI、配置/场景目录、环境变量和构件布局:Matrix 冒烟通道。
  • pnpm openclaw qa telegram
  • 在 Telegram 的 Test Server 上运行 Telegram 实时 QA 通道,使用一个 Convex 租用的 SUT 机器人和一个独立的 TDLib 用户会话。
  • 默认使用 --credential-source convex,并拒绝 env。请提供 OPENCLAW_QA_CONVEX_SITE_URL 和所选 --credential-role 的密钥。
  • 默认场景涵盖 canary、提及门控、命令寻址、/status、机器人间提及回复以及核心原生命令回复。mock-openai 默认值还涵盖确定性回复链和 Telegram 最终消息流式传输回归。使用 --list-scenarios 查看 session_status 等可选检查。
  • 当任何场景失败时以非零退出码退出。使用 --allow-failures 可在不返回失败退出码的情况下生成构件。
  • 租用的用户驱动并观察共享的 Test Server 群组。不使用生产环境的 Telegram 账户或机器人间观察者。
  • 在 .artifacts/qa-e2e/... 下写入 Telegram QA 报告、摘要和 qa-evidence.json。回复场景包含从 driver 发送请求到观察到 SUT 回复的 RTT。

实时传输通道共享同一标准契约,因此新传输不会漂移;各通道的覆盖矩阵位于 QA 概览 - 实时传输覆盖。 qa-channel 是广泛的合成测试套件,不属于该矩阵。

通过 Convex 共享 Telegram 凭据(v1)

当为实时传输 QA 启用 --credential-source convex(或 OPENCLAW_QA_CREDENTIAL_SOURCE=convex)时,QA 实验室会从由 Convex 支持的凭据池中获取一个独占租约,在通道运行期间对该租约发送心跳,并在关闭时释放租约。Telegram 始终使用该来源。本节名称早于 Buzz、Discord、Slack 和 WhatsApp 支持;租约契约在所有类型之间共享。

Convex 项目脚手架参考:qa/convex-credential-broker/

必需的环境变量:

  • OPENCLAW_QA_CONVEX_SITE_URL(例如 https://your-deployment.convex.site)
  • 所选角色的一个密钥:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER 用于 maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI 用于 ci
  • 凭据角色选择:
  • CLI:--credential-role maintainer|ci
  • 环境变量默认值:OPENCLAW_QA_CREDENTIAL_ROLE(在 CI 中默认为 ci,否则为 maintainer)

可选环境变量:

  • OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS(默认 1200000)
  • OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS(默认 30000)
  • 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(可选 trace id)
  • OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 允许仅用于本地开发的回环 http:// Convex URL。

正常运行时,OPENCLAW_QA_CONVEX_SITE_URL 应使用 https://。

维护者管理命令(pool add/remove/list)特别要求 OPENCLAW_QA_CONVEX_SECRET_MAINTAINER。

维护者 CLI 辅助命令:

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

在实时运行前使用 doctor 检查 Convex 站点 URL、broker 密钥、端点前缀、HTTP 超时以及 admin/list 可达性,且不打印密钥值。在脚本和 CI 工具中使用 --json 获取机器可读输出。

默认端点契约(OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1)。 请求使用 Authorization: Bearer <role secret> 请求头进行身份验证;以下请求体省略该请求头:

  • POST /acquire
  • 请求:{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • 成功:{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • 已耗尽/可重试:{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
  • POST /payload-chunk
  • 请求:{ kind, ownerId, actorRole, credentialId, leaseToken, index }
  • 成功:{ status: "ok", index, data }
  • POST /heartbeat
  • 请求:{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • 成功:{ status: "ok" }(或空 2xx)
  • POST /release
  • 请求:{ kind, ownerId, actorRole, credentialId, leaseToken }
  • 成功:{ status: "ok" }(或空 2xx)
  • POST /admin/add(仅维护者密钥)
  • 请求:{ kind, actorId, payload, note?, status? }
  • 成功:{ status: "ok", credential }
  • POST /admin/remove(仅维护者密钥)
  • 请求:{ credentialId, actorId }
  • 成功:{ status: "ok", changed, credential }
  • 活动租约保护:{ status: "error", code: "LEASE_ACTIVE", ... }
  • POST /admin/list(仅维护者密钥)
  • 请求:{ kind?, status?, includePayload?, limit? }
  • 成功:{ status: "ok", credentials, count }

Telegram 类型的 payload 结构:

  • { groupId: string, driverToken: string, sutToken: string }
  • groupId 必须是数字形式的 Telegram 聊天 id 字符串。
  • admin/add 会为 kind: "telegram" 验证该结构,并拒绝格式错误的 payload。

由 broker 验证的多通道 payload:

  • Buzz:{ relayUrl: string, roomId: string, driverPrivateKey: string, sutPrivateKey: string, driverAuthTag?: string, sutAuthTag?: string }
  • Discord:{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
  • WhatsApp:{ driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Slack 通道也可以从池中获取租约,但 Slack payload 验证目前位于 Slack QA 运行器中,而不是 broker 中。对于 Slack 行,请使用 { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }。

向 QA 添加通道

新通道适配器的架构和场景辅助函数名称位于 QA 概览 - 添加通道。 最低要求:在共享的 qa-lab 宿主接缝上实现传输运行器,为共享场景添加 adapterFactory,在插件清单中声明 qaRunners,以 openclaw qa <runner> 挂载,并在 qa/scenarios/ 下编写场景。

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