消息网关

通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles（iMessage）、QQ、Yuanbao、Microsoft Teams、LINE、ntfy 或浏览器与 Hermes 对话。网关是一个单一后台进程，连接所有已配置的平台，管理会话，运行 cron 任务，并传递语音消息。

完整的语音功能集——包括 CLI 麦克风模式、消息中的语音回复以及 Discord 语音频道对话——请参阅 Voice Mode 和 Use Voice Mode with Hermes。

平台对比

平台	语音	图片	文件	线程	表情反应	输入提示	流式输出
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
Google Chat	—	✅	✅	✅	—	✅	—
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
SMS	—	—	—	—	—	—	—
Email	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	✅	✅	✅
DingTalk	—	✅	✅	—	✅	—	✅
Feishu/Lark	✅	✅	✅	✅	✅	✅	✅
WeCom	✅	✅	✅	—	—	✅	✅
WeCom Callback	—	—	—	—	—	—	—
Weixin	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—
QQ	✅	✅	✅	—	—	✅	—
Yuanbao	✅	✅	✅	—	—	✅	✅
Microsoft Teams	—	✅	—	✅	—	✅	—
LINE	—	✅	✅	—	—	✅	—
ntfy	—	—	—	—	—	—	—

语音 = TTS 音频回复和/或语音消息转录。图片 = 发送/接收图片。文件 = 发送/接收文件附件。线程 = 线程式对话。表情反应 = 对消息添加 emoji 反应。输入提示 = 处理时显示正在输入状态。流式输出 = 通过编辑消息实现渐进式更新。

架构

每个平台适配器接收消息，通过每个聊天的会话存储进行路由，并将其分发给 AIAgent 处理。网关还运行 cron 调度器，每 60 秒触发一次以执行到期任务。

快速配置

配置消息平台最简单的方式是使用交互式向导：

该向导引导你通过方向键选择配置各平台，显示哪些平台已配置，并在完成后提示启动/重启网关。

网关命令

聊天命令（在消息平台内使用）

命令	说明
`/new` 或 `/reset`	开始新对话
`/model [provider:model]`	显示或切换模型（支持 `provider:model` 语法）
`/personality [name]`	设置人格
`/retry`	重试上一条消息
`/undo`	删除上一轮对话
`/status`	显示会话信息
`/whoami`	显示你在当前范围内的斜杠命令权限（管理员 / 普通用户 / 无限制）
`/stop`	停止正在运行的 agent
`/approve`	批准待执行的危险命令
`/deny`	拒绝待执行的危险命令
`/sethome`	将此聊天设为主频道
`/compress`	手动压缩对话上下文
`/title [name]`	设置或显示会话标题
`/resume [name]`	恢复之前命名的会话
`/usage`	显示本会话的 token 用量
`/insights [days]`	显示用量洞察与分析
`/reasoning [level\|show\|hide]`	更改推理强度或切换推理显示
`/voice [on\|off\|tts\|join\|leave\|status]`	控制消息语音回复和 Discord 语音频道行为
`/rollback [number]`	列出或恢复文件系统检查点
`/background <prompt>`	在独立后台会话中运行 prompt（提示词）
`/reload-mcp`	从配置重新加载 MCP 服务器
`/update`	将 Hermes Agent 更新至最新版本
`/help`	显示可用命令
`/<skill-name>`	调用任意已安装的技能

会话管理

会话持久化

会话在消息之间持续保留，直到重置。Agent 会记住你的对话上下文。

重置策略

会话根据可配置的策略重置：

策略	默认值	说明
每日	凌晨 4:00	每天在指定时间重置
空闲	1440 分钟	空闲 N 分钟后重置
两者	（组合）	以先触发者为准

在 ~/.hermes/gateway.json 中配置各平台的覆盖设置：

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

安全

默认情况下，网关拒绝所有不在白名单中或未通过私信配对的用户。 这是具有终端访问权限的机器人的安全默认设置。

私信配对（白名单的替代方案）

无需手动配置用户 ID，未知用户私信机器人时会收到一次性配对码：

配对码 1 小时后过期，有频率限制，并使用密码学随机数生成。

管理员与普通用户

白名单解决的是"此人能否访问机器人"的问题。管理员 / 普通用户的划分解决的是"既然已经进来了，他们被允许做什么"的问题。

每个允许的用户在每个范围（私信 vs 群组/频道）内属于以下两个层级之一：

管理员 — 完全访问权限。可运行所有已注册的斜杠命令（内置 + 插件）并使用所有受限功能。

普通用户 — 受限访问权限。可正常与 agent 聊天，但只能运行你明确启用的斜杠命令。始终允许的最低权限为 /help 和 /whoami。

层级按平台和范围分别配置。私信管理员身份不意味着群组/频道管理员身份——每个范围有各自的管理员列表。

当前层级控制的内容： 斜杠命令。该划分贯穿实时命令注册表，因此无需逐功能配置即可覆盖内置命令和插件注册的命令。普通聊天不受影响——非管理员仍可与 agent 对话。

未来可能受控的内容： 更多功能面（工具访问、模型切换、高消耗操作）将随着我们的添加挂载到同一管理员 / 普通用户区分上。现在配置好划分，意味着未来的限制可以干净落地，无需重新规划谁是管理员。

配置

向后兼容： 如果某个范围未设置 allow_admin_from，则该范围的层级划分被禁用，所有允许的用户拥有完全访问权限。现有安装无需任何更改即可继续工作——需要区分时再选择启用。

查看你的权限

在任意平台使用 /whoami 查看当前范围、你的层级（管理员 / 普通用户 / 无限制）以及你可以运行的斜杠命令。平台特定示例请参阅 Telegram 和 Discord 页面。

中断 Agent

在 agent 工作时发送任意消息即可中断它。关键行为：

正在执行的终端命令立即终止（SIGTERM，1 秒后 SIGKILL）

工具调用被取消 — 仅当前正在执行的工具调用会运行，其余跳过

多条消息合并 — 中断期间发送的消息合并为一个 prompt

/stop 命令 — 中断而不排队后续消息

队列 vs 中断 vs 引导（繁忙输入模式）

默认情况下，向繁忙的 agent 发送消息会中断它。另有两种模式可用：

queue — 后续消息等待，在当前任务完成后作为下一轮运行。

steer — 后续消息通过 /steer 注入当前运行，在下一次工具调用后到达 agent。不中断，不开新轮次。如果 agent 尚未开始，则回退为 queue 行为。

第一次在任意平台向繁忙的 agent 发送消息时，Hermes 会在繁忙确认中附加一行提示，说明该配置项（"💡 First-time tip — …"）。该提示每次安装只触发一次——由 onboarding.seen.busy_input_prompt 下的标志锁定。删除该键可再次看到提示。

如果你觉得繁忙确认消息过多——尤其是使用语音输入或快速连续发送消息时——可设置 display.busy_ack_enabled: false。你的输入仍会正常排队/引导/中断，只是聊天回复被静默。

工具进度通知

在 ~/.hermes/config.yaml 中控制显示多少工具活动信息：

启用后，机器人在工作时发送状态消息：

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

后台会话

在独立的后台会话中运行 prompt，让 agent 独立处理，同时保持主聊天响应：

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

Hermes 立即确认：

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

工作原理

每个 /background prompt 会生成一个独立的 agent 实例异步运行：

隔离会话 — 后台 agent 拥有自己的会话和对话历史。它不了解你当前的聊天上下文，只接收你提供的 prompt。

相同配置 — 继承当前网关配置中的模型、提供商、工具集、推理设置和提供商路由。

非阻塞 — 你的主聊天保持完全交互。在后台任务运行期间，你可以发送消息、运行其他命令或启动更多后台任务。

结果传递 — 任务完成后，结果发送回发出命令的同一聊天或频道，前缀为"✅ Background task complete"。如果失败，你会看到"❌ Background task failed"及错误信息。

后台进程通知

当运行后台会话的 agent 使用 terminal(background=true) 启动长时间运行的进程（服务器、构建等）时，网关可以向你的聊天推送状态更新。通过 ~/.hermes/config.yaml 中的 display.background_process_notifications 控制：

模式	你收到的内容
`all`	运行输出更新以及最终完成消息（默认）
`result`	仅最终完成消息（无论退出码）
`error`	仅在退出码非零时的最终消息
`off`	不接收任何进程监控消息

也可通过环境变量设置：

使用场景

服务器监控 — "/background Check the health of all services and alert me if anything is down"

长时间构建 — "/background Build and deploy the staging environment"，同时继续聊天

研究任务 — "/background Research competitor pricing and summarize in a table"

文件操作 — "/background Organize the photos in ~/Downloads by date into folders"

提示

消息平台上的后台任务是即发即忘的——你无需等待或主动查询。任务完成后，结果会自动出现在同一聊天中。

服务管理

Linux（systemd）

笔记本和开发机使用用户服务。VPS 或无头主机（需要开机自动启动而不依赖 systemd linger）使用系统服务。

除非你确实有此需要，否则避免同时安装用户和系统网关单元。Hermes 检测到两者同时存在时会发出警告，因为 start/stop/status 行为会变得不明确。

多个安装

如果你在同一台机器上运行多个 Hermes 安装（使用不同的 HERMES_HOME 目录），每个安装都有自己的 systemd 服务名称。默认的 ~/.hermes 使用 hermes-gateway；其他安装使用 hermes-gateway-<hash>。hermes gateway 命令会自动针对当前 HERMES_HOME 对应的正确服务。

macOS（launchd）

生成的 plist 文件位于 ~/Library/LaunchAgents/ai.hermes.gateway.plist。它包含三个环境变量：

PATH — 安装时你的完整 shell PATH，并在前面添加了 venv bin/ 和 node_modules/.bin。这确保用户安装的工具（Node.js、ffmpeg 等）可供网关子进程（如 WhatsApp 桥接）使用。

VIRTUAL_ENV — 指向 Python 虚拟环境，使工具能正确解析包。

HERMES_HOME — 将网关限定到你的 Hermes 安装。

安装后 PATH 变更

launchd plist 是静态的——如果你在配置网关后安装了新工具（例如通过 nvm 安装新版 Node.js，或通过 Homebrew 安装 ffmpeg），请重新运行 hermes gateway install 以捕获更新后的 PATH。网关会检测到过时的 plist 并自动重新加载。

多个安装

与 Linux systemd 服务类似，每个 HERMES_HOME 目录都有自己的 launchd 标签。默认的 ~/.hermes 使用 ai.hermes.gateway；其他安装使用 ai.hermes.gateway-<suffix>。

平台专属工具集

每个平台有自己的工具集：

平台	工具集	功能
CLI	`hermes-cli`	完全访问
Telegram	`hermes-telegram`	完整工具，包括终端
Discord	`hermes-discord`	完整工具，包括终端
WhatsApp	`hermes-whatsapp`	完整工具，包括终端
Slack	`hermes-slack`	完整工具，包括终端
Google Chat	`hermes-google_chat`	完整工具，包括终端
Signal	`hermes-signal`	完整工具，包括终端
SMS	`hermes-sms`	完整工具，包括终端
Email	`hermes-email`	完整工具，包括终端
Home Assistant	`hermes-homeassistant`	完整工具 + HA 设备控制（ha_list_entities、ha_get_state、ha_call_service、ha_list_services）
Mattermost	`hermes-mattermost`	完整工具，包括终端
Matrix	`hermes-matrix`	完整工具，包括终端
DingTalk	`hermes-dingtalk`	完整工具，包括终端
Feishu/Lark	`hermes-feishu`	完整工具，包括终端
WeCom	`hermes-wecom`	完整工具，包括终端
WeCom Callback	`hermes-wecom-callback`	完整工具，包括终端
Weixin	`hermes-weixin`	完整工具，包括终端
BlueBubbles	`hermes-bluebubbles`	完整工具，包括终端
QQBot	`hermes-qqbot`	完整工具，包括终端
Yuanbao	`hermes-yuanbao`	完整工具，包括终端
Microsoft Teams	`hermes-teams`	完整工具，包括终端
API Server	`hermes-api-server`	完整工具（去除 `clarify`、`send_message`、`text_to_speech`——程序化访问没有交互用户）
Webhooks	`hermes-webhook`	完整工具，包括终端

运营多平台网关

网关通常同时运行多个适配器（Telegram + Discord + Slack 等）。以下章节涵盖跨所有平台的日常运维操作。

`/platform` 命令

网关运行后，可从任意已连接的 CLI 会话或聊天使用 /platform 斜杠命令检查和控制单个适配器，无需重启整个网关：

/platform list                  # 显示所有适配器及其状态
/platform pause <name>          # 停止向某个适配器分发新消息
/platform resume <name>         # 重新启用已暂停的适配器

/platform list 显示每个适配器是 running（运行中）、paused（手动暂停）还是 paused-by-breaker（见下文）。暂停会保持适配器加载状态及其后台循环——传入消息被丢弃，但连接本身保持开启，因此恢复是即时的。

另请参阅更广泛的状态汇总命令 /platforms。

自动熔断器

每个适配器都包裹在熔断器中。反复出现的可重试失败（网络抖动、限流回复、上游 5xx 响应、websocket 断开）会导致熔断器触发——适配器被自动暂停，当配置了主频道时向另一个存活平台的主频道发送运营通知，并输出结构化日志行。

熔断器不会自动恢复——它保持断开状态，直到你手动运行 /platform resume <name>。这是有意为之：如果某个平台持续故障，你不希望网关不断重试重连。

适配器暂停时的排查步骤

当适配器暂停时，检查：

网关日志（~/.hermes/logs/gateway.log 或 systemd / launchd 单元日志）。搜索平台名称以及 circuit breaker、paused 或 disabled。触发事件包含失败次数和最后一个错误。

/platform list 输出——显示当前状态和最后原因。

提供商状态页面（Telegram bot API 状态、Discord 状态等）。熔断器触发是因为平台不健康；在平台恢复之前不要尝试恢复。

上游恢复正常后，/platform resume <name> 清除熔断器并重新激活适配器。

重启通知

当网关重启（或在有进行中会话时关闭）时，它可以向每个平台的主频道发送一条"agent 已恢复"/"agent 被中断"的一次性消息。这由 gateway-config.yaml 中每个平台的 gateway_restart_notification 标志控制，默认为 true：

在嘈杂或低优先级的平台上禁用，同时在主要聊天上保持启用。无论有多少会话正在进行，每次重启只发送一次通知。

网关重启后的会话恢复

当网关在工具调用或生成进行中时关闭，受影响的会话被标记为 restart_interrupted。下次启动时，网关为每个会话安排自动恢复——用户在聊天中收到简短提示（"Send any message after restart and I'll try to resume where you left off."），当他们回复时，会话从最后提交的轮次继续。

此行为默认开启，并在网关启动时记录日志：

Scheduled auto-resume for N restart-interrupted session(s)

无需配置。如果你不想要提示消息，在该平台上设置 gateway_restart_notification: false。

进度气泡清理（可选启用）

工具进度消息、"仍在处理中……"心跳以及状态回调气泡可在最终响应落地后自动删除。通过 display.platforms.<platform>.cleanup_progress 按平台启用：

默认为 false。仅实现了 delete_message 的适配器平台支持此设置（目前为 Telegram 和 Discord）。运行失败时跳过清理，气泡保留作为调试线索。

后续步骤

BlueBubbles 配置（iMessage）

Open WebUI + API Server

Webhooks

"消息网关"

消息网关#

平台对比#

架构#

快速配置#

网关命令#

聊天命令（在消息平台内使用）#

会话管理#

会话持久化#

重置策略#

安全#

私信配对（白名单的替代方案）#

管理员与普通用户#

配置#

查看你的权限#

中断 Agent#

队列 vs 中断 vs 引导（繁忙输入模式）#

工具进度通知#

后台会话#

工作原理#

后台进程通知#

使用场景#

服务管理#

Linux（systemd）#

macOS（launchd）#

平台专属工具集#

运营多平台网关#

/platform 命令#

自动熔断器#

适配器暂停时的排查步骤#

重启通知#

网关重启后的会话恢复#

进度气泡清理（可选启用）#

后续步骤#

消息网关

平台对比

架构

快速配置

网关命令

聊天命令（在消息平台内使用）

会话管理

会话持久化

重置策略

安全

私信配对（白名单的替代方案）

管理员与普通用户

配置

查看你的权限

中断 Agent

队列 vs 中断 vs 引导（繁忙输入模式）

工具进度通知

后台会话

工作原理

后台进程通知

使用场景

服务管理

Linux（systemd）

macOS（launchd）

平台专属工具集

运营多平台网关

`/platform` 命令

自动熔断器

适配器暂停时的排查步骤

重启通知

网关重启后的会话恢复

进度气泡清理（可选启用）

后续步骤