Skill: polityang/telegram-qr-login-workaround (version 1.0.0)

--- name: telegram-qr-login-workaround description: Telegram新设备登录 — 绕过PHONE_CODE_EXPIRED错误，用QR码扫描代替验证码，附脚本和完整流程 triggers: - telegram 登录 验证码 过期 - PHONE_CODE_EXPIRED - telegram 新设备 登录失败 - telethon qr_login --- # Telegram QR Login — 绕过"PHONE_CODE_EXPIRED"的终极方案 ## 问题症状 用 Pyrogram/Telethon 通过手机号+验证码登录 Telegram 时： - 验证码明明刚收到，立即写入文件 - 仍然报 `PHONE_CODE_EXPIRED` - Telegram 官方邮件说"Device not approved" ## 根本原因 Telegram 的新设备登录安全机制： 1. 检测到来自新设备（IP/设备指纹） 2. 要求在**手机 App**上手动批准（设置 → 设备 → 批准新设备） 3. 验证码本身没问题，但设备未被批准 = 直接过期 **注意**：`PHONE_CODE_EXPIRED` 在这里是误导性错误，真实原因是"设备未批准"，而非5分钟超时。 ## 解决方案：QR码登录（100%有效） 用 Telethon 的 `qr_login()` 方法，让用户直接扫QR，设备自动加入可信列表。 ### 环境准备 ```bash # 创建独立 Python 环境（推荐3.12） python3 -m venv /tmp/tg_env source /tmp/tg_env/bin/activate pip install telethon qrcode pillow ``` ### 完整脚本 ```python import asyncio, os, qrcode from telethon import TelegramClient API_ID = "你的api_id" # https://my.telegram.org API_HASH = "你的api_hash" # 同上 SESSION_PATH = "/path/to/session" # session文件路径 OUT_PNG = "/tmp/tg_qr.png" async def main(): client = TelegramClient(SESSION_PATH, API_ID, API_HASH) print("Connecting...", flush=True) await client.connect() print("Connected. Generating QR...", flush=True) # 获取QR码 qr_login = await client.qr_login() url = qr_login.url print(f"QR URL: {url}", flush=True) # 生成PNG图片 img = qrcode.make(url) img.save(OUT_PNG) print(f"QR saved: {OUT_PNG}", flush=True) # 等待扫码完成 print("Waiting for scan...", flush=True) await qr_login.wait() print("Scanned!", flush=True) me = await client.get_me() print(f"OK: {me.first_name} @{me.username} ID={me.id}", flush=True) await client.disconnect() asyncio.run(main()) ``` ### 使用流程 1. 运行脚本 → 生成 `/tmp/tg_qr.png` 2. 用户手机 Telegram → 设置 → 设备 → 扫描QR码 3. 扫完即登录成功，session文件自动保存 4. 以后复用这个session，无需再验证码 ### 推送QR码给用户（示例） ```python # 发送图片给Telegram用户 with open("/tmp/tg_qr.png", "rb") as f: await client.send_file("telegram_chat_id", f) ``` ## 常见坑 | 错误 | 原因 | 解决 | |------|------|------| | `PHONE_CODE_EXPIRED` | 设备未批准，被误判为超时 | 用QR码登录 | | `PHONE_NUMBER_INVALID` | 短时间内请求次数过多被封 | 等2分钟再试 | | `PeerUser not found` (删私聊时) | 对话已不存在 | 跳过，无需处理 | | QR扫描后立即过期 | 网络问题或IP不稳定 | 换个网络重试 | ## 关键发现 1. **验证码过期 ≠ 真的过期**：Telegram 的错误信息有误导性 2. **QR码绕过所有验证**：扫描即入可信设备列表，不需要手机号验证 3. **Session 格式**：Telethon 和 Pyrogram 的 session 文件格式**互不兼容**，选一个一直用 4. **独立 venv**：避免系统 Python 包冲突 ## 批量清理对话 清理可疑频道/陌生私聊：见 `references/telegram-cleanup-workflow.md`（含脚本 + 失败处理） ## 发布到 GitHub / ClawHub ### GitHub Gist（最快，1分钟搞定） 用户去 https://github.com/settings/tokens/new 创建 PAT（勾 `gist` scope），发给你后用 curl 直接调用 GitHub API： ```bash curl -s -X POST "https://api.github.com/gists" \ -H "Authorization: token <PAT>" \ -H "Content-Type: application/json" \ -d '{ "description": "<标题>", "public": true, "files": { "telegram-qr-login.md": {"content": "..."} } }' ``` 返回 `html_url` 即为发布链接。无需 `gh` CLI，无需登录。 ### ClawHub ClawHub 需要独立的 GitHub OAuth 登录（`Sign in with GitHub`），不支持 GitHub PAT。 流程： 1. `npm i -g clawhub`（已装） 2. 用户在 https://clawhub.ai/login 用 GitHub OAuth 登录 3. 登录后用 `clawhub login --token <token>` 或浏览器交互方式认证 4. `clawhub skill publish <path> --slug <slug>` 注意：ClawHub skill 存储在 Convex 数据库，GitHub 仓库 openclaw/clawhub 的 skills/ 目录是模板，非实际发布路径。 ## 适用场景 - 新设备首次登录 Telegram - 账号因频繁验证请求被临时封禁 - 自动化脚本需要无感知的长期登录


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)