📚 本系列目录：《Hermes Agent》当前第 8/9 篇 · 上一篇：最佳实践与生态展望——Hermes Agent 深度使用指南 · 下一篇：Hermes Agent 完全使用指南：日常技巧与常见用法详解

📚 系列导航

《Hermes Agent》共 9 篇，本篇是第 8 篇。

Hermes-Agent（八）：消息网关深度指南——统一多平台接入的核心枢纽

Hermes Agent 的消息网关（Messaging Gateway）是你与 AI 助手交互的中央入口。它将来自 Telegram、Discord、Slack、微信等不同平台的消息统一抽象，让 Hermes Agent 能够跨平台保持对话上下文，同时为每个平台提供原生体验。本篇将深入剖析 Gateway 的架构设计、支持平台、配置方法和高级技巧。

一、Gateway 架构：消息路由的核心枢纽

1.1 为什么需要消息网关？

在没有 Gateway 之前，如果你同时使用多个 IM 平台，你需要：

在 Telegram 上启动一个 Hermes 实例
在 Discord 上再启动一个
在 Slack 上又启动一个
每个实例独立运行，无法共享记忆和上下文

Gateway 的核心价值： 单一 Hermes Agent 实例，通过 Gateway 接入多个平台，所有平台的对话共享同一套记忆系统和技能系统。

                    ┌─────────────┐
                    │   Hermes    │
                    │   Agent     │
                    │   Core      │◄─── 共享记忆系统
                    │             │◄─── 共享技能系统
                    └──────┬──────┘
                           │ 统一消息协议
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼────┐  ┌────▼────┐  ┌───▼───┐
         │ Telegram│  │ Discord │  │ Slack │
         │ Adapter │  │ Adapter │  │Adapter│
         └────┬────┘  └────┬────┘  └───┬───┘
              │            │            │
         ┌────▼────┐  ┌────▼────┐  ┌───▼───┐
         │ Telegram│  │ Discord │  │ Slack │
         │ 用户 A  │  │ 用户 B  │  │ 用户 C │
         └─────────┘  └─────────┘  └────────┘

1.2 Gateway 的消息流程

用户发送消息
     │
     ▼
平台适配器（Adapter）
     │ 将平台特有格式转换为统一消息格式
     ▼
消息路由层（Router）
     │ 识别用户、会话、意图
     ▼
Hermes Agent Core
     │ AI 推理 + 工具调用 + 记忆检索
     ▼
响应生成
     │
     ▼
平台适配器（Adapter）
     │ 将统一响应格式转换为平台原生格式
     ▼
用户收到回复

1.3 统一消息格式（Unified Message Format）

Gateway 定义了一套平台无关的消息格式，所有适配器都需要将消息转换为这个格式：

{
  "message_id": "msg_abc123",
  "chat_id": "chat_xyz789",
  "chat_type": "direct|group|channel",
  "platform": "telegram|discord|slack|...",
  "sender": {
    "id": "user_123",
    "username": "johndoe",
    "display_name": "John Doe",
    "is_bot": false
  },
  "content": {
    "text": "用户输入的文本",
    "raw": {},  // 平台原始数据
    "attachments": [],
    "mentions": []
  },
  "timestamp": 1715400000,
  "reply_to": "msg_original_id",
  "thread_id": "thread_abc",
  "metadata": {}
}

这意味着什么？ 无论消息来自哪个平台，Hermes Agent Core 接收到的都是相同格式的数据。这让技能开发和工具调用完全与平台解耦。

二、支持的平台一览

2.1 完整支持矩阵

平台	适配器状态	群组支持	频道支持	语音转文字	特殊功能
Telegram	✅ 稳定	✅	✅	✅	Bot API, Slash Commands
Discord	✅ 稳定	✅	✅	❌	Slash Commands, Webhooks
Slack	✅ 稳定	✅	✅	✅	Block Kit, Modal
WhatsApp	✅ 稳定	❌	❌	✅	WhatsApp Business API
Signal	✅ 稳定	❌	❌	❌	Signal Protocol
Microsoft Teams	🧪 预览	✅	✅	✅	SSO, Graph API
IRC	🧪 预览	✅	✅	❌	传统协议支持
Matrix	🧪 预览	✅	✅	❌	去中心化协议
微信（HermesClaw）	🔌 桥接	❌	❌	❌	需 HermesClaw 桥接
飞书	🔌 桥接	✅	✅	✅	自建机器人
钉钉	🔌 桥接	✅	✅	✅	企业内部部署

2.2 各平台接入要点

Telegram —— 最推荐的接入方式

为什么首选 Telegram：

Bot API 成熟稳定，文档完善
支持几乎所有消息类型（文本、图片、视频、音频、文件、位置、联系方式）
内置 Slash Commands 支持
无需企业认证，个人即可创建 Bot
消息投递可靠，延迟低

Bot 创建流程：

与 @BotFather 对话
发送 /newbot
按提示设置 Bot 名称和用户名
获得 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

配置示例：

# 交互式配置
hermes gateway setup
# 选择 Telegram
# 输入 Bot Token
# 设置允许的用户白名单（可选）

# 或直接命令行配置
hermes config set gateway.telegram.token "YOUR_BOT_TOKEN"
hermes config set gateway.telegram.allowed_users "user_id_1,user_id_2"
hermes config set gateway.telegram.group_mode "relay"  # 群组模式: relay|agent|commands

群组模式详解：

模式	说明	使用场景
`relay`	Bot 被 @ 时才响应，私聊直接响应	公开群组使用
`agent`	私聊和被 @ 都响应所有消息	小圈子 Bot
`commands`	只响应 `/` 开头的命令	需要严格控制的场景

# gateway.telegram.yaml 高级配置
telegram:
  bot:
    token: "${TELEGRAM_BOT_TOKEN}"
    
  # 消息过滤
  filters:
    # 允许的用户 ID 列表，留空则允许所有人
    allowed_users: []
    # 允许的群组 ID 列表
    allowed_chats: []
    # 是否只响应 / 命令
    commands_only: false
    
  # 群组设置
  group:
    # 响应模式
    mode: "relay"  # relay | agent | commands
    # 识别 Bot 的方式
    mention_patterns: ["@YourBotName", "yourbotname"]
    # 是否响应回复 Bot 消息的内容
    respond_to_replies: true
    # 消息前缀识别（如 "!"）
    command_prefix: []
    
  # 功能开关
  features:
    # 是否处理频道帖子
    channel_posts: false
    # 是否处理 inline query（@bot 查询）
    inline_queries: true
    # 语音消息自动转文字
    voice_to_text: true
    
  # 速率限制
  rate_limit:
    # 每用户每分钟最大消息数
    per_user: 20
    # 每群组每分钟最大消息数
    per_chat: 60
    # 限流后的冷却时间（秒）
    cooldown: 60

Discord —— 功能最丰富的平台

Discord 适配器的独特能力：

支持 Slash Commands（与官方 API 一致）
支持 Thread（频道内的讨论线程）
支持 Webhook（自定义消息样式）
支持 Channel Categories（频道分类）
支持 Forum Channels（论坛频道）

创建 Discord Bot：

访问 https://discord.com/developers/applications
点击 "New Application"
在 "Bot" 页面获取 Token
在 "OAuth2" → "URL Generator" 中选择：
- bot 权限
- applications.commands 权限
使用生成的 URL 将 Bot 添加到服务器

Discord 配置：

# gateway.discord.yaml
discord:
  bot:
    token: "${DISCORD_BOT_TOKEN}"
    # intents 权限（必需）
    intents:
      - MESSAGE_CONTENT
      - GUILD_MESSAGES
      - DIRECT_MESSAGES
      - THREADS
      
  # 频道映射
  channels:
    # 指定哪些频道作为主对话频道
    primary: ["channel_id_1"]
    # 忽略哪些频道
    ignored: ["channel_id_2", "channel_id_3"]
    
  # Slash Commands 自动注册
  commands:
    auto_register: true
    commands:
      - name: "ask"
        description: "向 Hermes 提问"
        options:
          - name: "question"
            type: 3  # STRING
            description: "你的问题"
            required: true
      - name: "search"
        description: "搜索记忆库"
      - name: "skill"
        description: "管理技能"
        
  # 消息样式
  appearance:
    # 响应消息的最大字符数（Discord 限制 2000）
    max_length: 1900
    # 超出限制时分块发送
    split_mode: "chunk"
    # 消息引用格式
    quote_style: "reply"  # reply | blockquote | none

Discord Webhook 消息示例：

{
  "username": "Hermes",
  "avatar_url": "https://example.com/hermes-avatar.png",
  "embeds": [{
    "title": "处理结果",
    "description": "这是响应内容...",
    "color": 5814783,
    "fields": [
      {"name": "处理时间", "value": "1.2s", "inline": true},
      {"name": "工具调用", "value": "web_search", "inline": true}
    ],
    "footer": {"text": "Hermes Agent"}
  }]
}

Slack —— 企业场景首选

Slack 适配器的企业特性：

支持 Slack OAuth 2.0（企业 SSO）
支持 Block Kit（结构化消息）
支持 Interactive Messages（按钮、选择器）
支持 Modal（表单弹窗）
支持 Scheduled Messages
与 Google Workspace、Microsoft 365 深度集成

创建 Slack App：

访问 https://api.slack.com/apps
点击 "Create New App" → "From scratch"
配置以下权限（Scopes）：
- chat:write
- channels:history
- groups:history
- im:history
- mpim:history
- app_mentions:read
- reactions:read
- files:read
- files:write
启用 Socket Mode（推荐，无需公网 Webhook）

# gateway.slack.yaml
slack:
  # OAuth 配置
  oauth:
    client_id: "${SLACK_CLIENT_ID}"
    client_secret: "${SLACK_CLIENT_SECRET}"
    signing_secret: "${SLACK_SIGNING_SECRET}"
    
  # Socket Mode（推荐）
  socket_mode:
    enabled: true
    app_token: "${SLACK_APP_TOKEN}"
    
  # 传统 Webhook 模式
  webhook:
    enabled: false
    url: "${SLACK_WEBHOOK_URL}"
    
  # 频道映射
  workspaces:
    default:
      token: "${SLACK_BOT_TOKEN}"
      signing_secret: "${SLACK_SIGNING_SECRET}"
      # Bot 监听哪些关键词
      triggers:
        - "hermes"
        - "@HermesBot"
      # 是否只在被提及时响应
      mention_only: true
      
  # Block Kit 消息模板
  templates:
    response:
      - type: "section"
        text:
          type: "mrkdwn"
          text: "{{content}}"
      - type: "context"
        elements:
          - type: "mrkdwn"
            text: "由 Hermes Agent 生成 • {{timestamp}}"

WhatsApp —— 通过 WhatsApp Business API

重要前提： WhatsApp 接入需要 WhatsApp Business API 访问权限，这需要：

Facebook Business 账户
WhatsApp Business 解决方案提供商（ BSP ）或直接申请
手机号码（不能是普通 WhatsApp 账号）

不支持： WhatsApp Web / 个人账号（被官方禁止）

# gateway.whatsapp.yaml
whatsapp:
  # WhatsApp Business Cloud API
  api:
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    business_account_id: "${WA_BUSINESS_ACCOUNT_ID}"
    
  # Webhook 配置
  webhook:
    verify_token: "${WA_WEBHOOK_VERIFY_TOKEN}"
    callback_url: "https://your-domain.com/webhook/whatsapp"
    
  # 消息限制（WhatsApp 有严格限制）
  limits:
    # 广播列表最大收件人
    broadcast_max_recipients: 256
    # 模板消息冷却（秒）
    template_cooldown: 30
    
  # 支持的消息类型
  supported_types:
    - text
    - image
    - audio
    - document
    - video
    - location
    - contacts

Signal —— 注重隐私的首选

Signal 的独特优势：

端到端加密（Signal Protocol）
无元数据收集
开源客户端
无企业追踪

接入要求：

注册 Signal 账号（需要手机号）
使用 Signal-Server 或第三方服务（如常青 Signal Gateway）

# gateway.signal.yaml
signal:
  gateway:
    # Signal Gateway 服务地址
    url: "https://signal-gateway:8080"
    api_key: "${SIGNAL_GATEWAY_API_KEY}"
    
  # 账号配置
  accounts:
    primary:
      number: "${SIGNAL_NUMBER}"  # 格式：+8613812345678
      # UUID 由 Signal Gateway 分配
      uuid: "${SIGNAL_UUID}"
      
  # 消息处理
  messages:
    # 是否自动回复群组消息
    group_auto_reply: false
    # 附件大小限制（MB）
    max_attachment_mb: 20

三、跨平台对话统一性

3.1 共享记忆的跨平台体验

这是 Hermes Gateway 最强大的特性之一。用户可以在 Telegram 上开始一段对话，然后切换到 Discord 继续，Hermes Agent 记得之前的所有上下文。

示例场景：

用户（13:00，在 Telegram）：
用户: "帮我规划下周的行程"
Hermes: "好的，你下周主要在杭州...（开始规划）"
         [记忆系统记录：用户下周在杭州有3个会议]

用户（14:30，切换到 Discord）：
用户: "继续刚才的行程规划"
Hermes: "继续完善你的杭州行程..."  [自动读取之前的记忆]
         "第三天晚上的餐厅我已经预订好了..."

3.2 平台感知的内容适配

虽然底层是统一格式，但响应可以根据目标平台进行调整：

# 技能中的平台感知示例
def generate_response(user_message: str, platform: str, **kwargs) -> str:
    base_response = process_message(user_message)
    
    # 根据平台调整输出格式
    if platform == "discord":
        return format_for_discord(base_response)  # 支持 Embed
    elif platform == "slack":
        return format_for_slack(base_response)    # Block Kit 格式
    elif platform == "telegram":
        return format_for_telegram(base_response) # 支持 HTML 格式
    elif platform == "whatsapp":
        return format_for_whatsapp(base_response) # 纯文本，emoji 友好
    else:
        return base_response

平台特性差异处理：

平台	支持 HTML	支持 Markdown	支持代码高亮	最大消息长度
Telegram	✅	✅（MarkdownV2）	✅	4096 字符
Discord	❌（用 Embed）	✅（标准）	✅（fenced）	2000 字符
Slack	✅（部分）	✅（标准）	✅（fenced）	3000 字符
WhatsApp	❌	❌	❌（图片）	65536 字符
Signal	❌	❌	❌	65536 字符

四、微信接入：HermesClaw 桥接方案

4.1 为什么需要桥接？

微信的封闭性（没有官方 Bot API、网页微信协议不稳定、官方严厉打击第三方客户端）使得直接接入微信非常困难。HermesClaw 是一个桥接方案，通过在本地运行一个兼容 OpenClaw 的中间层来间接接入微信。

4.2 HermesClaw 工作原理

微信客户端（手机/电脑）
    │
    │ 微信协议（私有，非官方）
    ▼
HermesClaw（本地桥接服务）
    │
    │ 转换为 OpenClaw/Gateway 协议
    ▼
Hermes Agent Core
    │
    │ 响应
    ▼
HermesClaw
    │
    │ 转换为微信消息格式
    ▼
微信用户

4.3 HermesClaw 配置

重要：依赖条件

OpenClaw 客户端（Windows/macOS/Linux）
微信账号（建议使用小号，遵守微信服务条款）
本地网络可达（用于 WebSocket 连接）

# 安装 HermesClaw（OpenClaw 插件）
openclaw plugin install hermes-claw

# 首次配置
openclaw claw setup
# 配置向导：
# 1. 选择桥接模式（wechat-native 或 wechat-work）
# 2. 扫码登录微信
# 3. 配置监听范围（哪些群/好友）

# 启动桥接
openclaw claw start

# 查看状态
openclaw claw status
# 输出示例：
# HermesClaw Bridge: Running
# Connected Accounts: 1
# Active Chats: 12
# Messages Today: 47

配置参数：

# ~/.openclaw/hermes-claw.yaml
hermes-claw:
  # 连接模式
  mode: "wechat-native"  # wechat-native | wechat-work
  
  # OpenClaw Gateway 地址
  gateway:
    host: "localhost"
    port: 8080
    path: "/api/v1/chat"
    
  # 消息监听范围
  scope:
    # 是否监听所有私聊
    all_private: false
    # 允许的私聊好友列表（微信昵称或备注）
    allowed_contacts:
      - "Hermes"
      - "我的小号"
    # 是否监听所有群
    all_groups: false
    # 允许的群聊列表
    allowed_groups:
      - "AI 技术交流群"
      - "开发团队"
      
  # 触发方式
  triggers:
    # 私聊：always（始终响应）| mentioned（被@时响应）
    private: "always"
    # 群聊：never（不响应）| mentioned（被@时响应）| keyword（关键词触发）
    group: "mentioned"
    # 关键词列表（keyword 模式时使用）
    keywords:
      - "hermes"
      - "小助手"
      - "帮我"
      
  # 消息处理
  processing:
    # 是否自动转译语音消息
    voice_to_text: true
    # 是否下载图片进行 OCR
    image_ocr: false
    # 文件下载目录
    download_path: "~/Downloads/hermes-claw"
    
  # 限流
  rate_limit:
    # 每用户每分钟最大消息数
    per_user_per_minute: 10
    # 消息处理超时（秒）
    processing_timeout: 120

4.4 企业微信（WeCom）桥接

如果你是企业用户，企业微信提供了更稳定的 API 支持：

# 企业微信配置
hermes-claw:
  mode: "wechat-work"
  
  # 企业微信应用配置
  work:
    corp_id: "${WECOM_CORP_ID}"
    agent_id: "${WECOM_AGENT_ID}"
    corp_secret: "${WECOM_CORP_SECRET}"
    
  # Webhook 地址（企业微信提供）
  webhook_url: "${WECOM_WEBHOOK_URL}"

五、安全配置

5.1 用户白名单

防止未授权用户访问你的 Hermes Agent：

# 安全配置
security:
  # 全局白名单模式
  whitelist_mode: true
  
  # 允许的用户（按平台）
  allowed_users:
    telegram:
      - "123456789"      # 用户 ID
      - "987654321"
    discord:
      - "111222333444555"  # Discord Snowflake ID
    slack:
      - "U1234567890"      # Slack User ID
    signal:
      - "+8613812345678"   # Signal 号码
      
  # 拒绝消息处理
  on_unauthorized:
    # 回复提示（可选，留空则不回复）
    reply: "抱歉，我没有权限响应你的消息。"
    # 记录到日志
    log: true
    # 发送通知给管理员
    notify_admin: true

5.2 群组访问控制

# 群组配置
groups:
  # 允许 Bot 加入的群组（留空允许所有）
  allowed:
    telegram: []
    discord:
      - "guild_id_123"
      - "guild_id_456"
      
  # 群组级白名单（仅这些群组可用）
  whitelist_mode: false
  
  # 信任的群组成员
  trusted_members:
    discord:
      "guild_id_123":
        - "role_id_admin"
        - "user_id_owner"

5.3 速率限制（Rate Limiting）

防止滥用和 API 配额耗尽：

# 速率限制
rate_limit:
  # 全局设置
  global:
    # 每分钟最大消息数
    messages_per_minute: 100
    # 令牌桶大小
    burst_size: 20
    
  # 按用户限制
  per_user:
    messages_per_minute: 20
    messages_per_hour: 500
    messages_per_day: 5000
    
  # 按群组限制
  per_group:
    messages_per_minute: 60
    # 响应比例（%）
    response_ratio: 30
    
  # 限流响应
  on_limit:
    action: "cooldown"  # cooldown | drop | error
    cooldown_seconds: 60
    notify_user: true

六、部署方案

6.1 前台运行（开发调试用）

hermes gateway --verbose
# 输出详细日志，Ctrl+C 停止

6.2 后台运行（systemd）

# 安装为系统服务
sudo hermes gateway install

# 服务管理
sudo systemctl start hermes-gateway
sudo systemctl stop hermes-gateway
sudo systemctl restart hermes-gateway
sudo systemctl status hermes-gateway

# 查看日志
sudo journalctl -u hermes-gateway -f

systemd 服务文件（自动生成）：

[Unit]
Description=Hermes Agent Messaging Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hermes
Group=hermes
WorkingDirectory=/home/hermes
Environment="HERMES_CONFIG=/home/hermes/.hermes/config.yaml"
ExecStart=/usr/local/bin/hermes gateway
Restart=always
RestartSec=10

# 安全设置
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/hermes/.hermes

[Install]
WantedBy=multi-user.target

6.3 Docker 部署（推荐生产环境）

# docker-compose.yaml
version: '3.8'

services:
  hermes-gateway:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    
    environment:
      # 模型配置
      - HERMES_MODEL=${MODEL_PROVIDER:-openai}
      - HERMES_API_KEY=${API_KEY}
      - HERMES_MODEL_NAME=${MODEL_NAME:-gpt-4o}
      
      # Gateway 配置
      - HERMES_GATEWAY_ENABLED=true
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}
      
    volumes:
      # 持久化记忆和配置
      - hermes_data:/data/hermes
      - ./config:/config
      # SSL 证书（如果需要 HTTPS Webhook）
      - ./certs:/certs:ro
      
    ports:
      - "8080:8080"  # Gateway API
      - "8081:8081"  # 管理界面
      
    healthcheck:
      test: ["CMD", "hermes", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

volumes:
  hermes_data:
    driver: local

# 一键启动
docker-compose up -d

# 查看日志
docker-compose logs -f hermes-gateway

# 更新版本
docker-compose pull && docker-compose up -d

6.4 反向代理配置

如果需要从公网访问 Gateway Webhook：

Nginx 配置：

upstream hermes_gateway {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name hermes.your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/hermes.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hermes.your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # Telegram 要求
    ssl_prefer_server_ciphers on;
    
    location / {
        proxy_pass http://hermes_gateway;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Telegram Webhook 特殊处理
        proxy_read_timeout 60s;
        proxy_connect_timeout 60s;
        
        # 长时间响应支持
        proxy_send_timeout 300s;
    }
}

Cloudflare Tunnel（无需公网 IP）：

# 安装 cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# 启动隧道
cloudflared tunnel --url http://localhost:8080
# 输出示例：
# Your tunnel <tunnel-id> is now running on https://xxxx.trycloudflare.com

# 使用固定域名（需要 Cloudflare Zero Trust）
cloudflared tunnel run --token <your-token>

七、监控与运维

7.1 健康检查

# 检查 Gateway 状态
hermes gateway status

# 输出示例：
# Gateway Status: healthy
# Uptime: 5d 12h 34m
# Connected Platforms: 3
#   - Telegram: connected (Bot: @MyHermesBot)
#   - Discord: connected (Guilds: 2)
#   - Slack: connected (Workspace: mycompany)
# Messages Today: 342
# Active Sessions: 12
# Memory Usage: 1.2 GB
# Last Error: none

7.2 日志配置

# logging.yaml
logging:
  # 日志级别
  level: "info"  # debug | info | warning | error
  
  # 日志输出
  outputs:
    - type: "console"
      format: "pretty"  # pretty | json
      color: true
      
    - type: "file"
      path: "/var/log/hermes/gateway.log"
      max_size: "100MB"
      max_backups: 5
      compress: true
      
    - type: "syslog"  # 可选，发送到集中日志系统
      host: "syslog.company.com"
      port: 514
      protocol: "tcp"
      
  # 特定模块的日志级别
  modules:
    "gateway.adapter.telegram": "debug"
    "gateway.router": "info"
    "gateway.core": "warning"

7.3 Prometheus 指标

# 启用 Prometheus 指标端点
metrics:
  enabled: true
  port: 9090
  path: "/metrics"
  
  # 指标类型
  collectors:
    - messages_total        # 消息总数
    - messages_by_platform  # 按平台分类的消息数
    - response_time_seconds # 响应时间
    - active_sessions       # 当前活跃会话数
    - token_usage           # Token 消耗
    - error_rate            # 错误率

Prometheus 查询示例：

# Gateway 消息吞吐量
rate(hermes_messages_total[5m])

# 按平台分类的消息
rate(hermes_messages_by_platform[5m])

# P99 响应时间
histogram_quantile(0.99, rate(hermes_response_time_seconds_bucket[5m]))

# 错误率
rate(hermes_errors_total[5m]) / rate(hermes_messages_total[5m])

7.4 Grafana 仪表盘

Gateway 内置了 Grafana 仪表盘定义，可以一键导入：

# 导出仪表盘 JSON
hermes dashboard export --format grafana > hermes-dashboard.json

# 或者直接在 Grafana 中导入
# Administration → Dashboards → Import → 上传 JSON

八、高级技巧

8.1 多 Bot 负载均衡

对于高流量场景，可以运行多个 Hermes 实例：

# 使用 nginx 或 consul 做负载均衡
upstream hermes_cluster {
    least_conn;  # 最少连接优先
    
    server hermes-1:8080;
    server hermes-2:8080;
    server hermes-3:8080;
}

# 注意：所有实例需要共享存储（记忆系统）
# 可以使用 Redis 或 PostgreSQL 作为后端存储

8.2 消息队列解耦

使用消息队列解耦平台适配器和核心处理：

# 使用 Redis Streams 作为消息队列
queue:
  enabled: true
  type: "redis"
  
  redis:
    url: "redis://localhost:6379"
    stream: "hermes:gateway:queue"
    consumer_group: "hermes-processors"
    
  # 配置消费者数量
  workers: 4
  
  # 消息确认模式
  ack_mode: "manual"  # auto | manual

8.3 自定义平台适配器

如果你的平台不在支持列表中，可以开发自定义适配器：

# gateway/adapters/custom_adapter.py
from hermes.gateway.base import BaseAdapter
from hermes.gateway.types import UnifiedMessage

class CustomAdapter(BaseAdapter):
    """自定义平台适配器模板"""
    
    platform_name = "my_platform"
    
    async def connect(self) -> None:
        """建立与平台的连接"""
        pass
        
    async def disconnect(self) -> None:
        """断开连接"""
        pass
        
    async def send_message(self, message: UnifiedMessage) -> None:
        """发送消息到平台"""
        pass
        
    async def handle_incoming(self, raw_data: dict) -> UnifiedMessage:
        """将平台原始数据转换为统一格式"""
        return UnifiedMessage(
            message_id=raw_data["id"],
            chat_id=raw_data["chat_id"],
            platform=self.platform_name,
            content={"text": raw_data["text"]},
            sender={"id": raw_data["user_id"]},
            timestamp=raw_data["timestamp"]
        )
        
    def format_response(self, response: str, original: UnifiedMessage) -> dict:
        """将响应格式化为平台原生格式"""
        return {
            "chat_id": original.chat_id,
            "text": response
        }

注册适配器：

# 注册自定义适配器
hermes adapter register --name my_platform --path ./custom_adapter.py

# 或在配置中声明
# gateway:
#   adapters:
#     - my_platform

九、故障排查

常见问题速查

问题	原因	解决方案
Telegram Bot 无响应	Token 错误或未设置 Webhook	检查 Token，确认 Bot 已 start
Discord Slash Commands 不显示	未正确配置 Intent	在 Discord Developer Portal 启用 MESSAGE CONTENT INTENT
Slack Bot 无法加入频道	OAuth Scope 不足	添加 `channels:write`、`groups:write` 权限
微信桥接频繁掉线	微信检测到异常行为	降低消息频率，使用企业微信 API
消息延迟高	网络问题或模型响应慢	检查网络，启用消息队列缓冲
记忆不跨平台同步	共享存储未正确配置	检查数据库连接，确认 session 共享

诊断命令

# 完整诊断
hermes gateway doctor

# 测试特定平台连接
hermes gateway test --platform telegram --token YOUR_TOKEN

# 查看详细日志
hermes gateway --log-level debug

# 重置平台连接
hermes gateway reset --platform telegram

十、最佳实践总结

从 Telegram 开始：最简单、最稳定，适合初次部署
始终配置白名单：防止陌生人滥用你的 Agent
使用 Docker 部署：简化依赖管理，便于迁移
配置速率限制：保护 API 配额，防止滥用
启用监控：Prometheus + Grafana 是标配
定期备份记忆：将记忆数据库纳入备份计划
微信用小号：遵守平台规则，降低账号风险
多平台统一体验：利用平台感知功能，为每个平台优化输出格式

系列文章预告

（九）最佳实践与生态展望：日常使用最佳实践、安装配置清单、性能优化技巧、社区生态、Discord、Skills Hub、GitHub。Roadmap 与开源意义。快速查询核心命令。

有问题？欢迎在评论区留言或加 Discord 社区讨论。

📚 系列导航

Hermes-Agent（八）：消息网关深度指南——统一多平台接入的核心枢纽

一、Gateway 架构：消息路由的核心枢纽

1.1 为什么需要消息网关？

1.2 Gateway 的消息流程

1.3 统一消息格式（Unified Message Format）

二、支持的平台一览

2.1 完整支持矩阵

2.2 各平台接入要点

Telegram —— 最推荐的接入方式

Discord —— 功能最丰富的平台

Slack —— 企业场景首选

WhatsApp —— 通过 WhatsApp Business API

Signal —— 注重隐私的首选

三、跨平台对话统一性

3.1 共享记忆的跨平台体验

3.2 平台感知的内容适配

四、微信接入：HermesClaw 桥接方案

4.1 为什么需要桥接？

4.2 HermesClaw 工作原理

4.3 HermesClaw 配置

4.4 企业微信（WeCom）桥接

五、安全配置

5.1 用户白名单

5.2 群组访问控制

5.3 速率限制（Rate Limiting）

六、部署方案

6.1 前台运行（开发调试用）

6.2 后台运行（systemd）

6.3 Docker 部署（推荐生产环境）

6.4 反向代理配置

七、监控与运维

7.1 健康检查

7.2 日志配置

7.3 Prometheus 指标

7.4 Grafana 仪表盘

八、高级技巧

8.1 多 Bot 负载均衡

8.2 消息队列解耦

8.3 自定义平台适配器

九、故障排查

常见问题速查

诊断命令

十、最佳实践总结

系列文章预告

系列：Hermes-Agent系列

评论

发表评论

📚 系列导航

Hermes-Agent（八）：消息网关深度指南——统一多平台接入的核心枢纽

一、Gateway 架构：消息路由的核心枢纽

1.1 为什么需要消息网关？

1.2 Gateway 的消息流程

1.3 统一消息格式（Unified Message Format）

二、支持的平台一览

2.1 完整支持矩阵

2.2 各平台接入要点

Telegram —— 最推荐的接入方式

Discord —— 功能最丰富的平台

Slack —— 企业场景首选

WhatsApp —— 通过 WhatsApp Business API

Signal —— 注重隐私的首选

三、跨平台对话统一性

3.1 共享记忆的跨平台体验

3.2 平台感知的内容适配

四、微信接入：HermesClaw 桥接方案

4.1 为什么需要桥接？

4.2 HermesClaw 工作原理

4.3 HermesClaw 配置

4.4 企业微信（WeCom）桥接

五、安全配置

5.1 用户白名单

5.2 群组访问控制

5.3 速率限制（Rate Limiting）

六、部署方案

6.1 前台运行（开发调试用）

6.2 后台运行（systemd）

6.3 Docker 部署（推荐生产环境）

6.4 反向代理配置

七、监控与运维