Mantis

기준일: 2026-07-26
공식 기준: Mantis

Mantis 문서는 OpenClaw 공식 문서(concepts/mantis)를 한국어로 정리한 가이드입니다. Mantis captures visual end-to-end evidence for live transport comparisons and focused candidate-only browser proofs, then attaches the artifacts to PRs. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Mantis captures visual end-to-end evidence for live transport comparisons and focused candidate-only browser proofs, then attaches the artifacts to PRs.

한국어 가이드 범위: concepts/mantis 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Ownership
• CLI commands
• discord-smoke
• run
• desktop-browser-smoke
• slack-desktop-smoke
• telegram-desktop-builder
• Evidence manifest
• GitHub automation
• Machines and secrets
• Run outcomes
• Adding a scenario
• Open questions

상세 내용

본문

Mantis publishes visual CI evidence and a PR comment for OpenClaw behavior. Live transport scenarios compare a known-bad baseline with a candidate ref; focused browser lanes may instead prove one candidate against a deterministic mocked transport. Discord shipped first with real bot auth, guild channels, reactions, threads, and a browser witness. Slack, Telegram, and focused Control UI chat lanes exist too; WhatsApp and Matrix are unimplemented.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Ownership

주요 항목:

• OpenClaw (extensions/qa-lab/src/mantis/*): scenario runtime, pnpm openclaw qa mantis <command> CLI, evidence schema.
• QA Lab (extensions/qa-lab/src/live-transports/*): live transport harness, driver/SUT bots, report/evidence writers.
• Crabbox (openclaw/crabbox): warmed Linux machines, leases, VNC, crabbox media preview.
• GitHub Actions (.github/workflows/mantis-*.yml): remote entrypoints, artifact retention.
• ClawSweeper: parses maintainer PR commands, dispatches workflows, posts the final PR comment.

CLI commands

All commands are pnpm openclaw qa mantis , defined in extensions/qa-lab/src/mantis/cli.ts. Requires OPENCLAW_ENABLE_PRIVATE_QA_CLI=1 at build/run time (bundled workflows set OPENCLAW_BUILD_PRIVATE_QA=1 and OPENCLAW_ENABLE_PRIVATE_QA_CLI=1 before building).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Command	Purpose
discord-smoke	Verify the Mantis Discord bot can see the guild/channel, post, and react.
run	Run a before/after scenario against baseline and candidate refs (Discord only).
desktop-browser-smoke	Lease/reuse a Crabbox desktop, open a visible browser, capture screenshot + video.
slack-desktop-smoke	Lease/reuse a Crabbox desktop, run Slack QA inside it, open Slack Web, capture evidence.
telegram-desktop-builder	Lease/reuse a Crabbox desktop, install Telegram Desktop, optionally configure an OpenClaw gateway.
visual-task / visual-driver	Generic Crabbox desktop capture with optional image-understanding assertions; visual-driver is the driver half launched under crabbox record --while.

discord-smoke

Calls the Discord REST API (https://discord.com/api/v10) to fetch the bot user, the guild, the guild's channels, and the target channel, asserts the channel belongs to the guild, then (unless --skip-post) posts a message and adds a 👀 reaction. Writes mantis-discord-smoke-summary.json and mantis-discord-smoke-report.md.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

run

--transport currently only accepts discord. --scenario is one of two built-in ids, each with its own default baseline ref and expected before/after labels (extensions/qa-lab/src/mantis/run.runtime.ts):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Scenario	Default baseline	Baseline expects	Candidate expects
discord-status-reactions-tool-only	0bf06e953fdda290799fc9fb9244a8f67fdae593	queued-only	queued -> thinking -> done
discord-thread-reply-filepath-attachment	81349cdc2a9d5143fd0991ed858b739e7d96e05c	thread reply omits filePath attachment	thread reply includes it

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

desktop-browser-smoke

Leases or reuses a Crabbox desktop, launches a browser inside the VNC session pointed at --browser-url (default https://openclaw.ai) or a rendered --html-file, waits, screenshots with scrot, optionally records an MP4 with ffmpeg, and rsyncs desktop-browser-smoke.png / .mp4 / remote-metadata.json back to --output-dir.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• --lease-id <cbx_...> reuses a warmed desktop instead of creating one.
• --browser-profile-dir <remote-path> reuses a remote Chrome user-data-dir so a persistent desktop stays logged in between runs (used for a long-lived Discord Web viewer profile).
• --browser-profile-archive-env <name> restores a base64 .tgz Chrome profile archive from that env var before launch (default OPENCLAW_MANTIS_BROWSER_PROFILE_TGZ_B64); used for logged-in witnesses like Discord Web.
• --video-duration <seconds> controls MP4 capture length (default 10s).
• --keep-lease (or OPENCLAW_MANTIS_KEEP_VM=1) keeps a lease this run created open for VNC inspection; failed runs that created a lease also keep it by default.

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

slack-desktop-smoke

Leases or reuses a Crabbox desktop, syncs the checkout into the VM, runs pnpm openclaw qa slack inside it, opens Slack Web in the VNC browser, captures the desktop, and copies both the Slack QA artifacts (slack-qa/) and the VNC screenshot/video back locally. This is the only Mantis shape where the SUT gateway and the browser both run inside the same VM.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• OPENCLAW_QA_SLACK_CHANNEL_ID
• OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_APP_TOKEN
• OPENCLAW_LIVE_OPENAI_KEY for the remote model lane (if only OPENAI_API_KEY

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

telegram-desktop-builder

Leases or reuses a Crabbox desktop, installs native Linux Telegram Desktop, optionally restores a user-session archive, configures OpenClaw with the leased Telegram SUT bot token, starts openclaw gateway run --dev --allow-unconfigured --port 38974, posts a driver-bot readiness message to the leased private group, then captures a screenshot and MP4. A bot token only configures OpenClaw; it never logs Telegram Desktop in. The desktop viewer is a separate Telegram user session restored from --telegram-profile-archive-env or logged in manually through VNC and kept alive with --keep-lease.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Evidence manifest

Every scenario that publishes to a PR writes mantis-evidence.json next to its report:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

.artifacts/qa-e2e/mantis/<run-id>/
  mantis-report.md
  mantis-evidence.json
  baseline/
  candidate/
  comparison.json

GitHub automation

scripts/mantis/publish-pr-evidence.mjs is the reusable publisher. Workflows call it with the manifest, target PR, artifact target root, comment marker, artifact URL, run URL, and request source. It uploads declared artifacts to the Mantis R2 bucket, builds a summary-first PR comment with inline images/previews and linked videos, then updates the existing marker comment or creates a new one. Required env:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• MANTIS_ARTIFACT_R2_ACCESS_KEY_ID
• MANTIS_ARTIFACT_R2_SECRET_ACCESS_KEY
• MANTIS_ARTIFACT_R2_BUCKET (workflows set openclaw-crabbox-artifacts)
• MANTIS_ARTIFACT_R2_ENDPOINT
• MANTIS_ARTIFACT_R2_REGION (workflows set auto)
• MANTIS_ARTIFACT_R2_PUBLIC_BASE_URL (workflows set https://artifacts.openclaw.ai)

Workflow	Trigger	What it does
Mantis Discord Smoke	manual dispatch	Runs discord-smoke against a chosen ref.
Mantis Discord Status Reactions	PR comment or manual dispatch	Builds separate baseline/candidate worktrees, runs discord-status-reactions-tool-only on each, renders each lane's timeline in a Crabbox desktop browser, generates motion-trimmed GIF/MP4 previews with crabbox media preview, uploads artifacts, posts inline PR evidence.
Mantis Scenario	manual dispatch	Generic dispatcher: takes scenario_id (discord-status-reactions-tool-only, discord-thread-reply-filepath-attachment, slack-desktop-smoke, telegram-live, telegram-desktop-proof, web-ui-chat-proof), baseline_ref, candidate_ref, pr_number, and forwards to the matching scenario workflow.
Mantis Slack Desktop Smoke	manual dispatch	Leases a Crabbox Linux desktop (defaults to aws, choice of hetzner), runs slack-desktop-smoke --gateway-setup against the candidate, records the desktop, generates a motion preview, uploads artifacts, posts PR evidence when a PR number is given.
Mantis Telegram Live	PR comment or manual dispatch	Runs the bot-API Telegram live QA lane (openclaw qa telegram), writes mantis-evidence.json from the QA summary, renders redacted evidence HTML through a Crabbox desktop browser, generates a motion GIF, posts PR evidence. Telegram Web login is not required for this lane.
Mantis Telegram Desktop Proof	maintainer PR label (mantis: telegram-visible-proof) plus PR comment, or manual dispatch	Agentic native Telegram Desktop before/after proof. Hands the PR, baseline/candidate refs, and maintainer instructions to Codex, which runs the real-user Crabbox Telegram Desktop proof lane for both refs and posts a 2-column PR evidence table.
Mantis Web UI Chat Proof	PR comment or manual dispatch	Runs the focused OpenClaw Control UI chat Playwright proof against the candidate, verifies the browser sends through the mocked Gateway, captures screenshot/video artifacts, and posts PR evidence. This lane is web chat proof only, not WinUI/native-app or arbitrary visual proof.

@openclaw-mantis discord status reactions
@openclaw-mantis discord status reactions baseline=origin/main candidate=HEAD
@openclaw-mantis telegram
@openclaw-mantis telegram scenario=telegram-status-command
@openclaw-mantis telegram scenarios=telegram-status-command,channel-canary
@openclaw-mantis web ui chat
@openclaw-mantis web-ui-chat candidate=HEAD

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

Machines and secrets

Local CLI Crabbox defaults are --provider hetzner --class beast; override with --provider, --class/--machine-class, or OPENCLAW_MANTIS_CRABBOX_PROVIDER / OPENCLAW_MANTIS_CRABBOX_CLASS. GitHub workflows commonly override both (for example --class standard, and the Slack workflow's aws/hetzner provider choice input). If a provider is too slow or unavailable, add it behind the same Crabbox interface rather than hardcoding a fallback.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN
• OPENCLAW_QA_DISCORD_GUILD_ID
• OPENCLAW_QA_DISCORD_CHANNEL_ID
• Local qa mantis run --credential-source env also requires
• OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 for public artifact uploads
• OPENCLAW_QA_CONVEX_SITE_URL, OPENCLAW_QA_CONVEX_SECRET_CI
• OPENAI_API_KEY (or the Telegram Desktop proof-specific
• CRABBOX_COORDINATOR / CRABBOX_COORDINATOR_TOKEN (workflows also accept
• CRABBOX_ACCESS_CLIENT_ID, CRABBOX_ACCESS_CLIENT_SECRET
• MANTIS_GITHUB_APP_ID, MANTIS_GITHUB_APP_PRIVATE_KEY

Run outcomes

Before/after transport scenarios distinguish these outcomes so a flaky environment does not read as a product regression:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Bug reproduced: baseline failed the way the scenario expects.
• Harness failure: environment setup, credentials, transport API, browser,

Adding a scenario

Live transport scenarios are TypeScript-defined per transport (see MANTIS_SCENARIO_CONFIGS in extensions/qa-lab/src/mantis/run.runtime.ts for the Discord before/after shape), not a standalone declarative file format. Each scenario needs: id and title, transport, required credentials, baseline ref policy, candidate ref policy, OpenClaw config patch, setup/stimulus steps, expected baseline and candidate oracle, visual capture targets, timeout budget, and cleanup steps.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Open questions

주요 항목:

• Which Discord bot should be the driver vs. the SUT when the existing Mantis
• How long should GitHub retain Mantis artifacts for PRs?
• When should ClawSweeper automatically recommend a Mantis scenario instead of
• Should screenshots be redacted or cropped before upload for public PRs?

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/mantis
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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 desktop-browser-smoke \
  --output-dir .artifacts/qa-e2e/mantis/desktop-browser

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

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

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

관련 링크

• 공식 원문: concepts/mantis
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.