消息网关Messaging Gateway让同一个 Agent——同样的记忆、技能和工具——在 20 平台上无缝运行。本章将介绍 Gateway 的配置与部署、会话生命周期、多用户隔离策略以及安全访问控制。消息网关概览消息网关是一个常驻后台进程统一管理所有消息平台的连接、会话、定时任务和媒体投递。你在 CLI 中教给 Agent 的一切——记忆、技能、偏好——在所有平台上完全一致。支持的平台Hermes 支持 20 消息平台CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、钉钉、飞书/Lark、企业微信、微信、QQ、元宝、BlueBubblesiMessage、Home Assistant、Microsoft Teams、Google Chat 等。平台能力对比平台语音图片文件消息串表情反应打字指示流式输出Telegram支持支持支持支持—支持支持Discord支持支持支持支持支持支持支持Slack支持支持支持支持支持支持支持WhatsApp—支持支持——支持支持Signal—支持支持——支持支持飞书/Lark支持支持支持支持支持支持支持企业微信支持支持支持————钉钉—支持支持—支持—支持Microsoft Teams—支持—支持—支持—Email—支持支持支持———SMS———————Matrix支持支持支持支持支持支持支持跨平台会话连续性同一个 Agent 可以在不同平台之间保持上下文。比如你在 Telegram 上跟 Agent 聊了一半切换到 Discord 后 Agent 仍然记得之前的对话。Gateway 启动与配置桌面版配置打开左侧菜单的消息平台可以看到支持的平台点击对应平台即可对应配置交互模式下配置使用交互式向导完成所有平台的初始配置hermes gateway setup向导会引导你完成每个平台的配置选择平台、填写 Bot Token、设置允许用户列表等。比如选择飞书进入后可以选择扫描二维码创建机器人或通过 APP ID 创建网关管理命令实例# 前台运行调试时使用hermes gateway# 安装为用户级系统服务Linux systemd / macOS launchdhermes gateway install# Linux安装为开机自启的系统服务sudo hermes gateway install --system# 服务控制hermes gateway start # 启动服务hermes gateway stop # 停止服务hermes gateway restart # 重启服务hermes gateway status # 查看服务状态Telegram Bot 接入实战以 Telegram 为例完成一个完整的 Bot 接入流程。步骤一创建 Telegram Bot。在 Telegram 中搜索 BotFather发送 /newbot 命令按提示设置 Bot 名称和用户名。BotFather 会返回一个 Bot API Token格式类似1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。步骤二配置 Hermes Gateway。实例# 文件路径~/.hermes/config.yaml# Telegram 平台配置platforms:telegram:enabled: truebot_token: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz# 可选允许的用户 ID 列表白名单模式allowed_users:- 123456789# 可选是否需要在群组中被 提及 才响应require_mention: true# 可选免 提及 的频道列表free_response_channels:- -1001234567890步骤三启动并测试。实例# 启动 Gatewayhermes gateway start# 在 Telegram 中向你的 Bot 发送消息测试首次接入建议使用白名单模式allowed_users只允许你自己的账号与 Agent 交互待验证一切正常后再开放给其他人。平台内可用的斜杠命令在任何消息平台内都可以使用以下命令命令功能/new 或 /reset开启新会话/model [名称]查看或切换模型/retry重试上一条消息/undo撤销上一轮对话/stop中断当前任务/approve / /deny审批/拒绝危险命令/background 任务在后台会话中运行任务/status显示当前会话信息/usage显示本次会话 Token 用量/voice [on/off/tts]控制语音回复/compress手动压缩对话上下文/resume [标题]恢复之前命名的会话/skill-name调用任意已安装技能/reload-mcp重新加载 MCP 服务器/update更新 Hermes 到最新版本/help显示所有可用命令会话生命周期Session 是 Hermes Gateway 中管理对话的核心概念。理解 Session 的工作原理有助于你配置合适的会话隔离策略和重置规则。SessionSource消息来源描述符每条进入 Gateway 的消息都附带一个 SessionSource它记录了这条消息「从哪里来」。字段类型说明platformstring平台名称telegram、discord、slack 等chat_idstring会话标识私聊 ID、群组 ID、频道 IDchat_typestring会话类型dm私聊、group群组、channel频道、thread线程user_idstring消息发送者的平台 IDuser_namestring消息发送者的显示名称thread_idstring论坛话题 IDTelegram 论坛/ Discord 线程 IDguild_idstringDiscord 服务器 ID用于服务器隔离Session Key 生成规则Session Key 是由 SessionSource 中的字段组合而成的确定性字符串。它决定了哪些消息属于同一个会话格式如下agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}不同场景下的 Session Key 示例场景Session KeyTelegram 私聊agent:main:telegram:dm:12345Telegram 群组agent:main:telegram:group:-10012345:user_abcTelegram 论坛话题agent:main:telegram:group:-10012345:thread_678:user_abcDiscord 私聊agent:main:discord:dm:12345Discord 服务器频道agent:main:discord:channel:12345:user_abcDiscord 线程agent:main:discord:thread:12345:thread_678Session Key 的生成规则是网关最重要的配置之一。如果配置不当可能导致不同用户的会话「串线」——两个不同的人看到对方的对话内容。SessionEntry活跃会话记录每个 Session Key 对应一个 SessionEntry它记录了会话的元数据和状态。字段说明session_id会话唯一标识格式YYYYMMDD_HHMMSS_8位随机hexcreated_at会话创建时间updated_at最后活动时间用于闲置超时判断total_tokens累计 token 消耗estimated_cost_usd累计费用估算美元suspended是否被强制挂起/stop 命令或异常循环resume_pending是否在等待恢复崩溃后重启恢复标记多用户隔离策略多用户隔离决定了多个用户在同一个群组或频道中是共享一个会话还是各自独立。这个配置直接影响用户体验——共享会话意味着用户 A 可以看到用户 B 的对话上下文。隔离策略配置配置项默认值含义group_sessions_per_usertrue群组/频道中每个用户拥有独立的会话thread_sessions_per_userfalse线程中所有用户共享同一个会话不同场景的行为场景默认行为说明私聊DM始终独立私聊永远是私有的不可配置群组/频道每个用户独立会话用户 A 和用户 B 在同一个群组中各自拥有独立的会话上下文线程论坛话题所有用户共享会话Telegram 论坛话题和 Discord 线程中所有参与者共享同一个上下文共享会话的系统提示词变化当会话是共享模式shared_multi_user_session true时系统提示词会发生变化不再固定一个用户名而是提示「多用户会话——消息前缀有发送者名称」每条用户消息前会加上发送者的显示名称让 Agent 知道是谁在说话这种设计保持了提示词缓存的有效性系统提示词不随发送者变化而变化默认的隔离策略群组 per-user线程 shared是经过大量实践验证的最佳实践。除非有特殊需求否则不建议修改。网关安全配置用户访问控制默认情况下网关拒绝所有未在白名单中的用户——这是拥有终端访问权限的 Bot 的安全默认设置。配置允许访问的用户在 .env 文件中实例# 文件路径~/.hermes/.env# 针对特定平台的用户白名单TELEGRAM_ALLOWED_USERS123456789,987654321DISCORD_ALLOWED_USERS123456789012345678SLACK_ALLOWED_USERSU012AB3CD,U012EF4GHFEISHU_ALLOWED_USERSou_xxxxxxxx,ou_yyyyyyyyWECOM_ALLOWED_USERSuser-id-1,user-id-2TEAMS_ALLOWED_USERSaad-object-id-1# 跨所有平台生效的白名单GATEWAY_ALLOWED_USERS123456789,987654321# 允许所有用户不推荐用于有终端权限的 BotGATEWAY_ALLOW_ALL_USERStrueDM 配对替代白名单无需手动配置用户 ID新用户私信 Bot 时会收到一次性配对码实例# 用户私信 Bot 后会看到配对码XKGH5N7P# 你来批准该用户的访问权限hermes pairing approve telegram XKGH5N7P# 查看待处理 已批准的用户列表hermes pairing list# 撤销某个用户的访问权限hermes pairing revoke telegram 123456789配对码 1 小时后过期有频率限制使用密码学随机数生成。沉默令牌用于群聊、Hook 和自动化流程中让 Agent 在特定条件下不发送任何消息# Agent 回复中仅包含以下内容之一时网关不会向平台发送任何消息 [SILENT] SILENT NO_REPLY NO REPLY沉默是投递决策不影响会话记录——该回复仍存储在会话历史中保证对话交替逻辑正常。会话重置策略配置会话何时自动重置防止上下文无限增长实例{reset_by_platform: {telegram: { mode: idle, idle_minutes: 240 },discord: { mode: idle, idle_minutes: 60 },slack: { mode: daily, reset_hour: 4 }}}策略默认值说明daily凌晨 4 点每天特定时刻重置会话idle1440 分钟空闲超时后重置会话both组合哪个先触发就重置常用命令速查实例# ─── 网关管理 ────────────────────────────────────────────────hermes gateway setup # 交互式平台配置hermes gateway # 前台运行调试hermes gateway install # 安装为用户服务hermes gateway start / stop / restart # 服务控制hermes gateway status # 查看服务状态# ─── 用户配对 ────────────────────────────────────────────────hermes pairing list # 查看配对列表hermes pairing approve platform code # 批准配对hermes pairing revoke platform user_id # 撤销访问# ─── 会话内斜杠命令 ──────────────────────────────────────────/new # 开启新会话/model [名称] # 查看或切换模型/retry # 重试上一条消息/undo # 撤销上一轮对话/stop # 中断当前任务/approve / /deny # 审批/拒绝危险命令/background 任务 # 后台运行任务/status # 当前会话信息/usage # Token 用量/voice [on/off/tts] # 控制语音/compress # 压缩上下文/resume [标题] # 恢复会话/skill-name # 调用技能/reload-mcp # 重新加载 MCP/update # 更新 Hermes/help # 所有命令