08. Gateway 与多平台使用

Hermes 不一定非要待在终端里。Gateway 让它可以生活在 Telegram、Discord、Slack、WhatsApp、Signal 等消息平台中。

本章目标

• 理解 Gateway 的角色
• 学会启动和管理 Gateway
• 理解 allowlist、home channel、平台会话的基本规则
• 区分 CLI 和消息平台的能力差异

适用读者

• 想远程使用 Hermes 的用户
• 想把 Hermes 长期部署在服务器上的用户
• 需要团队共享 agent 接口的部署者

前置条件

• 已完成基础安装
• 已有至少一个可用模型
• 对应平台的 bot 凭据或接入条件已准备好

核心概念

Gateway 是“消息入口层”

它把 Telegram、Discord、Slack 等平台的消息统一转换成 Hermes 会话事件，再交给 AIAgent 处理。也就是说，CLI 和 Gateway 最终共享的是同一套 agent 核心，只是入口不同。

Home channel 是“主动送达”的落点

Cron 结果、后台任务通知、主动消息推送都需要一个默认送达位置。这个位置通常通过 /sethome 指定。

授权控制非常重要

一旦 Gateway 接上 terminal 类能力，你就必须严肃对待 allowlist 和 pairing。不要把“公开 bot”当成默认模式。

操作步骤

启动 gateway 配置

先执行：

hermes gateway setup

然后再用这些命令管理 gateway：

hermes gateway run
hermes gateway start
hermes gateway stop
hermes gateway status

配置平台凭据

不同平台的变量不同，常见例子：

• TELEGRAM_BOT_TOKEN
• DISCORD_BOT_TOKEN
• SLACK_BOT_TOKEN
• SLACK_APP_TOKEN

通常都放在 ~/.hermes/.env 中。

配置 allowlist

非常建议显式限制允许访问的用户，例如：

• TELEGRAM_ALLOWED_USERS
• DISCORD_ALLOWED_USERS
• GATEWAY_ALLOWED_USERS

不要轻易打开 GATEWAY_ALLOW_ALL_USERS=true。

设置 home channel

进入对应平台会话后：

/sethome

这样后续 cron 和后台任务结果才知道发到哪里。

理解消息平台常用命令

消息平台里最常用的是：

• /new
• /status
• /model
• /personality
• /retry
• /undo
• /sethome
• /compress
• /title
• /resume
• /usage
• /reload-mcp
• /background

注意：/tools、/toolsets、/browser、/config 这类通常是 CLI-only。

常见场景

场景 1：Telegram 上的个人远程助手

这是最常见组合。你在服务器上跑 Hermes gateway，然后随时在手机上给它发任务。

场景 2：Discord 团队机器人

更适合团队协作，但必须把授权策略、是否要求 mention、线程行为等配置清楚。

场景 3：多平台并存

Hermes 支持多平台共存，但这通常意味着你需要更认真地设计：

• 哪个平台面向谁
• 哪些平台允许主动通知
• 哪些平台需要严格 allowlist

常见问题与排错

bot 在线但不回消息

优先检查：

1. token 是否正确
2. allowlist 是否包含当前用户
3. 平台是否要求 mention
4. gateway 服务是否真的在运行

cron 没收到结果

优先检查 home channel 是否设置，以及对应平台的投递目标是否可用。

消息平台能不能完全替代 CLI

不建议。Gateway 更适合日常交互和远程控制；复杂调试、工具观察、配置修复仍然更适合 CLI。

本章总结

Gateway 让 Hermes 从“本地终端助手”变成“长期在线代理”。但也正因为如此，授权、送达目标和平台行为差异必须处理清楚。

下一步建议

继续看 定时任务、后台进程与自动化，把 Hermes 从“被动响应”推进到“主动执行”。