螳螂

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

目標

• 使用與使用者看到相同的傳輸形態，重現 GitHub issue 或 PR 中的錯誤。
• 在套用修正前，於基準 ref 上擷取 before artifact。
• 在套用修正後，於候選 ref 上擷取 after artifact。
• 盡可能使用確定性的 oracle，例如 Discord REST 反應讀取或頻道逐字稿檢查。
• 當錯誤有可見 UI 表面時擷取螢幕截圖。
• 從代理控制的 CLI 於本機執行，並從 GitHub 遠端執行。
• 保留足夠的機器狀態，以便在登入、瀏覽器自動化或 provider 驗證卡住時進行 VNC 救援。
• 當執行受阻、需要手動 VNC 協助或完成時，將精簡狀態發布到操作者 Discord 頻道。

​

非目標

• Mantis 不是單元測試的替代品。修正被理解後，Mantis 執行通常應轉成 較小的迴歸測試。
• Mantis 不是一般快速 CI gate。它較慢、使用 live credentials， 且保留給 live 環境很重要的錯誤。
• Mantis 在正常運作時不應需要人類介入。手動 VNC 是救援路徑， 不是理想路徑。
• Mantis 不會在 artifacts、記錄、螢幕截圖、Markdown 報告或 PR 留言中儲存原始 secrets。

​

所有權

• OpenClaw 擁有 scenario runtime、transport adapters、evidence schema， 以及 pnpm openclaw qa mantis 底下的本機 CLI。
• QA Lab 擁有 live transport harness 組件、browser capture helpers， 以及 artifact writers。
• 需要遠端 VM 時，Crabbox 擁有預熱的 Linux 機器。
• GitHub Actions 擁有遠端 workflow entrypoint 與 artifact retention。
• ClawSweeper 擁有 GitHub comment routing：解析維護者命令、 dispatch workflow，並發布最終 PR comment。
• 當情境需要 agentic 設定、除錯或卡住狀態回報時， OpenClaw agents 會透過 Codex 驅動 Mantis。

​

命令形態

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

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

pnpm openclaw qa mantis run \
  --transport discord \
  --scenario discord-thread-reply-filepath-attachment \
  --baseline <bug-ref> \
  --candidate <fix-ref> \
  --output-dir .artifacts/qa-e2e/mantis/local-discord-thread-attachment

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

• --lease-id <cbx_...> 或 OPENCLAW_MANTIS_CRABBOX_LEASE_ID 會重用預熱的 desktop。
• --browser-url <url> 會變更可見瀏覽器開啟的頁面。
• --html-file <path> 會在可見瀏覽器中呈現 repo-local HTML artifact。Mantis 用它透過真實 Crabbox desktop 擷取產生的 Discord status-reaction timeline。
• --browser-profile-dir <remote-path> 會重用遠端 Chrome user-data-dir，讓持久性 Mantis desktop 能在執行之間維持登入狀態。請將它用於長期存在的 Discord Web viewer profile。
• --browser-profile-archive-env <name> 會在啟動瀏覽器前，從指定環境變數還原 base64 .tgz Chrome user-data-dir archive。請將它用於已登入的見證者，例如 Discord Web。預設 env var 是 OPENCLAW_MANTIS_BROWSER_PROFILE_TGZ_B64。
• --video-duration <seconds> 控制 MP4 擷取長度。對需要時間穩定的慢速已登入 web apps，請使用較長時間。
• --keep-lease 或 OPENCLAW_MANTIS_KEEP_VM=1 會讓新建立且通過的 lease 保持開啟，以供 VNC 檢查。失敗執行若建立了 lease，預設會保留它，讓操作者可以重新連線。
• --class、--idle-timeout 與 --ttl 會調整機器大小與 lease 生命週期。

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

• OPENCLAW_QA_SLACK_CHANNEL_ID
• OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_APP_TOKEN
• 遠端 model lane 需要 OPENCLAW_LIVE_OPENAI_KEY。若本機只設定了 OPENAI_API_KEY，Mantis 會在呼叫 Crabbox 前將它映射到 OPENCLAW_LIVE_OPENAI_KEY，讓 Crabbox 的 OPENCLAW_* env forwarding 能將它帶入 VM。

• --lease-id <cbx_...> 會對操作者已透過 VNC 登入 Slack Web 的機器重新執行。
• --gateway-setup 會在 VM 中啟動持久性 OpenClaw Slack gateway，而不是只執行 bot-to-bot QA lane。
• --keep-lease 會在成功後保持 gateway VM 開啟以供 VNC 檢查；--no-keep-lease 會在收集 artifacts 後停止它。
• --slack-url <url> 會開啟指定 Slack Web URL。若未提供，且 SUT bot token 可用，Mantis 會從 Slack auth.test 推導 https://app.slack.com/client/<team>/<channel>。
• --slack-channel-id <id> 控制 gateway setup 使用的 Slack channel allowlist。
• OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR 控制 VM 內的持久性 Chrome profile。預設為 $HOME/.config/openclaw-mantis/slack-chrome-profile，因此手動 Slack Web 登入可在同一個 lease 的重新執行間保留。
• --credential-source convex --credential-role ci 會使用共享 credential pool，而不是直接使用 Slack env tokens。
• --provider-mode、--model、--alt-model 與 --fast 會傳遞給 Slack live lane。

• baseline_ref：預期會重現 queued-only 行為的 ref。
• candidate_ref：預期會顯示 queued -> thinking -> done 的 ref。

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

• --lease-id <cbx_...> 會針對操作員已登入 Telegram Desktop 的 VM 重新執行。
• --telegram-profile-archive-env <name> 會從該環境變數讀取 base64 .tgz Telegram Desktop profile 封存，並在啟動前還原。
• --telegram-profile-dir <remote-path> 控制遠端 Telegram Desktop profile 目錄。預設值是 $HOME/.local/share/TelegramDesktop。
• --no-gateway-setup 會安裝並開啟 Telegram Desktop，但不設定 OpenClaw。
• --credential-source convex --credential-role ci 使用共享認證 broker，而不是直接 Telegram 環境 token。

{
  "schemaVersion": 1,
  "id": "discord-status-reactions",
  "title": "Mantis Discord Status Reactions QA",
  "summary": "Human-readable top summary for the PR comment.",
  "scenario": "discord-status-reactions-tool-only",
  "comparison": {
    "baseline": { "sha": "...", "status": "fail", "expected": "queued-only" },
    "candidate": { "sha": "...", "status": "pass", "expected": "queued -> thinking -> done" },
    "pass": true
  },
  "artifacts": [
    {
      "kind": "timeline",
      "lane": "baseline",
      "label": "Baseline queued-only",
      "path": "baseline/timeline.png",
      "targetPath": "baseline.png",
      "alt": "Baseline Discord timeline",
      "width": 420
    }
  ]
}

• timeline：決定性的情境螢幕截圖，通常是前後對照。
• desktopScreenshot：VNC/瀏覽器桌面螢幕截圖。
• motionPreview：從桌面錄影產生的行內動畫 GIF。
• motionClip：移除靜態開頭與結尾的動作裁切 MP4。
• fullVideo：用於深入檢查的完整 MP4 錄影。
• metadata：JSON/log sidecar。
• report：Markdown 報告。

@Mantis discord status reactions

@Mantis discord status reactions baseline=origin/main candidate=HEAD

@Mantis telegram
@Mantis telegram scenario=telegram-status-command
@Mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

@clawsweeper mantis discord discord-status-reactions-tool-only
@clawsweeper verify e2e discord

​

執行生命週期

1. 取得認證。
2. 配置或重用 VM。
3. 當情境需要 UI 證據時，準備桌面/瀏覽器 profile。
4. 為基準 ref 準備乾淨的 checkout。
5. 安裝相依項並只建置情境所需的內容。
6. 使用隔離的狀態目錄啟動子 OpenClaw Gateway。
7. 設定即時傳輸、提供者、模型和瀏覽器 profile。
8. 執行情境並擷取基準證據。
9. 停止 gateway 並保留日誌。
10. 在同一個 VM 中準備候選 ref。
11. 執行相同情境並擷取候選證據。
12. 比較 oracle 結果與視覺證據。
13. 寫入 Markdown、JSON、日誌、螢幕截圖和選用 trace 成品。
14. 上傳 GitHub Actions 成品。
15. 發布簡潔的 PR 或 Discord 狀態訊息。

• 已重現錯誤：基準以預期方式失敗。
• Harness 失敗：環境設定、認證、Discord API、瀏覽器或提供者在 bug oracle 具有意義之前失敗。

​

Discord MVP

• 它在 Discord 中顯示為觸發訊息上的 reactions。
• 它透過 Discord 訊息 reaction 狀態具備強大的 REST oracle。
• 它會演練真實的 OpenClaw Gateway、Discord bot auth、訊息 dispatch、來源回覆傳遞模式、status reaction 狀態和模型 turn 生命週期。
• 它足夠狹窄，可以讓第一個實作保持務實。

id: discord-status-reactions-tool-only
transport: discord
baseline:
  expect:
    reproduced: true
candidate:
  expect:
    fixed: true
config:
  messages:
    ackReaction: "👀"
    ackReactionScope: "group-mentions"
    groupChat:
      visibleReplies: "message_tool"
    statusReactions:
      enabled: true
      timing:
        debounceMs: 0
discord:
  requireMention: true
  notifyChannel: operator-notify
evidence:
  rest:
    messageReactions: true
  browser:
    screenshotMessageRow: true

pnpm openclaw qa discord \
  --scenario discord-status-reactions-tool-only \
  --provider-mode live-frontier \
  --model openai/gpt-5.4 \
  --alt-model openai/gpt-5.4 \
  --fast \
  --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate

​

現有 QA 元件

• pnpm openclaw qa discord 已經執行包含 driver 和 SUT bots 的即時 Discord 通道。
• 即時傳輸 runner 已經在 .artifacts/qa-e2e/ 下寫入報告和觀察到的訊息成品。
• Convex 認證租約已經提供共享即時傳輸認證的獨佔存取。
• 瀏覽器控制服務已經支援螢幕截圖、snapshots、headless managed profiles 和遠端 CDP profiles。
• QA Lab 已經具備用於 transport-shaped testing 的 debugger UI 和 bus。

​

證據模型

.artifacts/qa-e2e/mantis/<run-id>/
  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

• 測試的 refs 和 SHAs
• transport 和情境 id
• 機器提供者和機器 id 或租約 id
• 不含 secret 值的認證來源
• 基準結果
• 候選結果
• bug 是否在基準上重現
• 候選是否修復它
• 成品路徑
• 已清理的設定或清理問題

​

瀏覽器與 VNC

• Headless automation：CI 的預設模式。Chrome 會啟用 CDP 執行， 並由 Playwright 或 OpenClaw 瀏覽器控制擷取螢幕截圖。
• VNC rescue：在同一台 VM 上啟用，用於登入、MFA、Discord 反自動化， 或視覺除錯需要人工介入時。

• 執行 id
• 情境 id
• 機器提供者
• artifact 目錄
• 可用時的 VNC 或 noVNC 連線指示
• 簡短的阻塞原因文字

​

機器

• Linux，且安裝具備桌面能力的 Chrome 或 Chromium
• 用於瀏覽器自動化的 CDP 存取
• 用於救援的 VNC 或 noVNC
• Node 22 和 pnpm
• OpenClaw checkout 與相依套件快取
• 使用 Playwright 時的 Playwright Chromium 瀏覽器快取
• 足夠執行一個 OpenClaw Gateway、一個瀏覽器與一次模型執行的 CPU 和記憶體
• 可對 Discord、GitHub、模型提供者與憑證 broker 進行對外存取

​

秘密

• OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN
• OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN
• OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN
• OPENCLAW_QA_DISCORD_GUILD_ID
• OPENCLAW_QA_DISCORD_CHANNEL_ID
• OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID
• OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 用於公開 GitHub artifact 上傳
• OPENCLAW_QA_CONVEX_SITE_URL
• OPENCLAW_QA_CONVEX_SECRET_CI
• OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR
• OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN

• Discord bot token
• 提供者 API key
• 瀏覽器 cookie
• auth profile 內容
• VNC 密碼
• 原始憑證 payload

​

GitHub artifacts 與 PR 留言

Mantis Discord Status Reactions QA

Summary: Mantis reran the reported Discord status-reaction bug against the known
bad baseline and the candidate fix. The baseline reproduced the bug, while the
candidate showed the expected queued -> thinking -> done sequence.

- Scenario: `discord-status-reactions-tool-only`
- Run: <workflow run link>
- Artifact: <artifact link>
- Baseline: `<status>` at `<sha>`
- Candidate: `<status>` at `<sha>`

| Baseline            | Candidate           |
| ------------------- | ------------------- |
| <inline screenshot> | <inline screenshot> |

​

私人部署注意事項

​

新增情境

• id 和標題
• 傳輸
• 所需憑證
• baseline ref 政策
• candidate ref 政策
• OpenClaw 設定 patch
• 設定步驟
• 刺激
• 預期 baseline oracle
• 預期 candidate oracle
• 視覺擷取目標
• timeout 預算
• 清理步驟

• 反應錯誤使用 Discord reaction state
• threading 錯誤使用 Discord message reference
• Slack 錯誤使用 Slack thread ts 與 reaction API state
• email 錯誤使用 email message id 與 header
• UI 是唯一可靠可觀察項時使用瀏覽器螢幕截圖

​

提供者擴充

• Slack：reactions、threads、app mentions、modals、file uploads。
• Email：在 connectors 不足時，使用 gog 進行 Gmail auth 與 message threading。
• WhatsApp：QR login、re-identification、message delivery、media、reactions。
• Telegram：group mention gating、commands、可用時的 reactions。
• Matrix：encrypted rooms、thread 或 reply relations、restart resume。

​

未解問題

• 重複使用現有 Mantis bot 時，哪個 Discord bot 應作為 driver，哪個應作為 SUT？
• 第一階段的觀察者瀏覽器登入應使用真人 Discord 帳號、測試帳號， 還是只使用 bot 可讀的 REST 證據？
• GitHub 應保留 Mantis PR artifacts 多久？
• ClawSweeper 何時應自動建議 Mantis，而不是等待維護者命令？
• 公開 PR 的螢幕截圖在上傳前是否應遮蔽或裁切？