第十册:多平台接入实战
本章你将学到
- 为什么多平台接入是 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 | 个人用户、开发者社群、海外团队 | ⭐ 简单 |
| 海外商务沟通、亲友联络 | ⭐⭐ 中等 | ||
| Signal | 高隐私要求场景 | ⭐⭐ 中等 | |
| SMS | 无网络环境下的备用通道 | ⭐⭐ 中等 | |
| 企业协作 | 飞书(Lark) | 国内团队、字节生态 | ⭐ 简单 |
| 企业微信 | 腾讯生态企业、国内商务 | ⭐⭐ 中等 | |
| Slack | 海外团队、开发者社区 | ⭐ 简单 | |
| Discord | 游戏社群、开源社区、粉丝群 | ⭐ 简单 | |
| Matrix | 去中心化、隐私优先团队 | ⭐⭐⭐ 复杂 | |
| Mattermost | 自托管企业协作 | ⭐⭐⭐ 复杂 | |
| 社交媒体 | 微信公众号 | 内容运营、客服自动化 | ⭐⭐⭐ 复杂 |
| 智能家居 | Home Assistant | 语音控制、IoT 联动 | ⭐⭐ 中等 |
| 编辑器 | VS Code | 编程辅助、代码审查 | ⭐ 简单 |
| Zed | 新一代代码编辑器 | ⭐ 简单 | |
| JetBrains IDE | Java/Python/Go 开发 | ⭐⭐ 中等 | |
| 语音 | 语音交互后端 | 语音输入/输出 | ⭐⭐ 中等 |
| 邮件 | 异步沟通、报告分发 | ⭐⭐ 中等 |
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 设计的一个容易混淆的地方。
获取方法很简单:
- 在 Telegram 搜索
@userinfobot - 发送
/start或任意消息 - 它会回复你的用户信息:
@userinfobot:
Id: 12345678
First: 张三
Lang: zh-hans
这里的 Id: 12345678 就是你要的数字用户 ID。
常见问题 Q: 为什么不能用 @用户名做 allowlist? A: 因为 @用户名是可以修改的,而数字 ID 终身不变。用数字 ID 更安全、更稳定。
如果你想查看群里其他人的 ID,可以使用 @getidsbot:
- 把 @getidsbot 加到群里
- 随便发一条消息
- 它会回复包含所有成员 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: true3.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.log3.6 安全配置:允许列表(Allowlist)详解
Allowlist 是 Gateway 的第一道安全防线。它的作用很简单:只有列表里的用户能与你的 Bot 交互。
为什么必须设置 Allowlist?
想象你没设置 allowlist,然后你的 Bot Token 不小心泄露到了 GitHub 上(别笑,这种事每天都在发生)。黑客拿到 Token 后,可以:
- 查询你的 Bot 收到了哪些消息
- 冒充你的 Bot 给用户发钓鱼链接
- 利用你的 Bot 做跳板攻击其他系统
- 消耗你的 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 加到群组
- 在 Telegram 中打开目标群组
- 点击群组名称 → 添加成员
- 搜索你的 Bot 用户名(如
@HermesAssistantBot) - 添加后,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 会自动:
- 下载语音文件(.ogg 格式)
- 调用语音识别 API 转文字
- 把文字送进 AI 处理
- 生成回复文本
- (如果开启 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 不响应
排查:
- 确认 Bot 已经被添加为群组成员
- 确认 Bot 有发送消息的权限
- 检查
require_mention设置,确认你正确@了 Bot - 确认群组 ID 在 allowlist 中(如果是负数 ID,检查是否写对了
-100前缀)
问题4:中文消息显示乱码
解决: 在 config.yaml 中设置字符编码:
gateways:
telegram:
encoding: "utf-8"问题5:文件上传失败
排查:
- 检查文件大小是否超过
max_file_size - 检查文件类型是否在
allowed_file_types中 - Telegram 对 Bot 有文件大小限制(通常 20MB)
问题6:Webhook 模式收不到消息
排查:
- 确认你的服务器有公网 IP 和 HTTPS 证书
- 确认 webhook_url 可访问(用浏览器或 curl 测试)
- 检查防火墙是否放行了 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 回复很慢
排查:
- 检查 AI 模型是否响应慢(直接测试 API)
- 检查是否有大量消息在队列中:
hermes gateway status - 增加 worker 数量:
queue: worker_count: 8 # 从 4 增加到 8
问题9:Token 泄露了怎么办
紧急处理:
- 立即找 @BotFather 发送
/revoke - 选择你的 Bot
- BotFather 会生成新 Token,旧 Token 立即失效
- 更新你的环境变量和配置
问题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 飞书企业自建应用创建流程
飞书对第三方接入采用了"自建应用"的模式。你需要在飞书开放平台创建一个属于你自己的应用,然后给这个应用授权访问消息等能力。
步骤一:进入飞书开放平台
- 打开浏览器,访问 https://open.feishu.cn/
- 用企业管理员账号登录(注意:必须是企业管理员,普通员工没有创建应用的权限)
注意 如果你不是企业管理员,可以让管理员帮你操作,或者创建一个测试企业(免费)。创建测试企业的方法:飞书 App → 我的 → 创建或加入企业 → 创建企业 → 选择"用于开发测试"。
步骤二:创建企业自建应用
- 点击"开发者后台"
- 点击"创建企业自建应用"
- 填写应用信息:
- 应用名称:Hermes 智能助手(可以自定义)
- 应用描述:基于 Hermes 架构的 AI 智能助手
- 应用图标:上传一张 512x512 的 PNG 图片
- 点击"确定创建"
步骤三:获取 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: xxxxxxxx4.4 事件订阅配置
飞书使用"事件订阅"机制来推送消息。你需要在飞书开放平台中配置一个回调 URL,飞书会把用户消息推送到这个 URL。
配置步骤:
- 在飞书开放平台 → 你的应用 → 事件订阅
- 设置 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 的地址
- 如果你有自己的服务器:
- 设置 Verification Token:从 Hermes 配置向导中复制
- 设置 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 不可达,或返回格式不正确。
解决:
- 确认 URL 可以从公网访问(用浏览器或 curl 测试)
- 确认返回了正确的 challenge 响应
- 检查防火墙和 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 权限,或权限未审批。
解决:
- 检查权限管理页面是否已申请发送消息权限
- 检查应用是否已发布并通过审批
- 检查 Bot 是否被用户添加到会话中
问题3:用户 ID 找不到
飞书的用户标识体系比较复杂:
| ID 类型 | 示例 | 用途 |
|---|---|---|
user_id | ou_xxxxxxxxxxxxxxxx | 飞书内部用户 ID |
union_id | on_xxxxxxxxxxxxxxxx | 企业内唯一 ID |
open_id | ou_xxxxxxxxxxxxxxxx | 应用维度唯一 ID |
employee_id | 12345 | 员工工号 |
Hermes 的 allowlist 使用的是 user_id(以 ou_ 或 on_ 开头)。
问题4:应用在群里收不到消息
解决:
- 把 Bot 添加到群里(在群里 @Bot 并选择"添加到群聊")
- 确保订阅了"接收消息"事件
- 检查应用是否有群聊消息的权限
问题5:企业管理员不审批怎么办
如果你的应用卡在"待审核"状态:
- 联系企业管理员手动审批
- 或者创建测试企业自己当管理员
- 飞书开放平台也有"测试企业和人员"功能,可以免审批测试
本章小结(飞书章节) 我们学习了飞书接入的完整流程:创建自建应用、获取 App ID/Secret、配置事件订阅、设置最小权限。飞书的消息卡片能力让 AI 回复的展示效果更上一层楼。对于国内用户来说,飞书是团队协作场景下接入 Hermes 的最佳选择。
5. 微信接入
微信是国内使用最广泛的即时通讯工具,但它对第三方 Bot 的限制也最严格。微信生态有三个主要接入点:企业微信、微信公众号、以及个人微信(需第三方桥接)。
5.1 企业微信自建应用接入教程
企业微信是微信生态中对第三方应用最友好的入口,适合企业内部使用。
步骤一:注册企业微信
- 访问 https://work.weixin.qq.com/
- 注册一个企业(可以用个人身份注册)
- 进入"应用管理"
步骤二:创建自建应用
- 应用管理 → 自建 → 创建应用
- 填写应用信息:
- 应用名称:Hermes 智能助手
- 应用介绍:AI 办公助手
- 可见范围:选择可以使用此应用的部门/成员
- 上传应用 Logo
- 点击"创建应用"
步骤三:获取凭证
创建完成后,在应用详情页获取:
AgentId: 1000002
Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
同时还需要企业 ID:
- 我的企业 → 企业 ID
- 复制
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,适合做客服和内容推送。
前提条件:
- 一个已认证的微信公众号(个人订阅号功能受限)
- 服务器和域名(接收微信推送)
配置步骤:
- 微信公众平台 → 开发 → 基本配置
- 获取 AppID 和 AppSecret
- 设置服务器配置:
- URL:
https://your-domain.com/webhook/wechat-mp - Token:自定义,和 Hermes 配置一致
- EncodingAESKey:随机生成
- 消息加解密模式:明文/兼容/安全
- URL:
- 在 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 微信 | ⭐ 差 | 极易被封 |
| 企业微信互通 | 通过企业微信连接微信 | ⭐⭐⭐ 较好 | 较低 |
注意 使用非官方方案接入个人微信存在封号风险! 微信对此类行为的打击力度一直在加强。建议优先使用企业微信或微信公众号作为替代方案。
如果你确实需要个人微信接入,推荐使用基于 gewe 或 wechaty 的方案,但它们需要额外部署中间件服务:
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
- 访问 https://discord.com/developers/applications
- 用 Discord 账号登录
步骤二:创建应用
- 点击"New Application"
- 输入应用名称:Hermes Assistant
- 点击"Create"
步骤三:添加 Bot
- 左侧菜单 → "Bot" → "Add Bot"
- 点击"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 邀请链接:
- 左侧菜单 → "OAuth2" → "URL Generator"
- 在 Scopes 中选择
bot - 在 Bot Permissions 中选择:
✅ Send Messages ✅ Send Messages in Threads ✅ Read Message History ✅ Use Slash Commands ✅ Attach Files ✅ Embed Links ✅ Add Reactions - 复制生成的 URL,在浏览器中打开,邀请 Bot 加入你的服务器
6.3 频道管理与权限
Discord 的权限模型比较复杂,分为服务器级、频道级和角色级。
建议的权限设置:
- 创建一个专门给 Bot 使用的角色(如"AI Assistant")
- 在频道设置中:
- 允许 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 类似:
步骤:
- https://api.slack.com/apps → Create New App
- 选择"From scratch"
- 在"OAuth & Permissions"中申请权限:
chat:write—— 发送消息im:history—— 读取私信历史channels:history—— 读取频道历史app_mentions:read—— 读取 @提及
- 安装应用到 Workspace,获取 Bot User OAuth Token
- 在"Event Subscriptions"中订阅
app_mention和message.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 官方审批,流程较长:
- 注册 Meta 开发者账号
- 创建 Business App
- 申请 WhatsApp Business API 访问权限
- 设置 Business Account 和 Phone Number
- 获取 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。需要使用第三方库 signald 或 signal-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) 与其深度集成。
安装扩展
- 打开 VS Code
- 点击左侧扩展图标(或按
Cmd+Shift+X) - 搜索 "Hermes Assistant"
- 点击"安装"
配置连接
安装后,点击左侧 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 插件:
- 打开 IDE → Settings → Plugins → Marketplace
- 搜索 "Hermes"
- 安装并重启 IDE
- 配置 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.3s10.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 --followTips 对于生产环境,推荐使用 systemd 或 Docker 管理进程,因为它们提供了更完善的日志收集、自动重启、资源限制等功能。内置的
--daemon适合个人开发和轻量级部署。
本章小结 在本章(第十册)中,我们完成了多平台接入的完整学习之旅:
- 理解了 Gateway 架构的设计理念和工作原理
- 详细学习了 Telegram、飞书、微信、Discord 的接入流程
- 了解了 Slack、WhatsApp、Email、Home Assistant 等其他平台的配置
- 掌握了编辑器集成(VS Code、Zed、JetBrains)和语音交互的配置
- 学会了多平台协同使用的策略
- 建立了 Token 安全管理和网关运维的最佳实践
现在,你的 Hermes 已经可以在任何你需要的地方响应你的指令——无论是在手机上、电脑前、还是智能家居设备旁。多平台接入的真正价值,是让 AI 成为你生活中无缝衔接的一部分。