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，设备自动加入可信列表。

环境准备

# 创建独立 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())

使用流程

1. 运行脚本 → 生成 /tmp/tg_qr.png
2. 用户手机 Telegram → 设置 → 设备 → 扫描QR码
3. 扫完即登录成功，session文件自动保存
4. 以后复用这个session，无需再验证码

推送QR码给用户（示例）

# 发送图片给Telegram用户
with open("/tmp/tg_qr.png", "rb") as f:
    await client.send_file("telegram_chat_id", f)

常见坑

关键发现

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：

curl -s -X POST "https://api.github.com/gists" \
  -H "Authorization: token \x3CPAT>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "\x3C标题>",
    "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 \x3Ctoken> 或浏览器交互方式认证
4. clawhub skill publish \x3Cpath> --slug \x3Cslug>

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

适用场景

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