🌐 Gateway 接入原理深度解析

🏗️ 1. Gateway 架构原理

Gateway 是 Hermes Agent 的接入适配层，负责将不同平台的消息协议统一转换为 Agent 可处理的标准格式，再将 Agent 的响应转换回平台格式发送出去。

消息流转机制

每条消息经历以下处理流程：

1. 接收：Gateway 通过 Polling 或 Webhook 接收平台推送的原始事件
2. 鉴权：校验发送者是否在白名单中（防止陌生人滥用）
3. 解析：提取消息文本、附件、发送者信息，转换为统一格式
4. 路由：根据会话 ID 找到或创建对应的 Agent 上下文
5. 执行：将消息传入 Agent Loop，等待响应
6. 回复：将 Agent 响应格式化后，通过平台 API 发送回去

创建 Bot 与获取 Token

1. 通过 @BotFather 创建 Bot
   在 Telegram 中搜索 @BotFather，发送 /newbot，依次输入 Bot 显示名称和用户名（必须以 bot 结尾）。BotFather 会返回 Bot Token，格式为 123456789:ABCdef...。
2. 配置 Hermes Gateway
   bash

   hermes gateway setup   # 选择 Telegram，粘贴 Token
   # 或直接配置
   hermes config set TELEGRAM_BOT_TOKEN 123456789:ABCdef...

3. 配置白名单（强烈建议）
   通过 @userinfobot 获取自己的 Telegram User ID，在配置中添加白名单，防止陌生人调用你的 Agent 消耗 API 额度。
4. 启动并验证
   bash

   hermes gateway start
   hermes gateway status   # 确认 Running 状态

   找到你的 Bot，发送 /start 验证响应。

Polling vs Webhook 模式

Hermes Telegram Gateway 默认使用 Long Polling 模式：

1. 创建 Discord Application
   访问 Discord Developer Portal，点击「New Application」，输入名称后进入应用设置页。
2. 创建 Bot 并获取 Token
   左侧菜单选「Bot」→「Add Bot」→「Reset Token」获取 Token。Token 只显示一次，立即保存。
3. 开启 Message Content Intent（关键步骤）
   在 Bot 设置页面，找到「Privileged Gateway Intents」，开启 Message Content Intent。不开启此项，Bot 将无法读取用户消息内容。
4. 生成邀请链接并加入服务器
   「OAuth2 → URL Generator」中勾选 bot + applications.commands，Bot Permissions 勾选「Send Messages」「Read Message History」「Use Slash Commands」，复制链接邀请 Bot 加入你的服务器。
5. 配置 Hermes Gateway
   bash

   hermes gateway setup   # 选择 Discord，粘贴 Token

Discord Intent 权限机制深度解析

Discord 的 Intent 系统是其安全模型的核心。Bot 必须声明它需要接收哪类事件，Discord 才会推送对应的数据：

• GUILDS：服务器基本信息（默认开启）
• GUILD_MESSAGES：服务器频道消息事件（需要声明）
• MESSAGE_CONTENT：消息的实际文本内容（需要在 Portal 开启 Privileged Intent）
• DIRECT_MESSAGES：私信消息（需要声明）

1. 创建 Slack App
   访问 Slack API，「Create New App」→「From scratch」，选择工作区。
2. 配置 OAuth Scopes
   「OAuth & Permissions → Scopes → Bot Token Scopes」添加：chat:write、channels:history、im:history、im:write、app_mentions:read。
3. 安装到工作区获取 Bot Token
   「Install to Workspace」授权后，获取以 xoxb- 开头的 Bot User OAuth Token。
4. 开启 Socket Mode（推荐）
   「Socket Mode」→ 开启，生成以 xapp- 开头的 App-Level Token。Socket Mode 让 Slack 主动推送事件到你的进程，无需公网 IP。
5. 订阅事件
   「Event Subscriptions」→ 开启，订阅 message.im（私信）和 app_mention（@提及）事件。
6. 配置 Hermes Gateway
   bash

   hermes gateway setup   # 选择 Slack，输入 xoxb- 和 xapp- Token

Socket Mode 原理

传统 Slack Bot 需要一个公网可访问的 HTTPS Webhook 端点。Socket Mode 通过 WebSocket 长连接解决了这个问题：

🚀 5. 生产部署方案

持久化运行

Gateway 进程必须持续运行才能响应消息。推荐使用 systemd 管理：

# /etc/systemd/system/hermes-gateway.service
[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/home/your-user/.local/bin/hermes gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway
sudo systemctl status hermes-gateway

多平台并行运行

Hermes Gateway 支持同时接入多个平台，一个 Agent 实例可以同时服务 Telegram 和 Discord：

# config.yaml 中配置多个 Gateway
gateways:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    whitelist: [123456789]
  discord:
    enabled: true
    token: "${DISCORD_BOT_TOKEN}"

🚧 6. 踩坑记录