Telegram CrabBox E2E Proof Skill

1. Skill Overview

This skill is designed for Telegram PR reviews and bug reproduction workflows. Its objective is to validate runtime behavior within genuine Telegram user sessions and produce visual evidence such as recorded GIF screencasts. It spins up a Telegram Desktop instance hosted on a Crabbox remote desktop, leases a shared disposable test account via Convex, and enables the Agent to send messages, execute slash commands, and record the full interaction flow just like a real human user.

Core Principle: Never utilize personal accounts; credentials must never be committed to the repository, prompts, or output artifacts.

2. Core Capabilities

2.1 Start a Persistent Session

Launch a long-lived Crabbox session from the OpenClaw repository targeting the test branch:

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

This command performs the following steps:

Lease exclusive telegram-user credentials from Convex
Restore TDLib and Telegram Desktop, logging in under the same disposable test account
Boot a simulated OpenClaw Telegram System Under Test (SUT) from the current git checkout
Navigate to the preconfigured Telegram chat window within a visible Linux desktop session
Start desktop recording at 24 FPS

2.2 Deterministic Visual Reproduction with Mocked Responses

For workflows requiring consistent, repeatable visual outputs, inject static mocked model responses from a file during session initialization:

"$proof_cmd" start \
  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

2.3 Runtime Session Operations

After session startup, the Agent may invoke these interactive subcommands:

View Messages

Directly open a group/topic chat via message ID using native tg://privatepost deep links (avoids generic xdg-open); resizes the Telegram window to 650×1000 for clean chat panel cropping in recordings:

"$proof_cmd" view \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --message-id <id>

Send User Messages

Dispatch chat messages as a real human test user:

"$proof_cmd" send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status

Remote Shell Execution

Run arbitrary shell commands on the remote Crabbox host:

"$proof_cmd" run \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  -- bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh && python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'

Capture Screenshot

Take a static desktop snapshot without terminating the active recording session:

"$proof_cmd" screenshot \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

Check Session Status

Inspect account lease status and retrieve WebVNC connection instructions:

"$proof_cmd" status \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

2.4 User-Driver Script Subcommands

Inside the Crabbox environment, user-driver.py exposes standardized test automation logic:

Command	Purpose
`status --json`	Output structured runtime session state
`chats --json`	Enumerate all available chat threads
`transcript --limit 20 --json`	Fetch JSON-formatted history of the most recent 20 messages
`send --text '/status@{sut}'`	Send slash commands directed at the SUT bot
`probe --text '@{sut} Reply exactly: USER-E2E-{run}' --expect USER-E2E-`	Send validation probe messages and assert matching bot reply prefixes

2.5 Finalize Session & Generate Artifacts

Wrap up testing, finalize all outputs, and release leased resources:

"$proof_cmd" finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --preview-crop telegram-window

The finish workflow executes these steps:

Stop desktop video recording
Generate motion-trimmed MP4 and compressed GIF visual artifacts
Export final static screenshots and full runtime logs
Release the leased Convex test account credentials
Shut down the local SUT instance and terminate the Crabbox lease

2.6 Publish Evidence to Pull Request

Attach visual proof artifacts directly to the target PR thread:

"$proof_cmd" publish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --pr <number> \
  --summary 'Telegram real-user Crabbox session motion GIF'

By default, only the GIF is uploaded; raw logs are omitted. The --full-artifacts flag is only used when complete debug logs are explicitly required.

2.7 One-Click Quick Smoke Test

For lightweight single-shot validation without persistent sessions:

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}" "$proof_cmd" --text /status

This shorthand encapsulates start → send → finish in a single invocation. Persistent held sessions are recommended for PR reviews and iterative bug reproduction requiring multiple retries.

3. Primary Use Cases

Telegram behavior validation during PR reviews

When bot-to-bot automated tests cannot fully reproduce edge cases, run real human-user sessions to capture visual proof of chat interaction logic.
Reproduce Telegram-related functional bugs

Recreate defect conditions within a fully controlled Crabbox environment and record the full failure sequence.
Before/after regression comparison evidence

Execute one full session on the main base branch and another on the PR HEAD branch to generate side-by-side GIF recordings for visual regression comparison in pull requests.
Slash command and bot conversational testing

Send native user slash commands such as /status to validate end-to-end bot response behavior.
Deterministic visual regression suites

Lock model outputs with --mock-response-file to guarantee identical visual recordings across repeated test runs.

4. Critical Guiding Principles

No personal user accounts: All test traffic uses disposable shared burner accounts leased via Convex
Credential secrets must never appear in repository code, prompts, or exported artifacts
Agents may hold sessions open for several minutes to enable multiple retries, manual inspection via WebVNC, and log review until the target behavior is fully understood
The view subcommand does not bind the Escape key; pressing Escape closes the active chat window and breaks recording context
Bottom-aligned chat context is critical: deep-linking to the latest message anchors the Telegram view to the chat bottom, ensuring new inbound messages appear within the recorded frame
Publish only high-value artifacts: default upload limited to GIF screencasts; exclude raw logs, credentials, TDLib databases, and full session archives unless requested
Mandatory cleanup after abnormal failures: if a session JSON file exists and credentials are still leased, run the finish command to release resources before retrying the workflow

Summary

Telegram User Crabbox Proof is a specialized QA skill for PR validation and bug reproduction of OpenClaw’s Telegram bot integration. It spins up isolated remote desktop environments with disposable shared test accounts, simulates real human chat behavior, and generates trimmed GIF video evidence for pull request review. Supporting persistent held sessions, mocked deterministic model responses, remote shell execution, and one-click smoke testing, it delivers repeatable, visual end-to-end validation that pure bot-to-bot unit tests cannot replicate, while enforcing strict credential security and resource cleanup rules.