第十册:多平台接入实战

本章你将学到

  • 为什么多平台接入是 Hermes 的杀手级特性
  • Gateway 消息网关的工作原理与配置方法
  • Telegram、飞书、微信、Discord 等主流平台的完整接入流程
  • 编辑器集成与语音交互的配置技巧
  • 多平台协同使用的实战策略与安全运维方案

1. 为什么需要多平台接入

1.1 从"只在电脑前用"到"随时随地指挥"

想象一下这样的场景:

早上你在地铁上,突然想到一个绝妙的创意,你想立刻让 AI 帮你整理思路、查找资料。但你只有手机,而你的 AI 助手却乖乖地待在电脑里。你只能手忙脚乱地打开手机备忘录,草草记几笔,等到了公司再重新输入给 AI。

中午你在咖啡馆见客户,客户临时提了一个技术问题,你想让 AI 快速查一下行业数据。但你电脑上没装通信软件,手机上的 AI 又没法访问你电脑里的文件和工具。

晚上你躺在床上,突然想到明天要给团队汇报的方案还没完善。你翻个身摸到手机,给 AI 发一条语音消息,它立刻帮你生成了一份完整的汇报提纲,还自动发到了飞书群里。

这就是多平台接入带来的变革。

在传统的 AI 使用方式里,你和 AI 的关系就像医生和病人——必须面对面坐在诊室里才能交流。但有了多平台接入,AI 就像你的贴身助理,无论你是在电脑前、手机上、智能手表里,甚至是在家里的智能音箱旁,它都能随时随地响应你的指令。

Tips Hermes 的多平台接入能力,本质上是一套消息网关(Gateway)系统。它相当于 AI 的"多语言翻译官",能把不同平台的消息格式翻译成 AI 能理解的通用语言,再把 AI 的回复翻译成对应平台能展示的格式。

1.2 消息网关的设计理念

Hermes 的 Gateway 架构设计,借鉴了互联网领域中成熟的消息队列和网关模式。它的核心理念可以用一句话概括:"一次接入,处处可达"

让我们用一个生活中的类比来理解 Gateway 的工作原理:

想象你是一家跨国公司的 CEO,你的助理(Gateway)需要同时处理来自不同渠道的信息——微信上的客户消息、邮件里的合作邀约、电话里的紧急事务、钉钉上的内部审批。助理的职责不是让你同时盯着十个屏幕,而是把所有信息统一整理成标准格式的待办事项,按优先级呈现给你。当你给出指示后,助理再根据每条信息的来源渠道,用合适的方式回复出去。

Hermes 的 Gateway 就是你的这位超级助理:

  • 消息路由(Routing):识别消息来自哪个平台、哪个用户、哪个群组,决定把回复发回哪里
  • 格式转换(Transcoding):把 Telegram 的 Markdown 格式转成飞书的富文本卡片,把语音消息转成文字,把文件 attachments 统一处理
  • 状态同步(State Sync):你在手机上和 AI 聊到一半,回到电脑前继续聊,AI 记得刚才聊到哪儿了
  • 身份认证(Authentication):确认发消息的人是你,不是你二舅冒充你让 AI 转账

注意 Gateway 不是简单地"转发消息",它维护着一套完整的会话上下文。你在 Telegram 里问"刚才说的那个方案呢",AI 能准确理解"刚才"指的是你在飞书里的上一轮对话——这才是真正的多平台协同。

1.3 15+ 平台一览与分类

截止到目前,Hermes 已经支持接入的平台超过了 15 个,涵盖了即时通讯、企业协作、社交媒体、编辑器、语音设备等多个类别。下面这张表帮你快速了解全貌:

类别平台适用场景接入复杂度
即时通讯Telegram个人用户、开发者社群、海外团队⭐ 简单
WhatsApp海外商务沟通、亲友联络⭐⭐ 中等
Signal高隐私要求场景⭐⭐ 中等
SMS无网络环境下的备用通道⭐⭐ 中等
企业协作飞书(Lark)国内团队、字节生态⭐ 简单
企业微信腾讯生态企业、国内商务⭐⭐ 中等
Slack海外团队、开发者社区⭐ 简单
Discord游戏社群、开源社区、粉丝群⭐ 简单
Matrix去中心化、隐私优先团队⭐⭐⭐ 复杂
Mattermost自托管企业协作⭐⭐⭐ 复杂
社交媒体微信公众号内容运营、客服自动化⭐⭐⭐ 复杂
智能家居Home Assistant语音控制、IoT 联动⭐⭐ 中等
编辑器VS Code编程辅助、代码审查⭐ 简单
Zed新一代代码编辑器⭐ 简单
JetBrains IDEJava/Python/Go 开发⭐⭐ 中等
语音语音交互后端语音输入/输出⭐⭐ 中等
邮件Email异步沟通、报告分发⭐⭐ 中等

Tips 如果你第一次接触多平台接入,建议从 Telegram飞书 开始。这两个平台的文档最完善、社区支持最好、配置也最直观。等熟悉了 Gateway 的工作模式后,再逐步扩展到其他平台。


2. Gateway 架构与基础配置

2.1 hermes gateway 命令详解

在 Hermes 的命令行工具中,hermes gateway 是管理消息网关的核心命令。它就像机场塔台的指挥系统,负责让所有"航班"(来自不同平台的消息)有序起降。

先来看一下 gateway 命令的完整帮助信息:

# 查看 gateway 命令帮助
$ hermes gateway --help
 
Usage: hermes gateway [OPTIONS] COMMAND [ARGS]...
 
  管理消息网关(Gateway)的多平台接入
 
Commands:
  setup      交互式配置一个新平台
  start      启动网关服务
  stop       停止网关服务
  restart    重启网关服务
  status     查看网关运行状态
  list       列出所有已配置的平台
  logs       查看网关日志
  test       发送测试消息到指定平台

每个子命令的详细用法:

# 交互式配置新平台(最常用)
$ hermes gateway setup
# 会弹出一个菜单让你选择要接入的平台,然后一步步引导你完成配置
 
# 启动网关服务(前台运行,适合调试)
$ hermes gateway start
 
# 启动网关服务(后台守护进程)
$ hermes gateway start --daemon
 
# 停止网关
$ hermes gateway stop
 
# 查看网关状态(哪些平台在线、消息队列长度等)
$ hermes gateway status
 
# 查看已配置的平台列表
$ hermes gateway list
 
# 实时查看网关日志(调试用)
$ hermes gateway logs --follow
 
# 发送测试消息验证配置
$ hermes gateway test telegram --message "Hello from Hermes!"

Tips 建议在首次配置时,先用 hermes gateway start(前台模式)启动网关。这样如果有报错,你能立刻在终端看到红色错误信息。等一切正常后,再用 --daemon 模式放到后台运行。

2.2 hermes gateway setup 交互式配置

hermes gateway setup 是 Hermes 最贴心的功能之一。你不需要手写复杂的配置文件,只需要跟着向导回答几个问题,就能完成平台接入。

下面是一个完整的 setup 流程示例(以 Telegram 为例):

$ hermes gateway setup
 
🌐 Hermes Gateway 配置向导
══════════════════════════════════════════
 
请选择要接入的平台:
 
  [1] Telegram     - 海外最流行的即时通讯
  [2] 飞书 (Lark)  - 国内企业协作首选
  [3] 企业微信      - 腾讯生态企业通讯
  [4] Discord      - 游戏与开发者社区
  [5] Slack        - 海外团队协作
  [6] 微信公众号    - 内容运营与客服
  [7] WhatsApp     - 海外商务沟通
  [8] Matrix       - 去中心化通讯
  [9] Email        - 邮件收发
 [10] 更多平台...
 
请输入数字选择: 1
 
📱 Telegram 配置
──────────────────────────────────────────
 
第一步:获取 Bot Token
  1. Telegram 中搜索 @BotFather
  2. 发送 /newbot 创建新机器人
  3. 按提示命名你的 Bot(例如:HermesAssistant)
  4. 保存获得的 Token(格式:123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
 
请输入你的 Bot Token: 123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 Token 格式验证通过
 
第二步:设置允许列表(Allowlist)
  允许列表用于限制哪些用户可以与你的 Hermes Bot 交互。
  建议先设置为你自己的用户 ID,测试成功后再添加其他人。
 
请输入允许的用户 ID(多个用逗号分隔,直接回车表示允许所有人): 12345678
 
⚠️ 注意:你选择了限制模式,只有以下用户能与 Bot 交互:
   - 用户 ID: 12345678
 
第三步:高级选项(可选)
是否启用群组模式?Bot 可以在群组中被 @ 提到时响应 [y/N]: y
 
配置预览:
  平台:      Telegram
  Bot Token: 123456789:XXX...XXX(已隐藏)
  允许用户:  12345678
  群组模式:  已启用
 
确认保存配置? [Y/n]: Y
 
 Telegram 配置已保存到 ~/.hermes/config.yaml
 
提示:运行 `hermes gateway start` 启动网关

Tips setup 向导会自动验证你输入的 Token 格式是否正确。如果提示"格式错误",请检查是不是多复制了一个空格,或者漏掉了冒号后面的部分。

2.3 Gateway 的工作原理

要真正掌握多平台接入,你需要理解 Gateway 的"黑盒"里到底在发生什么。让我们拆开来看:

2.3.1 整体架构图

┌─────────────────────────────────────────────────────────────┐
│                      Hermes Core Engine                      │
│                    (AI 大脑:推理、记忆、工具调用)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Gateway Manager                         │
│         (统一消息格式转换、会话管理、权限控制)                  │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Telegram   │    │    飞书       │    │   Discord    │
│   Adapter    │    │   Adapter    │    │   Adapter    │
└──────────────┘    └──────────────┘    └──────────────┘
      │                    │                    │
      ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Telegram API │    │  飞书 Open   │    │ Discord API  │
│   (Webhook   │    │    API       │    │  (WebSocket) │
│   /Polling)  │    │  (Event Hub) │    │              │
└──────────────┘    └──────────────┘    └──────────────┘

2.3.2 消息流转的完整流程

当一条消息从 Telegram 发过来时,整个处理流程是这样的:

第一步:接收(Receive)

Telegram Adapter 通过 Webhook 或 Long Polling 持续监听 Telegram 服务器的消息推送。当有新消息到达时,Adapter 接收到的是一个 JSON 对象:

{
  "update_id": 123456789,
  "message": {
    "message_id": 1,
    "from": {
      "id": 12345678,
      "first_name": "张三",
      "username": "zhangsan"
    },
    "chat": {
      "id": 12345678,
      "type": "private"
    },
    "date": 1704067200,
    "text": "帮我查一下明天北京的天气"
  }
}

第二步:标准化(Normalize)

Gateway Manager 把这个平台特定的 JSON 转换成 Hermes 内部的标准消息格式:

{
  "message_id": "msg_tg_123456789_1",
  "platform": "telegram",
  "channel_id": "12345678",
  "sender": {
    "id": "12345678",
    "name": "张三",
    "username": "zhangsan"
  },
  "content": {
    "type": "text",
    "text": "帮我查一下明天北京的天气"
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "reply_to": null
}

注意到这里做了几件事:

  • 生成了全局唯一的 message_id
  • 统一了 platform 字段标识来源
  • 提取了发送者信息
  • 把不同平台的消息内容结构统一了

第三步:权限检查(Auth)

Gateway Manager 检查 sender.id 是否在 allowlist 中。如果不在,直接丢弃这条消息(或者回复"你没有权限使用此服务")。

第四步:上下文加载(Context)

Gateway Manager 从记忆系统中加载这个用户的会话历史:

  • 查找 user_id = "12345678" 的短期记忆
  • 加载最近 10 轮对话上下文
  • 检查是否有正在进行的任务流

第五步:交给 AI 处理(Process)

标准消息被送进 Hermes Core Engine,AI 开始思考、调用工具、生成回复。

第六步:格式化输出(Format)

AI 生成的是纯文本回复,Gateway Manager 需要把它转成目标平台支持的格式。比如:

AI 生成的原始回复:
"北京明天的天气预报:\n\n**天气**:晴转多云\n**温度**:15°C ~ 22°C\n**风力**:东北风 3-4 级\n\n建议穿薄外套。"

转成 Telegram 格式:
- Telegram 原生支持 MarkdownV2,可以直接发送

转成飞书格式:
- 需要封装成富文本卡片(Interactive Card)

第七步:发送(Send)

对应的 Adapter 调用平台 API,把回复发回去。

注意 如果你在手机上用 Telegram 发了一条消息,然后在电脑前用飞书继续同话题聊天,Gateway 会自动把两条消息关联到同一个 session_id 下。这意味着 AI 知道"刚才"指的是跨平台的上一条消息。

2.4 config.yaml 中的 gateway 配置项

虽然 setup 向导能帮你完成大部分配置,但了解 config.yaml 的结构对进阶排错和自定义非常重要。

Gateway 的配置位于 ~/.hermes/config.yaml 文件的 gateway 节下:

# ~/.hermes/config.yaml
 
# ==================== Gateway 全局配置 ====================
gateway:
  # 网关监听地址和端口
  # 如果你希望外网能访问(比如接收 Webhook),设为 "0.0.0.0"
  host: "127.0.0.1"
  port: 8080
 
  # 日志级别:debug, info, warning, error
  log_level: "info"
 
  # 消息队列配置
  queue:
    max_size: 1000        # 最大队列长度,超过将丢弃旧消息
    worker_count: 4       # 并行处理消息的工作线程数
    timeout: 300          # 单条消息处理超时(秒)
 
  # 全局安全设置
  security:
    # 全局允许列表(优先级低于各平台的 allowlist)
    # 如果设置了,只有这些用户能使用任何平台的 Bot
    global_allowlist: []
 
    # 消息内容过滤(正则表达式列表)
    # 匹配到的消息会被拒绝
    blocked_patterns:
      - "(?i)(密码|password)\s*[=:]\s*\S+"
 
    # 文件传输限制
    max_file_size: "10MB"
    allowed_file_types: ["txt", "pdf", "jpg", "png", "docx"]
 
# ==================== 各平台具体配置 ====================
gateways:
  # Telegram 配置
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"  # 从环境变量读取(推荐!)
    # 或者硬编码(不推荐,安全性差):
    # bot_token: "123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
    # 接收消息的方式:"polling" 或 "webhook"
    receive_mode: "polling"
 
    # 如果是 webhook 模式,需要配置以下项
    webhook_url: "https://your-domain.com/webhook/telegram"
    webhook_secret: "${TELEGRAM_WEBHOOK_SECRET}"
 
    # 允许列表(空数组表示允许所有人)
    allowlist:
      - "12345678"     # 用户数字 ID
      - "87654321"
 
    # 群组模式
    group_mode:
      enabled: true
      # 只有在消息中 @ 提到 Bot 时才响应
      require_mention: true
      # Bot 的 @用户名(会自动检测,也可以手动指定)
      bot_username: "HermesAssistantBot"
 
    # 消息格式
    formatting:
      # 使用 Markdown 还是纯文本
      parse_mode: "MarkdownV2"
      # 是否自动把长消息拆分成多条
      split_long_messages: true
      max_message_length: 4096
 
  # 飞书配置
  lark:
    enabled: true
    app_id: "${LARK_APP_ID}"
    app_secret: "${LARK_APP_SECRET}"
 
    # 加密密钥(事件订阅用)
    encrypt_key: "${LARK_ENCRYPT_KEY}"
 
    # 事件订阅的验证 Token
    verification_token: "${LARK_VERIFICATION_TOKEN}"
 
    receive_mode: "webhook"
    webhook_url: "https://your-domain.com/webhook/lark"
 
    allowlist: []
 
    # 消息卡片配置
    card_mode: true
 
  # Discord 配置
  discord:
    enabled: true
    bot_token: "${DISCORD_BOT_TOKEN}"
    receive_mode: "websocket"
    allowlist: []
 
  # 更多平台...

Tips 永远不要把 Token 硬编码在 config.yaml 里! 上面的示例中使用了 ${VAR_NAME} 语法,Hermes 会自动从环境变量中读取。正确的做法是在你的 shell 配置文件(如 ~/.zshrc~/.bashrc)中设置:

export TELEGRAM_BOT_TOKEN="123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

2.5 多平台同时接入的配置方法

让 Hermes 同时接入多个平台非常简单——你只需要在 gateways 下配置多个平台,并都设置 enabled: true

gateways:
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    allowlist: ["12345678"]
 
  lark:
    enabled: true
    app_id: "${LARK_APP_ID}"
    app_secret: "${LARK_APP_SECRET}"
    allowlist: []
 
  discord:
    enabled: true
    bot_token: "${DISCORD_BOT_TOKEN}"
    allowlist: []
 
  email:
    enabled: true
    imap_server: "imap.gmail.com"
    imap_port: 993
    username: "${EMAIL_USERNAME}"
    password: "${EMAIL_PASSWORD}"
    allowlist:
      - "[email protected]"
      - "[email protected]"

启动网关后,你会看到类似这样的输出:

$ hermes gateway start
 
🌐 Hermes Gateway 启动中...
══════════════════════════════════════════════════
 
[✓] Telegram    - 已连接 (@HermesAssistantBot)
[✓] 飞书        - 已连接 (应用: Hermes Assistant)
[✓] Discord     - 已连接 (Bot: Hermes#1234)
[✗] Email       - 连接失败: IMAP 认证错误,请检查密码
 
4 个平台已配置,3 个正常运行,1 个异常
消息处理线程:4
监听地址:127.0.0.1:8080
 
 Ctrl+C 停止网关

注意 当多个平台同时在线时,来自任何平台的消息都会进入同一个消息队列,由 AI 统一处理。但每个平台的会话上下文是独立的——你在 Telegram 里的聊天历史不会自动出现在飞书里,除非两个平台绑定了同一个用户 ID(通过 user_mapping 配置)。

2.6 本章小结

在本章中,我们学习了:

  • 多平台接入的意义:让 AI 从"电脑里的程序"变成"随身助理"
  • Gateway 架构:消息路由、格式转换、状态同步三大核心能力
  • 命令行工具hermes gateway setup/start/stop/status 的日常用法
  • 配置文件:config.yaml 的完整结构和最佳实践
  • 多平台并行:同时接入多个平台的配置方法

下一章,我们将从最流行的 Telegram 开始,手把手教你完成第一个平台的接入。


3. Telegram 接入(最流行,详细教程)

Telegram 是 Hermes 社区中使用最广泛的平台,原因很直观:免费、稳定、API 友好、隐私保护做得好,而且在中国以外的地区普及率极高。如果你是第一次接入多平台,强烈建议从 Telegram 开始。

3.1 创建 Telegram Bot(@BotFather 全流程)

Telegram 提供了一个官方的"机器人之父"——@BotFather,专门用来创建和管理 Bot。整个过程就像去民政局办营业执照一样简单。

步骤一:找到 @BotFather

打开 Telegram(手机 App 或桌面版都可以),在顶部的搜索框里输入 @BotFather。注意认准蓝勾认证标志,别加到假冒的机器人。

步骤二:开始对话

点击 @BotFather 后,发送 /start 开始对话。你会看到一长串命令列表。

步骤三:创建新 Bot

发送 /newbot 命令:

你: /newbot
BotFather: Alright, a new bot. How are we going to call it?
         Please choose a name for your bot.

你: Hermes 智能助手
BotFather: Good. Now let's choose a username for your bot.
         It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.

你: HermesAssistantBot
BotFather: Done! Congratulations on your new bot.
         You will find it at t.me/HermesAssistantBot
         ...
         Use this token to access the HTTP API:
         123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
         ...

这里有两个名字需要注意区分:

名称类型示例用途
显示名称(Name)Hermes 智能助手用户在聊天列表中看到的名字,可以包含中文和空格
用户名(Username)HermesAssistantBot唯一标识,必须以 bot 结尾,用于 @ 提及和链接

步骤四:保存 Token

BotFather 发给你的那一串 123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 就是 Bot Token。这是你的 Bot 的"身份证+密码",一定要妥善保管:

# 保存到环境变量(推荐)
export TELEGRAM_BOT_TOKEN="123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
# 为了持久化,添加到 shell 配置文件
echo 'export TELEGRAM_BOT_TOKEN="123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"' >> ~/.zshrc
source ~/.zshrc

注意 Token 泄露 = 机器人被劫持。 任何人拿到你的 Token 就能控制你的 Bot,读取所有消息、冒充你的身份发消息。如果不小心泄露了,立刻找 @BotFather 发送 /revoke 命令重置 Token。

步骤五(可选):设置头像和描述

你: /setuserpic
BotFather: Choose a bot to change profile photo.

你: @HermesAssistantBot
[上传一张图片]

你: /setdescription
BotFather: Choose a bot to change description.

你: @HermesAssistantBot
你: 我是你的 AI 智能助手,基于 Hermes 架构构建。
         我可以帮你查资料、写代码、管理日程,随时为你效劳!

Tips 一个好的 Bot 描述能让用户一眼明白它是干嘛的。建议写清楚:1) 这是什么;2) 能做什么;3) 基于什么技术(比如"Powered by Hermes")。

3.2 获取 Bot Token

其实上一步你已经拿到了 Token。这里单独列出来,是为了强调几个重要的最佳实践:

Token 的安全存储方案对比:

存储方式安全性便利性推荐度
硬编码在 config.yaml⭐ 极差⭐⭐⭐ 方便❌ 绝不推荐
环境变量⭐⭐⭐ 好⭐⭐ 中等✅ 推荐
系统密钥管理器(Keychain)⭐⭐⭐⭐⭐ 极好⭐⭐ 中等✅✅ 最推荐
密码管理器(1Password 等)⭐⭐⭐⭐ 很好⭐⭐ 中等✅ 推荐

在 macOS 上,你可以用系统 Keychain 来存储 Token:

# 保存到 Keychain
security add-generic-password -s "hermes-telegram-token" \
  -a "$(whoami)" -w "123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
# 从 Keychain 读取(Hermes 支持这种语法)
export TELEGRAM_BOT_TOKEN="$(security find-generic-password -s "hermes-telegram-token" -w)"

3.3 获取数字用户 ID(@userinfobot)

配置 allowlist 时,你需要的是数字用户 ID,不是你的 @用户名。这是 Telegram 设计的一个容易混淆的地方。

获取方法很简单:

  1. 在 Telegram 搜索 @userinfobot
  2. 发送 /start 或任意消息
  3. 它会回复你的用户信息:
@userinfobot:
Id: 12345678
First: 张三
Lang: zh-hans

这里的 Id: 12345678 就是你要的数字用户 ID。

常见问题 Q: 为什么不能用 @用户名做 allowlist? A: 因为 @用户名是可以修改的,而数字 ID 终身不变。用数字 ID 更安全、更稳定。

如果你想查看群里其他人的 ID,可以使用 @getidsbot:

  1. 把 @getidsbot 加到群里
  2. 随便发一条消息
  3. 它会回复包含所有成员 ID 的信息

3.4 配置 Hermes

拿到 Token 和用户 ID 后,配置 Hermes 只需要一行命令:

# 方法1:使用交互式向导
$ hermes gateway setup
# 然后选择 Telegram,按提示输入 Token 和 allowlist
 
# 方法2:直接用命令行设置
$ hermes config set TELEGRAM_BOT_TOKEN "123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
$ hermes config set TELEGRAM_ALLOWLIST "12345678"
 
# 方法3:手动编辑 config.yaml
$ nano ~/.hermes/config.yaml
# 在 gateways.telegram 下填入配置

完整的 Telegram 配置示例:

gateways:
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    receive_mode: "polling" # 个人用户建议 polling
    allowlist:
      - "12345678" # 你的用户 ID
    group_mode:
      enabled: true
      require_mention: true
    formatting:
      parse_mode: "MarkdownV2"
      split_long_messages: true

3.5 启动网关与测试

配置完成后,启动网关并测试:

# 启动网关(前台模式,便于观察日志)
$ hermes gateway start
 
# 你应该看到类似输出:
🌐 Hermes Gateway 启动中...
[✓] Telegram - 已连接 (@HermesAssistantBot)
消息处理线程:4
监听地址:127.0.0.1:8080
 
# 打开 Telegram,给你的 Bot 发消息
# 你: 你好
# Bot: 你好!我是 Hermes 智能助手,很高兴为你服务。

如果启动失败,可以用调试模式查看详细日志:

# 设置调试日志级别
$ hermes config set GATEWAY_LOG_LEVEL debug
 
# 重新启动并查看日志
$ hermes gateway start 2>&1 | tee gateway.log

3.6 安全配置:允许列表(Allowlist)详解

Allowlist 是 Gateway 的第一道安全防线。它的作用很简单:只有列表里的用户能与你的 Bot 交互

为什么必须设置 Allowlist?

想象你没设置 allowlist,然后你的 Bot Token 不小心泄露到了 GitHub 上(别笑,这种事每天都在发生)。黑客拿到 Token 后,可以:

  1. 查询你的 Bot 收到了哪些消息
  2. 冒充你的 Bot 给用户发钓鱼链接
  3. 利用你的 Bot 做跳板攻击其他系统
  4. 消耗你的 API 额度(如果接了付费模型)

设置了 allowlist 后,即使 Token 泄露,黑客也无法与 Bot 交互——因为他们的用户 ID 不在白名单里。

Allowlist 配置详解

gateways:
  telegram:
    # 方式1:仅允许特定用户
    allowlist:
      - "12345678"      # 你的 ID
      - "87654321"      # 你队友的 ID
 
    # 方式2:允许特定群组(把群组 ID 当作用户 ID)
    allowlist:
      - "-1001234567890"  # 群组 ID(注意负号!)
 
    # 方式3:允许所有人(不推荐用于生产环境)
    allowlist: []
 
    # 方式4:动态 allowlist(从外部 API 加载)
    allowlist_url: "https://your-company.com/api/hermes-users"
    allowlist_refresh_interval: 3600  # 每小时刷新一次

注意 群组 ID 通常是以 -100 开头的负数。在 Telegram 中,超级群组(Supergroup)的 ID 格式是 -100xxxxxxxxxx。如果你用错了格式,群组消息会收不到。

3.7 群组中使用 Bot

在群组中使用 Bot 和在私聊中略有不同,主要体现在权限管理和触发机制上。

把 Bot 加到群组

  1. 在 Telegram 中打开目标群组
  2. 点击群组名称 → 添加成员
  3. 搜索你的 Bot 用户名(如 @HermesAssistantBot
  4. 添加后,Bot 会收到一条系统消息,告知它已被加入群组

群组权限配置

你需要给 Bot 设置合适的权限。在群组设置 → 管理员 → 你的 Bot 中:

✅ 删除消息        —— 如果需要 Bot 管理群规
✅ 限制用户        —— 如果需要自动禁言功能
✅ 置顶消息        —— 如果需要发布公告
✅ 发送消息        —— 必须开启!
✅ 发送媒体        —— 如果需要发图片/文件
✅ 发送投票        —— 如果需要投票功能
❌ 保持匿名        —— 建议关闭,方便识别
❌ 添加新管理员     —— 绝对不能给 Bot!

触发机制

在群组中,默认要求用户 @ 提到 Bot 才会响应:

用户A: 大家好
用户A: @HermesAssistantBot 帮我总结一下今天的讨论
Bot: [回复用户A] 好的,今天的讨论要点如下:...

用户B: Hermes 帮我查一下天气     ← 没有 @,Bot 不会响应

你也可以关闭 require_mention,让 Bot 响应群里的所有消息:

group_mode:
  enabled: true
  require_mention: false # ⚠️ 慎用!会产生大量 API 调用

注意 在大型群组中关闭 require_mention 会导致 Bot 对每条消息都进行处理,可能迅速耗尽你的 API 额度。建议只在 10 人以下的小群中使用。

3.8 富文本消息、文件传输、语音消息

Telegram 支持丰富的消息类型,Hermes 对这些类型的支持情况如下:

富文本消息

Hermes 支持在 Telegram 中发送格式化的 Markdown 消息:

Bot 发送的消息示例:

**加粗文本**
*斜体文本*
`行内代码`
```代码块```
[超链接](https://example.com)

配置方法:

formatting:
  parse_mode: "MarkdownV2" # 或 "HTML"

常见问题 Q: 为什么有些特殊字符显示不出来? A: Telegram 的 MarkdownV2 模式要求对某些字符进行转义:_ * [ ] ( ) ~ > # + - = | { } . !`。如果你发现格式错乱,检查是否忘了转义。

文件传输

用户可以给 Bot 发送文件,Hermes 会下载并处理:

用户: [上传文件:report.pdf]
Bot: 已收到文件 report.pdf(2.3MB),正在分析...
Bot: 这是这份报告的核心观点:...

文件处理配置:

security:
  max_file_size: "10MB"
  allowed_file_types: ["txt", "pdf", "docx", "jpg", "png"]

语音消息

Telegram 支持语音消息输入和输出:

# 开启语音输入(用户发语音,AI 识别文字并回复)
voice_input:
  enabled: true
  language: "zh-CN" # 语音识别语言
 
# 开启语音输出(AI 用语音回复)
voice_output:
  enabled: true
  voice: "alloy" # 语音音色

用户发送语音消息后,Hermes 会自动:

  1. 下载语音文件(.ogg 格式)
  2. 调用语音识别 API 转文字
  3. 把文字送进 AI 处理
  4. 生成回复文本
  5. (如果开启 voice_output)把回复转成语音发回

Tips 语音输入特别适合开车、做饭、健身时"动口不动手"的场景。但注意语音识别对环境噪音敏感,建议在相对安静的环境下使用。

3.9 常见问题排障(10个)

问题1:Bot 完全没有响应

排查步骤:

# 1. 检查网关是否启动
$ hermes gateway status
 
# 2. 检查 Bot Token 是否正确
$ curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"
# 如果返回 {"ok":true,...},Token 有效;如果 401 Unauthorized,Token 错了
 
# 3. 检查 allowlist
$ hermes config get TELEGRAM_ALLOWLIST
# 确认你的用户 ID 在列表中
 
# 4. 查看日志
$ hermes gateway logs --tail 50

常见原因:

  • Token 输错或已失效
  • 用户 ID 不在 allowlist
  • 网关进程崩溃了
  • 网络不通(国内可能需要代理)

问题2:可以收到消息但发不出去

原因: Bot 被 Telegram 限制了发送消息(通常是新注册的 Bot 有频率限制)。

解决: 等 24 小时后再试,或者给 BotFather 发送 /setprivacy 设置为 Disabled

问题3:群组里 Bot 不响应

排查:

  1. 确认 Bot 已经被添加为群组成员
  2. 确认 Bot 有发送消息的权限
  3. 检查 require_mention 设置,确认你正确 @ 了 Bot
  4. 确认群组 ID 在 allowlist 中(如果是负数 ID,检查是否写对了 -100 前缀)

问题4:中文消息显示乱码

解决: 在 config.yaml 中设置字符编码:

gateways:
  telegram:
    encoding: "utf-8"

问题5:文件上传失败

排查:

  1. 检查文件大小是否超过 max_file_size
  2. 检查文件类型是否在 allowed_file_types
  3. Telegram 对 Bot 有文件大小限制(通常 20MB)

问题6:Webhook 模式收不到消息

排查:

  1. 确认你的服务器有公网 IP 和 HTTPS 证书
  2. 确认 webhook_url 可访问(用浏览器或 curl 测试)
  3. 检查防火墙是否放行了 443 端口
# 测试 Webhook 是否可达
curl -X POST https://your-domain.com/webhook/telegram \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

问题7:Polling 模式频繁断线

原因: 网络不稳定,或同时运行了多个 Gateway 实例。

解决:

# 检查是否有多个 hermes gateway 进程
ps aux | grep hermes
 
# 如果有多个,杀掉所有进程后重新启动
killall hermes-gateway
hermes gateway start

问题8:AI 回复很慢

排查:

  1. 检查 AI 模型是否响应慢(直接测试 API)
  2. 检查是否有大量消息在队列中:hermes gateway status
  3. 增加 worker 数量:
    queue:
      worker_count: 8 # 从 4 增加到 8

问题9:Token 泄露了怎么办

紧急处理:

  1. 立即找 @BotFather 发送 /revoke
  2. 选择你的 Bot
  3. BotFather 会生成新 Token,旧 Token 立即失效
  4. 更新你的环境变量和配置

问题10:如何查看 Bot 的 webhook 信息

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

这个 API 会返回当前 webhook 的状态、挂起的更新数量、最后错误信息等,是排障的利器。

本章小结(Telegram 章节) 我们学习了 Telegram 接入的完整流程:创建 Bot、获取 Token、配置 allowlist、启动网关。还深入了解了群组使用、富文本、文件传输、语音消息等高级功能,以及 10 个常见问题的排障方案。现在你的 Hermes 已经可以通过 Telegram 随时响应你的指令了。


4. 飞书接入(国内最方便)

对于中国用户来说,飞书(Lark)是接入 Hermes 最方便的选择。 reasons 很简单:不用翻墙、服务器在国内、API 文档全中文、企业级稳定性。如果你的团队已经在用飞书,那接入 Hermes 后,团队成员可以直接在飞书里和 AI 对话,不需要额外安装任何 App。

4.1 飞书企业自建应用创建流程

飞书对第三方接入采用了"自建应用"的模式。你需要在飞书开放平台创建一个属于你自己的应用,然后给这个应用授权访问消息等能力。

步骤一:进入飞书开放平台

  1. 打开浏览器,访问 https://open.feishu.cn/
  2. 用企业管理员账号登录(注意:必须是企业管理员,普通员工没有创建应用的权限)

注意 如果你不是企业管理员,可以让管理员帮你操作,或者创建一个测试企业(免费)。创建测试企业的方法:飞书 App → 我的 → 创建或加入企业 → 创建企业 → 选择"用于开发测试"。

步骤二:创建企业自建应用

  1. 点击"开发者后台"
  2. 点击"创建企业自建应用"
  3. 填写应用信息:
    • 应用名称:Hermes 智能助手(可以自定义)
    • 应用描述:基于 Hermes 架构的 AI 智能助手
    • 应用图标:上传一张 512x512 的 PNG 图片
  4. 点击"确定创建"

步骤三:获取 App ID 和 App Secret

创建完成后,你会进入应用详情页。在"凭证与基础信息"栏目下:

App ID: cli_xxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

这两个值就是你的"用户名"和"密码",保存好它们:

export LARK_APP_ID="cli_xxxxxxxxxxxxxxxx"
export LARK_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

4.2 App ID 和 App Secret 获取

实际上上一步已经拿到了这两个值。这里重点强调安全存储:

# 保存到 macOS Keychain
security add-generic-password -s "hermes-lark-app-id" \
  -a "$(whoami)" -w "cli_xxxxxxxxxxxxxxxx"
security add-generic-password -s "hermes-lark-app-secret" \
  -a "$(whoami)" -w "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
# 然后在 shell 配置文件中添加读取逻辑
# ~/.zshrc:
export LARK_APP_ID="$(security find-generic-password -s "hermes-lark-app-id" -w)"
export LARK_APP_SECRET="$(security find-generic-password -s "hermes-lark-app-secret" -w)"

4.3 hermes gateway setup 选飞书

$ hermes gateway setup
 
🌐 Hermes Gateway 配置向导
══════════════════════════════════════════
 
请选择要接入的平台:
  ...
  [2] 飞书 (Lark)  - 国内企业协作首选
  ...
 
请输入数字选择: 2
 
📱 飞书配置
──────────────────────────────────────────
 
请输入 App ID: cli_xxxxxxxxxxxxxxxx
请输入 App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 凭证验证通过,应用名称:Hermes 智能助手
 
请选择接收模式:
  [1] Webhook - 需要公网服务器(推荐生产环境)
  [2] 事件回调 - 飞书主动推送事件
 
请输入数字选择: 2
 
事件订阅配置:
  事件订阅 URL: https://your-domain.com/webhook/lark
  验证 Token: xxxxxxxx
  加密密钥: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
请复制以下信息到飞书开放平台的事件订阅配置中:
  Request URL: https://your-domain.com/webhook/lark
  Verification Token: xxxxxxxx

4.4 事件订阅配置

飞书使用"事件订阅"机制来推送消息。你需要在飞书开放平台中配置一个回调 URL,飞书会把用户消息推送到这个 URL。

配置步骤:

  1. 在飞书开放平台 → 你的应用 → 事件订阅
  2. 设置 Request URL:
    • 如果你有自己的服务器:https://your-domain.com/webhook/lark
    • 如果你在内网/本地开发:使用 ngrok 穿透
      # 安装 ngrok
      brew install ngrok
      # 注册并获取 authtoken
      ngrok config add-authtoken xxxxx
      # 启动穿透(把本地 8080 映射到公网)
      ngrok http 8080
      # 会得到类似 https://abc123.ngrok-free.app 的地址
  3. 设置 Verification Token:从 Hermes 配置向导中复制
  4. 设置 Encrypt Key(可选但推荐):用于加密传输内容

订阅需要的事件:

在"事件订阅"页面,添加以下事件:

✅ 接收消息(v2.0)           —— 必须!接收用户消息
✅ 应用被用户添加至群聊        —— 用于群组场景
✅ 用户进入会话               —— 可选,用于欢迎语
✅ 消息被撤回                —— 可选

4.5 权限设置(最小权限原则)

安全的第一原则是最小权限——只给应用它必须的权限,不多给一寸。

在飞书开放平台 → 你的应用 → 权限管理,申请以下权限:

必要权限(必须):
  ✅ 获取与发送单聊、群聊消息(im:chat:readonly, im:message:send_as_bot)
  ✅ 获取用户 user ID(contact:user.employee_id:readonly)

推荐权限(常用功能):
  ✅ 获取用户信息(contact:user.base:readonly)
  ✅ 获取群组信息(im:chat:readonly)
  ✅ 上传文件(drive:file:write)

可选权限(按需申请):
  ✅ 读取日历(calendar:calendar:readonly)
  ✅ 读取文档(docx:document:readonly)

注意 每次修改权限后,必须点击"申请发布" → "创建版本" → "保存",然后企业管理员在"应用审核"中批准,权限才能生效。这是很多新手卡住的地方。

4.6 消息卡片与富文本

飞书的强项是"消息卡片"(Interactive Card),它支持比纯文本丰富得多的展示形式。

Hermes 可以自动把 AI 的回复渲染成飞书卡片:

gateways:
  lark:
    card_mode: true
    card_template: "default"

示例效果——当 AI 回复天气查询时:

┌─────────────────────────────────────┐
│  ☀️ 北京明日天气预报                  │
├─────────────────────────────────────┤
│  天气:晴转多云                       │
│  温度:15°C ~ 22°C                   │
│  风力:东北风 3-4 级                  │
│  空气质量:良                         │
├─────────────────────────────────────┤
│  [查看详情] [分享]                   │
└─────────────────────────────────────┘

Tips 飞书卡片的消息长度限制比纯文本宽松得多。如果你的 AI 回复特别长(比如一份完整报告),开启 card_mode 能获得更好的阅读体验。

4.7 常见问题排障

问题1:事件订阅验证失败

原因: Request URL 不可达,或返回格式不正确。

解决:

  1. 确认 URL 可以从公网访问(用浏览器或 curl 测试)
  2. 确认返回了正确的 challenge 响应
  3. 检查防火墙和 HTTPS 证书
# 测试回调 URL
curl -X POST https://your-domain.com/webhook/lark \
  -H "Content-Type: application/json" \
  -d '{"challenge": "test123", "type": "url_verification"}'
 
# 期望返回:
# {"challenge": "test123"}

问题2:消息能收到但发不出去

原因: 没有申请 im:message:send_as_bot 权限,或权限未审批。

解决:

  1. 检查权限管理页面是否已申请发送消息权限
  2. 检查应用是否已发布并通过审批
  3. 检查 Bot 是否被用户添加到会话中

问题3:用户 ID 找不到

飞书的用户标识体系比较复杂:

ID 类型示例用途
user_idou_xxxxxxxxxxxxxxxx飞书内部用户 ID
union_idon_xxxxxxxxxxxxxxxx企业内唯一 ID
open_idou_xxxxxxxxxxxxxxxx应用维度唯一 ID
employee_id12345员工工号

Hermes 的 allowlist 使用的是 user_id(以 ou_on_ 开头)。

问题4:应用在群里收不到消息

解决:

  1. 把 Bot 添加到群里(在群里 @Bot 并选择"添加到群聊")
  2. 确保订阅了"接收消息"事件
  3. 检查应用是否有群聊消息的权限

问题5:企业管理员不审批怎么办

如果你的应用卡在"待审核"状态:

  1. 联系企业管理员手动审批
  2. 或者创建测试企业自己当管理员
  3. 飞书开放平台也有"测试企业和人员"功能,可以免审批测试

本章小结(飞书章节) 我们学习了飞书接入的完整流程:创建自建应用、获取 App ID/Secret、配置事件订阅、设置最小权限。飞书的消息卡片能力让 AI 回复的展示效果更上一层楼。对于国内用户来说,飞书是团队协作场景下接入 Hermes 的最佳选择。


5. 微信接入

微信是国内使用最广泛的即时通讯工具,但它对第三方 Bot 的限制也最严格。微信生态有三个主要接入点:企业微信、微信公众号、以及个人微信(需第三方桥接)。

5.1 企业微信自建应用接入教程

企业微信是微信生态中对第三方应用最友好的入口,适合企业内部使用。

步骤一:注册企业微信

  1. 访问 https://work.weixin.qq.com/
  2. 注册一个企业(可以用个人身份注册)
  3. 进入"应用管理"

步骤二:创建自建应用

  1. 应用管理 → 自建 → 创建应用
  2. 填写应用信息:
    • 应用名称:Hermes 智能助手
    • 应用介绍:AI 办公助手
    • 可见范围:选择可以使用此应用的部门/成员
  3. 上传应用 Logo
  4. 点击"创建应用"

步骤三:获取凭证

创建完成后,在应用详情页获取:

AgentId: 1000002
Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

同时还需要企业 ID:

  1. 我的企业 → 企业 ID
  2. 复制 wwxxxxxxxxxxxxxxxx 格式的企业 ID

步骤四:配置 Hermes

gateways:
  wecom:
    enabled: true
    corp_id: "${WECOM_CORP_ID}"
    agent_id: "${WECOM_AGENT_ID}"
    secret: "${WECOM_SECRET}"
    receive_mode: "webhook"
    webhook_url: "https://your-domain.com/webhook/wecom"
    token: "${WECOM_TOKEN}"
    encoding_aes_key: "${WECOM_AES_KEY}"
    allowlist: []

步骤五:配置接收消息

在企业微信应用详情 → 接收消息 → 设置 API:

URL: https://your-domain.com/webhook/wecom
Token: 随机生成一个字符串(和 config.yaml 中的 token 一致)
EncodingAESKey: 随机生成或手动输入(和 config.yaml 中的 encoding_aes_key 一致)
消息加解密:推荐选择"安全模式"

注意 企业微信的消息加密比较严格,Token 和 AES Key 必须完全匹配。如果验证失败,仔细检查大小写和空格。

5.2 微信公众号接入方式

微信公众号(订阅号/服务号)也可以接入 Hermes,适合做客服和内容推送。

前提条件:

  • 一个已认证的微信公众号(个人订阅号功能受限)
  • 服务器和域名(接收微信推送)

配置步骤:

  1. 微信公众平台 → 开发 → 基本配置
  2. 获取 AppID 和 AppSecret
  3. 设置服务器配置:
    • URL:https://your-domain.com/webhook/wechat-mp
    • Token:自定义,和 Hermes 配置一致
    • EncodingAESKey:随机生成
    • 消息加解密模式:明文/兼容/安全
  4. 在 Hermes config.yaml 中配置:
gateways:
  wechat_mp:
    enabled: true
    app_id: "${WECHAT_MP_APP_ID}"
    app_secret: "${WECHAT_MP_APP_SECRET}"
    token: "${WECHAT_MP_TOKEN}"
    encoding_aes_key: "${WECHAT_MP_AES_KEY}"

注意 微信公众号有严格的接口频率限制:普通订阅号每天只能发 1 条群发消息,服务号每月 4 条。用户主动发消息没有限制,但回复必须在 48 小时内。这些限制使得微信公众号不适合高频对话场景,更适合做"问答客服"。

5.3 个人微信接入方案(第三方桥接)

个人微信(就是你在手机上天天用的那个微信)没有官方 Bot API。如果有人说能"直接接入个人微信",那一定是在用非官方的第三方方案。

目前主流的方案有以下几种:

方案原理稳定性风险
iPad 协议模拟 iPad 客户端登录⭐⭐ 一般可能被封号
Windows Hook注入 Windows 微信进程⭐ 差极易被封
Android Hook注入 Android 微信⭐ 差极易被封
企业微信互通通过企业微信连接微信⭐⭐⭐ 较好较低

注意 使用非官方方案接入个人微信存在封号风险! 微信对此类行为的打击力度一直在加强。建议优先使用企业微信或微信公众号作为替代方案。

如果你确实需要个人微信接入,推荐使用基于 gewewechaty 的方案,但它们需要额外部署中间件服务:

gateways:
  wechat_puppet:
    enabled: true
    puppet_type: "wechaty-puppet-wechat"
    puppet_endpoint: "http://localhost:8788"
    # 需要额外运行一个 wechaty gateway 服务

5.4 限制与注意事项

微信生态接入的限制汇总:

企业微信:
  ✓ 官方支持,稳定可靠
  ✓ 适合企业内部使用
  ✗ 外部客户使用需要购买接口许可
  ✗ 消息模板审核严格

微信公众号:
  ✓ 官方支持,用户基数大
  ✗ 频率限制严格
  ✗ 需要认证才能使用高级接口
  ✗ 48小时回复窗口限制

个人微信(第三方):
  ✗ 无官方 API
  ✗ 封号风险
  ✗ 需要额外部署中间件
  ✗ 不稳定

本章小结(微信章节) 企业微信是微信生态中接入 Hermes 的最佳选择,官方支持、稳定可靠。微信公众号适合做轻量级客服。个人微信接入风险较高,不建议生产环境使用。


6. Discord 接入

Discord 是全球游戏玩家和开发者社区的首选平台。如果你管理着一个开源社区、游戏公会或者技术讨论群,把 Hermes 接入 Discord 能让成员随时向 AI 提问。

6.1 Discord Bot 创建流程

步骤一:进入 Discord Developer Portal

  1. 访问 https://discord.com/developers/applications
  2. 用 Discord 账号登录

步骤二:创建应用

  1. 点击"New Application"
  2. 输入应用名称:Hermes Assistant
  3. 点击"Create"

步骤三:添加 Bot

  1. 左侧菜单 → "Bot" → "Add Bot"
  2. 点击"Yes, do it!"

步骤四:获取 Token

在 Bot 页面,点击"Reset Token",复制新生成的 Token:

export DISCORD_BOT_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxx"

注意 Discord 的 Token 格式是三段式的,中间有 . 分隔。如果 Token 泄露,立即 Reset Token,旧的会立即失效。

6.2 Token 获取与权限配置

设置 Bot 权限:

在"Bot"页面,打开以下开关:

✅ Presence Intent     —— 获取在线状态
✅ Server Members Intent —— 获取服务器成员列表
✅ Message Content Intent —— 必须!读取消息内容

注意 Message Content Intent 是最容易被遗漏的选项。如果不开启,Bot 只能收到"有人发消息了"的事件,但看不到消息内容。这是 Discord 2022 年后的安全策略变更。

生成 OAuth2 邀请链接:

  1. 左侧菜单 → "OAuth2" → "URL Generator"
  2. 在 Scopes 中选择 bot
  3. 在 Bot Permissions 中选择:
    ✅ Send Messages
    ✅ Send Messages in Threads
    ✅ Read Message History
    ✅ Use Slash Commands
    ✅ Attach Files
    ✅ Embed Links
    ✅ Add Reactions
    
  4. 复制生成的 URL,在浏览器中打开,邀请 Bot 加入你的服务器

6.3 频道管理与权限

Discord 的权限模型比较复杂,分为服务器级、频道级和角色级。

建议的权限设置:

  1. 创建一个专门给 Bot 使用的角色(如"AI Assistant")
  2. 在频道设置中:
    • 允许 Bot 角色:查看频道、发送消息、读取历史、嵌入链接
    • 拒绝 Bot 角色:管理频道、管理消息、踢人、禁言

配置 Hermes:

gateways:
  discord:
    enabled: true
    bot_token: "${DISCORD_BOT_TOKEN}"
    receive_mode: "websocket"
    allowlist: []
    # 只在特定频道响应(可选)
    allowed_channels:
      - "1234567890123456789"
    # 忽略特定频道
    ignored_channels: []
    # 命令前缀
    command_prefix: "!"

Tips Discord 支持 Slash Command(/ask 这种命令形式)。Hermes 可以自动注册 Slash Command,让用户在任意频道输入 /ask 问题 来触发 AI。


7. 其他平台接入

7.1 Slack 接入

Slack 是海外企业协作的标配。接入流程和 Discord 类似:

步骤:

  1. https://api.slack.com/apps → Create New App
  2. 选择"From scratch"
  3. 在"OAuth & Permissions"中申请权限:
    • chat:write —— 发送消息
    • im:history —— 读取私信历史
    • channels:history —— 读取频道历史
    • app_mentions:read —— 读取 @提及
  4. 安装应用到 Workspace,获取 Bot User OAuth Token
  5. 在"Event Subscriptions"中订阅 app_mentionmessage.im
gateways:
  slack:
    enabled: true
    bot_token: "${SLACK_BOT_TOKEN}"
    signing_secret: "${SLACK_SIGNING_SECRET}"
    receive_mode: "webhook"
    webhook_url: "https://your-domain.com/webhook/slack"
    allowlist: []

7.2 WhatsApp 接入

WhatsApp Business API 需要 Meta 官方审批,流程较长:

  1. 注册 Meta 开发者账号
  2. 创建 Business App
  3. 申请 WhatsApp Business API 访问权限
  4. 设置 Business Account 和 Phone Number
  5. 获取 Access Token 和 Phone Number ID
gateways:
  whatsapp:
    enabled: true
    api_token: "${WHATSAPP_API_TOKEN}"
    phone_number_id: "${WHATSAPP_PHONE_NUMBER_ID}"
    business_account_id: "${WHATSAPP_BUSINESS_ACCOUNT_ID}"
    receive_mode: "webhook"
    webhook_verify_token: "${WHATSAPP_VERIFY_TOKEN}"

注意 WhatsApp Business API 不是免费的。Meta 按对话收费,24小时内的消息往来算一个对话(约 0.005-0.08 美元,视地区而定)。使用前请确认成本预算。

7.3 Signal 接入

Signal 以隐私著称,官方没有 Bot API。需要使用第三方库 signaldsignal-cli

gateways:
  signal:
    enabled: true
    # 需要本地运行 signald 或 signal-cli 服务
    signal_cli_endpoint: "http://localhost:8080"
    phone_number: "+8613800138000"

7.4 Email 接入

Email Gateway 让 Hermes 可以通过邮件与你交互,适合异步场景:

gateways:
  email:
    enabled: true
    # IMAP 配置(接收邮件)
    imap_server: "imap.gmail.com"
    imap_port: 993
    imap_ssl: true
    username: "[email protected]"
    password: "${EMAIL_PASSWORD}"
    # SMTP 配置(发送邮件)
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    smtp_starttls: true
    # 检查频率
    poll_interval: 300 # 每 5 分钟检查一次
    # 只处理特定主题的邮件
    subject_filter: "[Hermes]"
    allowlist:
      - "[email protected]"

Tips Gmail 需要使用"应用专用密码"(App Password),不能使用你的 Google 账号密码。在 Google 账号 → 安全性 → 两步验证 → 应用专用密码 中创建。

7.5 SMS 接入

SMS Gateway 需要第三方短信服务商(如 Twilio):

gateways:
  sms:
    enabled: true
    provider: "twilio"
    account_sid: "${TWILIO_ACCOUNT_SID}"
    auth_token: "${TWILIO_AUTH_TOKEN}"
    from_number: "+1234567890"
    receive_mode: "webhook"
    webhook_url: "https://your-domain.com/webhook/sms"

7.6 Matrix 接入

Matrix 是去中心化的通讯协议,适合自托管和隐私优先的场景:

gateways:
  matrix:
    enabled: true
    homeserver: "https://matrix.org"
    user_id: "@hermes:matrix.org"
    access_token: "${MATRIX_ACCESS_TOKEN}"
    device_id: "HERMES_GATEWAY"
    allowed_rooms:
      - "!xxxxxxxx:matrix.org"

7.7 Mattermost 接入

Mattermost 是开源的 Slack 替代品,适合自托管企业:

gateways:
  mattermost:
    enabled: true
    server_url: "https://mattermost.your-company.com"
    bot_token: "${MATTERMOST_BOT_TOKEN}"
    team_name: "your-team"

7.8 Home Assistant 接入

Home Assistant 是开源智能家居平台。通过接入 Hermes,你可以用自然语言控制家里的设备:

gateways:
  homeassistant:
    enabled: true
    server_url: "http://homeassistant.local:8123"
    long_lived_token: "${HA_TOKEN}"
    webhook_id: "hermes_gateway"
    # 暴露给 AI 的设备域
    allowed_domains:
      - "light"
      - "switch"
      - "climate"
      - "media_player"

配合 Hermes 的工具调用能力,你可以说:

你: 把客厅的灯关掉,空调调到 26 度
Hermes: 好的,已关闭客厅灯光,空调温度已设置为 26°C。

Tips Home Assistant 的 long_lived_token 可以在"用户资料" → "长期访问令牌"中创建。务必妥善保管,这个 Token 拥有和你账号一样的所有权限。


8. 编辑器集成

编辑器集成是 Hermes 的杀手锏功能之一。它让你在写代码的同时,直接把 AI 召唤到编辑器里,不需要切换窗口、复制粘贴。

8.1 VS Code 集成(ACP 协议)

VS Code 是目前最流行的代码编辑器,Hermes 通过 ACP(Agent Communication Protocol) 与其深度集成。

安装扩展

  1. 打开 VS Code
  2. 点击左侧扩展图标(或按 Cmd+Shift+X
  3. 搜索 "Hermes Assistant"
  4. 点击"安装"

配置连接

安装后,点击左侧 Hermes 图标,输入你的 Hermes 服务器地址:

// VS Code settings.json
{
  "hermes.serverUrl": "http://localhost:8080",
  "hermes.apiKey": "your-api-key",
  "hermes.autoConnect": true,
  "hermes.inlineCompletion": true,
  "hermes.chatLocation": "sidebar"
}

使用方式

方式1:侧边栏聊天
  - 点击左侧 Hermes 图标
  - 在聊天框输入问题
  - 支持多轮对话

方式2:内联编辑(Inline Edit)
  - 选中一段代码
  - 按 Cmd+Shift+A(或右键 → Ask Hermes)
  - 输入指令,比如"给这段代码加注释"
  - AI 会直接修改选中的代码

方式3:命令面板
  - Cmd+Shift+P → "Hermes: Explain Code"
  - Cmd+Shift+P → "Hermes: Generate Tests"
  - Cmd+Shift+P → "Hermes: Fix Bugs"

方式4:智能补全
  - 输入代码时,按 Tab 接受 AI 建议
  - 灰色文字是 AI 的续写建议

Tips ACP 协议让 VS Code 和 Hermes 之间可以传递丰富的上下文信息——不只是当前文件内容,还包括光标位置、选中的代码、打开的终端输出、甚至调试器状态。这让 AI 的回答比普通聊天精准得多。

8.2 Zed 编辑器集成

Zed 是新一代高性能编辑器,内置了 AI 助手功能。Hermes 可以作为 Zed 的自定义 AI 后端:

// ~/.config/zed/settings.json
{
  "assistant": {
    "version": "2",
    "default_model": {
      "provider": "hermes",
      "model": "hermes-default"
    },
    "providers": {
      "hermes": {
        "type": "openai",
        "api_url": "http://localhost:8080/v1",
        "available_models": [
          {
            "name": "hermes-default",
            "display_name": "Hermes",
            "max_tokens": 128000
          }
        ]
      }
    }
  }
}

配置完成后,在 Zed 中按 Ctrl+~(或 Cmd+~)打开 Assistant 面板,即可与 Hermes 对话。

8.3 JetBrains IDE 集成

JetBrains 系列(IntelliJ IDEA、PyCharm、WebStorm 等)通过插件市场安装 Hermes 插件:

  1. 打开 IDE → Settings → Plugins → Marketplace
  2. 搜索 "Hermes"
  3. 安装并重启 IDE
  4. 配置 Hermes 服务器地址

使用方式:

  • 选中代码 → 右键 → Hermes → Explain / Refactor / Test
  • 底部工具栏打开 Hermes 聊天面板
  • 使用快捷键 Alt+H 快速提问

9. 语音交互

语音是人类最自然的交互方式。Hermes 支持完整的语音输入和输出能力,让你"动动嘴"就能指挥 AI。

9.1 语音输入/输出配置

# ~/.hermes/config.yaml
 
voice:
  # 语音输入(语音识别)
  input:
    enabled: true
    # 识别引擎:openai_whisper, azure_speech, local_whisper
    provider: "openai_whisper"
    # 语言代码
    language: "zh"
    # 自动检测语言
    auto_detect_language: true
    # 识别超时
    timeout: 30
 
  # 语音输出(语音合成)
  output:
    enabled: true
    # 合成引擎:openai_tts, azure_tts, edge_tts
    provider: "openai_tts"
    # 音色选择
    voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer
    # 语速:0.25 ~ 4.0
    speed: 1.0
    # 输出格式
    format: "mp3"

9.2 支持的语音后端

后端类型质量成本隐私
OpenAI Whisper识别⭐⭐⭐⭐⭐按量计费数据上传至 OpenAI
OpenAI TTS合成⭐⭐⭐⭐⭐按量计费数据上传至 OpenAI
Azure Speech识别+合成⭐⭐⭐⭐按量计费数据上传至 Azure
Edge TTS合成⭐⭐⭐免费本地处理
Local Whisper识别⭐⭐⭐⭐免费(消耗本地 GPU)完全本地

Local Whisper 配置(完全离线):

voice:
  input:
    provider: "local_whisper"
    model: "base" # tiny, base, small, medium, large
    device: "cuda" # cuda 或 cpu
    download_root: "~/.hermes/models/whisper"

Tips 如果你在意隐私(比如处理公司内部敏感信息),强烈推荐使用 Local Whisper。base 模型在消费级 GPU 上实时识别没有问题,medium 模型准确率接近云端 API。

9.3 语音交互最佳实践

场景1:开车时查询信息
  你(语音):" Hermes,查一下今天有哪些会议"
  AI(语音):"今天你有三个会议:上午 10 点的产品评审、下午 2 点的技术分享、下午 4 点的客户沟通"

场景2:做饭时听新闻摘要
  你(语音):"总结一下今天的人工智能新闻"
  AI(语音):"今天 AI 领域有三条重要消息:第一,..."

场景3:睡前口述日记
  你(语音):"记录一下,今天完成了用户调研报告,明天需要..."
  AI(文字+语音):"已记录到待办事项..."

注意 语音识别的准确率受环境影响很大。嘈杂环境、方言口音、专业术语都可能导致识别错误。建议在安静环境下使用,或者对重要信息做二次确认。


10. 多平台协同使用

多平台接入的真正威力,不在于"能在很多平台上用",而在于"不同平台之间能协同工作"。

10.1 同一 Hermes 实例多平台同时接入

我们已经知道,只需要在 config.yaml 中启用多个平台,它们就会同时在线:

gateways:
  telegram:
    enabled: true
    # ...
  lark:
    enabled: true
    # ...
  discord:
    enabled: true
    # ...

启动后,Gateway Manager 会同时维护三个 Adapter 的连接:

$ hermes gateway status
 
🌐 Gateway 运行状态
══════════════════════════════════════════════════
Telegram 在线  (@HermesAssistantBot)
飞书 在线  (应用: Hermes Assistant)
Discord 在线  (Bot: Hermes#1234)
Email 离线  (IMAP 连接失败)
 
消息队列:3/1000
活跃会话:12
平均响应时间:2.3s

10.2 上下文和记忆在平台间同步

默认情况下,每个平台的会话上下文是独立的。但 Hermes 支持通过 user_mapping 把不同平台的用户身份关联起来:

gateway:
  user_mapping:
    # 把 Telegram 用户和飞书用户映射到同一个 Hermes 用户 ID
    - hermes_user_id: "user_zhangsan"
      platform_users:
        - platform: "telegram"
          platform_user_id: "12345678"
        - platform: "lark"
          platform_user_id: "ou_xxxxxxxx"

配置后,当"张三"在 Telegram 里问"刚才说的方案呢",AI 能找到他在飞书里上一轮对话的上下文——因为它们被映射到了同一个 hermes_user_id

10.3 实战案例:手机 Telegram → 电脑执行 → 飞书汇报

这是一个真实的多平台协同场景:

时间线:

09:00  [手机 - Telegram]
        你: "帮我查一下竞品 A 公司最近三个月的融资信息"
        Hermes: "好的,正在搜索..."

09:05  [Hermes 后台]
        - 调用搜索工具,查找竞品 A 的融资新闻
        - 整理成结构化数据
        - 保存到记忆系统,标记为"竞品分析任务"

09:15  [电脑 - VS Code]
        你(看到侧边栏通知):"把刚才的竞品分析整理成 PPT 大纲"
        Hermes: "基于刚才的搜索结果,PPT 大纲如下:..."

09:30  [Hermes 后台]
        - 生成完整的 PPT 大纲
        - 保存到文件 ~/Documents/竞品分析_2024Q1.md

10:00  [飞书]
        你: "把今天的竞品分析发送到产品群"
        Hermes: "已发送到飞书群「产品团队」"
        [飞书群里出现一条消息卡片,包含完整的竞品分析]

这个案例展示了多平台协同的核心价值:

  • 设备无关:手机上发起任务,电脑上继续处理
  • 状态持久:AI 记得"刚才"指的是什么
  • 渠道分发:结果自动发送到最合适的平台(飞书群汇报)

11. 安全与运维

11.1 Token/Key 安全管理

所有平台接入都需要某种形式的凭证(Token、Key、Secret)。安全管理的核心原则:

原则1:绝不硬编码

# ❌ 错误示范
gateways:
  telegram:
    bot_token: "123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
# ✅ 正确示范
gateways:
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"

原则2:使用密钥管理工具

# macOS Keychain
security add-generic-password -s "hermes-tg-token" -w "..."
 
# 或 1Password CLI
op read "op://Private/Hermes/TelegramToken"
 
# 或 AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id hermes/tokens

原则3:定期轮换

建议每 3-6 个月重置一次 Token,尤其是 Telegram 和 Discord 的 Bot Token。

原则4:最小权限

每个平台的凭证只申请必需的权限。不要图省事给"所有权限"。

11.2 访问控制与白名单

我们在 Telegram 章节已经介绍了 allowlist,这里补充一些进阶用法:

gateway:
  security:
    # 全局 allowlist(优先级最高)
    global_allowlist:
      - "telegram:12345678"
      - "lark:ou_xxxxxxxx"
      - "discord:987654321"
 
    # 时间限制(只允许工作时间)
    allowed_hours:
      start: "09:00"
      end: "21:00"
      timezone: "Asia/Shanghai"
 
    # 频率限制(防刷屏)
    rate_limit:
      max_requests_per_minute: 30
      max_requests_per_hour: 200
      # 超限后的冷却时间
      cooldown_seconds: 60
 
    # 内容过滤
    blocked_patterns:
      - "(?i)(密码|password)\s*[=:]\s*\S+"
      - "(?i)(token|secret|key)\s*[=:]\s*\S+"

11.3 网关进程管理

生产环境中,你需要稳定地管理 Gateway 进程。

使用 systemd(Linux 服务器):

# /etc/systemd/system/hermes-gateway.service
[Unit]
Description=Hermes Gateway
After=network.target
 
[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
Environment=TELEGRAM_BOT_TOKEN=xxx
Environment=LARK_APP_ID=xxx
Environment=LARK_APP_SECRET=xxx
ExecStart=/usr/local/bin/hermes gateway start
Restart=always
RestartSec=5
 
[Install]
WantedBy=multi-user.target
# 启动服务
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway
 
# 查看状态
sudo systemctl status hermes-gateway
 
# 查看日志
sudo journalctl -u hermes-gateway -f

使用 PM2(Node.js 风格管理):

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: "hermes-gateway",
      script: "hermes",
      args: "gateway start",
      instances: 1,
      autorestart: true,
      watch: false,
      max_memory_restart: "1G",
      env: {
        NODE_ENV: "production",
        TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
      },
      log_file: "./logs/gateway.log",
      error_file: "./logs/gateway-error.log",
      out_file: "./logs/gateway-out.log",
      time: true,
    },
  ],
};
pm2 start ecosystem.config.js
pm2 save
pm2 startup

使用 Docker(容器化部署):

# Dockerfile
FROM python:3.11-slim
 
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
 
COPY . .
 
ENV TELEGRAM_BOT_TOKEN=""
ENV LARK_APP_ID=""
ENV LARK_APP_SECRET=""
 
EXPOSE 8080
 
CMD ["hermes", "gateway", "start"]
# docker-compose.yml
version: "3.8"
 
services:
  hermes-gateway:
    build: .
    ports:
      - "8080:8080"
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - LARK_APP_ID=${LARK_APP_ID}
      - LARK_APP_SECRET=${LARK_APP_SECRET}
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "hermes", "gateway", "status"]
      interval: 30s
      timeout: 10s
      retries: 3

使用 Hermes 内置的 daemon 命令:

# 启动守护进程
hermes gateway start --daemon
 
# 查看状态
hermes gateway status
 
# 停止
hermes gateway stop
 
# 重启
hermes gateway restart
 
# 查看日志
hermes gateway logs --tail 100 --follow

Tips 对于生产环境,推荐使用 systemd 或 Docker 管理进程,因为它们提供了更完善的日志收集、自动重启、资源限制等功能。内置的 --daemon 适合个人开发和轻量级部署。


本章小结 在本章(第十册)中,我们完成了多平台接入的完整学习之旅:

  • 理解了 Gateway 架构的设计理念和工作原理
  • 详细学习了 Telegram、飞书、微信、Discord 的接入流程
  • 了解了 Slack、WhatsApp、Email、Home Assistant 等其他平台的配置
  • 掌握了编辑器集成(VS Code、Zed、JetBrains)和语音交互的配置
  • 学会了多平台协同使用的策略
  • 建立了 Token 安全管理和网关运维的最佳实践

现在,你的 Hermes 已经可以在任何你需要的地方响应你的指令——无论是在手机上、电脑前、还是智能家居设备旁。多平台接入的真正价值,是让 AI 成为你生活中无缝衔接的一部分。