OpenClaw QA 栈提供比单元测试更接近真实渠道的端到端测试能力，支持合成渠道（qa-channel）和实时传输通道（Telegram/Discord/Slack/Matrix）。通过 pnpm openclaw qa 系列命令运行；qa:lab:up 启动双面板 QA 站点（左侧网关控制台 + 右侧 QA Lab）。实时通道需配置对应环境变量或使用 Convex 共享凭证池；各通道场景覆盖提及限流、机器人对机器人、顶回复、线程隔离等行为。

OpenClaw QA 端到端测试：命令、操作与多渠道配置 #

概述 #

OpenClaw 的私有 QA 栈以比单元测试更接近真实渠道的方式验证智能体行为。当前模块包括：

• extensions/qa-channel：合成消息通道，覆盖 DM、群聊、线程、表情回复、编辑和删除。
• extensions/qa-lab：调试 UI 和 QA 总线，用于观察对话记录、注入入站消息、导出 Markdown 报告。
• extensions/qa-matrix（未来运行插件）：实时传输适配器，在子 QA 网关中驱动真实 Matrix 渠道。
• qa/：Git 仓库内的种子资产，包括启动任务和基线 QA 场景。
• Mantis：真实传输层的回归验证，支持浏览器截图、VM 状态和 PR 证据。

命令参考 #

所有 QA 流程通过 pnpm openclaw qa <子命令> 执行。多数命令也有 pnpm qa:* 快捷别名。

操作流程：启动双面板 QA 站点 #

当前的 QA 操作员流程使用双面板 QA 站点：

• 左侧：网关控制台（Control UI），与智能体交互。
• 右侧：QA Lab，展示类 Slack 对话记录和场景计划。

启动方式：

pnpm qa:lab:up

该命令会构建 QA 站点、启动 Docker 后端网关通道，并暴露 QA Lab 页面。操作员或自动化循环可在左侧给智能体下达 QA 任务，在右侧观察真实渠道行为，并记录哪些通过、哪些失败、哪些卡住。

如果需要更快的 QA Lab UI 迭代（不重复构建 Docker 镜像），可以：

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

qa:lab:up:fast 使用预制镜像并 bind-mount 本地 extensions/qa-lab/web/dist。qa:lab:watch 在文件变化时自动重建，浏览器自动重载。

OpenTelemetry 链路追踪烟雾测试 #

pnpm qa:otel:smoke

启动本地 OTLP/HTTP trace 接收器，运行 otel-trace-smoke 场景（启用 diagnostics-otel 插件），解码 protobuf span 并断言关键 span 存在：openclaw.run、openclaw.harness.run、openclaw.model.call、openclaw.context.assembled、openclaw.message.delivery。模型调用中成功的轮次不应出现 StreamAbandoned；原始诊断 ID 和 openclaw.content.* 属性不得出现在 trace 中。输出 otel-smoke-summary.json 到 QA 产物目录。

可观测性 QA 仅限源码检出。npm tarball 有意省略 QA Lab，因此打包发布的不执行 qa 命令。变更诊断插桩后，应从源码检出的目录执行 pnpm qa:otel:smoke。

Matrix 实时传输烟雾测试 #

pnpm openclaw qa matrix --profile fast --fail-fast

完整 CLI 参考、profile/场景目录、环境变量和产物布局见 Matrix QA。简要过程：在 Docker 中启动一次性 Tuwunel homeserver，注册临时 driver/SUT/observer 用户，在子 QA 网关中运行真实 Matrix 插件（不含 qa-channel），输出 Markdown 报告、JSON 摘要、观测事件产物和合并日志到 .artifacts/qa-e2e/matrix-<timestamp>/。

Mantis 完整桌面 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 产物目录。--hydrate-mode source（默认）从源码检出验证并执行安装/构建；--hydrate-mode prehydrated 仅在已存在 node_modules 和 dist/ 时跳过安装，否则失败。--gateway-setup 会在 VM 内持久运行 OpenClaw Slack 网关（端口 38973），否则命令仅执行 bot 对 bot 的 Slack QA 通道然后退出。

Mantis 视觉桌面任务 #

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

租用或复用 Crabbox 桌面/浏览器机器，通过 visual-driver 驱动浏览器，截图，运行 openclaw infer image describe（当 --vision-mode image-describe 时），输出 visual-task.mp4、mantis-visual-task-summary.json 等。--expect-text 让视觉提示要求结构化 JSON 判词，仅当模型报告正面可见证据才算通过。若 Crabbox 没有生成非空视频文件，任务失败。

使用前检查共享凭据 #

pnpm openclaw qa credentials doctor

检查 Convex broker 环境变量、验证端点设置，并在拥有维护者密钥时验证 admin 列表的可达性。

实时传输通道测试覆盖 #

实时传输通道共同遵守同一份合同（见下表），取代各自定义场景列表。qa-channel 是广义的合成产品行为套件，不包含在此矩阵中。

对于不会将 Docker 引入 QA 路径的场景，可使用 Multipass 运行：

pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

启动全新 Multipass 虚拟机，安装依赖，在虚拟机内构建 OpenClaw，运行 qa suite，将报告和摘要复制回宿主机的 .artifacts/qa-e2e/...。默认并行执行场景（并发数 4），可通过 --concurrency <count> 调整，--concurrency 1 串行执行。--pack personal-agent 运行个人助手基准包。--allow-failures 允许失败时不退出非零。

Telegram QA #

pnpm openclaw qa telegram

针对一个真实的私有 Telegram 群组，使用两个不同的 bot（driver 和 SUT）。SUT bot 必须有 Telegram 用户名；建议在 @BotFather 中为两个 bot 启用 Bot-to-Bot Communication Mode。

当 --credential-source env 时需要以下环境变量：

• OPENCLAW_QA_TELEGRAM_GROUP_ID（数字格式的 chat id）
• OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN
• OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN

可选：

• OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1：保留消息体到观测产物中（默认会打码）。

场景文件位于 extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts，包含 telegram-canary、telegram-mention-gating 等共 16 个。默认集合始终覆盖 canary、提及限流、原生命令回复、命令寻址和 bot-to-bot 群回复。mock-openai 模式下还包括确定性回复链和最终消息流检查。telegram-current-session-status-tool 为 opt-in，仅在 canary 后线程化稳定。

产物：

• telegram-qa-report.md
• telegram-qa-summary.json（含从 canary 开始的每回复 RTT）
• telegram-qa-observed-messages.json（除非 OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1，否则消息体打码）

RTT 包比较 #

pnpm rtt openclaw@beta \
  --credential-source convex \
  --credential-role maintainer \
  --samples 20 \
  --sample-timeout-ms 30000

当 --credential-source convex 时，RTT Docker 封装会租用 kind: "telegram" 凭据，导出租用的群/driver/SUT bot 环境变量到安装包的运行中，心跳维持，并在关闭时释放。--samples 和 --sample-timeout-ms 分别控制 OPENCLAW_NPM_TELEGRAM_WARM_SAMPLES 和 OPENCLAW_NPM_TELEGRAM_SAMPLE_TIMEOUT_MS。

Discord QA #

pnpm openclaw qa discord

针对一个真实的私有 Discord 公会频道，使用两个 bot：由 harness 控制的 driver bot，以及由子 OpenClaw 网关通过捆绑的 Discord 插件启动的 SUT bot。验证频道提及处理、SUT bot 是否注册了原生 /help 命令，以及 opt-in 的 Mantis 证据场景。

当 --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 返回的 bot 用户 ID 一致，否则快速失败）

可选：

• OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1
• OPENCLAW_QA_DISCORD_VOICE_CHANNEL_ID（指定语音/频道用于 discord-voice-autojoin；未设置时自动选择第一个可见频道）

场景文件位于 extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36，包括 discord-canary、discord-mention-gating、discord-native-help-command-registration、discord-voice-autojoin（opt-in）、discord-status-reactions-tool-only（opt-in Mantis 场景）。

运行语音加入场景示例：

pnpm openclaw qa discord \
  --scenario discord-voice-autojoin \
  --provider-mode mock-openai

运行 Mantis 状态反应场景示例：

pnpm openclaw qa discord \
  --scenario discord-status-reactions-tool-only \
  --provider-mode live-frontier \
  --model openai/gpt-5.5 \
  --alt-model openai/gpt-5.5 \
  --fast

产物：

• discord-qa-report.md
• discord-qa-summary.json
• discord-qa-observed-messages.json（消息体打码除非 OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1）
• discord-qa-reaction-timelines.json 和 discord-status-reactions-tool-only-timeline.png（当运行状态反应场景时）

Slack QA #

pnpm openclaw qa slack

针对一个真实的私有 Slack 频道，使用两个不同的 bot：driver bot（由 harness 控制）和 SUT bot（由捆绑的 Slack 插件启动）。

当 --credential-source env 时需要：

• OPENCLAW_QA_SLACK_CHANNEL_ID
• OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_APP_TOKEN

可选：

• OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1

场景文件位于 extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39，包括 slack-canary、slack-mention-gating、slack-allowlist-block、slack-top-level-reply-shape、slack-restart-resume、slack-thread-follow-up、slack-thread-isolation。

产物：

• slack-qa-report.md
• slack-qa-summary.json
• slack-qa-observed-messages.json（消息体打码除非 OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1）

设置 Slack 工作区 #

该通道需要两个不同的 Slack 应用在同一工作区，以及一个两个 bot 都已加入的频道。

1. 创建 Driver 应用

前往 api.slack.com/apps → Create New App → From a manifest → 选择 QA 工作区，粘贴以下配置，然后 Install to Workspace：

{
  "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。Driver 只需发送消息和识别自身，不需要事件或 Socket Mode。

2. 创建 SUT 应用

再次执行 Create New App → From a manifest，粘贴以下（比捆绑插件精简，不含表情反应相关权限和事件——因为实时 Slack QA 套件尚未覆盖反应处理）：

{
  "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",
        "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"
      ]
    }
  }
}

创建后执行两步：

• Install to Workspace → 复制 Bot User OAuth Token → 成为 sutBotToken。
• Basic Information → App-Level Tokens → Generate Token and Scopes → 添加 scope connections:write → 保存 → 复制 xapp-... 值 → 成为 sutAppToken。

验证两个 bot 的用户 ID 不同：对每个 token 调用 auth.test。如果复用同一个应用，提及限流会立即失败。

3. 创建频道

在 QA 工作区创建一个频道（如 #openclaw-qa），邀请两个 bot：

/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT

从频道信息 → About → Channel ID 复制 Cxxxxxxxxxx，这就是 channelId。公开频道即可；若使用私有频道，两个应用都已具备 groups:history 权限。

4. 注册凭据

两种方式：

• 本地调试：设置四个 OPENCLAW_QA_SLACK_* 环境变量，传递 --credential-source env。
• 共享 Convex 凭据池：将四个字段写成 JSON 文件，然后使用 qa credentials add 添加。

示例 JSON：

{
  "channelId": "Cxxxxxxxxxx",
  "driverBotToken": "xoxb-...",
  "sutBotToken": "xoxb-...",
  "sutAppToken": "xapp-..."
}

注册命令：

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. 端到端验证

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 状态为 pass。若挂起约 90 秒并退出 Convex credential pool exhausted for kind "slack"，说明池为空或所有行已被租用——运行 qa credentials list --kind slack --status all --json 查看。

Convex 凭据池 #

Telegram、Discord、Slack 和 WhatsApp 通道可以从共享 Convex 凭据池中租用凭据，而无需读取环境变量。传递 --credential-source convex（或设置 OPENCLAW_QA_CREDENTIAL_SOURCE=convex），QA Lab 将获取排他租约，在运行期间心跳维持，并在关闭时释放。池的 kind 包括 "telegram"、"discord"、"slack" 和 "whatsapp"。

broker 验证的 payload 形状：

• Telegram（kind: "telegram"）：{ groupId: string, driverToken: string, sutToken: string }，groupId 必须是数字 chat-id 字符串。
• Telegram 真实用户（kind: "telegram-user"）：仅用于 Mantis Telegram Desktop 证明，包含多个字段（如 testerUserId、telegramApiId 等）。通用 QA Lab 通道不得获取此 kind。
• Discord（kind: "discord"）：{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }。
• WhatsApp（kind: "whatsapp"）：{ driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }。
• Slack（kind: "slack"）：{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }，通道 ID 格式如 Cxxxxxxxxxx。

操作环境变量和 Convex broker 端点约定见 Testing → Shared Telegram credentials via Convex。

Repo 内置种子场景 #

种子资源存放在 qa/ 目录：

• qa/scenarios/index.md
• qa/scenarios/<theme>/*.md

计划放入 Git，让人类和智能体都能看到。每个场景 Markdown 文件定义：

• 场景元数据
• 可选的分类、能力、通道和风险元数据
• 文档和代码引用
• 可选的插件要求
• 可选的网关配置补丁
• 可执行的 qa-flow

可重用的运行时表面保持通用和跨领域。场景 ID 在文件移动时应保持稳定；使用 docsRefs 和 codeRefs 实现可追溯性。

基线列表应覆盖：DM 和频道聊天、线程行为、消息动作生命周期、Cron 回调、Memory 回忆、模型切换、子智能体交接、仓库和文档阅读、小型构建任务（如 Lobster Invaders）。

Provider 模拟通道 #

qa suite 有两个本地 provider 模拟通道：

• mock-openai：场景感知的 OpenClaw 模拟，作为确定性默认通道。
• aimock：启动 AIMock 支持的 provider 服务器，用于试验性协议、fixture、录制/回放和混沌覆盖。

Provider 通道实现位于 extensions/qa-lab/src/providers/。每个 provider 拥有其默认值、本地服务器启动、网关模型配置、认证 profile 登台需求和实时/模拟能力标志。

传输适配器扩展机制 #

qa-lab 拥有一套通用的传输 seam，供 Markdown QA 场景使用。qa-channel 是第一个适配器。架构层面：

• qa-lab 负责通用场景执行、worker 并发、产物写入和报告生成。
• 传输适配器负责网关配置、就绪检查、入站和出站观测、传输动作和标准化传输状态。
• Markdown 场景文件定义测试运行；qa-lab 提供可重用的运行时表面。

添加新通道 #

向 Markdown QA 系统添加通道需要两个步骤：

1. 实现该通道的传输适配器。
2. 编写覆盖通道合同的场景包。

不要新增顶层 QA 命令根；使用共享的 qa-lab 宿主。新通道的最小采纳标准：

• 保持 qa-lab 作为共享 qa 根的所有者。
• 在共享 qa-lab 宿主 seam 上实现传输运行者。
• 将传输特定机制保留在运行者插件或通道 harness 内。
• 将运行者挂载为 openclaw qa <runner>。运行者插件应在 openclaw.plugin.json 中声明 qaRunners，并从 runtime-api.ts 导出对应的 qaRunnerCliRegistrations。
• 编写或适配 Markdown 场景到 qa/scenarios/ 分类目录。
• 新场景使用通用助手函数。

决策规则：如果行为可在 qa-lab 中表达一次，则放入 qa-lab；如果行为依赖于某个通道传输，则保留在运行者插件中；如果场景需要多个通道可用的新能力，则添加通用助手。

场景助手命名 #

新场景推荐使用的通用助手：

• waitForTransportReady
• waitForChannelReady
• injectInboundMessage
• injectOutboundMessage
• waitForTransportOutboundMessage
• waitForChannelOutboundMessage
• waitForNoTransportOutbound
• getTransportSnapshot
• readTransportMessage
• readTransportTranscript
• formatTransportTranscript
• resetTransport

现有场景的兼容别名（如 waitForQaChannelReady、waitForOutboundMessage）仍然可用，但新场景应使用通用名称。

测试报告 #

qa-lab 从观测到的总线时间线导出 Markdown 协议报告，回答四个问题：

• 什么通过了
• 什么失败了
• 什么卡住了
• 值得补充哪些后续场景

查看可用场景清单：pnpm openclaw qa coverage（加 --json 获取机器可读输出）。

角色评估（Character Eval） #

跨多个实时模型运行相同场景，输出带裁判评分的 Markdown 报告：

pnpm openclaw qa character-eval \
  --model openai/gpt-5.5,thinking=medium,fast \
  --model openai/gpt-5.2,thinking=xhigh \
  --model openai/gpt-5,thinking=xhigh \
  --model anthropic/claude-opus-4-7,thinking=high \
  --model anthropic/claude-sonnet-4-6,thinking=high \
  --model zai/glm-5.1,thinking=high \
  --model moonshot/kimi-k2.5,thinking=high \
  --model google/gemini-3.1-pro-preview,thinking=high \
  --judge-model openai/gpt-5.5,thinking=xhigh,fast \
  --judge-model anthropic/claude-opus-4-7,thinking=high \
  --blind-judge-models \
  --concurrency 16 \
  --judge-concurrency 16

该命令运行本地 QA 网关子进程（非 Docker）。角色评估场景应通过 SOUL.md 设置 persona，然后运行普通用户轮次（聊天、工作区帮助、小文件任务）。候选模型不应被告知正在被评估。命令保留完整对话记录，记录基本运行统计，然后使用 fast 模式、xhigh 推理（支持时）的裁判模型按自然度、氛围和幽默排序。使用 --blind-judge-models 时，裁判提示中候选模型引用被替换为中性标签（如 candidate-01）。候选模型默认使用 high thinking，GPT-5.5 使用 medium，旧版 OpenAI eval 引用使用 xhigh。OpenAI 候选默认启用 fast 模式。裁判模型和候选模型的并发默认均为 16，可通过 --concurrency 和 --judge-concurrency 调整。当未指定 --model 时，默认使用上述 8 个模型；未指定 --judge-model 时默认使用 openai/gpt-5.5,thinking=xhigh,fast 和 anthropic/claude-opus-4-7,thinking=high。

常见问题 #

如何运行 OpenClaw 端到端测试？ #

执行 pnpm openclaw qa suite 运行基于仓库的默认场景套件。启动双面板 QA 站点使用 pnpm qa:lab:up。特定实时通道如 Telegram 执行 pnpm openclaw qa telegram，需先配置对应环境变量或使用 Convex 凭据池。

Telegram QA 需要哪些环境变量？ #

当使用 --credential-source env 时，需设置 OPENCLAW_QA_TELEGRAM_GROUP_ID（数字 chat id）、OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN 和 OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN。可选设置 OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1 保留消息正文。

Slack QA 需要创建几个应用？ #

需要两个独立的 Slack 应用：Driver 应用（仅发消息，无需 Socket Mode）和 SUT 应用（需开启 Socket Mode 并订阅事件）。Driver 使用简单 manifest，SUT 需配置 connections:write 应用级 token。两个 bot 必须被邀请到同一频道。所有凭据可通过环境变量或 Convex 凭据池提供。

相关文档 #

• Matrix QA
• Personal agent benchmark pack
• QA Channel
• Testing
• Dashboard