这是一条从零到可撤销的 Telegram 接入路线。你会先在个人私聊证明 bot、Hermes profile、授权和 session 都正确，再进入一个测试群。任何一步失败都停在当前层，不同时改 BotFather、Gateway、模型和群权限。
本课使用两个唯一标记：私聊 TG-CANARY-417，群聊 TG-GROUP-418。它们没有敏感信息，适合出现在日志和验收表中。
本站验证范围： 本页于 2026-09-09 核读 v0.21.1 / v2026.9.7 当前 Telegram、Messaging Gateway 和 Slash Commands；没有创建真实 bot、保存 token、运行 Gateway 或加入群聊。
下载实验材料
模板只能离线填写。不要把填过 token 的副本提交 Git、发进聊天、上传网盘或截图到验收表。
准备：在 BotFather 创建专用测试 bot
打开 Telegram 的官方 @BotFather：
- 发送
/newbot； - 设置可辨认的 display name；
- 设置以
bot结尾的唯一 username； - 收到 API token 后只放进目标 profile 的
.env； - 验收表只记录 bot username 和 token 已保存，不记录 token 本身。
如果 token 曾出现在 Git、截图、公开聊天或日志附件，立刻在 BotFather 使用 /revoke，用新 token 重新验收。删除泄露消息不能恢复秘密性。
T01：找到数字 user ID 并配置
Hermes 授权使用数字 Telegram user ID，不使用 @username。官方当前推荐向 @userinfobot 获取；也可以使用文档列出的其他方法。将 ID 写入目标 profile 的配置，但公开验收记录只留后四位。
运行：
hermes dump
hermes gateway setup在向导中只选 Telegram，输入 bot token 和允许的数字 user ID。手工配置时核心环境变量是：
TELEGRAM_BOT_TOKEN=<真实 token>
TELEGRAM_ALLOWED_USERS=<你的数字 user ID>没有 TELEGRAM_ALLOWED_USERS 时，当前 Hermes 默认拒绝所有人。不要用开放通配符绕过这一安全默认值。
T02：前台启动并看清错误层
hermes gateway通过标准是 Telegram adapter 初始化，没有 InvalidToken、重复 token、代理或 polling/webhook 冲突。终端保持运行只证明进程层；还不能证明你的账号已授权或回复能送达。
若同一 token 正由另一个 Hermes profile、旧服务或其他 bot 程序 polling，先停止旧消费者。不要同时启动多个进程抢同一个 bot。
T03–T04：先完成授权私聊
用允许账号打开 bot 私聊，先发送：
/whoami记录当前 scope、tier 和命令列表。如果显示 unrestricted 而你计划区分管理员和普通用户，先修正命令权限，再继续。
然后发送：
请只回复 TG-CANARY-417，不调用工具，不补充解释。同一私聊收到精确标记才算 T04 通过。模型回复正确但出现在另一个 chat，属于路由硬失败。
T05：必须做未授权账号负例
使用第二个自控 Telegram 账号向 bot 发送无害问候。预期没有 Agent 回复，Gateway 的脱敏日志显示拒绝或忽略，并且没有启动模型 turn。
不要找陌生人测试，也不要让测试账号发送敏感内容。这个负例只证明 allowlist 门禁，不需要真实攻击样本。
T06：验证 session 不是 Memory
授权私聊运行：
/status
/title telegram-dm-canary重启 Gateway 后再次 /status，当前 session 应继续存在。随后执行：
/new telegram-clean-room
/status只有 /new 或 /reset 才创建新会话。重启后能接上上下文属于 session persistence，不证明长期 Memory；新会话仍知道长期事实时，再按 Memory 教程区分来源。
T07：理解 BotFather Privacy Mode
Telegram 群聊有两层门：
- BotFather Privacy Mode 决定 Telegram 会把哪些群消息交给 bot；
- Hermes allowlist 与 mention 规则 决定已收到的消息是否触发 Agent。
Privacy Mode 默认开启时，bot 主要能收到 slash command、直接回复 bot、服务消息，以及它作为管理员时的频道消息。若你关闭 Privacy Mode，必须把 bot 从既有群移除后重新加入，Telegram 才会刷新该群的投递行为。把 bot 升为群管理员也会让它看到更多消息，但会扩大平台权限，需要单独记录理由。
第一轮建议保持 Privacy Mode 开启，只测试明确 mention 或回复，不要求 bot 观察全部群聊。
T07–T09：只进入一个测试群
先分清数字 chat ID 与 user ID。当前 Hermes 的两种群授权是任选一种权限模型：TELEGRAM_GROUP_ALLOWED_USERS 只授权指定发送者；TELEGRAM_GROUP_ALLOWED_CHATS 授权该群的所有成员。为了让 T09 能验证未授权成员，首轮只使用发送者授权：
TELEGRAM_GROUP_ALLOWED_USERS=<允许触发的 user ID>并保持：
telegram:
require_mention: true
observe_unmentioned_group_messages: false重启 Gateway 后按顺序测试：
- 授权用户发送一条不 mention 的普通消息，bot 不应回复；
- 授权用户发送
@botusername 请只回复 TG-GROUP-418，bot 应在同群回复； - 未授权测试账号 mention bot，不应启动 Agent；
- bot 不加入任何其他群；首轮不扩大入口范围。
如果私聊正常、群聊沉默，按“Telegram 投递 → 重新入群 → 用户/chat allowlist → require_mention”顺序排查。不要先换模型。
可选：观察群聊但只在 mention 时回复
当确实需要后续 mention 使用前文时，可在明确 allowlist 群开启：
telegram:
allowed_chats:
- "<测试群 chat ID>"
group_allowed_chats:
- "<测试群 chat ID>"
require_mention: true
observe_unmentioned_group_messages: true这需要 Telegram 实际投递普通群消息，因此要关闭 Privacy Mode 或把 bot 设为管理员。未 mention 消息会进入共享 chat/topic session 作为 observed context，但不触发 Agent。扩大可见范围前先确认群成员知情、保留周期和敏感信息规则。
T10：限制普通用户的 slash command
当前命令分层放在 gateway.platforms.telegram.extra：
gateway:
platforms:
telegram:
enabled: true
extra:
allow_admin_from:
- "<DM 管理员 user ID>"
user_allowed_commands:
- status
group_allow_admin_from:
- "<群管理员 user ID>"
group_user_allowed_commands:
- status普通用户始终可以使用 /help 与 /whoami。DM admin 不自动成为 group admin；两个 scope 分别验收。让普通用户尝试一个未列出的无害命令，必须被拒绝。
T11：发送一个无害附件
在授权私聊上传一个不含隐私的 .txt，要求只返回文件名和一行摘要。记录是否收到正确文件、是否调用预期工具、是否出现无关主机路径。
如果 Agent 在 Docker backend 中生成文件，最终 MEDIA:/... 必须对运行 Gateway 的主机可读。容器内 /workspace/report.txt 存在，并不代表主机 Gateway 能发送它；需要明确共享 volume 和 host-visible path。
不要在首轮测试语音、超大文件、本地 Bot API 或 webhook。它们有独立网络、文件和权限变量，等 T01–T12 通过后再单独验收。
T12：暂停、恢复和停用
在 chat 或 CLI 中：
/platform pause telegram
/platform list暂停期发送金丝雀；恢复后它不应补跑：
/platform resume telegram最后停止 Gateway：
hermes gateway stop
hermes gateway status若决定弃用，再在 BotFather /revoke 并移除测试群中的 bot。停止进程、删除 bot 成员和撤销 token 是三个不同动作。
完成检查
- token 只存在于目标 profile 的秘密文件，验收表没有复制它。
- 授权私聊的
/whoami和精确金丝雀通过。 - 第二个自控账号被拒绝，没有 Agent turn。
- 你用
/new证明 session 边界，没有把重启误判为新会话。 - 测试群同时通过 unmentioned 静默、authorized mention 回复与 unauthorized mention 拒绝。
- 普通用户的 slash command 范围符合预期。
- 附件、pause/resume、stop 和 token revoke 路径都有记录。
完成后回到 Messaging Gateway 运维手册 填完 G01–G12。需要把结果定时发回 Telegram 时，再进入 Hermes Cron 自动化，不要在本轮同时增加自动触发变量。