{"kind":"Skill","metadata":{"namespace":"community","name":"telegram-crabbox-e2e-proof","version":"0.1.0"},"spec":{"description":"Use when reviewing, reproducing, or proving OpenClaw Telegram behavior with a real Telegram user on Crabbox, including PR review workflows that need an agent-controlled Telegram Desktop recording, TDLib user-driver commands, Convex-leased credentials, WebVNC observation, and motion-trimmed artifacts.","files":{"SKILL.md":"---\nname: telegram-crabbox-e2e-proof\ndescription: Use when reviewing, reproducing, or proving OpenClaw Telegram behavior with a real Telegram user on Crabbox, including PR review workflows that need an agent-controlled Telegram Desktop recording, TDLib user-driver commands, Convex-leased credentials, WebVNC observation, and motion-trimmed artifacts.\n---\n\n# Telegram Crabbox E2E Proof\n\nUse this for Telegram PR review or bug reproduction when bot-to-bot proof is\nnot enough. The goal is to let the agent keep a real Telegram user session open\nuntil it is satisfied, then attach visual proof.\n\nDo not use personal accounts. Do not add credentials to the repo, prompt, or\nartifact bundle. The runner leases the shared burner account from Convex.\n\n## Start\n\nRun from the OpenClaw repo and branch under test:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" start \\\n  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \\\n  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review\n```\n\nThis starts one held session:\n\n- leases the exclusive `telegram-user` Convex credential\n- restores TDLib and Telegram Desktop with the same user account\n- starts a mock OpenClaw Telegram SUT from the current checkout\n- selects the configured Telegram chat in the visible Linux desktop\n- starts a 24fps desktop recording\n- writes `.artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json`\n\nKeep the session alive while investigating. It is valid for the agent to test\nfor minutes, run several commands, use WebVNC, inspect transcripts, and only\nfinish once the behavior is understood.\n\nFor deterministic visual repros, put the exact mock-model reply in a file and\npass it to `start`:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" start \\\n  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \\\n  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \\\n  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review\n```\n\nThe runner defaults to `--class standard`, `--record-fps 24`,\n`--preview-fps 24`, and `--preview-width 1920`. Keep those defaults unless the\nproof needs something else.\n\n## While Testing\n\nFor visual proof, first send or identify a bottom marker message, then open the\ngroup/topic directly by message id:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" view \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \\\n  --message-id \u003cmessage-id\u003e\n```\n\nThis uses Telegram Desktop directly with `tg://privatepost`, not `xdg-open`.\nIt also resizes Telegram to `650x1000` at the tested desktop position so\nthe crop can isolate the chat pane even if Telegram keeps a split/sidebar\nlayout. Do not press Escape after this; Escape can close the selected chat.\n\nBottom behavior matters:\n\n- deep-linking to the newest message keeps Telegram pinned to the bottom, so\n  later messages appear live in the recording\n- deep-linking to an older message does not auto-scroll to new arrivals; link\n  again to the newest/final marker instead of clicking the down-arrow\n- the cropped GIF intentionally uses the chat pane, not the whole desktop or\n  whole Telegram window\n\nSend as the real Telegram user:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" send \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \\\n  --text /status\n```\n\nFor slash commands, omit the bot username; the runner targets the SUT bot.\n\nRun arbitrary commands on the Crabbox:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" run \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \\\n  -- bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh \u0026\u0026 python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'\n```\n\nUseful remote user-driver commands:\n\n```bash\nsource /tmp/openclaw-telegram-user-crabbox/env.sh\npython3 /tmp/openclaw-telegram-user-crabbox/user-driver.py status --json\npython3 /tmp/openclaw-telegram-user-crabbox/user-driver.py chats --json\npython3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json\npython3 /tmp/openclaw-telegram-user-crabbox/user-driver.py send --text '/status@{sut}'\npython3 /tmp/openclaw-telegram-user-crabbox/user-driver.py probe --text '@{sut} Reply exactly: USER-E2E-{run}' --expect USER-E2E-\n```\n\nCapture the current desktop without ending the session:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" screenshot \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json\n```\n\nCheck lease state and get the WebVNC command:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" status \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json\n```\n\n## Finish\n\nAlways finish or explicitly keep the box:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" finish \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \\\n  --preview-crop telegram-window\n```\n\n`finish` stops recording, creates motion-trimmed MP4/GIF artifacts, captures a\nfinal screenshot and logs, releases the Convex credential, stops the local SUT,\nand stops the Crabbox lease. `--preview-crop telegram-window` also creates a\nfixed-geometry GIF from the tested Telegram proof window for clean side-by-side\nPR tables; the full desktop video/GIF remains in the artifact directory. Pass\n`--keep-box` only when a human needs to continue VNC debugging after the\ncredential is released.\n\nAfter any failure or interruption, verify cleanup:\n\n```bash\ncrabbox list --provider aws\n```\n\nIf a session file exists and the credential may still be leased, run `finish`\nwith that session file before retrying.\n\n## Attach Proof\n\nAttach only the useful visual artifact to the PR unless logs are needed. The\nrunner is GIF-only by default:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" publish \\\n  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \\\n  --pr \u003cpr-number\u003e \\\n  --summary 'Telegram real-user Crabbox session motion GIF'\n```\n\nThis copies only the useful GIF into a temporary publish bundle and comments\nthat GIF. If `finish --preview-crop telegram-window` produced a cropped GIF,\npublish uses that; otherwise it uses `telegram-user-crabbox-session-motion.gif`.\nUse `--full-artifacts` only when the PR needs logs or JSON output. Never publish\ncredential payloads, local env files, TDLib databases, Telegram Desktop\nprofiles, or raw session archives.\n\nFor before/after proof, run one session on `main` and one on the PR head, then\npublish only the intended GIFs from a clean bundle:\n\n```bash\nmkdir -p .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison\ncp \u003cmain-output\u003e/telegram-user-crabbox-session-motion-telegram-window.gif \\\n  .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison/main-before.gif\ncp \u003cpr-output\u003e/telegram-user-crabbox-session-motion-telegram-window.gif \\\n  .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison/pr-after.gif\ncrabbox artifacts publish \\\n  --repo openclaw/openclaw \\\n  --pr 123 \\\n  --dir .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison \\\n  --summary 'Telegram before/after proof' \\\n  --no-comment\n```\n\nThen post a concise markdown table with those two URLs. Do not publish working\ndirectories that contain screenshots, raw videos, logs, session JSON, or crop\nexperiments unless those artifacts are explicitly needed.\n\n## Quick Smoke\n\nFor a fast one-shot check, use:\n\n```bash\nproof_cmd=\"${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}\"\n\"$proof_cmd\" --text /status\n```\n\nThis is a start/send/finish shortcut. Prefer the held session for PR review,\nissue reproduction, or any task where the agent may need several attempts.\n"},"import":{"commit_sha":"424c6d0a5f4665b803ad6768d08b0be7659deaf4","imported_at":"2026-05-18T20:13:36Z","license_text":"MIT License\n\nCopyright (c) 2025 Peter Steinberger\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","owner":"openclaw","repo":"openclaw/openclaw","source_url":"https://github.com/openclaw/openclaw/tree/424c6d0a5f4665b803ad6768d08b0be7659deaf4/.agents/skills/telegram-crabbox-e2e-proof"}},"content_hash":[26,117,113,72,133,59,50,236,47,102,84,54,9,130,249,2,235,18,123,135,60,201,26,135,21,215,174,76,142,233,235,247],"trust_level":"unsigned","yanked":false}