{"skill":{"slug":"telegram-qr-login-workaround","displayName":"Telegram QR Login Workaround","summary":"Telegram新设备登录 — 绕过PHONE_CODE_EXPIRED错误，用QR码扫描代替验证码，附脚本和完整流程","description":"---\nname: telegram-qr-login-workaround\ndescription: Telegram新设备登录 — 绕过PHONE_CODE_EXPIRED错误，用QR码扫描代替验证码，附脚本和完整流程\ntriggers:\n  - telegram 登录 验证码 过期\n  - PHONE_CODE_EXPIRED\n  - telegram 新设备 登录失败\n  - telethon qr_login\n---\n\n# Telegram QR Login — 绕过\"PHONE_CODE_EXPIRED\"的终极方案\n\n## 问题症状\n\n用 Pyrogram/Telethon 通过手机号+验证码登录 Telegram 时：\n- 验证码明明刚收到，立即写入文件\n- 仍然报 `PHONE_CODE_EXPIRED`\n- Telegram 官方邮件说\"Device not approved\"\n\n## 根本原因\n\nTelegram 的新设备登录安全机制：\n1. 检测到来自新设备（IP/设备指纹）\n2. 要求在**手机 App**上手动批准（设置 → 设备 → 批准新设备）\n3. 验证码本身没问题，但设备未被批准 = 直接过期\n\n**注意**：`PHONE_CODE_EXPIRED` 在这里是误导性错误，真实原因是\"设备未批准\"，而非5分钟超时。\n\n## 解决方案：QR码登录（100%有效）\n\n用 Telethon 的 `qr_login()` 方法，让用户直接扫QR，设备自动加入可信列表。\n\n### 环境准备\n\n```bash\n# 创建独立 Python 环境（推荐3.12）\npython3 -m venv /tmp/tg_env\nsource /tmp/tg_env/bin/activate\npip install telethon qrcode pillow\n```\n\n### 完整脚本\n\n```python\nimport asyncio, os, qrcode\nfrom telethon import TelegramClient\n\nAPI_ID = \"你的api_id\"        # https://my.telegram.org\nAPI_HASH = \"你的api_hash\"    # 同上\nSESSION_PATH = \"/path/to/session\"  # session文件路径\n\nOUT_PNG = \"/tmp/tg_qr.png\"\n\nasync def main():\n    client = TelegramClient(SESSION_PATH, API_ID, API_HASH)\n\n    print(\"Connecting...\", flush=True)\n    await client.connect()\n    print(\"Connected. Generating QR...\", flush=True)\n\n    # 获取QR码\n    qr_login = await client.qr_login()\n    url = qr_login.url\n    print(f\"QR URL: {url}\", flush=True)\n\n    # 生成PNG图片\n    img = qrcode.make(url)\n    img.save(OUT_PNG)\n    print(f\"QR saved: {OUT_PNG}\", flush=True)\n\n    # 等待扫码完成\n    print(\"Waiting for scan...\", flush=True)\n    await qr_login.wait()\n    print(\"Scanned!\", flush=True)\n\n    me = await client.get_me()\n    print(f\"OK: {me.first_name} @{me.username} ID={me.id}\", flush=True)\n    await client.disconnect()\n\nasyncio.run(main())\n```\n\n### 使用流程\n\n1. 运行脚本 → 生成 `/tmp/tg_qr.png`\n2. 用户手机 Telegram → 设置 → 设备 → 扫描QR码\n3. 扫完即登录成功，session文件自动保存\n4. 以后复用这个session，无需再验证码\n\n### 推送QR码给用户（示例）\n\n```python\n# 发送图片给Telegram用户\nwith open(\"/tmp/tg_qr.png\", \"rb\") as f:\n    await client.send_file(\"telegram_chat_id\", f)\n```\n\n## 常见坑\n\n| 错误 | 原因 | 解决 |\n|------|------|------|\n| `PHONE_CODE_EXPIRED` | 设备未批准，被误判为超时 | 用QR码登录 |\n| `PHONE_NUMBER_INVALID` | 短时间内请求次数过多被封 | 等2分钟再试 |\n| `PeerUser not found` (删私聊时) | 对话已不存在 | 跳过，无需处理 |\n| QR扫描后立即过期 | 网络问题或IP不稳定 | 换个网络重试 |\n\n## 关键发现\n\n1. **验证码过期 ≠ 真的过期**：Telegram 的错误信息有误导性\n2. **QR码绕过所有验证**：扫描即入可信设备列表，不需要手机号验证\n3. **Session 格式**：Telethon 和 Pyrogram 的 session 文件格式**互不兼容**，选一个一直用\n4. **独立 venv**：避免系统 Python 包冲突\n\n## 批量清理对话\n\n清理可疑频道/陌生私聊：见 `references/telegram-cleanup-workflow.md`（含脚本 + 失败处理）\n\n## 发布到 GitHub / ClawHub\n\n### GitHub Gist（最快，1分钟搞定）\n\n用户去 https://github.com/settings/tokens/new 创建 PAT（勾 `gist` scope），发给你后用 curl 直接调用 GitHub API：\n\n```bash\ncurl -s -X POST \"https://api.github.com/gists\" \\\n  -H \"Authorization: token <PAT>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"description\": \"<标题>\",\n    \"public\": true,\n    \"files\": {\n      \"telegram-qr-login.md\": {\"content\": \"...\"}\n    }\n  }'\n```\n\n返回 `html_url` 即为发布链接。无需 `gh` CLI，无需登录。\n\n### ClawHub\n\nClawHub 需要独立的 GitHub OAuth 登录（`Sign in with GitHub`），不支持 GitHub PAT。\n流程：\n1. `npm i -g clawhub`（已装）\n2. 用户在 https://clawhub.ai/login 用 GitHub OAuth 登录\n3. 登录后用 `clawhub login --token <token>` 或浏览器交互方式认证\n4. `clawhub skill publish <path> --slug <slug>`\n\n注意：ClawHub skill 存储在 Convex 数据库，GitHub 仓库 openclaw/clawhub 的 skills/ 目录是模板，非实际发布路径。\n\n## 适用场景\n\n- 新设备首次登录 Telegram\n- 账号因频繁验证请求被临时封禁\n- 自动化脚本需要无感知的长期登录\n","topics":["Telegram"],"tags":{"latest":"1.0.0","login":"1.0.0","pyrogram":"1.0.0","qr":"1.0.0","telegram":"1.0.0","telethon":"1.0.0"},"stats":{"comments":0,"downloads":329,"installsAllTime":12,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778373308641,"updatedAt":1779076292736},"latestVersion":{"version":"1.0.0","createdAt":1778373308641,"changelog":"Initial release — Telegram QR扫码绕过PHONE_CODE_EXPIRED登录问题\n\n- 提供详尽说明，解释PHONE_CODE_EXPIRED出现的真实原因与误导机制。\n- 提供基于Telethon的QR扫码登录完整Python脚本，实现无需手机验证码安全登录。\n- 附详细使用流程、环境依赖安装和常见问题排查。\n- 包含QR图片推送示例、批量对话清理方法及脚本引用。\n- 补充GitHub Gist与ClawHub平台的发布方法说明。\n- 适用于新设备无法验证码登录、频繁验证被限流等场景。","license":"MIT-0"},"metadata":null,"owner":{"handle":"polityang","userId":"s17bxgnxdrs1g7wadp5q392aa983kspy","displayName":"Polityang","image":"https://avatars.githubusercontent.com/u/154330127?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090775791}}