大菜的数字花园

telegram白名单操作手册

4分钟阅读

Telegram 白名单添加操作手册（实战验证版 v2）

来源：Hermes Agent + WSL2 环境实际踩坑验证。记录了从配置到联调的全链路。

1. 身份识别数据获取

在 Telegram 搜索 @userinfobot，发送任意消息获取 User ID（纯数字字符串）。

  • 核查要点：必须使用纯数字 ID，用户名（@username）无法通过验证。

2. 配置文件

涉及两个文件，存在覆盖优先级关系。

2.1 白名单配置：~/.hermes/config.yaml

telegram:
  allow_from: '[用户ID]'       # 你的数字 ID，建议单引号包裹
  proxy: http://127.0.0.1:7890   # 国内网络连 Telegram 必需

2.2 环境变量：~/.hermes/.env

TELEGRAM_BOT_TOKEN=123456...abc       # Bot Token（唯一存放位置）
# 如果要严格白名单，以下变量绝对不能出现：
# ❌ GATEWAY_ALLOW_ALL_USERS=true     # 大赦开关，会覆盖白名单

3. ⚠️ 关键：大赦开关的覆盖逻辑

.env 中 GATEWAY_ALLOW_ALL_USERS=true 是一个最高优先级的通行开关：

配置组合效果
allow_from 写对 + 无大赦✅ 白名单生效，仅指定 ID 可用
allow_from 写对 + 有大赦⚠️ 大赦覆盖白名单，人人都能用
无 allow_from + 有大赦⚠️ 完全开放，任何人可用

实测验证：将 allow_from 改成不存在的 ID 后 Bot 仍能回复，证实大赦 > 白名单。

4. 第一次连接 → 配对码机制

即使 config.yaml 的 allow_from 设置正确，收到的第一个消息不会直接通过，而是返回配对码：

Hi~ I don't recognize you yet!
Here's my pairing code: XXXXXXXX

Ask the bot owner to run:
hermes pairing approve telegram XXXXXXXX

这是 Hermes 的安全机制——即使 ID 在 allow_from 里，系统也会先走一次 pairing 验证。在服务器端执行批准：

hermes pairing approve telegram [配对码]

批准后用户即刻生效，后续消息正常响应。

5. 网关重启与状态验证

# 查看状态
hermes gateway status
 
# WSL 环境手动重启（无 systemd）
hermes gateway stop          # 或直接 kill PID
hermes gateway run           # 后台模式
 
# 确认日志正常
tail -f ~/.hermes/logs/gateway.log

WSL 说明：WSL2 默认没有 systemd，hermes gateway restart 会报错。手动 kill 旧进程 + hermes gateway run 即可。

6. 安全加固（BotFather 侧）

  1. 进入 @BotFather，输入 /mybots
  2. 选择 Bot → Bot Settings → Group Privacy
  3. Turn OFF（关闭隐私模式）：才能让 Bot 看到群消息

💡 Turn OFF = 关闭隐私模式 = Bot 不隐私了。Turn OFF 不是”开启”！

配置合规性检查清单

检查项判定标准风险级别
allow_from ID纯数字字符串，推荐单引号 '中
allow_from 缩进前面 2 个半角空格高
GATEWAY_ALLOW_ALL_USERS安全场景必须删除⛔ 高（覆盖白名单）
Token 存放仅 .env 中有效高
首次使用需先 pairing approve中（配对流程）
修改后重启必须重启网关高
网络环境需代理（端口 7890）高

关系图谱