hermes教程-消息网关

通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、钉钉、飞书/Lark、企业微信、微信、BlueBubbles（iMessage）、QQ、元宝、Microsoft Teams、LINE、ntfy 或浏览器与 Hermes 聊天。网关是一个单一的后台进程，连接到所有已配置的平台，处理会话，运行定时任务，并传递语音消息。

有关完整的语音功能集——包括 CLI 麦克风模式、消息中的语音回复以及 Discord 语音频道对话——请参阅语音模式和将语音模式与 Hermes 结合使用。

提示

机器人需要模型提供者和工具提供者（TTS、Web）。Nous Portal 订阅捆绑了所有这些。

平台对比

语音 = TTS 音频回复和/或语音消息转录。图片 = 发送/接收图片。文件 = 发送/接收文件附件。线程 = 线程化对话。反应 = 消息上的表情反应。输入指示 = 处理时显示输入指示。流式 = 通过编辑逐步更新消息。

架构

flowchart TB
    subgraph Gateway["Hermes 网关"]
        subgraph Adapters["平台适配器"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[钉钉]
    fs[飞书/Lark]
    wc[企业微信]
    wcb[企业微信回调]
    wx[微信]
    bb[BlueBubbles]
    qq[QQ]
    yb[元宝]
    ms[Microsoft Teams]
    api["API 服务器<br/>(兼容 OpenAI)"]
    wh[Webhooks]
        end

        store["会话存储<br/>每个聊天"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron 调度器<br/>每 60 秒触发"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

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

静默令牌

对于群聊、钩子和自动化流程，Hermes 支持显式的静默令牌。如果代理的最终响应恰好是一个受支持的令牌，网关将抑制出站传递，不向聊天发送任何内容。

受支持的令牌：

• [SILENT]
• SILENT
• NO_REPLY
• NO REPLY

空白和大小写会被规范化，但整个最终响应必须是该令牌。像“当没有变化时使用 [SILENT]”这样的句子会正常传递。

静默仅影响传递决策。Hermes 会在会话记录中保留助手的静默轮次，因此对话仍然正常交替：

user: 旁路闲聊
assistant: [SILENT]   # 已存储，未传递
user: 下一条消息

失败的轮次仍然会显示为错误；Hermes 不会因为文本类似于静默令牌而隐藏失败。

快速设置

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

hermes gateway setup        # 所有消息平台的交互式设置

这将引导您通过箭头键选择配置每个平台，显示哪些平台已配置，并在完成后提供启动/重启网关的选项。

网关命令

hermes gateway              # 在前台运行
hermes gateway setup        # 交互式配置消息平台
hermes gateway install      # 安装为用户服务（Linux）/ launchd 服务（macOS）
sudo hermes gateway install --system   # 仅 Linux：安装为开机系统服务
hermes gateway start        # 启动默认服务
hermes gateway stop         # 停止默认服务
hermes gateway status       # 检查默认服务状态
hermes gateway status --system         # 仅 Linux：显式检查系统服务

聊天命令（消息内部）

会话管理

会话持久性

会话在消息之间持续存在，直到重置。代理会记住您的对话上下文。

重置策略

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

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

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

安全

默认情况下，网关拒绝所有不在允许列表或通过 DM 配对的用户。 这是具有终端访问权限的机器人的安全默认设置。

## 限制为特定用户（推荐）：
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2
## 或者允许
GATEWAY_ALLOWED_USERS=123456789,987654321
## 或者显式允许所有用户（不推荐用于具有终端访问权限的机器人）：
GATEWAY_ALLOW_ALL_USERS=true

DM 配对（允许列表的替代方案）

无需手动配置用户 ID，未知用户在向机器人发送 DM 时会收到一次性配对码：

## 用户看到："配对码：XKGH5N7P"
## 您通过以下方式批准他们：
hermes pairing approve telegram XKGH5N7P
## 其他配对命令：
hermes pairing list          # 查看待处理 + 已批准的用户
hermes pairing revoke telegram 123456789  # 移除访问权限

配对码在 1 小时后过期，有速率限制，并使用加密随机性。

管理员与普通用户

允许列表回答“此人能否联系到机器人？” 管理员/用户分离回答“既然他们进来了，他们被允许做什么？”

每个允许的用户在每个作用域（DM 与群组/频道）中属于两个层级之一：

• 管理员 — 完全访问权限。可以运行所有已注册的斜杠命令（内置 + 插件）并使用所有受门控的能力。
• 普通用户 — 受限访问权限。可以正常与代理聊天，但只能运行您显式启用的斜杠命令。始终允许的最低限度是 /help 和 /whoami。

层级按平台和作用域配置。DM 管理员状态并不意味着群组/频道管理员状态——每个作用域都有自己的管理员列表。

当前层级门控的内容： 斜杠命令。分离通过实时命令注册表运行，因此涵盖内置和插件注册的命令，无需逐个功能接线。普通聊天不受影响——非管理员仍然可以与代理交谈。

未来可能门控的内容： 更多能力表面（工具访问、模型切换、昂贵操作）将挂载在相同的管理员/用户区分上，随着我们添加它们。现在配置分离意味着这些未来的限制将干净地落地，而无需您重新建模谁是管理员。

配置

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # 管理员 → 所有斜杠命令
        user_allowed_commands: [status, model]       # 非管理员可以运行的内容
## 可选：单独的群组/频道作用域
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

向后兼容： 如果某个作用域未设置 allow_admin_from，则该作用域的层级分离被禁用，所有允许的用户拥有完全访问权限。现有安装无需更改即可继续工作——当您想要区分时选择加入。

检查您的访问权限

在任何平台上使用 /whoami 查看活动作用域、您的层级（管理员/用户/无限制）以及您可以运行哪些斜杠命令。请参阅 Telegram 和 Discord 页面以获取特定平台的示例。

中断代理

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

• 正在进行的终端命令会立即被杀死（SIGTERM，1 秒后 SIGKILL）
• 工具调用被取消——只有当前正在执行的工具会运行，其余被跳过
• 多条消息被合并——中断期间发送的消息被合并为一个提示
• /stop 命令——中断而不排队后续消息

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

默认情况下，向忙碌的代理发送消息会中断它。还有两种其他模式可用：

• queue — 后续消息等待并在当前任务完成后作为下一轮运行。
• steer — 后续消息通过 /steer 注入到当前运行中，在下一个工具调用后到达代理。不中断，不产生新轮次。如果代理尚未开始，则回退到 queue 行为。

display:
  busy_input_mode: steer   # 或 queue，或 interrupt（默认）
  busy_ack_enabled: true   # 设置为 false 以完全抑制 ⚡/⏳/⏩ 聊天回复

当您第一次在任何平台上向忙碌的代理发送消息时，Hermes 会在忙碌确认后附加一行一次性提醒（"💡 首次提示 — …"）。该提醒在每个安装中触发一次——onboarding.seen.busy_input_prompt 下的标志会锁定它。删除该键可再次看到提示。

如果您觉得忙碌确认过于嘈杂——尤其是在语音输入或快速连续消息时——请设置 display.busy_ack_enabled: false。您的输入仍然会正常排队/引导/中断，只有聊天回复被静音。

工具进度通知

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

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # 设置为 true 以在消息中启用 /verbose
## 在支持消息编辑的平台上如何分组进度：
## accumulate（默认）— 在工具运行时原地编辑一个气泡
## separate             — 每个工具发送一条消息（v0.9 之前的风格；更嘈杂）
## 仅在已启用 tool_progress 时适用。
  tool_progress_grouping: accumulate   # accumulate | separate

模型上下文中的消息时间戳

默认关闭。启用后，Hermes 会在模型上下文中的每条用户消息前添加一个人类可读的时间戳（例如 [Tue 2026-04-28 13:40:53 CEST]），以便代理知道消息何时发送——对于时间推理（“您今天早上问过……”，注意到长时间间隔）很有用。它不会添加到助手消息或系统提示中。

gateway:
  message_timestamps:
    enabled: false   # 设置为 true 以向模型显示发送时间

持久化的记录始终保持干净——无论此开关如何，时间戳都作为消息元数据存储，因此稍后启用它也会显示过去消息的发送时间，并且重播永远不会累积重复的前缀。

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

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

后台会话

在单独的后台会话中运行提示，以便代理独立处理它，同时您的主聊天保持响应：

Hermes 立即确认：

🔄 后台任务已启动："检查集群中的所有服务器..."
   任务 ID: bg_143022_a1b2c3

工作原理

每个 /background 提示会生成一个独立的代理实例，异步运行：

• 隔离的会话 — 后台代理拥有自己的会话和自己的对话历史。它不知道您当前的聊天上下文，只接收您提供的提示。
• 相同的配置 — 继承您当前的模型、提供者、工具集、推理设置和提供者路由。
• 非阻塞 — 您的主聊天保持完全交互。在工作时发送消息、运行其他命令或启动更多后台任务。
• 结果传递 — 任务完成时，结果会发送回您发出命令的同一聊天或频道，前缀为“✅ 后台任务完成”。如果失败，您会看到“❌ 后台任务失败”以及错误。

后台进程通知

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

display:
  background_process_notifications: all    # all | result | error | off

您也可以通过环境变量设置：

HERMES_BACKGROUND_NOTIFICATIONS=result

使用场景

• 服务器监控 — "/background 检查所有服务的健康状况，如果有任何宕机请提醒我"
• 长时间构建 — "/background 构建并部署暂存环境"，同时您继续聊天
• 研究任务 — "/background 研究竞争对手定价并总结成表格"
• 文件操作 — "/background 将 ~/Downloads 中的照片按日期整理到文件夹中"

提示

消息平台上的后台任务是即发即忘的——您无需等待或检查它们。任务完成时，结果会自动到达同一聊天。

服务管理

Linux（systemd）

hermes gateway install               # 安装为用户服务
hermes gateway start                 # 启动服务
hermes gateway stop                  # 停止服务
hermes gateway status                # 检查状态
journalctl --user -u hermes-gateway -f  # 查看日志
## 启用驻留（注销后继续运行）
sudo loginctl enable-linger $USER
## 或者安装一个开机系统服务，但仍以您的用户身份运行
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

在笔记本电脑和开发机上使用用户服务。在 VPS 或无头主机上使用系统服务，这些主机应在启动时恢复，而不依赖 systemd 驻留。

提示 — 无头虚拟机：用户服务 + 驻留避免 root 提示

系统服务每次重启都需要 root 权限——包括 hermes update 结束时自动重启网关。当 hermes update 以非 root 用户身份运行时，它会尝试无密码的 sudo systemctl；如果不可用，它会跳过重启并打印手动 sudo systemctl restart hermes-gateway 命令（它永远不会阻塞在交互式密码提示上）。

对于您从不登录的无头虚拟机，启用驻留的用户服务可以为您提供相同的开机启动行为，且无需 root 参与：

bashCopy

hermes gateway install          # 用户服务
sudo loginctl enable-linger $USER   # 一次性：开机启动，注销后存活

之后，hermes update 可以在没有任何权限的情况下重启网关。如果您更喜欢保留系统服务，请使用 sudo hermes update 运行更新，或者为服务账户授予 systemctl 的无密码 sudo 权限，例如在 sudo visudo -f /etc/sudoers.d/hermes-gateway 中：

hermes ALL=(root) NOPASSWD: /usr/bin/systemctl --no-ask-password reset-failed hermes-gateway*, /usr/bin/systemctl --no-ask-password start hermes-gateway*, /usr/bin/systemctl --no-ask-password restart hermes-gateway*

除非您确实需要，否则避免同时安装用户和系统网关单元。如果 Hermes 检测到两者都存在，它会发出警告，因为启动/停止/状态行为会变得模糊。

信息 — 多个安装

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

macOS（launchd）

hermes gateway install               # 安装为 launchd 代理
hermes gateway start                 # 启动服务
hermes gateway stop                  # 停止服务
hermes gateway status                # 检查状态
tail -f ~/.hermes/logs/gateway.log   # 查看日志

生成的 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>。

平台特定工具集

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

运行多平台网关

一个网关通常同时运行多个适配器（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>。这是有意为之：如果某个平台处于持续中断状态，您不希望网关反复重连。

平台暂停时该检查什么

当适配器暂停时，请检查：

1. 网关日志（~/.hermes/logs/gateway.log 或 systemd / launchd 单元日志）。搜索平台名称和 circuit breaker、paused 或 disabled。跳闸事件包括失败计数和最后一个错误。
2. /platform list 输出——显示当前状态和最后原因。
3. 提供者的状态页面（Telegram 机器人 API 状态、Discord 状态等）。断路器跳闸是因为平台不健康；在它恢复之前不要尝试恢复。

一旦上游恢复健康，/platform resume <name> 会清除断路器并重新启用适配器。

重启通知

当网关重启（或关闭时存在进行中的会话）时，它可以向每个平台的家庭频道发送一次性的“代理已返回”/“代理被中断”消息。这由 gateway-config.yaml 中的 gateway_restart_notification 标志按平台控制，默认为 true：

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # 为此平台选择退出
    discord:
      home_chat_id: "987654321"
## gateway_restart_notification 省略 → 默认为 true

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

跨网关重启的会话恢复

当网关关闭时存在进行中的工具调用或生成，受影响的会话被标记为 restart_interrupted。在下次启动时，网关为每个会话安排自动恢复——用户会在聊天中收到简短提示（“重启后发送任何消息，我会尝试从您离开的地方继续。”），当他们回复时，会话从最后提交的轮次继续。

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

无需配置。如果您不想要提示，请在平台上设置 gateway_restart_notification: false。

移动端友好的进度默认值

Telegram 通常是移动收件箱，因此默认值针对该表面进行了调整：

• tool_progress 默认为 off — 没有每个工具的面包屑流填满聊天。
• busy_ack_detail 默认为 off — 忙碌状态确认和长时间运行的心跳保持简洁（没有 iteration 21/60 调试细节）。
• interim_assistant_messages 保持 on — 真正的轮次中助手评论（模型告诉您它将要做什么）是信号，不是噪音。
• long_running_notifications 保持 on — 一个原地编辑的“⏳ 工作中 — N 分钟”气泡每隔几分钟更新一次，因此您有一个心跳，而不是盯着 typing… 半小时。

选择退出任何一个保持开启的默认值，或按平台选择重新启用详细进度：

display:
  platforms:
    telegram:
## 重新启用工具进度流
      tool_progress: new
## 在心跳和忙碌确认中显示 "iteration N/M, running: tool"
      busy_ack_detail: true
## 或者完全静音它们
      interim_assistant_messages: false
      long_running_notifications: false

进度气泡清理（选择加入）

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

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

默认为 false。只有其适配器实现了 delete_message 的平台才支持此设置（目前是 Telegram 和 Discord）。失败的运行跳过清理，因此气泡保留为面包屑。

下一步

• Telegram 设置
• Discord 设置
• Slack 设置
• Google Chat 设置
• WhatsApp 设置
• WhatsApp Business Cloud API 设置
• Signal 设置
• SMS 设置 (Twilio)
• Email 设置
• Home Assistant 集成
• Mattermost 设置
• Matrix 设置
• 钉钉设置
• 飞书/Lark 设置
• 企业微信设置
• 企业微信回调设置
• 微信设置 (WeChat)
• BlueBubbles 设置 (iMessage)
• QQBot 设置
• 元宝设置
• Microsoft Teams 设置
• Teams 会议管道
• Open WebUI + API 服务器
• Webhooks