---
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="/zh-Hant/docs/hermes/understanding/08-automation-boundaries" />
  <Card title="訊息閘道器原理" description="繼續理解 Gateway、session、allowlist 和工具許可權如何組合——以及遠端控制 agent 與聊天機器人這兩種心智錨點的差異。" href="/zh-Hant/docs/hermes/understanding/07-messaging-gateway" />
</Cards>
