Hermes Relay——跨网络连接器

这篇讲的是：如何让 Hermes Agent 通过一个“中间人”连接 Discord、Telegram 等聊天平台，而不用把机器人密钥放在自己电脑上。

---

先打个比方

想象你住在一个没有门牌号的小区（没有公网 IP），快递员（聊天平台消息）根本找不到你。
Hermes Relay 就像一个小区代收点：快递员把包裹放到代收点，你主动去取，全程不用暴露自家地址。

Relay 本身不是聊天软件，它是一个连接器系统。你的网关（Gateway）只负责“拨号”连出去，不监听任何端口。所有平台密钥都存放在连接器那边，你的电脑上干干净净。

---

第1步：搞清楚你适不适合用 Relay

• 适合：你用的是托管/共享连接器服务，或者不想在自己机器上保存机器人令牌。
• 不适合：你自己直接跑机器人。那直接用原生适配器（Telegram、Discord 等）更简单。

---

第2步：注册（Enrollment）

连接器会给你一个一次性注册令牌（像一张临时门票）。在网关机器上运行：

hermes gateway enroll \
  --token <你的令牌> \
  --connector-url wss://connector.example.com/relay

这条命令会做四件事：

1. 从你已有的登录信息（~/.hermes/auth.json）换取一个身份令牌，证明“你是谁”。
2. 把注册令牌和网关 ID 发给连接器。
3. 连接器验证通过后，返回专属密钥和投递密钥。
4. 自动把这些密钥写进 ~/.hermes/.env 文件。

完成后重启网关，让新配置生效。

注意：如果你用的是托管安装，注册命令会被拒绝——托管平台会直接把密钥注入容器环境，你不需要手动操作。

---

第3步：配置（其实不用配太多）

Relay 没有独立开关——只要设置了连接器 URL，它就自动启用。最核心的配置就两个：

配置项	作用
GATEWAY_RELAY_URL	连接器的 WebSocket 地址（写在 ~/.hermes/.env）
GATEWAY_RELAY_PLATFORMS	你要通过这个连接器接入哪些平台，如 discord,telegram

其他像 GATEWAY_RELAY_SECRET、GATEWAY_RELAY_DELIVERY_KEY 都是注册时自动写好的，一般不用手动改。

---

第4步：看看能干什么（能力协商）

连接器在握手时会告诉你“我支持哪些操作”，网关只使用对方明确支持的功能。目前支持：

• 文字消息和流式输出——支持编辑的平台会逐字流式显示，不支持的退化为分段发送。
• 双向媒体——图片、语音、视频都能发，平台私密链接会被连接器转存（限 25MB，约 1 小时过期）。
• 原生交互按钮——审批、确认、追问都渲染成 Discord 按钮、Telegram 键盘等，不是文字数字。
• 反应表情——👀 处理中、✅ 完成，这些状态提示也能用。
• 线程管理——创建和重命名线程（但 Slack 线程不能改名，WhatsApp 没有线程）。
• 打字指示器——处理时让对方看到“正在输入”。
• 离线缓冲——网关掉线时，连接器帮你存消息，重连后按顺序补发，不丢不重。

---

常见问题速查

报错	原因	解决
401	身份验证失败	重新登录：hermes auth add nous
403	注册令牌无效/过期/已用	找管理员要新令牌（一次性）
连不上	连接器地址写错	检查 wss:// 或 https:// 地址

---

小结

Relay 的核心价值就一句话：你的网关不碰任何平台密钥，也不开任何入站端口，照样收发消息。适合多租户托管、或者不想在服务器上保存敏感令牌的场景。

---

下篇预告：连接器说“我支持流式输出”，网关怎么知道该不该用？下一篇我们拆解握手时的能力描述符，看看协商机制到底怎么工作。