Day 3 · 入驻聊天室：微信 / Telegram / Discord / Slack

今日目标

让 Hermes 出现在你每天都在用的 IM 里——国内大概率是微信，海外多半是 Telegram。今天完成任一条主线，就能在手机上 @ Hermes 并收到回复。

---

前置条件

• 已完成 Day 2，hermes 能在终端正常对话
• 选好一个平台起步。拿不定主意的话：
  • 日常用微信 → 走主线一（微信）
  • 喜欢折腾 / 想最低门槛 → 走主线二（Telegram）
  • Discord / Slack 往下翻「分支」章节

一次只接一个，跑通再加第二个

Gateway 支持同时接多个平台，但新手先单通道跑通。出问题才知道是通道本身、凭证还是白名单的锅。

---

先理解：Gateway 是独立进程

Hermes 在 IM 里说话靠的是 messaging gateway——一个独立于 hermes CLI 的长驻进程，职责是把各平台的消息翻译成 Hermes 能处理的对话。

┌──────────────┐     ┌────────────────────┐     ┌────────────┐
│ 微信 /       │ ←→ │ hermes gateway     │ ←→ │ Hermes     │
│ Telegram /   │     │ （长驻进程）        │     │ 核心（LLM）│
│ Discord /    │     └────────────────────┘     └────────────┘
│ Slack ...    │
└──────────────┘

这意味着两件事：

1. 终端里关掉 hermes 对 gateway 没有影响——gateway 是独立的。
2. gateway 必须一直运行，机器人才会在线。可以前台跑（hermes gateway），也可以装成系统服务（hermes gateway install）。

默认白名单：陌生人进不来

Gateway 默认拒绝所有不在 allowlist 里的用户。这是刻意的安全设计——你的机器人背后是一个能访问你终端的 AI，不做这层防护后果严重。陌生人 DM 机器人时会收到配对码，你用 hermes pairing approve 审批后才能通过。

---

主线一：微信（国内首选 · 30–45 分钟）

这一套走的是 iLink Bot 长轮询

官方微信适配器底层走的是 iLink Bot API + HTTP 长轮询（35 秒超时）。不需要公网 IP、不需要 webhook、不需要内网穿透——家里的 MacBook / 云服务器都能直接跑。凭证绑的是个人微信号（小号也行），企业微信请看后面 WeCom 一节。

Step 1：装依赖

微信适配器多了两个 Python 库，先装上：

pip install aiohttp cryptography
# 想让终端里直接画出二维码（推荐）：
pip install "hermes-agent[messaging]"

Step 2：跑配置向导，扫码登录

hermes gateway setup

向导会让你选平台——选 Weixin。然后：

1. 终端里会显示一张二维码（如果装了 hermes-agent[messaging]），或给你一个图片路径
2. 用手机微信扫一扫这张二维码
3. 手机上点「确认登录」
4. 向导自动把 account_id、token、base_url 写入 ~/.hermes/.env，凭证本体落在 ~/.hermes/weixin/accounts/ 目录里（这些是明文，别上传到 Git）

向导跑完后，.env 里会长这样：

WEIXIN_ACCOUNT_ID=xxxxxxxx
WEIXIN_TOKEN=xxxxxxxxxxxxxxxxxxxxxx
WEIXIN_DM_POLICY=pairing
WEIXIN_HOME_CHANNEL=              # 想发主动通知时填

建议用一个小号，不要用主号

iLink Bot 是基于个人微信号运行的。官方建议新开一个微信小号做机器人——原因：① 主号被风控会影响日常社交；② 机器人在群里的发言频率不可控，小号出问题损失低。

Step 3：收紧访问策略

首次登录默认 dm_policy=pairing（谁都可以发消息进来走配对流程）。日常使用应该改成 allowlist，只让自己和指定的人能聊：

~/.hermes/.env

WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=wxid_xxxxxxxxxxxx    # 你自己微信号的 wxid

不知道自己 wxid 怎么拿？先启动 gateway 自己给机器人发一条消息，日志里会打印出发件人的 wxid，复制下来填回来就行。

群聊默认是关闭的

group_policy 默认 disabled——这是刻意设计，个人微信在群里高频发言极易被风控。如果你确实要在某个群里让机器人响应，再手动放开：

WEIXIN_GROUP_POLICY=allowlist
WEIXIN_ALLOWED_GROUPS=<群 ID>   # 启动后看日志抓

Step 4：启动 Gateway

hermes gateway

看到类似下面的日志说明通了：

gateway online · weixin connected · account=xxxx · long-poll=35s

Step 5：在微信里对话

手机微信打开你机器人那个号（或进入你和它的私聊），发一条：

你好，现在几点？

正常情况下机器人会回复当前时间。如果没反应——先去看「常见问题」章节里的微信部分。

Step 6：装成后台服务（推荐）

前台跑只适合测试。要 7×24 在线：

hermes gateway install
hermes gateway start
hermes gateway status

---

微信媒体与消息限制

能力	说明
图片 / 视频 / 文件 / 语音	都支持。Tencent CDN 里的加密（AES-128-ECB）gateway 自动帮你解
单条消息长度	最多 4000 字符，超出会在合理位置自动拆成多条
Markdown 链接	gateway 会把 [文字](url) 渲染成微信可点的引用卡片
主动推送	设置 WEIXIN_HOME_CHANNEL 后，cron 或定时任务可以往这个对话推消息

---

企业微信（WeCom）简介

如果你要接的是企业微信（WeCom），而不是个人微信，走的是另一条路——

维度	个人微信（Weixin）	企业微信（WeCom）
适配器	weixin（iLink Bot）	wecom
传输	HTTP 长轮询	WebSocket 长连接
凭证	扫码登录，token 有状态	管理后台创建 AI Bot，拿 BOT_ID / SECRET
群聊默认	disabled	open（企业场景天然需要）
加密	AES-128-ECB	AES-256-CBC

启动方式一样是 hermes gateway setup 选 WeCom。.env 里换成：

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

完整流程见官方 WeCom 文档，这里不展开。

---

主线二：Telegram（30 分钟）

1. 在 BotFather 注册机器人

   在 Telegram 搜索 @BotFather 或打开 t.me/BotFather，按顺序发：

   /newbot
   Hermes Agent        ← 显示名（任意）
   my_hermes_bot       ← 用户名（必须以 bot 结尾，全局唯一）

   BotFather 会返回一段形如 123456789:ABCdef... 的 token，这就是你机器人的密码，泄漏等同把机器人拱手让人。

2. 找到你自己的 Telegram user ID

   Gateway 的白名单用的是数字 user ID，不是用户名。在 Telegram 搜 @userinfobot，发一条消息，它会返回你的 ID（类似 987654321）。

3. 运行配置向导

   回到终端：

   hermes gateway setup

   向导会问你：平台选什么（选 Telegram）→ 粘贴 token → 粘贴允许使用的 user ID。向导会自动写入 ~/.hermes/.env：

   TELEGRAM_BOT_TOKEN=123456789:ABCdef...
   TELEGRAM_ALLOWED_USERS=987654321

   手写也行

   不想走向导就直接写 ~/.hermes/.env。hermes config set 也可以，它会自动判断这是密钥、落到 .env 而不是 config.yaml。

4. 启动 Gateway（前台）

   hermes gateway

   看到 gateway online · telegram connected 这类日志就说明通了。不要关闭这个终端，关了机器人就离线。

5. 在 Telegram 里对话

   打开你刚建的机器人（BotFather 返回消息里有 t.me/xxx 链接），点「开始」然后发一条：

   你好，现在几点？

   正常响应：机器人回复当前时间并说明它用 terminal 工具查的。

6. 把 Gateway 装成后台服务（可选但推荐）

   命令与微信主线 Step 6 完全相同：hermes gateway install && hermes gateway start。

Telegram 群聊：privacy mode 和 @mention

把机器人加到群里后，默认会看不见大部分消息——这是 Telegram 的 privacy mode：机器人只能看到 / 开头的命令、直接回复它的消息、以及 @机器人 的消息。

两种处理方式，选一种：

方式	操作	效果
保留 privacy mode（推荐）	不动设置，在群里用 @my_hermes_bot 问题 触发	机器人只在被 @ 时响应，不刷屏
关闭 privacy mode	BotFather → /mybots → Bot Settings → Group Privacy → Turn off，然后把机器人从群里踢掉再重新拉进群	机器人能看到所有消息。需要配合 require_mention: true 否则会乱回

关闭 privacy 后，用下面这段 ~/.hermes/config.yaml 限制只在 @ 或特定关键词时响应：

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*小助手\\b"   # 叫「小助手」也触发

---

分支：Discord 关键步骤

只看清单，细节请跳官方文档

Discord 配置比 Telegram 繁琐（要在 Developer Portal 点 4–5 个开关）。下面是最容易踩坑的地方，完整步骤看官方 Discord Setup。

1. 建 Application + Bot：Discord Developer Portal → New Application → 侧栏 Bot → Reset Token（只显示一次，立刻复制）。

2. 必须开两个 Privileged Intent（90% 的”机器人不回复”都是这里漏开的）：

   • Server Members Intent
   • Message Content Intent ← 不开这个，机器人会收到消息事件但文本是空的

3. 邀请 bot 进服务器，权限整数用推荐值 274878286912（包含发消息、读历史、发附件、加反应等）：

   https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

4. 找 user ID：Discord 设置 → 高级 → 打开「开发者模式」→ 右键自己的名字 → 复制 User ID。

5. .env 要写：

   DISCORD_BOT_TOKEN=...
   DISCORD_ALLOWED_USERS=你的_user_id

6. 再跑一次 hermes gateway setup 选 Discord，或直接 hermes gateway 启动。

---

分支：Slack 关键步骤

Slack 走 Socket Mode，不需要公网 URL

Hermes 在 Slack 里用 WebSocket 长连接，所以你不需要公网域名 / 内网穿透，家里机器也能跑。完整步骤看官方 Slack Setup。

在 api.slack.com/apps 建应用，然后：

步骤	关键点
OAuth & Permissions	至少加这些 bot scope：chat:write、app_mentions:read、channels:history、im:history、im:write、users:read、files:read、files:write
Socket Mode	打开开关，生成 App-Level Token（xapp- 开头）
Event Subscriptions	订阅 message.im、message.channels、app_mention ← 90% 的”机器人不回复”是这一步漏订阅
Install to Workspace	生成 Bot Token（xoxb- 开头）

两个 token 写到 ~/.hermes/.env：

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USERS=U01XXXXX   # Slack user ID，不是用户名

最后在目标频道执行 /invite @Hermes Agent，机器人才会看到该频道的消息。

---

验证成果

无论你选哪个平台，本章完成的标志是：

$ hermes gateway status
● gateway:  running
● weixin:   connected     # 或 telegram / discord / slack
● session:  ready

然后在对应的 IM 里：

你：@Hermes 9.8 和 9.11 哪个大？
Hermes：9.8 比 9.11 大。9.8 = 9.80，而 9.11 = 9.11，所以 9.80 > 9.11。

---

常见问题

机器人不回复（通用排查顺序）

1. hermes gateway status — 进程是否还活着
2. hermes gateway 前台重启，看启动日志有没有报错
3. 检查 token 是否正确（.env 里有没有多空格、引号）
4. 检查自己的 user ID / wxid 是否在 *_ALLOWED_USERS 里

微信：errcode=-14 / session 过期

iLink 的会话凭证有寿命，长时间不用或手机端被挤下线都会触发 errcode=-14。解决方式：

hermes gateway stop
hermes gateway setup    # 重新扫码
hermes gateway start

凭证文件在 ~/.hermes/weixin/accounts/，重扫后旧的会被覆盖，无需手动清理。

微信：二维码刷新了 3 次还是没扫上

向导里的二维码默认最多自动刷新 3 次（每张大约 2 分钟）。超时后 Ctrl+C 退出，重开 hermes gateway setup 就行。通常是因为手机离电脑太远 / 终端二维码太小——装上 hermes-agent[messaging] 直接在终端画矢量二维码会清楚很多。

微信：同一个账号不能两端同时跑 gateway

一个微信凭证对应一个 iLink 会话。如果你在台式机和笔记本上用同一个号同时启动 gateway，两边会互踢。要么拆成两个微信号（推荐），要么用 hermes gateway stop 先停掉一边。

微信：群里 @ 了机器人没反应

99% 是 WEIXIN_GROUP_POLICY=disabled（默认值）。配置方式见上方 Step 3「群聊默认是关闭的」——启动 gateway 后在群里发一条消息，从日志里抓 chat_id 填进去即可。

Discord：收到消息但 Hermes 看不到内容

99% 是 Message Content Intent 没打开。Discord Developer Portal → Bot → Privileged Gateway Intents → 打开 Message Content Intent，然后重启 gateway（Discord 端不需要重新邀请）。

Slack：机器人进了频道但不响应 @

去 Event Subscriptions 页面检查是否订阅了 app_mention 和 message.channels。Slack 的 Event Subscription 改了之后不需要重新安装应用，但 gateway 需要重启。

Telegram 群里机器人收不到消息

Privacy mode 没关，并且你不是用 @bot名 ... 格式触发的。两个选择：用 @ 触发；或关掉 privacy mode 后把机器人踢出群再重新拉进来（设置才生效）。

陌生人给机器人发消息，我收到配对码提示？

这是 gateway 的内置保护：不在 allowlist 里的用户发消息，机器人不会回，但会给你这个管理员一个配对码。审批命令：

hermes pairing approve weixin ABC123       # 或 telegram / discord / slack

配对码 1 小时过期。不想要这个机制可以在 .env 设 GATEWAY_ALLOW_ALL_USERS=true——但机器人有终端访问权，开放给所有人风险很大，除非你知道自己在做什么。

会话状态什么时候重置？

默认规则：空闲超过一定时长（微信 180 分钟、Telegram 240 分钟、Discord 60 分钟）或到每日固定时间（默认凌晨 4 点）会重置。想改就编辑 ~/.hermes/gateway.json：

{
  "reset_by_platform": {
    "weixin":   { "mode": "idle", "idle_minutes": 120 },
    "telegram": { "mode": "idle", "idle_minutes": 60 }
  }
}