Telegram QR Login — 绕过"PHONE_CODE_EXPIRED"的终极方案
问题症状
用 Pyrogram/Telethon 通过手机号+验证码登录 Telegram 时：
- 验证码明明刚收到，立即写入文件
- 仍然报
PHONE_CODE_EXPIRED - Telegram 官方邮件说"Device not approved"
根本原因
Telegram 的新设备登录安全机制：
- 检测到来自新设备（IP/设备指纹）
- 要求在手机 App上手动批准（设置 → 设备 → 批准新设备）
- 验证码本身没问题，但设备未被批准 = 直接过期
注意：PHONE_CODE_EXPIRED 在这里是误导性错误，真实原因是"设备未批准"，而非5分钟超时。
解决方案：QR码登录（100%有效）
用 Telethon 的 qr_login() 方法，让用户直接扫QR，设备自动加入可信列表。
环境准备
# 创建独立 Python 环境（推荐3.12）
python3 -m venv /tmp/tg_env
source /tmp/tg_env/bin/activate
pip install telethon qrcode pillow
完整脚本
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())
使用流程
- 运行脚本 → 生成
/tmp/tg_qr.png - 用户手机 Telegram → 设置 → 设备 → 扫描QR码
- 扫完即登录成功，session文件自动保存
- 以后复用这个session，无需再验证码
推送QR码给用户（示例）
# 发送图片给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不稳定 | 换个网络重试 |
关键发现
- 验证码过期 ≠ 真的过期：Telegram 的错误信息有误导性
- QR码绕过所有验证：扫描即入可信设备列表，不需要手机号验证
- Session 格式：Telethon 和 Pyrogram 的 session 文件格式互不兼容，选一个一直用
- 独立 venv：避免系统 Python 包冲突
批量清理对话
清理可疑频道/陌生私聊：见 references/telegram-cleanup-workflow.md（含脚本 + 失败处理）
发布到 GitHub / ClawHub
GitHub Gist（最快，1分钟搞定）
用户去 https://github.com/settings/tokens/new 创建 PAT（勾 gist scope），发给你后用 curl 直接调用 GitHub API：
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。
流程：
npm i -g clawhub（已装）- 用户在 https://clawhub.ai/login 用 GitHub OAuth 登录
- 登录后用
clawhub login --token <token>或浏览器交互方式认证 clawhub skill publish <path> --slug <slug>
注意：ClawHub skill 存储在 Convex 数据库，GitHub 仓库 openclaw/clawhub 的 skills/ 目录是模板，非实际发布路径。
适用场景
- 新设备首次登录 Telegram
- 账号因频繁验证请求被临时封禁
- 自动化脚本需要无感知的长期登录