---
title: "接入消息网关和平台"
description: "理解 Hermes Messaging Gateway 的平台接入、session、allowlist、DM pairing、聊天命令、background session 和安全边界。"
verifiedAt: "2026-05-09"
---

Gateway（消息网关）会把 Hermes **从终端工具变成常驻远程入口**。只要 Agent 有 terminal、file、browser、MCP、cron 或 send_message 权限，消息平台用户就可能**远程触发真实动作**——一条消息可能等价于一条 shell 命令。这页讲怎么把这件事做对。

官方资料：[Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)、[Voice Mode](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)、[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)、[Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)。

> [!NOTE]
> **先给结论**：CLI 基础对话和 `hermes --continue` session 恢复没稳定前**不要**接 Gateway；上线前**必须**配置 allowlist（允许名单）或 DM pairing（私聊配对）；群聊和 background session 要比本地 CLI **更保守**——三类入口的人群不同，工具权限也应该不同。

## Gateway 做什么

Hermes Gateway 是一个后台进程，负责：

- 接收 Telegram、Discord、Slack、WhatsApp、Signal、Email 等平台消息。
- 为每个 chat 维护 session。
- 把消息送入 AIAgent。
- 运行 cron scheduler。
- 处理 voice message、file、image、thread、typing、streaming 等平台能力差异。
- 把结果发回原平台。

这不是“换个聊天界面”。它是带权限的远程控制入口。

## 支持的平台

官方文档列出的 Gateway 入口覆盖很多平台：

<Cards>
  <Card title="主流聊天" description="Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email。" />
  <Card title="团队与社区" description="Mattermost、Matrix、Microsoft Teams、Webhooks。" />
  <Card title="中国常用平台" description="DingTalk、Feishu/Lark、WeCom、Weixin、QQ、Yuanbao。" />
  <Card title="自动化和家庭场景" description="Home Assistant、API Server、browser/web frontend 等入口。" />
</Cards>

不要一次接很多平台。先接一个最可控的平台，跑通 allowlist、`/status`、`/stop`、`/reset` 和低风险 background task，再复制到其他平台。

## 快速设置

```bash
hermes gateway setup
```

常用命令：

```bash
hermes gateway              # 前台运行
hermes gateway setup        # 交互配置平台
hermes gateway install      # 安装用户服务
hermes gateway start
hermes gateway stop
hermes gateway status
```

Linux system service 需要额外确认权限边界。不要因为能 `sudo hermes gateway install --system` 就默认这样部署。

## 安全默认值

Gateway 默认拒绝不在 allowlist、也没有通过 DM pairing 的用户。这是正确默认值，因为 bot 背后可能有 terminal 权限。

示例：

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

`GATEWAY_ALLOW_ALL_USERS=true` 不建议用于任何有 terminal、file、browser 或 MCP 写入能力的 bot。开放入口加高权限工具，是最危险组合。

## DM pairing

如果不想手动收集 user id，可以用 DM pairing。未知用户私聊 bot 时拿到一次性 pairing code，管理员本地批准：

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

pairing code 有过期时间、速率限制和随机性，但它不是权限审计替代品。批准前仍要确认用户是谁、应该拿到哪些平台和工具权限。

## 聊天内命令（slash commands）

消息平台里可以执行很多 slash command（按官方 [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) 当前列表为准；具体清单跟 toolset 和已装 skill 联动）：

- `/new`、`/reset`：开新会话或重置当前会话。
- `/model`：查看或切换模型。
- `/retry`、`/undo`：重试上一条或撤销。
- `/status`：查看当前 session 状态（任务进度、上下文用量等）。
- `/stop`：停止当前正在跑的任务（重要——有问题第一时间用这个）。
- `/approve`、`/deny`：处理危险命令审批（terminal 工具产生的高风险动作弹窗）。
- `/compress`、`/usage`、`/insights`：压缩历史、查看用量、得到行为洞察。
- `/background <prompt>`：启动独立后台任务，主聊天保持响应。
- `/reload-mcp`：重新加载 MCP server 配置。
- `/<skill-name>`：直接调用某个 skill。

这意味着消息平台用户**不是"只能聊天"**——他们在**远程控制一个有工具、session 和后台任务能力的 agent**。这个心智锚点 mismatch 是大部分 Gateway 安全事故的根源：用户和管理员都默认把它当聊天机器人来管。

## Busy input：interrupt、queue、steer

默认情况下，agent 忙碌时收到新消息会 interrupt 当前任务。官方还提供两种模式：

- `queue`：当前任务结束后再运行下一条。
- `steer`：把跟进消息注入当前运行过程，等待下一次 tool call 后生效。

配置示例：

```yaml
display:
  busy_input_mode: steer
  busy_ack_enabled: true
```

如果用户会连续发语音或碎片消息，默认 interrupt 可能导致任务频繁中断；但 queue/steer 也可能让上下文更难追踪。团队入口要统一选择一种模式。

## Background session

`/background` 会启动独立 agent instance：

```text
/background Check all servers in the cluster and report any that are down
```

关键边界：

- 背景任务有自己的 session。
- 它继承当前 gateway 的 provider、toolsets、reasoning 和路由配置。
- 主 chat 保持可交互。
- 结果回到发起任务的同一个 chat/channel。
- background session 不知道你当前 chat 的完整上下文，只接收 prompt。

适合 background 的任务：巡检、报告、研究、低风险批处理。不要把生产发布、删除数据、数据库迁移、权限变更直接后台化。

## Session reset

Gateway session 会按策略重置，例如按每日固定时间或 idle minutes。团队使用时要明确 reset 策略，否则旧上下文可能影响新任务。

示例：

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

长任务要有标题、状态和恢复方式；短任务要能 `/reset` 清理上下文。

## 上线验收

上线前确认：

- CLI 本地 `hermes` 和 `hermes --continue` 已稳定。
- Gateway 只接入必要平台。
- allowlist 或 DM pairing 已启用。
- Bot token 没有进入仓库、截图、日志或群聊。
- `/status`、`/stop`、`/reset` 能工作。
- 低风险 `/background` 能完成并回到正确 chat。
- 群聊和 DM 使用不同 toolsets 或审批策略。
- 停止 Gateway 后平台入口不再接收任务。

## 常见坑

按事故频率从高到低：

- **CLI 还不稳定就接 Gateway** —— 故障来源至少多两层（平台 + Gateway 进程），定位时间指数增长
- **allowlist 没设就上线** —— 任何人发消息都能命令你的机器；最坏情况一晚上被滥用到限流封号
- **Bot token 写进仓库或截图** —— GitHub 推送扫描会泄露，截图分享到群里也跑不掉
- **群聊和 DM 共用一套宽权限** —— 群里人员变动，没及时收权限就出事
- **不知道 reset 策略，旧上下文污染新任务** —— 一个用户 4 小时前的危险任务影响下一次问候
- **background 任务没有范围、停止条件和输出格式** —— 后台跑成无限循环，等用户回来才发现 token 烧完
- **把 `/approve` 当成形式流程，没看清实际命令** —— 高风险审批要逐条人脑审，不是机械点 yes

## 官方资料

- [Messaging Gateway 总览 + 各平台子页](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway Internals](https://hermes-agent.nousresearch.com/docs/developer-guide/gateway-internals)（路由 / 授权 / session 调度）
- [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)（完整命令列表）
- [Voice Mode](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)
- [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)
- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)（命令审批、用户授权、容器隔离）

## 下一步

<Cards>
  <Card title="自动化边界" description="接入消息平台后，再看 cron、background 和 delegation 的边界——它们叠加在 Gateway 上风险面会再放大一层。" href="/docs/hermes/understanding/08-automation-boundaries" />
  <Card title="消息网关原理" description="继续理解 Gateway、session、allowlist 和工具权限如何组合——以及远程控制 agent 与聊天机器人这两种心智锚点的差异。" href="/docs/hermes/understanding/07-messaging-gateway" />
</Cards>
