Mantis 是 OpenClaw 的端到端可视化验证系统，用于在真实传输层（如 Discord、Slack、Telegram）上复现 bug，捕获修复前后的证据并发布到 PR 评论。在本地使用 pnpm openclaw qa mantis 命令运行，在 CI 中通过 GitHub Actions 触发。需要配置 Discord bot token、Crabbox 坐标等密钥，并确保 VM 环境支持浏览器自动化与 VNC 救援。

OpenClaw Mantis 端到端验证系统配置指南

Mantis 是 OpenClaw 项目中专为需要实际运行时环境、真正传输层和可视化证据的 bug 设计的端到端验证系统。它在已知有问题的基线 ref 上运行场景并捕获证据，随后在候选修复 ref 上运行相同场景，最后输出对比结果。维护者可以通过 PR 或本地命令直接检查这些产物。

Mantis 首选从 Discord 开始，因为 Discord 能提供高价值的第一条通道：真实的 bot 认证、公会频道、反应、线程、原生命令以及可供人类目视确认的浏览器界面。

目标

从 GitHub issue 或 PR 的评论触发复现，直接模拟用户所见传输形态。
在应用修复前捕获基线（before）证据。
在应用修复后捕获候选（after）证据。
尽可能使用确定性判定器（oracle），例如 Discord REST 读取反应状态或频道文本检查。
当 bug 涉及可视化界面时，截图捕获屏幕。
支持从本地开发者命令行运行（pnpm openclaw qa mantis）和从 GitHub Actions 远程运行。
保留足够的机器状态以实现 VNC 救援，当登录、浏览器自动化或 provider 认证卡住时，操作员可以手动介入。
当运行受阻、需要 VNC 人工协助或完成时，将简洁的状态发送到操作员 Discord 频道。

非目标

Mantis 不替代单元测试。每个 Mantis 场景在 bug 修复后应缩小为回归测试。
Mantis 不是常规的快速 CI 门禁。它较慢、需要真实凭证，仅用于需要真实环境的 bug。
正常运行不应依赖人工。VNC 是救援路径，不是常态。
Mantis 不会在产物、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。

维护职责

Mantis 归属 OpenClaw QA 栈：

OpenClaw 负责场景运行时、传输适配器、证据模式以及本地 CLI pnpm openclaw qa mantis。
QA Lab 提供实时传输工具链、浏览器捕获辅助程序和产物编写器。
Crabbox 负责在需要远程虚拟机时提供预热的 Linux 机器。
GitHub Actions 负责远程工作流入点位和产物保留。
ClawSweeper 负责解析维护者命令、分发工作流、发布最终 PR 评论。
OpenClaw 智能体通过 Codex 驱动 Mantis，当场景需要智能体设置、调试或卡住时上报。

常用命令

以下示例均可在本地运行，需要对应传输层的密钥环境变量。

Discord 烟雾测试

验证 Discord bot、公会、频道、消息发送、反应发送和产物路径：

bash

pnpm openclaw qa mantis discord-smoke \
  --output-dir .artifacts/qa-e2e/mantis/discord-smoke

Discord 前后对比运行

bash

pnpm openclaw qa mantis run \
  --transport discord \
  --scenario discord-status-reactions-tool-only \
  --baseline origin/main \
  --candidate HEAD \
  --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions

该命令会在产物目录下创建独立的基线与候选工作树，分别安装依赖并构建，运行场景（允许失败），然后写入 baseline/、candidate/、comparison.json 和 mantis-report.md。对于该场景，成功验证意味着基线状态 fail、候选状态 pass。

桌面浏览器烟雾测试

用于在 Crabbox 桌面上启动浏览器并截图：

bash

pnpm openclaw qa mantis desktop-browser-smoke \
  --output-dir .artifacts/qa-e2e/mantis/desktop-browser

它默认使用 Hetzner provider，可通过 --provider、--crabbox-bin 或 OPENCLAW_MANTIS_CRABBOX_PROVIDER 环境变量覆盖。其他常用标志包括 --lease-id（复用预热桌面）、--browser-url、--html-file（渲染本地 HTML）、--keep-lease（保持 VM 开启供 VNC 检查）、--video-duration（控制 MP4 录制长度）等。

Slack 桌面烟雾测试

bash

pnpm openclaw qa mantis slack-desktop-smoke \
  --output-dir .artifacts/qa-e2e/mantis/slack-desktop \
  --gateway-setup \
  --scenario slack-canary \
  --keep-lease

使用 --gateway-setup 时，会在 VM 内启动一个持久化 OpenClaw Slack 网关（端口 38973），保持 Chrome 运行在 VNC 会话中。需要设置 OPENCLAW_QA_SLACK_CHANNEL_ID、OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN 等环境变量。若使用 Convex 凭证池，则通过 --credential-source convex 获取。

Telegram 原生桌面证据构建

用于人工设置 Telegram Desktop 的会话环境：

bash

pnpm openclaw qa mantis telegram-desktop-builder \
  --credential-source convex \
  --credential-role maintainer \
  --keep-lease

支持 --telegram-profile-archive-env 恢复预先保存的用户配置，--telegram-profile-dir 指定远程配置目录。

从 PR 评论触发 Mantis

维护者（write、maintain 或 admin 权限）可通过评论命令触发 Mantis 运行。

Discord status reactions：在 PR 下评论 @openclaw-mantis discord status reactions，默认使用已知坏的基线 ref 和当前 PR 头 SHA 作为候选。可覆盖：@openclaw-mantis discord status reactions baseline=origin/main candidate=HEAD。
Telegram 实时 QA：评论 @openclaw-mantis telegram，默认运行 telegram-status-command 场景。可指定 scenario=...、scenarios=...、candidate=...、provider=aws|hetzner、lease=<cbx_...>。
ClawSweeper 命令：@clawsweeper mantis discord discord-status-reactions-tool-only 或 @clawsweeper verify e2e discord。

Mantis 工作流会将产物上传至 GitHub Actions 制品并发布 PR 评论，包含基线/候选截图对比。

证据产出结构

每次运行会在 .artifacts/qa-e2e/mantis/<run-id>/ 下产出以下文件：

text

mantis-report.md
mantis-summary.json
baseline/
    summary.json
    discord-message.json
    screenshot-message-row.png
    gateway-debug/
candidate/
    summary.json
    discord-message.json
    screenshot-message-row.png
    gateway-debug/
comparison.json
run.log

mantis-summary.json 是机器可读的事实源，包含 SHA、传输层、场景 ID、provider、凭证来源（不含值）、基线/候选结果、是否复现 bug、产物路径等。
截图应遵守脱敏规则：对于公开 PR，公开产物不应包含频道 ID、用户 ID 等元数据。设置 OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 启用脱敏。

支持的传输层场景

按原文，Mantis 目前或即将支持以下传输层及其烟雾/ bug 场景：

传输层	初始烟雾场景	常见 bug 场景
Discord	`discord-smoke`	`discord-status-reactions-tool-only`
Slack	`slack-desktop-smoke`	`slack-canary`，含网关设置
Telegram	`telegram-desktop-builder`（人工设置）	实时 QA 命令触发（`telegram-status-command`）
Email	待定	使用 `gog` 连接器
WhatsApp	待定	QR 登录、媒体消息等
Matrix	待定	加密房间、回复关系等

每个传输层应有一个低成本的烟雾场景和一个或多个错误类别场景。昂贵的可视化场景保持按需选择。

密钥与环境变量

Mantis 运行涉及的密钥全部以环境变量形式提供，严禁硬编码。

浏览器配置相关

MANTIS_DISCORD_VIEWER_CHROME_PROFILE_DIR：持久化 Chrome 用户数据目录路径。
MANTIS_DISCORD_VIEWER_CHROME_PROFILE_TGZ_B64：base64 编码的 Chrome 配置归档（小规模启动用）。
OPENCLAW_MANTIS_BROWSER_PROFILE_TGZ_B64：浏览器配置归档环境变量。
OPENCLAW_MANTIS_CRABBOX_PROVIDER：指定 Crabbox 的云提供商，默认 Hetzner。
OPENCLAW_MANTIS_CRABBOX_LEASE_ID：复用已有桌面机器。

重要限制

Mantis 运行器绝不可打印 bot token、provider API key、浏览器 cookie、VNC 密码或原始凭证载荷。
公开 PR 产物应启用 OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 脱敏 Discord bot、guild、channel、message 等 ID。
若 token 意外泄露到 issue、PR、聊天或日志中，请立即轮换。

工作流与 PR 评论

Mantis 产生的 GitHub Actions 工作流名称包括：

Mantis Discord Smoke
Mantis Discord Status Reactions
Mantis Slack Desktop Smoke
Mantis Telegram Live
Mantis Telegram Desktop Proof
Mantis Scenario（通用手动入口）

每个工作流上传完整的证据包作为短期 Actions 制品。对于 bug 报告或修复 PR，还会将脱敏的媒体文件发布到 Mantis R2/S3 存储桶，并在该 PR 上插入一条包含基线/候选截图的评论。

评论使用 Mantis GitHub App（需要 MANTIS_GITHUB_APP_ID 和 MANTIS_GITHUB_APP_PRIVATE_KEY）发布，格式为简短的可视化对比表。表头包含摘要、场景、运行链接、制品链接，以及 Baseline / Candidate 的截图列。

若运行因环境问题失败，评论会明确说明是线束失败而非产品失败。

添加新场景

添加一个 Mantis 场景需要声明以下信息：

id 和 title
传输层（transport）
所需凭证列表
基线 ref 策略
候选 ref 策略
OpenClaw 配置补丁
设置步骤
刺激输入
预期的基线判定器（oracle）
预期的候选判定器
可视化截图目标
超时预算
清理步骤

优先选择小型、类型化的判定器：对于反应 bug 使用 Discord 反应状态，对于线程 bug 使用消息引用，对于 Slack bug 使用 thread_ts 和反应 API，对于 UI 问题使用浏览器截图。

常见问题

怎么在本地运行 Mantis 的 Discord 烟雾测试？

需要先设置好 Discord bot token 等环境变量（参见上方密钥与环境变量），然后在项目根目录执行：

bash

pnpm openclaw qa mantis discord-smoke --output-dir .artifacts/qa-e2e/mantis/discord-smoke

从 PR 评论触发 Mantis 需要什么权限？

只有对仓库具有 write、maintain 或 admin 角色的用户才能触发。评论格式如 @openclaw-mantis discord status reactions，Mantis 会使用已知坏的基线 ref 和当前 PR 头 SHA 运行。

Mantis 的产物在哪里查看？

本地运行产物在 .artifacts/qa-e2e/mantis/<run-id>/ 目录下。远程 CI 运行会上传到 GitHub Actions 的制品页面，并与 PR 关联的 Mantis 评论中提供截图和视频预览。公开 PR 的产物会同时上传到 Mantis R2/S3 存储桶（URL 由 MANTIS_ARTIFACT_R2_PUBLIC_BASE_URL 指定）。

OpenClaw Mantis 端到端验证系统配置指南 ​

目标 ​

非目标 ​

维护职责 ​

常用命令 ​

Discord 烟雾测试 ​

Discord 前后对比运行 ​

桌面浏览器烟雾测试 ​

Slack 桌面烟雾测试 ​

Telegram 原生桌面证据构建 ​

从 PR 评论触发 Mantis ​

证据产出结构 ​

支持的传输层场景 ​

密钥与环境变量 ​

推荐 GitHub Secrets 名称 ​

浏览器配置相关 ​

重要限制 ​

工作流与 PR 评论 ​

添加新场景 ​

常见问题 ​

怎么在本地运行 Mantis 的 Discord 烟雾测试？ ​

从 PR 评论触发 Mantis 需要什么权限？ ​

Mantis 的产物在哪里查看？ ​

OpenClaw Mantis 端到端验证系统配置指南

目标

非目标

维护职责

常用命令

Discord 烟雾测试

Discord 前后对比运行

桌面浏览器烟雾测试

Slack 桌面烟雾测试

Telegram 原生桌面证据构建

从 PR 评论触发 Mantis

证据产出结构

支持的传输层场景

密钥与环境变量

推荐 GitHub Secrets 名称

浏览器配置相关

重要限制

工作流与 PR 评论

添加新场景

常见问题

怎么在本地运行 Mantis 的 Discord 烟雾测试？

从 PR 评论触发 Mantis 需要什么权限？

Mantis 的产物在哪里查看？