telegram-userbots

Telegram 用户机器人——MTProto，以及它的代价

机器人令牌是发给软件的。MTProto 会话是一个已登录的人——它保存在文件中，拥有该用户同等的权限，却没有令牌具备的任何保护措施。本技能中的一切都源于这一区别。

根据 Telethon 1.44.0 和 core.telegram.org 于 2026-08-25 查阅。Telethon 的次要版本会改变会话和实体缓存行为；你使用的版本是需要核实的事实，不应想当然。

深入内容，按需加载：

阅读	适用场景
references/sessions-and-auth.md	登录、存储会话、轮换会话，或在不同机器间迁移
references/rate-and-flood.md	任何遍历聊天、用户或消息的操作——FloodWait、节奏控制、数据导出
references/entities-and-history.md	解析对等方、遍历历史记录、大规模下载媒体

---

首先：你真的需要一个用户机器人吗？

写下任何代码之前，先回答这个问题，并把答案记下来。

工作	Bot API 可以做到	结论
回复机器人所在聊天中的消息	可以	使用机器人
向已启动机器人的用户发送消息	可以	使用机器人
读取其担任管理员的公开频道	可以	使用机器人
读取其未担任管理员的频道历史记录	不可以	用户机器人
读取加入聊天之前的历史记录	不可以	用户机器人
以特定人士的身份行事	不可以	用户机器人
下载超过 20 MB 的文件	不可以	用户机器人，或本地 Bot API 服务器
大规模枚举群组成员	不可以	用户机器人，另请参阅下方风险

**本地 Bot API 服务器可以突破文件大小上限，无需使用账号。**为了一个 21 MB 的视频而动用用户会话，相当于用永久性风险换取一项本来就要处理的基础设施任务。

**拒绝的理由，不是走形式：**用户账号可能会受到限制或被封禁，而 Telegram 不会说明原因、不会快速受理申诉，也不会恢复账号中的内容。如果账号属于真实人士，受影响的将是其消息、群组和登录状态。自动化个人账号必须由明确的责任人作出决定，否则就不能算是经过决策。

会话文件就是凭据

import os
from telethon import TelegramClient
from telethon.sessions import StringSession

client = TelegramClient(
    session=StringSession(os.environ["TG_SESSION"]),   # from the secret store
    api_id=int(os.environ["TG_API_ID"]),
    api_hash=os.environ["TG_API_HASH"],
)

• **.session 文件可以授予账号的完整访问权限，无需密码，也无需通过 2FA 提示。**将它复制到另一台机器，就会让那台机器登录账号。它应加入 .gitignore，存入密钥库，备份时也应像对待密码一样谨慎——绝不能放进镜像层或日志中。
• api_id/api_hash 来自 my.telegram.org，用于标识应用，而不是账号。它们不是会话，也不是同等敏感级别的机密，但仍不应公开。
• **会话丢失可以恢复；会话泄露则属于安全事件。**在账号自己的设备页面撤销会话，这会在所有地方结束该会话。
• 退出登录并不等于锁定账号，而终止会话需要依赖较早的会话。auth.logOut 可能返回一个 future_auth_token，可跳过下一次登录验证码，因此两步验证密码才是真正的防线；创建时间不足 24 小时的会话无法终止其他会话（FRESH_RESET_AUTHORISATION_FORBIDDEN）。接受 tg://login?token= 链接，就会登录生成该链接的人所对应的账号。列出、监控（UpdateNewAuthorization）并终止会话： references/sessions-and-auth.md。
• 于 2026-08-25 在这台机器上核实：五个 Telethon 项目都将会话加入 gitignore，没有任何会话被 git 跟踪——这是这套环境中唯一已排除的隐患。务必继续保持。

FloodWaitError 就是 API 的正常工作方式

from telethon.errors import FloodWaitError

try:
    await client.send_message(peer, text)
except FloodWaitError as e:
    if e.seconds > MAX_ACCEPTABLE:      # a decision, not a sleep
        raise
    await asyncio.sleep(e.seconds + 1)
    await client.send_message(peer, text)

• 这不是一个可以忽略的失败，也不是盲目重试的信号。 它会明确告知需要等待多久；不按提示操作，就是在猜 Telegram 已经告诉你的数字。
• seconds 非常大，意味着发生了不同的情况。 几分钟说明你的操作频率过高；几小时则说明账号受到限制，继续操作只会让限制升级为封禁。设置上限、发出警报，然后停止。
• 在请求处理程序中休眠，会让一次限流变成服务中断。 等待应放在带队列的工作进程中，而不是放在用户正在等待的处理流程里。
• 截至 2026-08-25，对这里的六个 Telethon 项目进行统计：六个中只有三个会处理 FloodWaitError。 另外三个会一直运行，直到遇到首次限流，然后在当时的状态下停止。

固定次版本，并了解原因

这套环境中的四个机器人固定使用 telethon==1.37.0，另一个使用 1.44.0；requirements.txt 中也写明了固定版本的原因：次版本更新会改变会话和实体缓存的行为；对于正在运行的机器人，跨越七个次版本进行升级，应作为独立变更处理并单独验证。

这做法很合理，值得作为准则明确下来。用户机器人依赖的不是普通库，而是持有登录状态的协议客户端。 升级可能导致会话格式失效、改变 get_entity 的开销，或变更异常所在的模块。应有计划地升级，每次只升级一个机器人，并确保会话可以重新创建。

实体需要解析，而且解析并非零成本

get_entity 可能会访问网络，在循环中调用它是最常见的原因之一，会导致看似莫名其妙的 FloodWait。

• 优先使用已有的 ID。 缓存的 InputPeer 不产生开销；用户名则需要发起请求。
• **PeerIdInvalidError 通常表示该账号从未遇到过这个 peer，**而不是 ID 错误。用户账号只能联系自己遇到过的对象。
• 使用库自带的迭代器（iter_messages、iter_dialogs），让它们负责分页；手动实现偏移量会导致重复请求，再次触发限流。
• 批量导出时，可以使用 takeout，这是获准的途径——它会针对这类操作提高限额，并告知 Telegram 你正在执行此操作。

详见 references/entities-and-history.md。

两个账号，两种生命周期

用户机器人还有一种机器人账号不会遇到的故障模式：用户在别处登录、更改密码或终止会话，导致你的进程持有的会话失效。 这是终止性／已撤销的授权状态，而非暂时性状态：进程可能仍处于 LIVE，但已经 NOT READY；重启只会反复尝试永远无法成功的登录。应发出警报并注明账号，停止工作，直至获得 FRESH 授权（需要手机号重新登录），切勿进入崩溃循环——这与 sheleg-dev 针对任何长期运行的已授权连接所采用的错误跟踪三态约定相同：存活性、就绪性、degraded_auth（暂时性重试，终止性停止）。监督程序仅在 recoverable 策略下才应重启；已撤销的会话属于 terminal，应进入该技能恢复契约表中的 STOP 并报警项，避免同一事件在两个工具包中触发相反的操作。绝不要让用户机器人处于本可由机器人处理的关键路径上。

上线前检查

1. 已记录用户为何需要账号，并已确认是否有 Bot API 替代方案（§ 首先：你真的需要账号吗？）。
2. 会话已存入机密存储、已加入 gitignore，并且可以撤销（§ 会话文件就是凭证）。
3. 已捕获、限制并针对 FloodWaitError 发出告警——绝不能无限期等待（§ FloodWaitError 说明 API 正在正常工作）。
4. 已固定客户端版本，升级作为单独的变更处理（§ 固定次要版本）。
5. 会话失效时会通知人工处理，而不是无限重启（§ 两个账号，两种生命周期）。
6. 账号已设置两步验证密码，并且有人监控其会话：新的 UpdateNewAuthorization 会通知人工处理，且终止的是最早的受信任会话（§ 会话文件就是凭证）。

触发词

还有一些会将用户引导至此处的短语：“用户账号”“读取频道历史记录”“api_hash”“телетон”。

以下短语已从 0.5.4 版本的描述中移至此处：“pyrogram”“мтпрото”“сессия телеграм”。