telegram-crabbox-e2e-proof

Telegram Crabbox 端到端验证

当机器人之间的证据仍不足时，可使用此方法进行 Telegram PR 审查或 缺陷复现。目标是让 Agent 保持真实的 Telegram 用户会话处于打开状态， 直到其满意，然后附加可视化证据。

不要使用个人账户。不要将凭据添加到仓库、提示词或 制品包中。运行器从 Convex 租用共享的一次性账号。

开始

在 OpenClaw 仓库中运行，并使用受测分支：

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

这会启动一个持续会话：

• 租用独占的 telegram-user Convex 凭据
• 使用同一用户账户恢复 TDLib 和 Telegram Desktop
• 从当前检出启动模拟 OpenClaw Telegram SUT
• 在可见的 Linux 桌面中选择已配置的 Telegram 聊天
• 以 24 fps 启动桌面录制
• 写入 .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

调查期间请让会话保持运行。Agent 可以花费数分钟进行测试、 运行多个命令、使用 WebVNC、检查记录，并且只有在 理解相关行为后才结束。

为了得到确定性的可视化复现结果，请将确切的模拟模型回复写入文件，并 传递给 start：

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 \
  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

当场景明确需要启用或禁用 Telegram 链接预览时， 请在 Gateway 启动前设置 SUT 配置：

"$proof_cmd" start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --link-preview false \
  --mock-response-chunk-delay-ms 1200 \
  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

不要编辑生成的配置，也不要重启持续会话的 Gateway 来应用 此设置；否则会绕过运行器负责的生命周期和清理流程。 分块延迟会将配置的响应拆分为两个流式增量，使 录像能够显示初始预览和之后的原位编辑。

运行器默认使用 --class standard、--record-fps 24、 --preview-fps 24 和 --preview-width 1920。除非证据需要其他设置， 否则请保留这些默认值。

测试期间

若要获取可视化证据，请先发送或确定一条底部标记消息，然后 通过消息 ID 直接打开群组/主题：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" view \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --message-id <message-id>

此操作直接使用 tg://privatepost 打开 Telegram Desktop，而不是 xdg-open。 它还会在受测桌面位置将 Telegram 调整为 650x1000，这样 即使 Telegram 保持分栏/侧边栏布局，裁剪区域也可单独保留聊天窗格。 此后不要按 Escape；Escape 可能会关闭所选聊天。

底部行为很重要：

• 深度链接到最新消息会使 Telegram 固定在底部，因此 后续消息会实时出现在录像中
• 深度链接到较旧消息不会自动滚动到新消息；请再次 链接到最新/最终标记，而不是点击向下箭头
• 裁剪后的 GIF 有意使用聊天窗格，而不是整个桌面或 整个 Telegram 窗口

以真实 Telegram 用户身份发送：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status

对于斜杠命令，请省略机器人用户名；运行器的目标是 SUT 机器人。

在 Crabbox 上运行任意命令：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$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'

有用的远程用户操控命令：

source /tmp/openclaw-telegram-user-crabbox/env.sh
python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py status --json
python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py chats --json
python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json
python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py send --text '/status@{sut}'
python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py probe --text '@{sut} Reply exactly: USER-E2E-{run}' --expect USER-E2E-

在不结束会话的情况下捕获当前桌面：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" screenshot \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

检查租约状态并获取 WebVNC 命令：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" status \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

结束

务必结束或明确保留该 Crabbox：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --preview-crop telegram-window

finish 会停止录制、创建裁剪掉无动作片段的 MP4/GIF 制品、捕获 最终截图和日志、释放 Convex 凭据、停止本地 SUT， 并终止 Crabbox 租约。--preview-crop telegram-window 还会从受测的 Telegram 证据窗口创建固定尺寸 GIF，以便在 PR 表格中整齐并排 展示；完整桌面的视频/GIF 仍保留在制品目录中。仅当凭据释放后仍需 由人员继续进行 VNC 调试时，才传入 --keep-box。

发生任何失败或中断后，请确认清理情况：

crabbox list --provider aws

如果存在会话文件且凭据可能仍处于租用状态，请在重试前使用该会话 文件运行 finish。

附上证明

除非需要日志，否则只将有用的视觉材料附到 PR。运行器默认 仅支持 GIF：

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

这会仅将有用的 GIF 复制到临时发布包中，并用该 GIF 发表评论。 如果 finish --preview-crop telegram-window 生成了裁剪后的 GIF， 发布时就使用该 GIF；否则使用 telegram-user-crabbox-session-motion.gif。 仅当 PR 需要日志或 JSON 输出时才使用 --full-artifacts。绝不发布 凭据载荷、本地环境文件、TDLib 数据库、Telegram Desktop 配置文件或原始会话归档。

如需前后对比证明，请在 main 上运行一个会话，在 PR 最新提交上运行 另一个会话，然后从干净的发布包中仅发布预期的 GIF：

mkdir -p .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison
cp <main-output>/telegram-user-crabbox-session-motion-telegram-window.gif \
  .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison/main-before.gif
cp <pr-output>/telegram-user-crabbox-session-motion-telegram-window.gif \
  .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison/pr-after.gif
crabbox artifacts publish \
  --repo openclaw/openclaw \
  --pr 123 \
  --dir .artifacts/qa-e2e/telegram-user-crabbox/pr-123/comparison \
  --summary 'Telegram before/after proof' \
  --no-comment

然后发布一个包含这两个 URL 的简洁 Markdown 表格。除非明确需要这些材料， 否则不要发布包含截图、原始视频、日志、会话 JSON 或裁剪实验的工作目录：

快速冒烟测试

进行快速一次性检查时，请使用：

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

这是 start/send/finish 快捷方式。进行 PR 审查、问题复现， 或任何 Agent 可能需要尝试多次的任务时，请优先使用长驻会话。