第四章聊天平台接入

装好了 Hermes，接下来最激动人心的一步——让墨鱼住进你的聊天软件里。从此，打开飞书/Telegram/Discord，墨鱼随时待命。

Gateway 是什么？

Gateway（网关）是 Hermes Agent 的消息中枢。它是一个后台进程，同时连接你所有配置好的聊天平台：

飞书 ──┐
Telegram ──┤
Discord ──┼──→ Gateway ──→ Hermes AI Agent
Slack ──┤
WhatsApp ──┘

一个 Gateway 进程搞定所有平台，不需要每个平台单独跑一个服务。

平台一览

Hermes 支持 15+ 聊天平台：

平台	推荐度	语音	图片	文件	群聊	难度
飞书/Lark	⭐⭐⭐⭐⭐	✅	✅	✅	✅	中
Telegram	⭐⭐⭐⭐⭐	✅	✅	✅	✅	低
Discord	⭐⭐⭐⭐	✅	✅	✅	✅	低
Slack	⭐⭐⭐⭐	✅	✅	✅	✅	低
WhatsApp	⭐⭐⭐	✅	✅	✅	❌	中
Signal	⭐⭐⭐	✅	✅	✅	❌	中
Email	⭐⭐⭐	❌	❌	✅	❌	低
Matrix	⭐⭐⭐	✅	✅	✅	✅	中
钉钉 DingTalk	⭐⭐⭐	✅	✅	✅	✅	中
企业微信 WeCom	⭐⭐⭐	✅	✅	✅	✅	中
微信 WeChat	⭐⭐	❌	✅	❌	❌	高
SMS (Twilio)	⭐⭐	❌	❌	❌	❌	中
iMessage	⭐⭐⭐	✅	✅	✅	❌	中

推荐组合

国内用户：飞书 + Telegram（科学上网后）海外用户：Telegram + Discord

交互式配置向导

最简单的方式是用 hermes gateway 向导：

bash

hermes gateway

向导会引导你选择平台、填写 Token、自动保存配置。配置完成后自动重启 Gateway。

手动配置

也可以直接编辑 ~/.hermes/.env 文件来配置，适合批量部署或脚本化场景。

飞书 / Lark 配置（推荐国内用户）

飞书是国内企业协作的主流平台。Hermes 通过飞书开放平台的 WebSocket 长连接接收消息，无需暴露公网 webhook URL，即可在私聊和群聊场景中使用。

创建飞书应用

打开飞书开放平台，登录后点击「创建企业自建应用」
填写应用名称（比如"我的 AI 墨鱼"）、描述，选择应用图标
进入应用详情页 →「凭证与基础信息」，复制并保管 App ID（格式 cli_xxx）和 App Secret

安全提醒

App Secret 务必保密，不要提交到代码仓库或公开渠道。如不慎泄露，请立即在开放平台重置。

Lark（国际版）用户：访问 open.larksuite.com/app，并在后续配置中将 FEISHU_DOMAIN 设为 lark。

配置应用权限

进入应用的「权限管理」页面，点击「批量导入」，粘贴以下 JSON：

json

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:resource",
      "im:chat",
      "im:chat:readonly",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write"
    ],
    "user": [
      "im:message",
      "im:message:readonly",
      "im:chat",
      "im:chat:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

以上权限覆盖消息收发、群聊管理、联系人读取、卡片消息等核心功能。部分权限可能因飞书版本差异导入失败，跳过即可，不影响核心消息功能。

启用机器人能力 & 配置事件订阅

进入「应用能力」→「机器人」，开启机器人能力，设置机器人名称和描述
进入「事件订阅」页面：
- 选择「使用长连接接收事件」（WebSocket 模式）
- 添加事件：im.message.receive_v1

注意

确保你已完成 Hermes 侧的配置并启动了 Gateway，否则长连接设置可能无法保存。

发布应用

进入「版本管理与发布」→ 创建应用版本 → 提交审核并发布。企业自建应用通常自动通过。

安装依赖

关键：venv 与系统 Python

Hermes 二进制文件使用项目 venv 内的 Python 解释器。所有 pip 安装都必须指向 venv，否则安装的包对 Hermes 不可见。

bash

# 源码安装的用户
/path/to/hermes-agent/venv/bin/pip install lark_oapi websockets python-socks

# 一键安装脚本的用户
hermes pip install lark_oapi websockets python-socks

已知问题：python-socks 缺失

如果系统环境设置了 SOCKS 代理变量（如 ALL_PROXY），Lark SDK 在导入时会要求 python-socks 包。如果未安装到 venv，Gateway 启动将失败：

[Lark] [ERROR] connect failed, err: python-socks is required to use a SOCKS proxy

解决方案：确认安装到正确的 Python 环境——venv/bin/pip install python-socks，而不是系统 pip。

配置 Hermes

方式 A：交互式配置

bash

hermes gateway
# 选择 Feishu / Lark
# 按提示填入 App ID、App Secret
# 选择 WebSocket 模式

方式 B：手动配置

编辑 ~/.hermes/.env，添加：

bash

# 飞书 / Lark 基础配置
FEISHU_APP_ID=cli_xxxxxxxxxx         # 替换为你的 App ID
FEISHU_APP_SECRET=your_app_secret    # 替换为你的 App Secret
FEISHU_DOMAIN=feishu                 # feishu（国内）或 lark（国际版）
FEISHU_CONNECTION_MODE=websocket     # 推荐 WebSocket 长连接模式

# 用户访问控制
GATEWAY_ALLOW_ALL_USERS=true         # 测试阶段：允许所有用户
# 生产环境请改为 false，并配置白名单：
# FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy  # 用户的 open_id，逗号分隔

启动 Gateway

bash

hermes gateway start

启动后检查日志，确认 WebSocket 连接建立：

bash

tail -f ~/.hermes/logs/gateway.log

成功的日志应包含：

[Lark] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2?...

在飞书中搜索你的机器人名称，发一条消息测试。如果墨鱼回复了，说明连接成功！

设置 Home Chat

在飞书聊天中发送：

/set-home

这会将当前聊天设为 Home Chat，定时任务（Cron）的结果和跨平台通知会发到这里。

也可以预配置：

bash

# 在 ~/.hermes/.env 中
FEISHU_HOME_CHAT_ID=oc_xxxxxxxxxxxxx

群聊策略

机器人默认在群聊中需要被 @提及才会响应。通过环境变量控制群聊行为：

bash

# always：群聊中所有消息都响应（需 @机器人）
# mention_only：仅响应 @机器人 的消息
# ignore：完全忽略群聊
FEISHU_GROUP_POLICY=always

安全提醒

生产环境务必配置 FEISHU_ALLOWED_USERS，不要使用 GATEWAY_ALLOW_ALL_USERS=true。否则任何能联系到机器人的人都能使用你的 Agent。

常见启动错误

错误信息	原因	解决方案
`python-socks is required`	缺少依赖或装错了 Python 环境	`venv/bin/pip install python-socks`
`Unauthorized user`	未配置用户白名单	设置 `GATEWAY_ALLOW_ALL_USERS=true` 或 `FEISHU_ALLOWED_USERS`
连接超时	网络/防火墙问题	确认可访问 `wss://msg-frontier.feishu.cn`
App ID/Secret 错误	凭证配置错误	检查 `.env` 中的值是否与开放平台一致

运维命令速查

bash

hermes gateway start      # 启动后台服务
hermes gateway stop       # 停止服务
hermes gateway restart    # 重启服务
hermes gateway status     # 查看状态
hermes doctor             # 健康检查
hermes doctor --fix       # 自动修复问题
tail -f ~/.hermes/logs/gateway.log  # 实时日志

配置参考

环境变量	说明	默认值
`FEISHU_APP_ID`	飞书应用 App ID	-
`FEISHU_APP_SECRET`	飞书应用 App Secret	-
`FEISHU_DOMAIN`	API 域名（`feishu` 或 `lark`）	`feishu`
`FEISHU_CONNECTION_MODE`	连接模式（`websocket` 或 `webhook`）	`websocket`
`FEISHU_ALLOWED_USERS`	允许的用户 open_id 列表（逗号分隔）	-
`GATEWAY_ALLOW_ALL_USERS`	允许所有用户（`true`/`false`）	`false`

Telegram 配置

第一步：创建 Bot

在 Telegram 中搜索 @BotFather，发送 /newbot
按提示设置 Bot 名称和用户名
记录下返回的 Bot Token（格式如 123456789:ABCdefGHI...）

第二步：配置 Hermes

编辑 ~/.hermes/.env：

bash

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

第三步：启动

bash

hermes gateway start

打开 Telegram，找到你的 Bot，发消息测试。

Discord 配置

第一步：创建 Discord 应用

打开 Discord Developer Portal
点击「New Application」，填写名称
进入「Bot」页面，点击「Add Bot」
点击「Reset Token」，复制 Bot Token
在「OAuth2 → URL Generator」中勾选 bot，复制邀请链接
用链接将 Bot 邀请到你的服务器

第二步：配置 Hermes

编辑 ~/.hermes/.env：

bash

DISCORD_BOT_TOKEN=MTIzNDU2Nzg5.xxxxx.xxxxx

第三步：启动

bash

hermes gateway start

Gateway 服务管理

Linux (systemd)

bash

# 安装为系统服务（开机自启）
hermes gateway install --system

# 启动 / 停止 / 重启 / 查看状态
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status

# 查看日志
hermes gateway logs

macOS (launchd)

bash

# 安装为用户服务
hermes gateway install

# 启动 / 停止 / 重启
hermes gateway start
hermes gateway stop
hermes gateway restart

TIP

macOS 上生成的 plist 文件位于 ~/Library/LaunchAgents/ai.hermes.gateway.plist。

多平台同时接入

你可以在 ~/.hermes/.env 中同时配置多个平台：

bash

# 飞书
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
FEISHU_MODE=websocket

# Telegram
TELEGRAM_BOT_TOKEN=123456:ABCdef

# Discord
DISCORD_BOT_TOKEN=MTIz.xxxxx.xxxxx

# 同时启用
GATEWAY_ALLOW_ALL_USERS=true

Gateway 启动后会同时连接所有已配置的平台，消息统一路由到同一个 AI Agent。

常见问题

问题	原因	解决方案
飞书机器人不回复	权限未配置	检查应用权限，确保 `im:message` 已开通
WebSocket 连接失败	缺少 websockets 包	`pip install websockets`
Telegram Bot 无响应	Token 错误	重新从 BotFather 获取 Token
Discord Bot 离线	未邀请到服务器	用 OAuth2 链接邀请 Bot
Gateway 启动报错	端口冲突 / 环境变量错误	`hermes doctor` 检查配置
安全警告：未配置允许用户	ALLOW_ALL_USERS=true	配置 `GATEWAY_ALLOWED_USERS`

深入阅读

官方文档：Messaging Gateway
飞书配置详解：Feishu / Lark Setup
Telegram 配置：Telegram Setup
Discord 配置：Discord Setup

第四章 聊天平台接入 ​

Gateway 是什么？ ​

平台一览 ​

交互式配置向导 ​

飞书 / Lark 配置（推荐国内用户） ​

创建飞书应用 ​

配置应用权限 ​

启用机器人能力 & 配置事件订阅 ​

发布应用 ​

安装依赖 ​

配置 Hermes ​

启动 Gateway ​

设置 Home Chat ​

群聊策略 ​

常见启动错误 ​

运维命令速查 ​

配置参考 ​

Telegram 配置 ​

第一步：创建 Bot ​

第二步：配置 Hermes ​

第三步：启动 ​

Discord 配置 ​

第一步：创建 Discord 应用 ​

第二步：配置 Hermes ​

第三步：启动 ​

Gateway 服务管理 ​

Linux (systemd) ​

macOS (launchd) ​

多平台同时接入 ​

常见问题 ​

深入阅读 ​

第四章聊天平台接入

Gateway 是什么？

平台一览

交互式配置向导

飞书 / Lark 配置（推荐国内用户）

创建飞书应用

配置应用权限

启用机器人能力 & 配置事件订阅

发布应用

安装依赖

配置 Hermes

启动 Gateway

设置 Home Chat

群聊策略

常见启动错误

运维命令速查

配置参考

Telegram 配置

第一步：创建 Bot

第二步：配置 Hermes

第三步：启动

Discord 配置

第一步：创建 Discord 应用

第二步：配置 Hermes

第三步：启动

Gateway 服务管理

Linux (systemd)

macOS (launchd)

多平台同时接入

常见问题

深入阅读