Telegram QR Login Workaround — Telegram QR 登录临时解决方案

Telegram QR 登录 — 绕过 "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 " \
  -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 或浏览器交互方式认证

clawhub skill publish  --slug 

注意：ClawHub skill 存储在 Convex 数据库，GitHub 仓库 openclaw/clawhub 的 skills/ 目录是模板，非实际发布路径。

适用场景 新设备首次登录 Telegram 账号因频繁验证请求被临时封禁 自动化脚本需要无感知的长期登录