Telegram 链接读取

配置独立 MCP Platform Reader 的用户账号、白名单与 OAuth，并验证读取和撤销权限的完整流程。

Telegram 私有消息链接不适合当作普通网页抓取。Telegram Reader 在独立的 MCP Platform 中使用用户账号，通过 MTProto 读取明确允许的频道和超级群组，再以只读 MCP 工具提供给客户端。不需要再创建一个 BotFather bot，也不需要另行部署 userbot 进程。

截至 2026-09-21：Reader 的 Admin 配置和 MCP 服务已实现；Hanori 的通用 MCP 连接仍缺少这项集成需要的 OAuth 登录与刷新流程。完成本文的 Reader 配置，不代表把链接发给原 Bot 就能自动读取。图片 MCP 的专用 OAuth 授权也不能直接复用。

先分清两个管理面板

位置	负责什么
MCP Platform Admin 的 `/telegram`	Telegram 应用凭据、用户登录、聊天白名单和链接测试
MCP Platform 的 `/mcp/telegram`	对外提供受 OAuth 保护的只读工具
Hanori 面板的 MCP Servers	Bot 侧的外部工具连接与使用范围；当前不能仅填 Reader URL 就完成授权

本文使用 https://mcp.example.com 表示你自己的 MCP Platform 公网 HTTPS 地址，操作时替换为实际域名。它不是 Hanori 文档站的地址。

1. 确认 Reader 服务可用

先让维护者确认部署包含 Telegram Reader，再开始登录：

部署平台显示目标版本已完成，而不只是 Git push 成功。
MCP Platform 的 /health/ready 返回 200，Admin /diagnostics 中数据库、迁移和凭据状态正常。
/telegram 页面可以通过 Owner 账号访问。
服务器可以连接 Telegram 的 MTProto 服务。普通网页能打开，不代表这条网络可用。

首次引入 Reader 的版本包含 0013_wonderful_grim_reaper.sql 迁移。MCP Platform 在 MIGRATION_MODE=run 时启动执行迁移；设置为 skip 时，需要部署流程提前完成迁移。不要把它当作 Hanori 的迁移，也不要为消除报错随意修改生产迁移模式。

升级前准备可恢复的数据库备份，并单独保护现有凭据加密主密钥。Reader 的账号会话保存在加密凭据存储中，不需要挂载额外的 SQLite session 文件，也不需要新增 Telegram 专用环境变量。

首次真实账号测试应确认 Reader 的单实例执行边界。当前共享数据库锁的测试不能代替双副本、网络分区下的真实 Telegram 验收；不要在未确认拓扑前共用同一个 session 跑多个独立部署。

2. 申请 Telegram 应用凭据

按照 Telegram 官方申请说明：

准备一个已在官方客户端注册、可正常使用的 Telegram 用户账号。
登录 my.telegram.org，打开 API development tools。
填写应用信息，取得自己的 API ID 和 API hash。

API ID / API hash 标识 Telegram 应用；用户账号决定能访问哪些聊天；MCP Platform Owner 账号负责管理集成。这三者都不是 Bot Token。

建议用只加入少量目标聊天的专用用户账号缩小访问范围，但专用账号并不免除 Telegram 的风控和使用规则。不要把 API hash、验证码、两步验证密码或 session 放进聊天、截图、issue 或公开文档。

3. 在 MCP Platform Admin 登录

打开 https://mcp.example.com/telegram：

在「Reader 配置」填写 API ID 和 API hash，保持 Reader 关闭，点击「保存配置」。
在「连接 Telegram 账号」输入带国家区号的手机号，点击「发送登录验证码」。
输入 Telegram 发来的最新验证码；如果账号开启两步验证，再输入密码并完成登录。
确认页面显示「已就绪」以及预期的用户账号。

登录挑战有效期为 10 分钟，重复发送验证码有 60 秒冷却，连续错误最多 5 次。遇到过期提示时重新开始登录，不要反复发送验证码或重放旧请求。

已保存的 API hash 不会回显，留空表示保留。替换应用凭据时需要同时填写 API ID 和 API hash。验证码和两步验证密码不会持久化到 Reader 数据库。

4. 加入目标并保存白名单

在 Telegram 官方客户端中，让刚登录 Reader 的用户账号加入目标频道或超级群组。
回到 Admin，点击「加载群组和频道」。
先只选择一个自己创建、包含自己测试消息的目标。
核实内容使用权限后勾选确认项，打开「启用 Telegram Reader」。
点击「保存配置」，再进行链接测试。

原 Bot 在群里，不等于这个用户账号也有权限。公开频道也必须经过发现并保存到白名单，页面不会自动入群。当前发现最多请求最近 100 个对话，排除私聊、旧式普通群组、已退出目标和受保护内容；列表不是账号全部聊天的目录。

内容可以访问，不代表可以交给 AI

Telegram API 条款和内容授权条款对 AI 使用有明确限制。条款描述的例外涉及所有相关用户针对具体内容与聊天范围提供明确、知情、肯定且持续的同意，并非公开内容自动获准。

Admin 的确认项只是操作声明，不能代替许可或相关用户同意。未核实适用权限前保持 Reader 关闭；不要把第三方聊天接入 AI。

5. 在 Admin 完成首次读取

在自己的测试超级群组发送一条无敏感信息的消息，复制它的消息链接，粘贴到「测试 Telegram 链接」。将「前后各读取的消息数」设为 0，点击「通过 Telegram 读取」，核对返回正文。

支持的链接形态包括公开频道用户名链接、/s/ 预览链接、/c/ 私有消息链接，以及带 topic ID 的消息链接。使用从 Telegram 复制的规范 HTTPS t.me 链接；不支持邀请链接、评论查询参数或任意其他网站。

验收动作	预期结果
读取白名单内的测试消息	正文与原消息一致
读取已获准的频道链接	返回有限数量的近期消息
读取非白名单目标	明确拒绝，不绕过权限抓取网页
关闭 Reader 并保存后再读	拒绝读取
重新启用并保存，在维护窗口重启应用后再读	登录和白名单保留，仍能读取
退出并撤销 Reader 设备	再次使用前需要重新登录

频道读取最多 20 条，单条消息前后文最多各 5 条。文本可能因大小限制被截断；前后文是邻近消息采样，不保证补齐讨论串。Reader 不下载附件、不读取私聊、不发送或删除消息、不持续监听，也不提供全历史搜索。

不要为测试连接生产数据库运行开发用集成测试或验收脚本。真实账号使用上述小范围手工流程，自动化测试应使用隔离环境。

6. 使用 OAuth MCP 客户端验证

先选用支持远程 MCP OAuth 的客户端，按其当前界面配置：

字段	值
MCP 地址	`https://mcp.example.com/mcp/telegram`
传输	Streamable HTTP
认证	OAuth
读取 scope	`mcp:telegram:read`

Admin 的「复制端点」当前只复制 /mcp/telegram；外部客户端需要完整域名。按客户端流程打开授权页，以 MCP Platform Owner 身份登录并同意对应资源的权限。需要长期使用时，客户端还应处理刷新授权，不能只保存一次短期访问令牌。

授权后先调用 list_allowed_telegram_chats，确认只返回获准目标，再用 read_telegram_link 读取同一条测试消息。工具参数 url 填实际消息链接，context 先设 0；读取频道时可设置较小的 limit。

API hash 不是 MCP Bearer Token；已有 PixAI 或通知 token 也不能复用到这个资源。访问令牌当前有效期为 10 分钟，不建议手工复制到静态 headers 作为长期方案。未经授权访问端点出现 401 是正常保护行为，不应关闭认证来解决。

Reader 返回文本是不可信内容，不应被当作指令覆盖系统提示词。客户端应限制工具调用和结果分发范围。

7. 要让原 Bot 自动读取，还差什么

当前 Hanori 的通用 MCP 管理器仅通过静态 headers 建立连接；已有图片 MCP 使用专用 OAuth 流程，不等于通用 MCP 已支持 Reader 授权。因此本文到此可以验收 Admin → Telegram 和 OAuth 客户端 → Reader，不能宣称 原 Bot → Reader 已完成。

后续接入需要实现并验证：

Owner 授权入口、回调校验、加密令牌存储和自动刷新。
哪些 Bot、用户和聊天可使用 Reader，避免群成员借 Owner 账号读取其他私有群。
遇到 t.me 链接优先调用 Reader 的工具选择；权限拒绝时清楚说明，不绕过限制。
访问令牌过期、应用重启、撤销授权，以及实际向 Bot 发送链接的端到端行为。

通用工具治理原则见 MCP 服务器。在这些工作完成前，不要仅因面板能保存 MCP URL 就认为连接已可用。

配置后的维护与排错

正常运行不需要反复登录。新增目标时先在官方客户端加入，再加载群组、更新白名单并保存；不再需要的目标及时从白名单移除。

现象	处理顺序
找不到目标群组	确认登录账号、成员资格、群组类型、内容保护和最近 100 个对话的发现上限
`CHAT_NOT_ALLOWED`	确认白名单已保存、账号仍有访问权、目标未启用内容保护
`INVALID_CODE` / `INVALID_PASSWORD`	输入最新验证码或正确的两步验证密码，避免连续重试
`LOGIN_EXPIRED` / `SESSION_EXPIRED`	按提示重新登录，不共用或复制 session 到其他程序
`READER_BUSY`	等待当前操作结束后重试，不并发反复点击
配置冲突	刷新最新状态，确认其他管理页面没有同时修改，再保存
网络超时	检查服务健康和服务器到 Telegram 的网络，不先轮换密钥
MCP 401 / 403	检查 OAuth 授权、scope、资源地址及令牌刷新，不关闭认证

临时停用时关闭 Reader 并保存；彻底停用时使用「退出并撤销此设备」。这不会登出账号的其他设备。网络故障导致撤销失败时，在 Telegram 官方客户端的设备管理中撤销对应 Reader 会话。

保持数据库与主密钥备份可恢复。应用回退前先停用 Reader，并确认旧版本与迁移及加密凭据格式兼容；不要直接让旧版本轮换新 Reader 凭据或删除迁移记录。

最后分别记录部署版本、健康状态、Admin 真实读取、OAuth 客户端调用和 Bot 端到端结果。构建、CI 或模拟测试通过，都不能代替真实 Telegram 登录和生产流程验证。

本页内容