OpenClaw QA测试

OpenClaw QA测试 是做什么的？

使用此技能进行 qa-lab / qa-channel 相关工作。仅限本地仓库QA。

前置阅读

• docs/concepts/qa-e2e-automation.md
• docs/help/testing.md
• docs/channels/qa-channel.md
• qa/README.md
• qa/scenarios/index.yaml
• extensions/qa-lab/src/suite.ts
• extensions/qa-lab/src/character-eval.ts

模型策略

• 普通的实时套件运行依赖 QA Lab 的源和认证感知默认值。
• 默认不传递 --model、--alt-model 或 --fast。省略 --fast 不意味着 fast 被禁用；fast 行为由源码方控制。
• 对于特定场景的运行，完整的 execution.summary 是权威的，并覆盖通用默认指导，包括当其需要其他标志时。仅在 execution.config.requiredProvider 或 requiredModel 要求时，才添加显式的提供者/模型固定。

默认工作流

1. 读取场景包和当前套件实现。
2. 决定通道：
   • mock/dev: mock-openai
   • 真实验证: live-frontier
3. 对于普通实时套件，使用：

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --output-dir .artifacts/qa-e2e/run-all-live-frontier-<tag>

4. 监控输出：
   • 摘要: .artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-summary.json
   • 报告: .artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-report.md
5. 如果用户想监控实时 UI，查找当前 openclaw-qa 监听端口并报告 http://127.0.0.1:<port>。
6. 如果场景失败，修复产品或测试框架的根本原因，然后重新运行整个通道。

OTEL 烟雾测试

对于本地 QA-lab 的 OpenTelemetry 验证，使用：

pnpm qa:otel:smoke

这会启动一个本地 OTLP/HTTP 跟踪接收器，通过 qa-channel 运行 otel-trace-smoke 场景，解码发出的 protobuf 跨度，并验证导出的跟踪名称和隐私契约。它不需要 Opik、Langfuse 或外部收集器凭证。

QA 凭证和 1Password

• 在此仓库中，仅在 tmux 内部使用 op 进行 QA 密钥查找。
• 在 tmux 内快速认证检查：

op account list

• 直接的 Telegram npm 实时测试密钥当前存储在 1Password 项目中：
  • 保险库: OpenClaw
  • 项目: Telegram E2E
• 该项目是查找以下内容的第一位置：
  • OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN
  • OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN
  • OPENCLAW_QA_PROVIDER_MODE
  • OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC
• Convex QA 密钥当前存储在 1Password 项目中：
  • 保险库: OpenClaw
  • 项目: OPENCLAW_QA_CONVEX_SITE_URL
  • 项目: OPENCLAW_QA_CONVEX_SECRET_MAINTAINER
  • 项目: OPENCLAW_QA_CONVEX_SECRET_CI
• QA 凭证工作中看到的其他相关备注/登录项目：
  • 保险库: Private
  • 项目: OPENCLAW QA、Convex、Telegram
• 如果所需值在这些备注中缺失：
  • 不要猜测
  • 向维护者/操作员询问当前值或当前的 1Password 项目名称
  • 对于 Telegram 直接运行，OPENCLAW_QA_TELEGRAM_GROUP_ID 可能独立存储在 Telegram E2E 之外
  • 对于 Convex 运行，租赁的 Telegram 凭证应同时提供 Telegram 组 ID 和机器人令牌；不需要单独的 OPENCLAW_QA_TELEGRAM_GROUP_ID
  • 对于 Convex 运行，优先使用 OpenClaw/OPENCLAW_QA_CONVEX_SITE_URL；如果该值已过期或不明确，请在运行前询问活动池 URL
• 当可用时，对于 npm Telegram Docker 通道，优先使用直接的 Telegram 环境变量：

OPENCLAW_QA_TELEGRAM_GROUP_ID="..." \
OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN="..." \
OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN="..." \
OPENCLAW_QA_PROVIDER_MODE="mock-openai" \
OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC="openclaw@beta" \
pnpm test:docker:npm-telegram-live

• 当目标是稳定的共享 QA 基础设施时，优先使用 Convex 模式：
  • 轮询凭证租赁
  • 更薄的包装器用于特定通道设置
  • 围绕池化凭证的 CLI/管理员流程
• 实时 npm Telegram Docker 通道说明：
  • scripts/e2e/npm-telegram-live-runner.ts 读取 OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE
  • 不要假设 OPENCLAW_QA_PROVIDER_MODE 被该包装器使用
  • 如果 1Password 备注仅提供了 OPENCLAW_QA_PROVIDER_MODE，请在运行 Docker 通道之前明确将其映射到 OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE
• 验证过的实时形态：
  • Convex 模式可以在没有直接 Telegram 环境变量的情况下通过真正的 Docker 通道
  • 租赁的 Telegram 负载包括与驱动程序/SUT 令牌配对的组 ID
  • pnpm test:docker:npm-telegram-live 的真实运行使用以下内容通过：
    • OPENCLAW_QA_CREDENTIAL_SOURCE=convex
    • OPENCLAW_QA_CREDENTIAL_ROLE=maintainer
    • OPENCLAW_QA_CONVEX_SITE_URL
    • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER
    • OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE=mock-openai
• 如果本地缺少直接 Telegram 环境变量并且 op signin 阻塞，优先调度手动 GitHub 通道，因为 qa-live-shared 环境已经拥有 Convex CI 凭证：

gh workflow run "NPM Telegram Beta E2E" --repo openclaw/openclaw --ref main \
  -f [email protected] \
  -f [email protected] \
  -f provider_mode=mock-openai

• 从调度 URL 轮询确切的运行 ID。gh run view --json artifacts 不受支持；使用以下命令列出产物：

gh api repos/openclaw/openclaw/actions/runs/<run-id>/artifacts

WhatsApp 实时凭证

在设置或替换 Convex kind=whatsapp 凭证时使用此部分。

• 将 WhatsApp QA 凭证视为操作员拥有的实时账户，而非生成的固定装置。
• 使用两个专用的支持 WhatsApp 的测试号码：一个驱动程序账户和一个 SUT 账户。不要使用个人号码或个人 OpenClaw WhatsApp 账户进入共享池。
• 手动在 WhatsApp 或 WhatsApp Business 上注册并关联每个账户，仅将 Web 认证存储在仓库外的隔离本地认证目录中。
• 对于群组覆盖，创建一个包含两个 QA 账户的专用测试群组，并将其 JID 存储为 groupJid；否则，集团提及门控场景应默认跳过，并在明确请求时失败。
• 将两个 Baileys 认证目录打包为 base64 .tgz 负载字段，并添加一个新的活动 Convex 凭证行。优先添加新行并禁用过时/损坏的行，而不是原地覆盖凭证。
• 预期的负载字段：driverPhoneE164、sutPhoneE164、driverAuthArchiveBase64、sutAuthArchiveBase64 和可选的 groupJid。
• 将凭证材料保留在仓库、日志、PR 和屏幕截图之外。除非操作员明确要求本地调试，否则编辑电话号码。
• 使用 pnpm openclaw qa whatsapp --credential-source convex --credential-role maintainer --provider-mode mock-openai 进行验证，并保留产物路径以及编辑过的通过/失败摘要。
• 如果 WhatsApp 使关联的 Web 会话过期或失效，则在本地重新链接，打包新的认证档案，添加一个新的 Convex 行，然后禁用过期行。

角色评估

使用 qa character-eval 跨多个实时模型进行风格/角色/氛围检查。

pnpm openclaw qa character-eval \
  --output-dir .artifacts/qa-e2e/character-eval-<tag>

• 运行本地 QA 网关子进程，而非 Docker。
• 打包的 pnpm build 有意省略了 QA Lab + qa-channel（仅源码签出）。要从构建的发行版中运行 openclaw qa/qa-channel，请使用 OPENCLAW_BUILD_PRIVATE_QA=1 pnpm build 构建（输出 dist/plugin-sdk/qa-lab.js、qa-runtime.js、dist/extensions/{qa-lab,qa-channel}）或通过 pnpm dev 运行。
• 没有模型标志时，角色评估使用其当前源码定义的候选、评审、思考和快速默认值。
• 仅替换显式对应的清单时，才重复 --model provider/model,thinking=<level>[,fast|,no-fast|,fast=<bool>] 或 --judge-model ...。
• 不要添加带有单独 --model-thinking 的新示例；将该标志保留为仅向后兼容。
• 报告包括评审排名、运行统计信息、持续时间和完整转录；不要包含原始评审回复。持续时间是基准上下文，而非评分信号。
• 候选和评审并发度默认为 16。当本地网关或提供者限制需要更温和的通道时，使用 --concurrency <n> 和 --judge-concurrency <n> 进行覆盖。
• 场景源仅为 qa/scenarios/ 下的 YAML 文件：使用 index.yaml 和每个场景的 *.yaml 文件，其中包含顶级的 title、scenario 和可选的 flow。切勿添加围栏式的 qa-scenario / qa-flow Markdown 文件。
• 对于隔离的角色/风格评估，将角色写入 SOUL.md，并在场景流程中清空 IDENTITY.md。仅在有意测试正常 OpenClaw 身份与角色的组合时，才使用 SOUL.md + IDENTITY.md。
• 保持提示自然且以任务为形状。候选模型应通过 SOUL.md 接收角色设置，然后接收正常的用户交互，例如聊天、工作空间帮助和小文件任务；不要问“你会如何反应？”或告诉模型它在评估中。
• 优先至少一个真实任务，例如创建或编辑一个微小的工作区产物，以便转录捕获角色在正常工具使用下的行为，而不是纯粹的角色扮演。

Codex CLI 模型通道

每当 QA 应将 Codex 作为模型后端进行测试时，使用形如 codex-cli/<codex-model> 的模型引用。

示例：

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --model codex-cli/<codex-model> \
  --alt-model codex-cli/<codex-model> \
  --scenario <scenario-id> \
  --output-dir .artifacts/qa-e2e/codex-<tag>

pnpm openclaw qa manual \
  --model codex-cli/<codex-model> \
  --message "Reply exactly: CODEX_OK"

• 将具体的 Codex 模型名称视为用户/配置输入；不要将其硬编码在源码、文档示例或场景中。
• 实时 QA 会保留 CODEX_HOME，以便 Codex CLI 认证/配置在工作，同时将 HOME 和 OPENCLAW_HOME 沙箱化。
• Mock QA 应擦除 CODEX_HOME。
• 如果 Codex 每轮都返回回退/认证文本，请首先检查 CODEX_HOME、相关的秘密支持认证和网关子日志，然后再更改场景断言。
• 对于模型比较，将 codex-cli/<codex-model> 作为另一个候选包含在 qa character-eval 中；报告应将其标记为不透明模型名称。

仓库事实

• 种子场景位于 qa/scenarios/index.yaml 和 qa/scenarios/<theme>/*.yaml。
• 主要实时运行器: extensions/qa-lab/src/suite.ts
• QA 实验室服务器: extensions/qa-lab/src/lab-server.ts
• 子网关工具包: extensions/qa-lab/src/gateway-child.ts
• 合成通道: extensions/qa-channel/

“完成”的样子

• 请求通道的完整测试套件为绿色。
• 用户获得：
  • 监控 URL（如果适用）
  • 通过/失败计数
  • 产物路径
  • 关于修复内容的简洁说明

常见失败模式

• 实时超时过短：
  • 在 extensions/qa-lab/src/suite.ts 中加宽实时等待时间
• 发现无法找到仓库文件：
  • 在已播种的工作空间中将提示指向 repo/...
• 子代理证据过于脆弱：
  • 优先使用稳定的最终回复证据，而非临时的子会话列表
• 测试框架“重建”延迟：
  • 脏树可能会触发运行前构建；在端口出现之前预期此情况

添加场景时

• 在 qa/scenarios/ 下添加或更新场景 YAML；不要添加 .md 场景文件或围栏式 YAML 块。
• 保持 qa/scenarios/index.yaml 中的启动期望一致
• 在 extensions/qa-lab/src/suite.ts 中添加可执行覆盖
• 优先使用端到端断言而非仅 mock 检查
• 将输出保存在 .artifacts/qa-e2e/ 下