Hermes Agent HelperHermes Agent Helper

Hermes Agent 消息平台配置完全指南：17 种平台接入教程

Hermes Agent Helperon a month ago

引言

Hermes Agent 支持 17 种消息平台，你可以在同一个 Gateway 实例中同时运行多个平台。本文提供每种平台的完整配置步骤，帮助你快速将 AI 助手接入日常使用的通讯工具。

如需托管部署服务，请 查看方案；如需技术支持，请 联系我们。

推荐阅读：微信 VS 飞书 VS Telegram 消息平台对比 — 了解三大主流平台的优劣对比，选择最适合你的消息平台。

通用说明

配置方式

Hermes 提供两种配置方式：

  1. 交互式向导：运行 hermes gateway setup，按提示选择平台并输入凭证
  2. 手动编辑：直接编辑 ~/.hermes/.env 文件

启动方式

  • 前台运行：hermes gateway run
  • 安装为系统服务：hermes gateway install（支持 systemd/launchd）

通用环境变量

  • GATEWAY_ALLOW_ALL_USERS=true：允许所有用户访问（不推荐用于生产环境）

1. Telegram

Telegram 是配置复杂度中等的平台，需要创建 Bot 并获取 Token。

必需环境变量

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_ALLOWED_USERS=123456789,987654321

配置步骤

  1. 创建 Bot

    • 在 Telegram 中搜索 @BotFather
    • 发送 /newbot 命令
    • 按提示设置 Bot 名称和用户名
    • 保存返回的 Bot Token

  2. 关闭隐私模式（如需群组使用）

    • 向 BotFather 发送 /mybots
    • 选择你的 Bot → Bot Settings → Group Privacy → Turn off
    • 否则 Bot 在群组中只能看到 /命令 和 @ 回复

  3. 获取 User ID

    • 搜索 @userinfobot 或 @getmyid_bot
    • 发送任意消息，获取你的 User ID
    • 将 ID 添加到 TELEGRAM_ALLOWED_USERS

  4. 写入配置并启动

    # 编辑 ~/.hermes/.env
hermes gateway

可选配置

TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook/telegram
TELEGRAM_HOME_CHANNEL=@your_channel

2. 飞书 / Lark

飞书配置相对复杂，需要在开放平台创建应用。我们平台提供 Hermes Agent 飞书配置小助手，可自动化大部分配置流程。

必需环境变量

FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_DOMAIN=feishu  # 国内用 feishu，国际版用 lark

配置步骤

  1. 创建应用

  2. 开启机器人能力

    • 在应用功能中启用「机器人」
    • 配置机器人名称和头像

  3. 配置权限

    • 权限管理 → 添加权限
    • 必需权限：接收消息、发送消息、获取用户信息等

  4. 选择连接模式

    • WebSocket 模式（推荐）：无需公网地址
    • Webhook 模式：需要配置回调地址

  5. 发布应用

    • 设置可用范围
    • 提交版本审核
    • 发布上线

  6. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

使用 Hermes Agent 飞书配置小助手

我们提供免费的 Hermes Agent 飞书配置小助手，可以自动化大部分配置流程：

  1. 下载小助手：访问 Hermes Agent 飞书配置小助手下载页面
  2. 按向导在飞书开放平台创建应用
  3. 输入 App ID 和 Secret，小助手自动完成权限配置
  4. 复制配置到你的 Hermes Agent 服务器

该工具永久免费，无论你是否订阅我们的服务都可以使用。

3. 微信（个人微信）

微信配置最为简单，扫码即可绑定。

必需环境变量

WEIXIN_ACCOUNT_ID=自动获取
WEIXIN_TOKEN=自动保存

配置步骤

  1. 启动配置向导

    hermes gateway setup
# 选择 Weixin

  2. 扫码登录

    • 终端会显示二维码

    • 使用微信扫码确认登录

    • 凭据自动保存到 ~/.hermes/weixin/accounts/

    提示：如果终端无法正确显示二维码（字符错位或乱码），终端通常会同时显示一个 URL 链接。复制该链接到浏览器打开，即可看到二维码图片，然后用微信扫描。

  3. 启动 Gateway

    hermes gateway

注意事项

  • 使用 iLink Bot API，非企业微信
  • 有封号风险，建议使用小号
  • 群聊默认关闭，需手动开启

4. 企业微信（WeCom）

必需环境变量

WECOM_BOT_ID=your_bot_id
WECOM_SECRET=your_secret

配置步骤

  1. 创建 AI 机器人

    • 登录企业微信管理后台
    • 应用管理 → 创建应用 → AI 机器人

  2. 获取凭证

    • 记录 Bot ID 和 Secret

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

特点

  • 使用 WebSocket 传输，无需公网
  • 私聊和群聊默认开启

5. Discord

必需环境变量

DISCORD_BOT_TOKEN=your_bot_token
DISCORD_ALLOWED_USERS=user_id_1,user_id_2

配置步骤

  1. 创建应用

  2. 创建 Bot

    • 进入 Bot 设置
    • 点击 Add Bot
    • 开启 Public Bot

  3. 配置权限（重要！）

    • 开启 Privileged Gateway Intents：
      • Server Members Intent ✓
      • Message Content Intent ✓（最常见的坑！）

  4. 获取 Token 和邀请链接

    • 复制 Bot Token
    • OAuth2 → URL Generator
    • 权限整数：274878286912
    • 生成邀请链接

  5. 邀请 Bot 到服务器

    • 使用邀请链接添加 Bot

  6. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

6. Slack

必需环境变量

SLACK_BOT_TOKEN=xoxb-xxxxx
SLACK_APP_TOKEN=xapp-xxxxx
SLACK_ALLOWED_USERS=U12345,U67890

配置步骤

  1. 创建 Slack App

  2. 配置 Bot Token Scopes

    • OAuth & Permissions → Scopes
    • 添加：chat:write、app_mentions:read、channels:history、im:history 等

  3. 开启 Socket Mode

    • Socket Mode → Enable
    • 创建 App-Level Token（需要 connections:write scope）

  4. 订阅事件

    • Event Subscriptions → Enable
    • 订阅：message.im、message.channels、message.groups、app_mention

  5. 开启 Messages Tab

    • App Home → Show Tabs → Messages Tab ✓

  6. 安装到 Workspace

    • Install App → Install to Workspace
    • 保存 Bot Token

  7. 邀请 Bot 到频道

    /invite @Hermes Agent

7. WhatsApp

必需环境变量

WHATSAPP_ENABLED=true
WHATSAPP_ALLOWED_USERS=8613800138000,8613900139000

配置步骤

  1. 启动配置向导

    hermes whatsapp
# 会显示 QR 码

  2. 扫码绑定

    • WhatsApp → 设置 → 关联设备 → 扫描二维码

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

注意事项

  • 使用 Baileys 非官方桥接
  • 有小封号风险，建议使用专用号码
  • 手机号格式：国际区号+号码，无 + 号

8. 钉钉（DingTalk）

必需环境变量

DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

配置步骤

  1. 创建应用

  2. 开启机器人能力

    • 选择 Stream Mode（WebSocket）

  3. 安装依赖

    pip install dingtalk-stream httpx

  4. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

特点

  • Stream Mode 使用 WebSocket，无需公网

9. Signal

必需环境变量

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+8613800138000

配置步骤

  1. 安装 signal-cli

    • 需要 Java 17+
    • 下载并安装 signal-cli

  2. 关联设备

    signal-cli link -n "HermesAgent"
# 使用 Signal App 扫描二维码

  3. 启动 Daemon

    signal-cli --account +号码 daemon --http 127.0.0.1:8080

  4. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

10. Email

必需环境变量

EMAIL_ADDRESS=[email protected]
EMAIL_PASSWORD=app_password
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

配置步骤

  1. 准备邮箱

    • 创建专用邮箱账号
    • 开启 IMAP 访问

  2. 获取 App Password（以 Gmail 为例）

    • 开启两步验证
    • 访问 Google 账号 → 安全性 → App 密码
    • 生成专用密码

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

11. Matrix

必需环境变量

MATRIX_HOMESERVER=https://matrix.org
MATRIX_ACCESS_TOKEN=syt_xxxxx
MATRIX_ALLOWED_USERS=@user:matrix.org

配置步骤

  1. 注册 Bot 账号

    • 在 homeserver 注册一个新账号

  2. 获取 Access Token

    • Element → 设置 → 帮助与关于 → 高级 → Access Token

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

E2EE 支持

如需端到端加密支持：

pip install mautrix[encryption]
# 需要安装 libolm

12. Mattermost

必需环境变量

MATTERMOST_URL=https://your-mattermost.com
MATTERMOST_TOKEN=your_bot_token
MATTERMOST_ALLOWED_USERS=user_id_1,user_id_2

配置步骤

  1. 开启 Bot Accounts

    • 系统控制台 → Integrations → Bot Accounts → Enable

  2. 创建 Bot

    • Integrations → Bot Accounts → Add Bot Account
    • 保存 Token

  3. 邀请 Bot 到频道

  4. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

13. Home Assistant

必需环境变量

HASS_TOKEN=your_long_lived_access_token

配置步骤

  1. 创建 Long-Lived Access Token

    • Home Assistant → 个人资料 → Long-Lived Access Tokens → 创建

  2. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

特点

  • 双重集成：Gateway 平台（事件）+ 智能家居工具（4 个 LLM 可调用工具）

14. SMS（Twilio）

必需环境变量

TWILIO_ACCOUNT_SID=ACxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+1234567890

配置步骤

  1. 注册 Twilio 账号

    • 获取 Account SID 和 Auth Token
    • 购买电话号码

  2. 配置 Webhook

    • 设置消息 webhook：https://your-server:8080/webhooks/twilio

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

注意事项

  • 需要公网可达的服务器
  • 纯文本传输，无加密

15. BlueBubbles（iMessage）

必需环境变量

BLUEBUBBLES_SERVER_URL=http://your-mac:1234
BLUEBUBBLES_PASSWORD=your_password

配置步骤

  1. 在 Mac 上安装 BlueBubbles Server

    • 下载并安装 BlueBubbles
    • 登录 Apple ID

  2. 获取 Server URL 和 Password

  3. 写入配置

    # 编辑 ~/.hermes/.env
hermes gateway

注意事项

  • 需要一台常开的 Mac

16. Webhooks

必需环境变量

WEBHOOK_ENABLED=true
WEBHOOK_SECRET=your_hmac_secret

配置步骤

  1. 在 .env 中启用 Webhook

  2. 定义路由

    • 在 config.yaml 中定义
    • 或使用 hermes webhook subscribe 动态创建

  3. 外部服务调用

    POST http://your-server:8644/webhooks/<route-name>

17. Open WebUI / API Server

必需环境变量

API_SERVER_ENABLED=true
API_SERVER_KEY=your_bearer_token

配置步骤

  1. 启用 API Server

    # 编辑 ~/.hermes/.env
hermes gateway

  2. 启动 Open WebUI

    docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your_bearer_token \
  ghcr.io/open-webui/open-webui:main

注意事项

  • URL 必须带 /v1 后缀

常见故障排查

回调验证失败

  • 检查公网证书与 TLS 链路
  • 检查反向代理是否改写路径
  • 查看 Hermes 日志中的签名/时间戳错误

机器人无响应

  • 事件订阅是否完整
  • Hermes 服务是否健康（hermes status）
  • 是否触发平台频控

权限错误

  • 检查 ALLOWED_USERS 配置
  • 确认平台权限设置完整

重要提示：配置后重启网关

完成任何消息平台配置后，都需要重启 Hermes Gateway 才能使配置生效：

hermes gateway restart

如果使用 systemd 管理服务：

sudo systemctl restart hermes-gateway

结论

Hermes Agent 支持 17 种消息平台，你可以根据团队需求选择一个或多个平台同时使用。对于中国用户，推荐使用飞书；对于国际用户，推荐使用 Telegram。

如需了解各平台的详细对比，请阅读 微信 VS 飞书 VS Telegram 消息平台对比。

如需托管部署服务，请 查看方案；如需技术支持，请 联系我们。