znlgis 博客

GIS开发与技术分享

第九章：消息网关与多平台接入

Hermes 最具差异化的能力之一，就是 Gateway——一个进程同时把同一个 Agent 暴露给 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、企业微信、飞书、钉钉、QQ、Yuanbao、Webhook、Open WebUI 等 15+ 平台。本章把 Gateway 的体系结构与所有主流平台的接入步骤逐一讲清，并重点关照中国区开发者关心的 WeCom（企业微信）/ Feishu（飞书）/ DingTalk（钉钉）。

9.1 Gateway 是什么

gateway/run.py 中的 GatewayRunner 是一个长时进程：

+----------------------------------------------------------+
|  GatewayRunner（gateway/run.py）                          |
|                                                          |
|  Adapter: telegram   discord   slack   whatsapp  ...     |
|     │         │         │         │                      |
|     └────┬────┴─────────┴─────────┘                      |
|          ▼                                               |
|     SessionStore（gateway/session.py）                    |
|          ▼                                               |
|        AIAgent（run_agent.py）                            |
|          ▼                                               |
|     Delivery（gateway/delivery.py） → 各 adapter 出站      |
+----------------------------------------------------------+

要点：

  • 每个平台一个 adapter（位于 gateway/platforms/<name>.py）；
  • 同一个 Agent、同一份记忆、同一份技能：Telegram 里说过的事，进 Discord 里依然记得；
  • DM Pairing：陌生人发起对话需先经过授权；
  • Cross-Session Mirror：可在不同平台间镜像对话；
  • Hooks：监听 agent:start / agent:end / command:* 等事件做日志、限流、告警；
  • Profile-Aware：每个 Profile 有独立锁，不会被多个进程互相覆盖。

9.2 总览：支持哪些平台

类别 平台
IM（国际） Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost
IM（国内） WeCom（企业微信）、Feishu（飞书）、DingTalk（钉钉）、Weixin（微信，需桥）、QQ、Yuanbao
异步通讯 Email（IMAP/SMTP）、SMS（Twilio 等）、BlueBubbles（iMessage 桥）
Web Open WebUI、自托管 Web Dashboard、ACP（IDE 协议）
编程式 Webhooks（GitHub/Stripe/…）、Home Assistant 事件

每个平台 adapter 的能力略有差异：

  • 文本消息：全平台都支持；
  • Markdown / 富文本：差异大，详见各 adapter 文档；
  • 附件（图片/语音/PDF）：大多数支持；
  • 语音消息转写：Telegram、Discord、WhatsApp、企业微信等支持，依赖 STT 模型；
  • TTS 回复：Telegram、Discord、企业微信、Slack（部分）等支持；
  • Voice Channel（实时语音）：仅 Discord VC；
  • 斜杠命令：所有平台都共享同一套 COMMAND_REGISTRY。

9.3 启动 Gateway

hermes gateway setup     # 交互式配置每个平台
hermes gateway start     # 启动
hermes gateway stop
hermes gateway status
hermes gateway logs --tail 200

后台运行（systemd 单元）：

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

[Service]
Type=simple
User=hermes
Environment=HERMES_HOME=/home/hermes/.hermes
ExecStart=/usr/local/bin/hermes gateway start --foreground
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

hermes gateway start --foreground 适合放进 systemd / docker / supervisord。

9.4 DM Pairing：陌生人不能随便用你的 Agent

gateway:
  pairing:
    mode: token        # token / approval / open
    valid_seconds: 600

模式：

  • token：用户发送 /pair <token> 完成配对；token 由你 hermes gateway pair create 生成；
  • approval：陌生人发起对话时你（管理员）会收到通知去 ✅；
  • open：完全开放（不推荐，仅适合内部测试）。

每个 pairing 都会被持久化在 ~/.hermes/pairings.db，可以 hermes gateway pair revoke <id> 撤销。

9.5 平台逐个接入

下面给出主要平台的”最少配置”。完整说明见 user-guide/messaging/<platform>.md。

9.5.1 Telegram

最容易入门：

  1. 在 Telegram 里跟 @BotFather 创建 bot，拿到 BOT_TOKEN；
  2. hermes gateway setup 选 Telegram，粘贴 token；
  3. 写入 .env：
TELEGRAM_BOT_TOKEN=123456:ABC-...
  1. 启动 hermes gateway start；
  2. 在 Telegram 找到你的 bot，发 /start，按提示完成 pairing。

支持：文本、图片、语音消息（自动转写）、TTS 回复、/cron、/skills 等所有斜杠命令。

9.5.2 Discord

pip install "hermes-agent[messaging]"
  1. Discord Developer Portal 建 Application + Bot，拿 BOT_TOKEN；
  2. 开启 “Message Content Intent”、”Server Members Intent”、（如需 VC）”Voice Connection”；
  3. OAuth URL Generator → scope: bot applications.commands，权限给齐；
  4. 拉到你服务器；
  5. .env：
DISCORD_BOT_TOKEN=...
  1. config.yaml：
gateway:
  discord:
    enabled: true
    voice_channels:        # 可选：实时语音
      - 1234567890123456

支持文本、图片、文件、语音 VC（语音模式见第十一章）、admin 工具集（频道管理、权限管理）。

9.5.3 Slack

pip install "hermes-agent[messaging]"
  1. api.slack.com/apps 新建 App；
  2. Socket Mode 打开（推荐，无需公网回调）；
  3. 拿 Bot User OAuth Token（xoxb-...）和 App-Level Token（xapp-...）；
  4. Scopes 给：chat:write、im:history、channels:history、files:read 等；
  5. .env：
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

9.5.4 WhatsApp

走 Meta Cloud API 或第三方桥（如 baileys）：

pip install "hermes-agent[messaging]"

需要：Meta Business Account、Phone Number、Webhook URL。详细步骤见 user-guide/messaging/whatsapp.md。

9.5.5 Signal

依赖 signal-cli；本地跑 daemon，Hermes 通过它发收。

9.5.6 Matrix / Mattermost

各自配 homeserver 或 Mattermost server URL + Token。

9.5.7 WeCom（企业微信）

国内开发者最关心的国内 IM 之一。

  1. 在 企业微信管理后台 建一个”自建应用”；
  2. 拿到 corp_id、agent_id、secret；
  3. 配置 接收消息 URL（需要公网入口；可用 Cloudflare Tunnel / FRP）；
  4. 设置 Token、EncodingAESKey；
  5. .env：
WECOM_CORP_ID=ww...
WECOM_AGENT_ID=10000xx
WECOM_SECRET=...
WECOM_TOKEN=...
WECOM_ENCODING_AES_KEY=...
  1. config.yaml：
gateway:
  wecom:
    enabled: true
    public_base_url: https://hermes.example.com
    callback_path: /wecom/callback
  1. hermes gateway start —— 它会起 HTTP 监听并自动注册回调。

支持文本、图文、语音消息（自动转写）、文件附件。默认 toolset 偏严（不带 terminal），适合企业场景。

9.5.8 Feishu（飞书 / Lark）

  1. 飞书开放平台 创建企业自建应用；
  2. 启用机器人能力，订阅 im.message.receive_v1；
  3. 拿 app_id、app_secret、verification_token、encrypt_key；
  4. 公网入口同上；
  5. .env：
FEISHU_APP_ID=cli_...
FEISHU_APP_SECRET=...
FEISHU_VERIFICATION_TOKEN=...
FEISHU_ENCRYPT_KEY=...
  1. config.yaml：
gateway:
  feishu:
    enabled: true
    public_base_url: https://hermes.example.com
    callback_path: /feishu/callback

支持卡片消息（富文本/按钮/表格）、图片、文件、群聊 @ 与单聊。

9.5.9 DingTalk（钉钉）

  1. 钉钉开放平台 创建企业内部应用；
  2. 启用机器人；
  3. 拿 client_id、client_secret、sign_key；
  4. 推荐 Stream 模式（无需公网回调）；
  5. .env：
DINGTALK_CLIENT_ID=...
DINGTALK_CLIENT_SECRET=...
DINGTALK_SIGN_KEY=...
  1. config.yaml：
gateway:
  dingtalk:
    enabled: true
    transport: stream

支持文本、Markdown 卡片、@ 与群聊。

9.5.10 Weixin（个人微信）

由于个人微信没有官方 bot API，需要桥：常见做法是把 HermesClaw 或 wcferry / wechaty 等开源桥跑成 stdio MCP / WebSocket，再让 Hermes Gateway 接入。详见 user-guide/messaging/weixin.md（如有）。注意：使用桥具有合规风险，仅限自用。

9.5.11 QQ Bot

用官方 QQ 频道机器人 / Mirai / NoneBot 等桥。

9.5.12 Yuanbao

腾讯元宝接入，需要在元宝平台建立机器人；详细配置见 user-guide/messaging/yuanbao.md。

9.5.13 Email

gateway:
  email:
    enabled: true
    imap:
      host: imap.gmail.com
      port: 993
      user: hermes@example.com
      password_env: EMAIL_PASS
      mailbox: INBOX
      poll_seconds: 30
    smtp:
      host: smtp.gmail.com
      port: 465
      user: hermes@example.com
      password_env: EMAIL_PASS
      from: "Hermes <hermes@example.com>"
    allowed_senders:
      - me@example.com
      - boss@example.com

Hermes 把每封新邮件作为一个对话；回信即继续。支持 attachments（自动转 markdown）。

9.5.14 SMS / BlueBubbles / Open WebUI / 自托管 Web Dashboard

  • SMS：Twilio / 阿里云短信，仅适合极简场景；
  • BlueBubbles：iMessage 桥（macOS 中转），让 Hermes 在 iPhone 接收 iMessage 后回；
  • Open WebUI：通过 hermes api start 暴露 OpenAI 兼容端点，再让 Open WebUI 直接连；
  • 自托管 Web Dashboard：仓库内置一个 Web UI，hermes web start 启动，浏览器即用。

9.5.15 Webhook

gateway:
  webhooks:
    - name: github-pr
      path: /webhooks/github-pr
      secret_env: GITHUB_WEBHOOK_SECRET
      action:
        prompt: |
          请评审这次 PR（payload: ），
          按照仓库 AGENTS.md 的规范，输出代码评审结论
        toolsets: [web, file, github-mcp]
        deliver_to: telegram://CHAT_ID

任何 HTTP 服务都能给 Hermes 喂事件，触发 Agent 任务并把结果投递到 IM。第十章会大量用到它。

9.5.16 Home Assistant

ha_* 工具组让 Hermes 可以读 / 写 Home Assistant 状态。Gateway 也可以接 Home Assistant 事件做触发器。详见 user-guide/messaging/home-assistant.md（如有）。

9.6 平台默认 toolset 与”安全级别”

每个平台 adapter 都有”默认开启的 toolset 集”，思路：

  • CLI：一切都开；
  • Discord 个人 server：基本都开；
  • Telegram 个人 bot：默认开 web/file/skills/memory/todo/send_message，不开 terminal；
  • Slack/WeCom/Feishu/DingTalk（企业场景）：偏紧，默认不开 terminal、code_execution、delegation，避免一条 IM 让 Agent 在公司机器上跑命令；
  • Webhook：完全跟随你在 webhook entry 里指定的 toolsets。

可以全部在 hermes tools 中按平台调整。

9.7 跨平台镜像与 send_message

send_message 工具可以让 Agent 主动给某个平台某个会话发消息：

send_message(target="telegram://1234567890", text="日报已生成 ✅，详情见附件")
send_message(target="wecom://group:hr", text="...", attachments=["./report.pdf"])
send_message(target="email://boss@example.com",
             subject="周度汇总", text="...")

配合 cron / webhook 即可做”无人值守的播报”——第十章详细展开。

gateway/mirror.py 还支持把”我在 CLI 跟 Hermes 对话”实时镜像到 Telegram，方便你在外面继续。

9.8 Hooks：在 Gateway 事件上跑你的代码

~/.hermes/hooks/<name>/：

HOOK.yaml      # 监听哪些事件
handler.py     # 异步函数 handle(event_type, context)

HOOK.yaml：

name: usage-logger
description: 把每次 agent 启动/结束写到 SQLite
events:
  - agent:start
  - agent:end
  - command:*

handler.py 必须暴露 async handle：

async def handle(event_type: str, context: dict):
    ...

事件包括（节选）：agent:start、agent:step、agent:end、message:in、message:out、command:<name>、tool:before、tool:after、pairing:created、compress:done 等。

第十二章会展开 plugin hooks 与 shell hooks（hooks: 块直接指向脚本）。

9.9 实战：一台 VPS 上的”全能 Hermes”

# 1) 装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 2) 配
hermes setup                    # 选 OpenRouter
hermes gateway setup            # 配 Telegram + WeCom + Email
hermes config set terminal.backend docker
hermes config set DAYTONA_API_TOKEN ...   # 可选：远程命令

# 3) 起
sudo cp /etc/systemd/system/hermes-gateway.service ...
sudo systemctl enable --now hermes-gateway
journalctl -u hermes-gateway -f

效果：

  • 你在 Telegram 找它聊天，跟在 CLI 一样；
  • 同一份记忆/技能；
  • 同事在企业微信里 @ 它问代码评审；
  • 每天它给你发邮件汇总；
  • VPS 关机你的对话不会丢（SQLite 持久化）。

9.10 调试与排错

症状 排查
Gateway 启动后 Telegram 不响应 BOT_TOKEN 是否正确；网络是否能到 api.telegram.org；hermes gateway logs
WeCom callback 报”签名错误” Token/EncodingAESKey 与企业微信后台一致；public_base_url 与企业微信白名单一致；HTTPS 证书有效
Discord bot 上线但 @ 它无反应 “Message Content Intent” 没开；scope 不全
Email 收到但不响应 发件人不在 allowed_senders；poll 周期未到
Webhook 收到了但工具没触发 secret_env 校验失败；prompt 里 `` 占位错
多个平台同时收消息但只一个响应 检查 profile lock；不要同时开两份 hermes gateway start

9.11 安全建议

  • 永远开 DM Pairing；
  • IM 平台默认不要开 terminal/code_execution；
  • 用 approval.require_confirmation 列禁止/审批的命令；
  • WeCom/Feishu/DingTalk 使用专用的”只读 + 部分 write”账户；
  • HTTPS 入口最好用 Cloudflare Tunnel + 客户端证书；
  • 使用 credential_pool 防止泄漏单一 Key；
  • 重要操作让 Agent 先打 /checkpoint 再动手；
  • 用 hooks 把所有平台收发记到独立的审计日志库。

9.12 本章小结

  • Gateway 是 Hermes “永远在线、跨平台”的引擎；
  • 一份 Agent + 一份记忆 + 多平台 adapter，互相镜像；
  • 默认安全：DM pairing、按平台收紧 toolset、命令审批；
  • 国内 IM（WeCom / Feishu / DingTalk）原生支持，国际 IM 全覆盖；
  • Webhook 把 Hermes 接进任意外部事件源；
  • Hooks 提供完整生命周期事件，可做日志/限流/告警。

下一章我们让它”自动干活”——Cron 定时任务与自动化模式。

↑