Hermes Agent 学习笔记 07：Messaging Gateway，让 Agent 从终端走向多平台入口

1. 为什么需要 Messaging Gateway？

前面几期中，我主要是在终端里使用 Hermes Agent。

第二期讲了安装和第一次运行，第三期讲了 CLI/TUI，第四期讲了工具调用系统，第五期讲了 Memory，第六期讲了 Skills。到这里，Hermes 已经可以在终端中完成很多任务：读取项目、执行命令、调用工具、记住用户偏好、沉淀 skills。

但是，如果 Hermes 只能在终端里使用，它仍然有一个明显局限：用户必须打开电脑、进入终端、启动会话，才能和 Agent 交互。

这和"长期运行的个人 Agent"还有距离。

一个真正长期运行的 Agent，不应该只待在命令行窗口里。它应该能在用户真实使用的入口中出现，比如 Telegram、Discord、Slack、Email，甚至手机消息软件。这样，用户可以随时给 Agent 发消息、发送文件、语音输入、接收定时任务结果，而不必一直守在终端前。

这就是 Messaging Gateway 的意义。

简单来说：

复制代码

CLI/TUI 让 Hermes 进入开发者终端。
Messaging Gateway 让 Hermes 进入用户日常沟通入口。

如果说前面的 CLI 是"本地工作台"，那么 Messaging Gateway 更像是"在线服务入口"。

2. Messaging Gateway 是什么？

Messaging Gateway 可以理解为 Hermes Agent 的多平台消息网关。

它不是一个新的模型，也不是一个单独的聊天机器人，而是 Hermes 和外部消息平台之间的连接层。

它主要做几件事：

复制代码

连接 Telegram、Discord、Slack、Email 等平台；
接收外部平台发来的消息；
把消息转换成 Hermes 可以处理的任务；
把任务交给 AIAgent 执行；
把 Agent 的回复发回原平台；
管理每个聊天窗口对应的会话；
运行 cron 定时任务；
把定时任务结果投递到指定聊天入口。

所以，Messaging Gateway 的核心价值是把 Hermes 从"只能在本机终端使用"扩展成"可以通过多个消息平台远程使用"。

用户可以这样理解：

复制代码

Hermes 本体负责思考和执行任务；
Messaging Gateway 负责收发消息和管理平台入口。

3. CLI 和 Messaging Gateway 的区别

CLI/TUI 和 Messaging Gateway 都可以和 Hermes 对话，但它们的使用场景不同。

CLI/TUI 更适合：

复制代码

本地开发；
源码阅读；
调试代码；
查看工具调用细节；
执行终端命令；
长时间坐在电脑前分析项目。

Messaging Gateway 更适合：

复制代码

手机随时提问；
远程触发任务；
接收定时结果；
发送语音消息；
上传文件让 Agent 处理；
在团队频道里共享 Agent；
让 Agent 长期运行在服务器上。

也就是说，CLI 更像开发者工作环境，Messaging Gateway 更像服务化入口。

例如，用户在电脑前分析代码时，可以用 CLI/TUI。

但用户外出时想让 Hermes 总结一份资料、查看服务器状态、接收每日摘要，就可以通过 Telegram 或 Email 和它交互。

这也是 Hermes 设计中很重要的一点：它不是把用户锁在一个界面里，而是让同一个 Agent 可以出现在不同平台上。

4. Messaging Gateway 的基本架构

从架构上看，Messaging Gateway 可以拆成三个部分：

复制代码

平台适配器
会话管理器
Agent 调度层

4.1 平台适配器

不同平台的消息格式不一样。

Telegram 有 Bot API。

Discord 有 bot 和 channel。

Slack 有 workspace、channel 和 thread。

Email 使用 IMAP/SMTP。

WhatsApp、Signal、Matrix、Feishu/Lark、Teams 等也都有自己的接入方式。

平台适配器负责把这些不同平台的消息统一转换成 Hermes 内部可以理解的格式。

也就是说，不管消息来自 Telegram 还是 Email，最终都要被转换成类似：

复制代码

用户是谁；
来自哪个平台；
属于哪个会话；
消息内容是什么；
有没有附件；
有没有语音；
是否是命令；
应该发回哪里。

这样，Hermes Agent 才能用统一方式处理。

4.2 会话管理器

Messaging Gateway 不是简单地把每条消息都当作新问题。

它需要知道：

复制代码

这个用户之前说了什么；
这个聊天窗口对应哪个 session；
当前会话是否应该延续；
是否需要重置；
是否是群聊；
是否是 thread；
是否是定时任务结果投递入口。

例如，用户在 Telegram 私聊里连续发三条消息，Hermes 应该知道这三条属于同一个会话。

如果用户在 Slack 的不同 thread 中提问，Hermes 可能需要把不同 thread 视为不同上下文。

如果一个群里很多人同时发言，Hermes 还要判断哪些内容应该触发回复，哪些只是旁观上下文。

所以，Messaging Gateway 不只是"收消息、发消息"，它还承担了会话边界管理。

4.3 Agent 调度层

当 Gateway 收到消息并确定会话后，就会把任务交给 Hermes 的 Agent 核心处理。

Agent 核心仍然会使用前面几期讲过的能力：

复制代码

调用模型；
使用 tools；
读取 memory；
加载 skills；
执行 shell；
访问浏览器；
运行 background task；
触发 cron。

也就是说，Messaging Gateway 只是入口变化了，Hermes 的核心能力没有变。

用户从 Telegram 发一句话，本质上和在 CLI 输入一句话一样，都可能触发 Agent 的推理、工具调用和回复生成。

5. Gateway 的启动方式

最简单的配置方式是运行：

复制代码

hermes gateway setup

这个命令会进入交互式配置向导，用户可以选择要配置的平台，例如 Telegram、Discord、Slack、Email 等。

配置完成后，可以直接在前台运行 Gateway：

复制代码

hermes gateway

前台运行适合初学和调试。因为你可以直接在终端里看到日志，知道平台是否连接成功、消息是否进来、报错在哪里。

如果确认配置正常，就可以把 Gateway 安装成系统服务：

复制代码

hermes gateway install

然后启动服务：

复制代码

hermes gateway start

查看服务状态：

复制代码

hermes gateway status

停止服务：

复制代码

hermes gateway stop

这说明 Gateway 不一定要一直开着一个终端窗口。它可以作为后台服务长期运行，这才符合"长期 Agent"的使用方式。

6. 为什么 Gateway 要长期运行？

如果只在终端里使用 Hermes，那么用户启动 hermes 后对话，退出后就结束。

但消息平台不一样。

如果用户希望随时给 Telegram bot 发消息，Hermes 就必须有一个后台进程一直监听 Telegram 消息。

如果用户希望每天早上收到 cron 总结，Gateway 就必须在指定时间运行并投递结果。

如果用户希望通过 Email 给 Agent 发任务，Gateway 就要定期检查邮箱并回复。

因此，Messaging Gateway 的本质是让 Hermes 从"手动启动的命令行程序"变成"持续在线的后台服务"。

这也是 Agent 产品形态的重要变化：

复制代码

CLI 模式：用户主动打开 Agent。
Gateway 模式：Agent 长期在线，等待用户或定时任务触发。

7. Telegram 接入示例

Telegram 是最适合作为初学示例的平台之一，因为它配置相对直观，适合个人使用。

典型流程是：

复制代码

创建 Telegram bot；
拿到 bot token；
找到自己的 Telegram user ID；
在 Hermes 中配置 token 和 allowlist；
启动 gateway；
给 bot 发送消息测试。

7.1 创建 Telegram Bot

在 Telegram 里找到 BotFather，然后发送：

复制代码

/newbot

接着按照提示设置 bot 名称和用户名。用户名通常需要以 bot 结尾。

创建完成后，BotFather 会返回一个 bot token。这个 token 很重要，因为任何拿到 token 的人都可能控制这个 bot，所以不能公开上传到 GitHub，也不能随便发给别人。

7.2 找到用户 ID

Hermes 通常使用 Telegram 的数字 user ID 做访问控制，而不是用户名。

这点很重要。因为 Telegram username 可以修改，但数字 user ID 更稳定。

找到 user ID 后，需要把它加入 Hermes 的允许列表。

7.3 配置 Hermes

可以使用交互式方式：

复制代码

hermes gateway setup

选择 Telegram，然后填入 bot token 和 allowed user IDs。

也可以手动在环境文件中配置：

复制代码

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

然后启动：

复制代码

hermes gateway

如果一切正常，Telegram bot 就可以接收消息并回复。

8. Telegram 群聊中的隐私模式

Telegram 群聊有一个很容易踩坑的地方：bot 默认开启 privacy mode。

当 privacy mode 开启时，bot 并不能看到群里的所有普通消息。它通常只能看到：

复制代码

以 / 开头的命令；
直接回复 bot 的消息；
成员加入、退出等服务消息；
bot 是管理员的频道消息。

所以，如果你把 Hermes bot 拉进群里，却发现它"看不见大家聊天"，不一定是 Hermes 配置错了，而可能是 Telegram bot 的隐私模式限制。

如果希望 bot 看到群里的普通消息，可以通过 BotFather 关闭隐私模式，或者把 bot 提升为群管理员。

但是这也带来新的问题：bot 看到的内容越多，隐私风险越大，prompt injection 风险也越大。

因此，群聊中更推荐采用明确触发方式，例如：

复制代码

@HermesBot 请总结上面讨论的需求

而不是让 bot 对所有消息都自动反应。

9. Email 接入：让 Hermes 变成一个可以收信的 Agent

除了即时通讯平台，Hermes 还可以通过 Email 接收和回复任务。

Email 接入方式和 Telegram 不同。它不是通过 bot API，而是使用传统的 IMAP/SMTP 协议：

复制代码

IMAP：接收邮件；
SMTP：发送回复。

用户可以给 Agent 的专用邮箱发邮件，Hermes 收到后解析内容，再通过同一个邮件线程回复。

这类方式适合一些更正式的任务场景：

复制代码

把文档发给 Agent 总结；
通过邮件提交日报生成任务；
让 Agent 回复固定格式报告；
给团队提供一个共享任务邮箱。

不过，Email 接入一定要注意安全。

首先，最好为 Hermes 准备一个专用邮箱，不要直接使用自己的个人主邮箱。

其次，如果邮箱开启了双重验证，通常应该使用 app password，而不是主密码。

再次，必须配置 allowed users，只允许可信邮箱给 Agent 发任务。

因为 Email gateway 一旦开放给所有人，任何知道这个邮箱地址的人都可能向 Agent 发指令。如果 Agent 同时拥有终端工具、文件工具或网络工具，就可能带来严重风险。

所以，Email 模式下的基本原则是：

复制代码

专用邮箱；
应用密码；
限制发件人；
保护 .env 文件；
不要让陌生人直接给 Agent 下命令。

10. 消息平台中的 slash commands

Messaging Gateway 不只是把普通文字转发给 Hermes，它也支持很多 slash commands。

例如：

复制代码

/new
/status
/model
/retry
/undo
/stop
/approve
/deny
/sethome
/compress
/title
/resume
/usage
/background
/help

这些命令的作用和 CLI 中类似，但使用场景更偏远程控制。

例如：

复制代码

/status

可以查看当前会话状态。

复制代码

/new

可以开启新会话，避免旧上下文干扰。

复制代码

/sethome

可以设置当前聊天为 home channel，让 cron 定时任务结果投递到这里。

复制代码

/background <prompt>

可以启动一个后台任务，任务完成后结果会自动发回当前聊天。

复制代码

/approve
/deny

可以用于远程批准或拒绝危险命令。

这说明 Messaging Gateway 并不是一个"简化版 Hermes"，而是把很多 Agent 控制能力搬到了消息平台中。

11. Home Channel：为什么要设置默认投递入口？

在 Messaging Gateway 中，一个很重要的概念是 home channel。

简单理解，home channel 就是 Hermes 主动发送结果的默认位置。

例如，用户设置了一个 cron 任务：

复制代码

每天早上 9 点总结昨天的项目进展

这个任务到时间后，Hermes 需要知道把结果发到哪里。这个"哪里"就是 home channel。

在 Telegram 中，可以进入某个私聊或群聊，然后发送：

复制代码

/sethome

这样，当前聊天就会被设置为默认投递位置。

这个设计非常重要。因为 CLI 模式下，用户通常就在终端前等回复；但 Gateway 模式下，很多任务是异步触发的，例如 cron、background task、监控任务。它们需要一个明确的结果投递位置。

所以，home channel 可以理解为 Hermes 的"默认汇报窗口"。

12. Background Task：消息平台上的异步任务

Messaging Gateway 支持 background task。

例如，在 Telegram 里输入：

复制代码

/background 请检查当前项目的测试覆盖情况，并总结主要问题。

Hermes 可以把这个任务放到后台执行。用户不需要一直等待，可以继续聊天。任务完成后，结果会自动发回当前聊天。

这种模式非常适合长任务：

复制代码

跑测试；
查资料；
生成报告；
整理文件；
扫描日志；
检查服务状态；
总结项目进展。

它和普通对话的区别是：

复制代码

普通对话：当前消息阻塞，等 Agent 完成。
Background task：另起后台会话，完成后再投递结果。

不过，background task 也要谨慎使用。因为它可能调用工具、执行命令、消耗 token，也可能运行很久。

初学阶段不建议一次启动太多后台任务。更稳妥的方式是先让 Hermes 做小任务，确认配置稳定后，再用于长期自动化。

13. 会话持久化与重置策略

Messaging Gateway 中的会话是会持续存在的。

这意味着你在 Telegram 或 Slack 中连续聊天，Hermes 会把这些消息作为同一个 session 处理，而不是每条消息都从零开始。

但会话也不能无限持续。否则上下文会越来越长，成本越来越高，也容易把不相关的旧任务混在一起。

因此，Gateway 支持会话重置策略，例如：

复制代码

按天重置；
空闲一段时间后重置；
两者结合。

比如某个平台可以设置为闲置 240 分钟后重置，另一个平台可以设置为每天固定时间重置。

这个机制的意义是平衡连续性和上下文清洁度。

如果任务需要连续，就保持会话。

如果任务已经结束，就应该重置或新建会话。

在使用时，可以主动发送：

复制代码

/new

或者：

复制代码

/reset

开启新的上下文，避免旧任务干扰当前问题。

14. 多用户访问控制：不能让任何人都能用你的 Agent

Messaging Gateway 最大的风险之一，就是它把 Agent 暴露到了外部平台。

在 CLI 模式下，能使用 Hermes 的通常只有本机用户。

但在 Gateway 模式下，如果没有访问控制，任何能给 bot 发消息的人都可能触发 Agent。

这非常危险。因为 Hermes 可能拥有：

复制代码

终端访问权限；
文件读取权限；
网络访问权限；
工具调用权限；
MCP 外部系统权限；
定时任务创建权限。

因此，必须配置 allowlist。

例如 Telegram：

复制代码

TELEGRAM_ALLOWED_USERS=123456789

Email：

复制代码

EMAIL_ALLOWED_USERS=trusted@example.com

也可以配置统一的 Gateway allowlist：

复制代码

GATEWAY_ALLOWED_USERS=123456789,987654321

不建议轻易使用：

复制代码

GATEWAY_ALLOW_ALL_USERS=true

因为这相当于允许所有人使用你的 Agent。对于一个拥有终端工具的 Agent 来说，这个风险太高。

15. DM Pairing：不用手动写 ID 的访问方式

除了手动配置 allowlist，Hermes Gateway 还支持 DM pairing。

大致流程是：

复制代码

未知用户给 bot 发私信；
bot 返回一个一次性 pairing code；
管理员在本机终端批准这个 code；
用户获得访问权限。

批准命令类似：

复制代码

hermes pairing approve telegram XKGH5N7P

也可以查看配对列表：

复制代码

hermes pairing list

撤销某个用户：

复制代码

hermes pairing revoke telegram 123456789

这种方式比手动找 ID 更方便，适合初次配置或临时授权。

但它仍然需要管理员批准，不是完全开放。

16. Admin 和 Regular User：进入之后还能做什么？

Allowlist 解决的是"谁可以访问 bot"。

但访问之后，还要继续区分权限。比如有些人只应该普通聊天，有些人可以运行高级 slash commands，有些人可以修改模型、批准命令、触发后台任务。

因此，Hermes Gateway 还区分 admin 和 regular user。

可以理解为：

复制代码

allowed user：可以访问 Agent；
admin user：可以使用更完整的控制命令；
regular user：只能使用有限命令和普通对话。

这在团队场景中很重要。

例如，团队可以允许多个成员在 Slack channel 里询问 Agent，但只有管理员能执行：

复制代码

/model
/update
/approve
/reload-mcp
/background

这样可以避免普通成员误触发高风险操作。

17. 平台专属 Toolset：不同入口可以有不同权限

一个很重要的设计是，不同平台可以拥有不同的 toolset。

例如：

复制代码

CLI 使用 hermes-cli toolset；
Telegram 使用 hermes-telegram toolset；
Discord 使用 hermes-discord toolset；
Slack 使用 hermes-slack toolset；
Email 使用 hermes-email toolset。

这意味着，不同入口可以有不同的工具权限。

例如，你可能希望 CLI 拥有完整终端能力，因为它在本机受控环境中使用。

但你可能不希望 Telegram bot 拥有高风险 shell 权限，因为手机消息入口更容易被误触发。

你可能希望 Email 只用于总结和回复，不允许它修改文件或执行危险命令。

这就是平台级权限控制的意义。

Messaging Gateway 不应该简单理解为"把 Hermes 复制到所有平台"。更合理的理解是：

复制代码

不同平台是不同入口；
不同入口应该有不同权限；
权限越外部，越应该谨慎。

18. 语音、图片和文件：为什么 Gateway 更适合真实使用？

在终端中输入任务，主要是文本交互。

但在手机消息平台中，用户经常会发语音、图片和文件。

Messaging Gateway 的价值就在于，它可以把这些多模态输入接入 Hermes 工作流。

例如：

复制代码

发送语音：Hermes 自动转写成文字；
发送截图：Hermes 调用视觉能力分析；
发送 PDF：Hermes 下载附件并让 Agent 读取；
发送 CSV：Hermes 可以分析数据；
发送图片：Hermes 可以理解界面、图表或错误截图。

这让 Hermes 更接近真实助手。

比如用户在路上突然想到一个任务，可以直接发语音给 Telegram bot。

用户看到一个报错截图，可以直接发图片让 Hermes 分析。

用户收到一个 PDF 文档，可以转发给 Hermes 让它总结。

这些场景在 CLI 中也可以做，但消息平台更自然。

19. Intentional Silence：为什么有时 Agent 应该"不回复"？

在群聊、自动化和 hook 场景中，有时 Agent 不应该每次都回复。

例如，Gateway 观察到群里有人聊天，但这只是上下文，不需要打断大家。

又比如某个 cron 检查发现"没有变化"，不想每天都发一条无意义消息。

因此，Hermes 支持 intentional silence tokens。也就是说，如果 Agent 最终回复是特定静默标记，Gateway 就不会把它发到聊天里。

这类设计很有意思，因为它说明长期 Agent 不只是"有话就说"，还需要学会在不必要的时候保持安静。

对一个进入消息平台的 Agent 来说，沉默也是一种产品能力。

如果它在群里过度回复，用户很快会觉得它吵。

如果它只在必要时发言，体验会更自然。

20. Gateway 的运行维护

如果要让 Hermes Gateway 长期运行，就不能只关心"能不能启动"。还要关心运行维护。

常见维护内容包括：

复制代码

查看 gateway 状态；
查看日志；
重启服务；
检查平台是否断开；
处理 token 失效；
处理网络代理问题；
检查 cron 是否正常投递；
检查后台任务是否卡住。

在 Linux 上，可以查看用户服务日志：

复制代码

journalctl --user -u hermes-gateway -f

如果安装为系统服务，则查看系统日志：

复制代码

journalctl -u hermes-gateway -f

在 macOS 上，可以查看：

复制代码

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

这些日志对于排错非常关键。

比如 Telegram 不回复，可能是 token 错了、网络不通、用户不在 allowlist、隐私模式限制、bot 没权限，或者 gateway 根本没有启动。

没有日志，很难判断原因。

21. Messaging Gateway 的安全习惯

我认为使用 Messaging Gateway 至少要遵守以下安全习惯。

第一，必须配置 allowlist。

不要让任何人都能和你的 Agent 对话。

第二，不要把 bot token、邮箱密码、API key 上传到公开仓库。

这些应该放在本地 .env 文件，并设置好权限。

第三，优先使用专用账号。

Telegram bot、Email 账号、Slack app 都最好和个人主账号隔离。

第四，外部平台不要默认开放高风险工具。

尤其是 shell、文件修改、MCP 外部系统调用。

第五，团队场景中区分 admin 和 regular user。

不是每个成员都应该有完整控制权限。

第六，群聊中谨慎处理上下文。

群聊里的普通消息可能包含无关内容，也可能包含恶意提示词。Agent 不应该把所有群聊消息都当作可信指令。

第七，定期检查 gateway 日志和访问列表。

长期运行的服务必须维护，否则配置会逐渐失控。

22. 对 Messaging Gateway 的理解

学习完 Messaging Gateway 后，我对 Hermes Agent 的整体形态有了更完整的认识。

前面几期讲的能力主要是 Agent 本体能力：

复制代码

Tools 让 Agent 能做事；
Memory 让 Agent 能记住背景；
Skills 让 Agent 能沉淀经验；
CLI/TUI 让 Agent 进入终端工作流。

而 Messaging Gateway 解决的是另一个问题：

复制代码

用户如何随时随地触达这个 Agent？

这看似只是交互入口变化，但实际上会改变 Agent 的使用方式。

当 Hermes 只在 CLI 中运行时，它更像开发者工具。

当 Hermes 接入 Telegram、Slack、Email 后，它更像一个长期在线的个人助手或团队助手。

当它再结合 cron、background task、memory、skills 和 tools，它就具备了长期自动化工作流的雏形。

所以，Messaging Gateway 不是附属功能，而是 Hermes 从"本地 Agent"走向"长期在线 Agent"的关键模块。

23. 小结

这一期主要学习了 Hermes Agent 的 Messaging Gateway。

我的理解是，Messaging Gateway 的核心作用是把 Hermes 接入外部消息平台，让用户可以通过 Telegram、Discord、Slack、Email 等入口与同一个 Agent 交互。它负责平台适配、消息收发、会话管理、cron 投递、后台任务结果返回和访问控制。

它让 Hermes 不再只是终端里的工具，而是可以长期运行在服务器上，通过用户熟悉的消息平台提供服务。

但 Gateway 也带来了更高的安全要求。因为一旦 Agent 暴露到外部平台，就必须认真配置 allowlist、DM pairing、admin 权限、平台 toolset 和日志监控。尤其是当 Agent 拥有终端和文件工具时，不能把它当成普通聊天机器人随便开放。

下一期，我将继续学习 Hermes Agent 的 Cron 定时任务系统，看看 Hermes 如何从"被动响应用户消息"进一步变成"按计划主动执行任务"的长期自动化 Agent。