Telegram 白名单”大赦天下”破案记

⚠️ 剧透预警

花了 30 分钟排查，结果是 .env 文件里一行配置把自己坑了。白名单没坏，是”大赦开关”一直开着。

---

背景：给机器人装个门禁

给 Hermes Agent 配上 Telegram Bot 之后，当然不希望谁都能来使唤它。于是照着操作手册设了白名单：

# config.yaml - 白名单配置
telegram:
  allow_from: '8341474632'   # 只让这个人用

设完感觉稳了。但我心里其实有个疑问——这玩意儿到底真的生效了，还是只是我觉得它生效了？

案发经过

第一步：AI 审稿发现疑点

我把操作手册扔给 AI 审查，AI 扫了一眼说：

“你的 .env 文件里有个 GATEWAY_ALLOW_ALL_USERS=true，这叫’大赦开关’。只要这个开着，白名单就是摆设。”

我不服。明明设了白名单啊，怎么可能不管用？

第二步：实锤测试

为了证明 AI 错了，我把 allow_from 改成 '0000000000'（一个不存在的用户 ID），重启网关，然后用我的号发消息——

居然能正常回复。

白名单实锤形同虚设。打脸了。

第三步：关了”大赦”又踩新坑

去掉 GATEWAY_ALLOW_ALL_USERS=true，重启网关。再发消息：

确实不回我了。但返回的不是”拒绝访问”——而是返回了一个配对码。

原来 Hermes 还有一个 pairing（配对）机制：就算你在白名单里，第一次连接也需要配对。又得执行一次 hermes pairing approve 才生效。

---

技术真相（一张表说清楚）

变量	作用	优先级
allow_from: '用户ID'	YAML 白名单，指定谁可以用	🔽 低（被大赦覆盖）
GATEWAY_ALLOW_ALL_USERS=true	🔓 大赦开关，所有人通行	🔼 高（覆盖一切）
pairing 机制	首次连接需要配对	⛔ 独立系统，跟上面两个没关系

三者关系：

消息进来
    ↓
大赦开关开着吗？ ── 开着 → 放行（不管白名单）
    ↓ 关着
在白名单里吗？   ── 在 → 需要先配对
    ↓ 不在
拒绝

---

灵魂拷问

“所以这配置之前到底是怎么跑通的？”

——都是大赦令的功劳。白名单就是个门面，门根本没锁。

---

教训

1. .env 里的变量要心里有数——GATEWAY_ALLOW_ALL_USERS=true 看起来是”方便调试”，实际上是”安全后门”。上线前必须检查。

2. 改了配置要重启——改了文件不重启，等于没改。

3. 第一次用要走 pairing 流程——就算白名单配对了，第一条消息也要执行 pairing approve 才能通。这是 Hermes 的额外安全机制。

4. 先测试再信手册——纸上得来终觉浅。一个 curl 命令或者一条测试消息，比看十遍配置都有用。

5. 两个”放行”开关是”或”关系，不是”与”——allow_from 和 GATEWAY_ALLOW_ALL_USERS 只要有一个通，消息就能进来。这不是 Bug，是设计——但设计成这样就没告诉用户，坑。