07 · 消息网关 · AI 编程教程中文版

Hermes Gateway（消息网关）是把 Hermes 接到消息平台的后台进程。它接收平台消息，维护 chat session（聊天会话），调用 agent，运行 cron scheduler（定时调度器），再把结果发回原平台。从架构上看，它把"本机 CLI 工具"变成了"互联网上常驻的远程服务"——这个跨度比想象的大。

官方资料：Messaging Gateway、Gateway Internals、Sessions、Security。

先给结论：Gateway 会把 Hermes 从"本机终端工具"变成"远程常驻服务"。上线前必须先跑稳 CLI、收敛 toolsets、配置 **allowlist（允许名单）**或 DM pairing（私聊配对），并区分 DM（私聊）、群聊和 background session（后台会话）的权限——三类场景的风险不一样。

Gateway 改变了什么

CLI 需要你坐在终端前才能用。Gateway 让你可以从手机、群聊、邮件、Home Assistant、Webhook 或 API frontend 调用 Hermes——人在地铁、Hermes 还在你 VPS 上做事。

flowchart LR
    subgraph Platforms["消息平台<br/>Telegram / Discord / Slack / 邮件 / ..."]
        U["用户消息"]
    end
    subgraph GW["Hermes Gateway 后台进程"]
        AC["allowlist / DM pairing<br/>访问控制"]
        SS["chat session 路由"]
        AG["agent 调用<br/>(toolsets + backend)"]
        CR["cron scheduler<br/>定时任务"]
    end
    Platforms --> AC --> SS --> AG --> Platforms
    CR --> AG

注意箭头方向：消息进 Gateway 之前必须先过 access control（访问控制）；Gateway 没配好 allowlist 就上线 = 任意陌生人可命令你的本机或 VPS。

适合：

远程跟进任务。
群组内低风险问答和总结。
定时报告投递。
服务器巡检结果回传。
通过 /background 发起异步任务。

不适合默认开放：

高权限 shell。
生产发布。
删除或迁移数据。
读取敏感文件。
无审查外发消息。

方便性提升的同时，风险也放大。

接入前检查

接消息平台前先确认：

普通 CLI 对话稳定。
hermes --continue 能恢复 session。
Toolsets 已按任务收敛。
Terminal backend 边界清楚。
Allowlist 或 DM pairing 已配置。
Bot token、邮箱密码、webhook secret 按凭据处理。
/stop、/reset、/status 的操作路径清楚。

这些没完成之前，不要上线消息入口。

平台入口不是等价的

官方支持的平台很多：Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、QQ、Yuanbao、Microsoft Teams、Webhooks、API Server 等。

但平台能力不同：

有的平台支持线程，有的不支持。
有的平台支持图片/文件，有的不支持。
有的平台支持 typing/streaming，有的不支持。
群聊和 DM 的风险完全不同。
语音、文件、图片会引入额外处理和隐私边界。

不要一次接很多平台。先接一个可控入口，验证权限、session、停止和日志，再扩展。

Chat session

每个 chat 都会维护自己的 session。这个设计让多轮对话可持续，也带来两个问题：

旧上下文可能影响新任务。
群聊上下文比 DM 更不可控。

因此要明确 reset 策略：

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

个人 DM 可以更长；团队频道应该更短、更容易 reset；公开或半公开群不要给宽权限。

Allowlist 与 DM pairing

Gateway 默认拒绝未 allowlist 或未配对的用户，这是正确默认值。

Allowlist 适合固定用户：

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
EMAIL_ALLOWED_USERS=[email protected]

DM pairing 适合临时批准用户：

hermes pairing list
hermes pairing approve telegram XKGH5N7P
hermes pairing revoke telegram 123456789

GATEWAY_ALLOW_ALL_USERS=true 不适合有 terminal、file、browser、MCP 写入能力的 bot。

聊天内命令

消息平台里的 slash command 可以重置会话、切模型、停止任务、查看状态、运行后台任务、调用 skill、重新加载 MCP、处理危险命令审批。

这意味着消息平台用户不是只能聊天，而是在远程控制一个带工具能力的 agent。

群聊入口必须更保守。能在 DM 里安全的能力，不一定适合群里。

Busy input · agent 忙碌时新消息怎么处理

Agent 忙碌（正在跑长任务、等工具响应）时收到新消息，三种官方策略：

策略	行为	何时用
interrupt（默认）	立即打断当前任务，处理新消息	个人用、消息确实是要"停下" 当前任务的指令
queue	等当前任务结束后排队执行新消息	团队入口、多人发指令但不希望相互干扰
steer	把新消息注入当前运行过程，等下一次 tool call 后生效（"让正在跑的任务知道你想加这条信息"）	长任务过程中追加约束（比如"不要碰 prod 表"），但不打断任务

团队入口要统一这个策略——否则有人以为自己在"补充信息"，实际却中断了长任务（默认 interrupt）；另一个人以为自己在"停止任务"，实际只是排队了下一条（queue）。同一个 chat 不同人对策略期待不同，会演变成长期沟通成本。

Background session

长任务更适合 background session。比如检查服务器、研究资料、跟进 PR、生成报告。

/background Run the test suite and summarize failures. Do not modify files.

它会让主聊天保持响应，并在任务完成后把结果发回原 chat。

边界必须写清：

任务范围。
允许工具。
是否允许写文件。
停止条件。
报告格式。
失败时怎么通知。

不要把高风险命令、发布动作、删除动作或数据库迁移放进 background。

验收清单

Gateway 上线前必须能证明下面 7 项。任何一项答不上来，先关掉 Gateway 修对再开：

当前 Gateway 接了哪些平台？（hermes gateway status）
只有 allowlist 或 paired users 能发任务？（用未授权账号发消息验证被拒）
/status、/stop、/reset 命令能工作？（在不同 chat 里都试一遍）
同一个 chat 的 session 能持续，也能按需要 reset？
一个 background session 能完成低风险任务并返回正确 chat？
群聊和 DM 的 toolsets 或审批策略不同？（防止群里有外部账号但配置和 DM 一样宽）
Gateway 停止后平台入口不再执行任务？（kill 进程后用户发消息应得不到回复，而不是"还在排队"）

官方资料

Messaging Gateway（接入总览 + 各平台子页）
Gateway Internals（路由、授权、session 调度细节）
Sessions（chat session 与 CLI session 共用机制）
Security（授权、审批、容器隔离）

07 · 消息网关