---
title: "07 · 消息网关"
description: "理解 Hermes Gateway、平台入口、chat session、allowlist、DM pairing、slash commands、busy input 和 background session 的关系。"
verifiedAt: "2026-05-09"
---

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

官方资料：[Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)、[Gateway Internals](https://hermes-agent.nousresearch.com/docs/developer-guide/gateway-internals)、[Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)、[Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)。

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

## Gateway 改变了什么

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

```mermaid
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。
- 生产发布。
- 删除或迁移数据。
- 读取敏感文件。
- 无审查外发消息。

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

## 接入前检查

接消息平台前先确认：

1. 普通 CLI 对话稳定。
2. `hermes --continue` 能恢复 session。
3. Toolsets 已按任务收敛。
4. Terminal backend 边界清楚。
5. Allowlist 或 DM pairing 已配置。
6. Bot token、邮箱密码、webhook secret 按凭据处理。
7. `/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 策略：

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

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

## Allowlist 与 DM pairing

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

Allowlist 适合固定用户：

```bash
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
EMAIL_ALLOWED_USERS=trusted@example.com
```

DM pairing 适合临时批准用户：

```bash
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、生成报告。

```text
/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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)（接入总览 + 各平台子页）
- [Gateway Internals](https://hermes-agent.nousresearch.com/docs/developer-guide/gateway-internals)（路由、授权、session 调度细节）
- [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)（chat session 与 CLI session 共用机制）
- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)（授权、审批、容器隔离）

## 下一步

<Cards>
  <Card title="自动化边界" description="Gateway 稳定后，再看 cron、background 和 delegation 的安全边界——它们叠在 Gateway 上会进一步放大权限面。" href="/docs/hermes/understanding/08-automation-boundaries" />
  <Card title="消息网关手册" description="需要具体平台接入步骤（Telegram bot token / Discord webhook 等），查官方教程中文版。" href="/docs/hermes/official/01-user-guide/messaging" />
</Cards>
