消息网关

你可以通过 Telegram、Discord、Slack、WhatsApp、Signal、短信、邮件、Home Assistant、Mattermost、Matrix、钉钉、飞书/Lark、企业微信、微信、BlueBubbles（iMessage）、QQ 甚至浏览器，和 Hermes 对话。消息网关本质上是一个统一的后台进程，它会连接你启用的所有平台、管理会话、运行定时任务，并处理语音消息等能力。

如果你要使用完整的语音功能，包括 CLI 麦克风模式、消息中的语音回复，以及 Discord 语音频道对话，请参阅 语音模式 和 使用语音模式与 Hermes。

平台对比

平台	语音	图片	文件	线程	表情反应	输入状态	流式传输
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
短信	—	—	—	—	—	—	—
电子邮件	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	✅	✅	✅
钉钉	—	—	—	—	—	✅	✅
飞书/Lark	✅	✅	✅	✅	✅	✅	✅
企业微信	✅	✅	✅	—	—	✅	✅
企业微信回调	—	—	—	—	—	—	—
微信	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—
QQ	✅	✅	✅	—	—	✅	—

语音 = TTS 音频回复和/或语音消息转录。图片 = 发送/接收图片。文件 = 发送/接收附件。线程 = 支持线性对话。表情反应 = 对消息进行表情符号反馈。输入状态 = 处理时显示输入提示。流式传输 = 通过编辑实现渐进式消息更新。

架构设计

每个平台适配器负责接收消息、把它们路由到对应会话的存储中，再交给 AIAgent 处理。网关还会运行一个定时调度器，每 60 秒轮询一次，用来执行所有到期任务。

快速设置

最简单的配置方式是交互式向导：

hermes gateway setup        # Interactive setup for all messaging platforms

该向导会带你逐个平台完成配置，支持方向键选择、显示当前已配置的平台列表，并在结束后提供启动或重启网关的选项。

网关命令

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

聊天命令（在消息中使用）

命令	描述
/new 或 /reset	开启全新对话
/model [provider:model]	显示或更改模型（支持 provider:model 语法）
/provider	显示可用提供商及其认证状态
/personality [name]	设置个性设定
/retry	重试上一条消息
/undo	删除最近一次交流
/status	查看会话信息
/stop	停止正在运行的代理
/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>	在独立后台会话中运行一个提示
/reload-mcp	从配置重新加载 MCP 服务器
/update	将 Hermes Agent 更新至最新版本
/help	显示可用命令列表
/<skill-name>	调用任意已安装的技能

会话管理

会话持久化

会话会在消息之间持续保留，直到被重置为止。代理会记住你当前这段对话的上下文。

重置策略

会话根据可配置策略自动重置：

策略	默认值	说明
每日	凌晨 4:00	每天特定时间重置
空闲	1440 分钟	连续空闲 N 分钟后重置
两者结合	（组合）	任一条件先触发即重置

可在 ~/.hermes/gateway.json 中为各平台设置覆盖规则：

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

安全机制

默认情况下，网关会拒绝所有未进入白名单、也未通过私聊配对的用户。 对于具备终端访问能力的机器人来说，这是最安全的默认设置。

# Restrict to specific users (recommended):
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

# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321

# Or explicitly allow all users (NOT recommended for bots with terminal access):
GATEWAY_ALLOW_ALL_USERS=true

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

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

# The user sees: "Pairing code: XKGH5N7P"
# You approve them with:
hermes pairing approve telegram XKGH5N7P

# Other pairing commands:
hermes pairing list          # View pending + approved users
hermes pairing revoke telegram 123456789  # Remove access

配对码有效期为 1 小时，具有速率限制，并使用加密随机生成。

中断代理

当代理正在工作时，发送任意消息即可中断其运行。关键行为如下：

• 正在进行的终端命令立即终止（先发送 SIGTERM，1 秒后若未结束则发送 SIGKILL）
• 工具调用被取消 —— 只有当前正在执行的调用继续，其余均跳过
• 多条消息合并处理 —— 中断期间发送的消息会被合并成一条新提示
• /stop 命令 —— 中断时不排队后续消息

工具进度通知

控制 ~/.hermes/config.yaml 中显示的工具活动程度：

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # set to true to enable /verbose in messaging

启用后，机器人将在执行过程中发送状态消息：

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

后台会话

在独立的后台会话中运行提示，使代理能独立处理任务，同时保持主聊天响应流畅：

/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 提示都会启动一个独立的代理实例，异步运行：

• 隔离会话 —— 后台代理拥有自己的会话和独立的对话历史。它不了解你当前聊天的上下文，只会接收你提供的提示。
• 相同配置 —— 继承当前网关中的模型、提供商、工具集、推理设置和路由配置。
• 非阻塞 —— 主聊天始终保持可交互状态。你可以继续发送消息、执行其他命令，或再启动更多后台任务。
• 结果送达 —— 任务完成后，结果会返回到发出命令的同一聊天或频道，并以“✅ 后台任务完成”为前缀；如果失败，则会显示“❌ 后台任务失败”以及错误详情。

后台进程通知

当后台会话中的代理使用 terminal(background=true) 启动长时间运行的进程（例如服务器或构建任务）时，网关可以把状态更新推送回你的聊天。你可以通过 ~/.hermes/config.yaml 中的 display.background_process_notifications 来控制这一行为：

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

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

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

HERMES_BACKGROUND_NOTIFICATIONS=result

典型应用场景

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

tip

消息平台上的后台任务采用“发送即忘”模式——无需等待或主动检查。任务完成后，结果会自动返回到同一聊天中。

服务管理

Linux（systemd）

hermes gateway install               # Install as user service
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
journalctl --user -u hermes-gateway -f  # View logs

# Enable lingering (keeps running after logout)
sudo loginctl enable-linger $USER

# Or install a boot-time system service that still runs as your user
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

在笔记本电脑和开发机上使用用户级服务；在 VPS 或无头服务器上使用系统级服务，以确保开机时能自动启动且不依赖 systemd linger。

除非你确实需要，否则请避免同时安装用户和服务两个网关单元。Hermes 检测到两者共存时会发出警告，因为启动/停止/状态行为将变得模糊不清。

多个安装实例

如果你在同一台机器上运行多个 Hermes 实例（使用不同的 HERMES_HOME 目录），每个实例都会拥有独立的 systemd 服务名称。默认的 ~/.hermes 使用 hermes-gateway；其他实例则使用 hermes-gateway-<hash>。hermes gateway 命令会自动针对当前 HERMES_HOME 所在环境选择正确的服务。

macOS（launchd）

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

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

• PATH —— 安装时的完整 shell PATH，已在前面添加了虚拟环境的 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	完整工具集，含终端支持
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 回调	hermes-wecom-callback	完整工具集，含终端支持
Weixin	hermes-weixin	完整工具集，含终端支持
BlueBubbles	hermes-bluebubbles	完整工具集，含终端支持
QQBot	hermes-qqbot	完整工具集，含终端支持
API Server	hermes（默认）	完整工具集，含终端支持
Webhooks	hermes-webhook	完整工具集，含终端支持

下一步操作

• Telegram 设置
• Discord 设置
• Slack 设置
• WhatsApp 设置
• Signal 设置
• SMS 设置（Twilio）
• Email 设置
• Home Assistant 集成
• Mattermost 设置
• Matrix 设置
• DingTalk 设置
• Feishu/Lark 设置
• WeCom 设置
• WeCom 回调设置
• Weixin 设置（微信）
• BlueBubbles 设置（iMessage）
• QQBot 设置
• Open WebUI + API Server
• Webhooks