擁有權
- OpenClaw(
extensions/qa-lab/src/mantis/*):情境執行階段、pnpm openclaw qa mantis <command>命令列介面、證據結構描述。 - QA Lab(
extensions/qa-lab/src/live-transports/*):即時傳輸測試框架、驅動程式/受測系統機器人、報告/證據寫入器。 - Crabbox(
openclaw/crabbox):預熱的 Linux 機器、租約、VNC、crabbox media preview。 - GitHub Actions(
.github/workflows/mantis-*.yml):遠端進入點、成品保留。 - ClawSweeper:剖析維護者 PR 命令、分派工作流程,並發布最終 PR 留言。
命令列介面命令
所有命令皆為pnpm openclaw qa mantis <command>,定義於
extensions/qa-lab/src/mantis/cli.ts。建置/執行時需要 OPENCLAW_ENABLE_PRIVATE_QA_CLI=1
(隨附的工作流程會在建置前設定 OPENCLAW_BUILD_PRIVATE_QA=1 與
OPENCLAW_ENABLE_PRIVATE_QA_CLI=1)。
每個命令都接受
--repo-root <path> 與 --output-dir <path>;Crabbox
命令也接受 --crabbox-bin、--provider、--machine-class/--class、
--lease-id、--idle-timeout、--ttl 與 --keep-lease。除非另有註明,本機命令列介面
的提供者/類別預設值為 hetzner/beast;CI 工作流程
通常會覆寫兩者。
discord-smoke
https://discord.com/api/v10)以取得機器人
使用者、伺服器、伺服器的頻道與目標頻道,斷言該
頻道屬於此伺服器,接著(除非使用 --skip-post)發布訊息並
加入 👀 表情回應。寫入 mantis-discord-smoke-summary.json 與
mantis-discord-smoke-report.md。
權杖解析順序:--token-file 值,接著是 OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN
(使用 --token-env 覆寫),再來是由 OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN_FILE 指定名稱的檔案
(使用 --token-file-env 覆寫)。伺服器/頻道 ID 來自
OPENCLAW_QA_DISCORD_GUILD_ID / OPENCLAW_QA_DISCORD_CHANNEL_ID(使用
--guild-id / --channel-id 覆寫),且必須是 17-20 位數的 Discord 雪花 ID。設定
OPENCLAW_QA_REDACT_PUBLIC_METADATA=1,即可在發布的摘要與報告中,將機器人/伺服器/頻道/訊息 ID
及名稱替換為 <redacted>。
run
--transport 目前只接受 discord。--scenario 是兩個
內建 ID 之一,各自具有預設的基準參照與預期的前後
標籤(extensions/qa-lab/src/mantis/run.runtime.ts):
--candidate 預設為 HEAD。其他旗標:--credential-source
(預設 convex)、--credential-role(預設 ci)、--provider-mode
(預設 live-frontier)、--fast(預設開啟)、--skip-install、--skip-build。
執行器會在 <output-dir>/worktrees/ 下,為基準與
候選版本建立分離的 git worktree 簽出,並在
各自的簽出中執行 pnpm install/pnpm build(除非略過),接著對每個工作樹執行
pnpm openclaw qa discord --scenario <id> --model openai/gpt-5.4 --alt-model openai/gpt-5.4 --allow-failures。
每個執行路徑都會寫入 discord-qa-reaction-timelines.json
以及一組 <scenario-id>-timeline.html/.png;執行器會將此
證據複製回 baseline//candidate/ 下,在輸出目錄中寫入 comparison.json、
mantis-report.md 與 mantis-evidence.json,若比較未通過(基準
fail 且候選版本 pass),則以非零狀態結束。
第二個 Discord 情境(discord-thread-reply-filepath-attachment)會使用
驅動機器人發布父訊息、建立真實討論串、使用存放庫內的 filePath 呼叫受測系統的
message.thread-reply 動作,接著輪詢
討論串以取得回覆與附件檔名。它預期有一個
名為 mantis-thread-report.md 的附件。
desktop-browser-smoke
--browser-url(預設 https://openclaw.ai)或已呈現的
--html-file,等待後使用 scrot 擷取螢幕截圖,可選擇使用
ffmpeg 錄製 MP4,並透過 rsync 將 desktop-browser-smoke.png / .mp4 / remote-metadata.json
同步回 --output-dir。
旗標:
--lease-id <cbx_...>會重用預熱的桌面,而非建立新桌面。--browser-profile-dir <remote-path>會重用遠端 Chrome 使用者資料目錄,讓持續運作的桌面在多次執行之間維持登入狀態(用於長期運作的 Discord Web 檢視器設定檔)。--browser-profile-archive-env <name>會在啟動前,從該環境變數還原 base64.tgzChrome 設定檔封存(預設OPENCLAW_MANTIS_BROWSER_PROFILE_TGZ_B64);用於 Discord Web 等已登入的見證器。--video-duration <seconds>控制 MP4 擷取長度(預設 10s)。--keep-lease(或OPENCLAW_MANTIS_KEEP_VM=1)會讓本次執行所建立的租約保持開啟,以供 VNC 檢查;建立了租約但執行失敗時,預設也會保留租約。
qa discord)仍具有權威性;設定
OPENCLAW_QA_DISCORD_CAPTURE_UI_METADATA=1 時,此情境也會寫入
Discord Web URL 成品,而 OPENCLAW_QA_DISCORD_KEEP_THREADS=1 會讓
討論串保持開啟足夠長的時間,供瀏覽器開啟。
GitHub 工作流程偏好透過
MANTIS_DISCORD_VIEWER_CHROME_PROFILE_DIR 使用持續保存的檢視器設定檔(完整設定檔封存可能超過
GitHub 的機密大小限制);對於小型/啟動設定檔,則可改從 MANTIS_DISCORD_VIEWER_CHROME_PROFILE_TGZ_B64 還原
base64 .tgz。若
兩種來源皆未設定,工作流程仍會發布確定性的
基準/候選版本螢幕截圖,並記錄已略過登入見證器。
slack-desktop-smoke
pnpm openclaw qa slack、於 VNC 瀏覽器中開啟 Slack Web、
擷取桌面,並將 Slack QA 成品(slack-qa/)及
VNC 螢幕截圖/影片複製回本機。這是唯一讓
受測系統閘道與瀏覽器都在同一個 VM 內執行的 Mantis 形式。
使用 --gateway-setup 時,命令會在 VM 的
$HOME/.openclaw-mantis/slack-openclaw 建立持續保存、可丟棄的 OpenClaw
主目錄,針對目標頻道修補 Slack
Socket Mode 設定、啟動
openclaw gateway run --dev --allow-unconfigured --port 38973,並讓
Chrome 繼續在 VNC 工作階段中執行;省略 --gateway-setup 則改為執行一般的
機器人對機器人 Slack QA 執行路徑。
--credential-source env 所需的環境變數(本機預設為 env;角色
預設為 maintainer):
OPENCLAW_QA_SLACK_CHANNEL_IDOPENCLAW_QA_SLACK_DRIVER_BOT_TOKENOPENCLAW_QA_SLACK_SUT_BOT_TOKENOPENCLAW_QA_SLACK_SUT_APP_TOKENOPENCLAW_LIVE_OPENAI_KEY,供遠端模型執行路徑使用(如果本機只設定了OPENAI_API_KEY, Mantis 會先將其複製到OPENCLAW_LIVE_OPENAI_KEY,再 呼叫 Crabbox)
--credential-source convex 時,Mantis 會在建立 VM 前,
從共用集區租用 Slack 受測系統認證資訊,並將頻道 ID、應用程式權杖與
機器人權杖作為 OPENCLAW_MANTIS_SLACK_* 環境變數轉送至 VM,因此 GitHub
工作流程只需要 Convex 代理程式機密,不需要原始 Slack 權杖。
其他旗標:--slack-url <url> 會開啟特定 URL(否則 Mantis 會從
auth.test 衍生 https://app.slack.com/client/<team>/<channel>);
--slack-channel-id <id> 設定閘道允許清單頻道;
OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR 控制 VM 內持續保存的 Chrome
設定檔(預設 $HOME/.config/openclaw-mantis/slack-chrome-profile);
--approval-checkpoints 執行原生 Slack 核准情境
(slack-approval-exec-native、slack-approval-plugin-native),並呈現
待處理/已解決的檢查點螢幕截圖,而非設定閘道(與
--gateway-setup 互斥);--hydrate-mode source|prehydrated、
--provider-mode、--model、--alt-model 與 --fast 會原樣傳遞至
Slack 即時執行路徑。
核准檢查點螢幕截圖是根據情境觀察到的 Slack API 訊息
呈現,而非即時 Slack UI;只有在租約的瀏覽器設定檔已登入時,
slack-desktop-smoke.png 才能證明 Slack Web 本身。
telegram-desktop-builder
openclaw gateway run --dev --allow-unconfigured --port 38974、將
驅動機器人的就緒訊息發布到租用的私人群組,接著擷取
螢幕截圖與 MP4。機器人權杖只會設定 OpenClaw;絕不會讓
Telegram Desktop 登入。桌面檢視器是獨立的 Telegram 使用者工作階段,
可從 --telegram-profile-archive-env <name> 還原,或
透過 VNC 手動登入,並使用 --keep-lease 維持執行。
旗標:--lease-id <cbx_...> 會針對已登入
Telegram Desktop 的 VM 重新執行;--telegram-profile-archive-env <name> 會在啟動前還原 base64
.tgz 設定檔封存;--telegram-profile-dir <remote-path>
設定遠端設定檔目錄(預設 $HOME/.local/share/TelegramDesktop);
--no-gateway-setup 僅安裝並開啟 Telegram Desktop;
--credential-source/--credential-role 預設為 convex/maintainer。
證據資訊清單
每個發佈至 PR 的情境都會在其報告旁寫入mantis-evidence.json:
path 是相對於資訊清單所在目錄;targetPath 則是相對於設定的 R2/S3 成品前綴。scripts/mantis/publish-pr-evidence.mjs 會拒絕路徑遍歷,並在檔案缺失時略過含有 "required": false 的項目。
成品種類:timeline(確定性的前後對照螢幕截圖)、desktopScreenshot(VNC/瀏覽器螢幕截圖)、motionPreview(錄影中的內嵌動態 GIF)、motionClip(裁除無動作片段的 MP4)、fullVideo(完整錄影)、metadata(JSON/記錄附屬檔案)、report(Markdown 報告)。
一次執行的磁碟成品配置:
OPENCLAW_QA_REDACT_PUBLIC_METADATA=1;Discord/Slack/Telegram GitHub 工作流程預設會啟用此設定。
GitHub 自動化
scripts/mantis/publish-pr-evidence.mjs 是可重複使用的發佈器。工作流程會使用資訊清單、目標 PR、成品目標根目錄、留言標記、成品 URL、執行 URL 和請求來源來呼叫它。它會將宣告的成品上傳至 Mantis R2 儲存貯體、建立先顯示摘要且含有內嵌圖片/預覽與影片連結的 PR 留言,然後更新現有的標記留言或建立新留言。必要環境變數:
MANTIS_ARTIFACT_R2_ACCESS_KEY_IDMANTIS_ARTIFACT_R2_SECRET_ACCESS_KEYMANTIS_ARTIFACT_R2_BUCKET(工作流程會設定openclaw-crabbox-artifacts)MANTIS_ARTIFACT_R2_ENDPOINTMANTIS_ARTIFACT_R2_REGION(工作流程會設定auto)MANTIS_ARTIFACT_R2_PUBLIC_BASE_URL(工作流程會設定https://artifacts.openclaw.ai)
MANTIS_GITHUB_APP_ID/MANTIS_GITHUB_APP_PRIVATE_KEY)發佈,而不是使用 github-actions[bot];並以隱藏的標記留言作為更新或插入的鍵值。
Mantis Discord Status Reactions 與 Mantis Telegram Live 都接受 baseline_ref/candidate_ref(或 PR 留言中的 baseline=/candidate=),並在使用含有機密認證資訊執行前,驗證解析出的 SHA 是否為 origin/main 的祖先、發行標籤(v*),或開放中 PR 的前端。
具有寫入/維護/管理員存取權的 PR 留言可使用下列觸發指令:
telegram-status-command 作為情境;它們接受 provider=aws|hetzner 和 lease=<cbx_...>,以指定特定的 Crabbox 提供者或預先暖機的桌面。只有當 PR 已帶有 mantis: telegram-visible-proof 標籤時,Mantis Telegram Desktop Proof 才會回應 PR 留言。
Web UI 聊天留言觸發器預設會以 PR 前端 SHA 作為候選版本。它們會執行 Control UI 模擬閘道的聊天證明並發佈瀏覽器成品;其他網頁和原生應用程式介面請使用一般 Playwright/瀏覽器證明、維護者螢幕截圖、Crabbox 或本機成品。
ClawSweeper 也可直接分派情境:
機器與機密
本機命令列介面的 Crabbox 預設值為--provider hetzner --class beast;可使用 --provider、--class/--machine-class 或 OPENCLAW_MANTIS_CRABBOX_PROVIDER/OPENCLAW_MANTIS_CRABBOX_CLASS 覆寫。GitHub 工作流程通常會同時覆寫兩者(例如 --class standard,以及 Slack 工作流程的 aws/hetzner 提供者選擇輸入)。若某個提供者速度過慢或無法使用,請在相同的 Crabbox 介面後加入該提供者,而不要硬式編碼備援方案。
VM 基準:具備可執行桌面版 Chrome/Chromium、CDP 存取、VNC/noVNC、Node 22.22.3+、24.15+ 或 25.9+ 及 pnpm 的 Linux、OpenClaw 簽出版本,以及對目標傳輸服務、GitHub、模型提供者和認證資訊代理程式的對外存取能力。
Mantis 命令與工作流程使用的認證資訊及環境變數名稱:
OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKENOPENCLAW_QA_DISCORD_GUILD_IDOPENCLAW_QA_DISCORD_CHANNEL_ID- 本機
qa mantis run --credential-source env還需要OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN、OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN和OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID。GitHub 工作流程通常使用--credential-source convex和下方的代理程式認證資訊,而非原始 Discord 機器人權杖。 - 用於公開上傳成品的
OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 OPENCLAW_QA_CONVEX_SITE_URL、OPENCLAW_QA_CONVEX_SECRET_CIOPENAI_API_KEY(或 Telegram Desktop 證明專用的OPENCLAW_MANTIS_AGENT_OPENAI_API_KEY)CRABBOX_COORDINATOR/CRABBOX_COORDINATOR_TOKEN(工作流程也接受OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR/_TOKEN作為備援,並在叫用 Crabbox 前 將它們對應至一般名稱)CRABBOX_ACCESS_CLIENT_ID、CRABBOX_ACCESS_CLIENT_SECRETMANTIS_GITHUB_APP_ID、MANTIS_GITHUB_APP_PRIVATE_KEY
執行結果
前後對照傳輸情境會區分下列結果,避免不穩定的環境被誤判為產品迴歸:- 已重現錯誤:基準版本依照情境預期的方式失敗。
- 測試工具失敗:在判定條件具備意義之前,環境設定、認證資訊、傳輸 API、瀏覽器或提供者即告失敗。
新增情境
即時傳輸情境是針對各傳輸服務以 TypeScript 定義(Discord 前後對照形式請參閱extensions/qa-lab/src/mantis/run.runtime.ts 中的 MANTIS_SCENARIO_CONFIGS),而非獨立的宣告式檔案格式。每個情境都需要:ID 與標題、傳輸服務、必要認證資訊、基準參照原則、候選參照原則、OpenClaw 設定修補、設定/刺激步驟、預期的基準與候選判定條件、視覺擷取目標、逾時預算,以及清理步驟。
聚焦且僅針對候選版本的瀏覽器證明可使用專用的確定性端對端測試與工作流程。請明確限定其範圍、在執行前驗證候選參照、隔離使用機密的發佈程序,並輸出相同的證據資訊清單契約。
應優先使用小型且具型別的判定條件,而非視覺檢查:Discord 反應狀態或訊息參照、Slack 討論串 ts/反應 API 狀態、電子郵件訊息 ID 與標頭。只有在 UI 是唯一可靠的可觀察項目時才使用瀏覽器螢幕截圖;若平台 API 判定條件存在,視覺檢查應作為其附加項目。
繼 Discord、Slack 和 Telegram 之後,相同的執行器形式可延伸至 WhatsApp(QR 登入、重新識別、傳遞、媒體、反應)和 Matrix(加密聊天室、討論串/回覆關係、重新啟動後續接);兩者目前皆尚未實作。
待解問題
- 重複使用現有的 Mantis 機器人時,哪個 Discord 機器人應作為驅動端,哪個應作為受測系統?
- GitHub 應為 PR 保留 Mantis 成品多久?
- ClawSweeper 應在何時自動建議 Mantis 情境,而不是 等待維護者命令?
- 針對公開 PR,上傳前是否應遮蔽或裁切螢幕截圖?