消息网关

通过消息网关，你可以从 Telegram、Discord、Slack、WhatsApp、Signal、飞书、微信、钉钉、企业微信、QQ、元宝、Microsoft Teams 等 15+ 平台与 Hermes 对话。网关是一个单一后台进程，连接到你配置的所有平台、处理会话、运行定时任务并投递语音消息。

平台对比

平台	语音	图片	文件	线程	表情回应	输入指示	流式输出
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
飞书/Lark	✅	✅	✅	✅	✅	✅	✅
微信	✅	✅	✅	—	—	✅	✅
企业微信	✅	✅	✅	—	✅	✅	✅
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
钉钉	—	✅	✅	—	✅	—	✅
QQ	✅	✅	✅	—	—	✅	—
元宝	✅	✅	✅	—	—	✅	✅
Microsoft Teams	—	✅	—	✅	—	✅	—
Matrix	✅	✅	✅	✅	✅	✅	✅
Email	—	✅	✅	✅	—	—	—

架构

每个平台适配器接收消息，通过每聊天的会话存储路由，然后分发给 AI Agent 处理。网关同时运行定时调度器，每 60 秒检查一次是否有需要执行的任务。

快速设置

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

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 专用：查看系统服务

聊天命令（消息平台内）

命令	说明
/new 或 /reset	开始新对话
/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>	在独立后台会话中运行提示
/reload-mcp	从配置重新加载 MCP 服务器
/update	更新 Hermes Agent 到最新版本
/help	显示可用命令
/<skill-name>	调用已安装的技能

会话管理

会话持久化

会话在重置之前会跨消息持久化。Agent 会记住你的对话上下文。

重置策略

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

策略	默认值	说明
Daily	4:00 AM	每天指定时间重置
Idle	1440 分钟	N 分钟无活动后重置
Both	组合	哪个先触发按哪个

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

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

安全

用户授权

默认情况下，网关拒绝所有未在白名单中或未通过 DM 配对的用户。这对于拥有终端访问权限的 Bot 来说是安全的默认行为。

# 限制为特定用户（推荐）
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# 或全局白名单
GATEWAY_ALLOWED_USERS=123456789,987654321

# 或显式允许所有用户（不推荐用于有终端访问权限的 Bot）
GATEWAY_ALLOW_ALL_USERS=true

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

无需手动配置用户 ID，未知的 DM 用户会收到一次配对码：

# 用户看到: "配对码: XKGH5N7P"
# 你批准他们:
hermes pairing approve telegram XKGH5N7P

# 其他配对命令:
hermes pairing list                           # 查看待处理和已批准的用户
hermes pairing revoke telegram 123456789      # 移除访问权限

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

管理员与普通用户

白名单解决”这个人能不能联系 Bot？“的问题。管理员/用户分层解决”既然能联系，他们能做什么？”

每个允许的用户在每个作用域（DM vs 群组/频道）下分为两个层级：

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

注意

层级按平台和作用域配置。DM 管理员身份不意味着群组/频道也是管理员 — 每个作用域有自己的管理员列表。如果未设置 allow_admin_from，该作用域将禁用分层，所有允许的用户都拥有完全访问权限。

配置示例：

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]

使用 /whoami 命令查看你当前的层级和可用命令。

中断 Agent

在 Agent 工作时发送任何消息即可中断它：

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

忙碌输入模式

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

• queue — 后续消息等待当前任务完成后作为下一轮运行
• steer — 后续消息通过 /steer 注入到当前运行中，在下一次工具调用后到达 Agent。不中断，不产生新轮次

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

工具进度通知

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

display:
  tool_progress: all           # off | new | all | verbose
  tool_progress_command: false # 设为 true 可在消息平台中启用 /verbose

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

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

后台会话

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

/background 检查集群中所有服务器，报告任何宕机的

Hermes 立即确认：

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

工作原理

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

• 隔离会话 — 后台 Agent 有自己的会话和对话历史，不知道你当前的聊天上下文
• 相同配置 — 继承你的模型、提供商、工具集、推理设置
• 非阻塞 — 你的主聊天完全可交互
• 结果投递 — 任务完成后，结果发送回你发出命令的聊天，前缀为”✅ 后台任务完成”

后台进程通知

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

模式	你会收到
all	运行输出更新和最终完成消息（默认）
result	仅最终完成消息
error	仅退出码非零的最终消息
off	完全不发送进程监视器消息

使用场景

• 服务器监控 — “/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

警告

避免同时安装用户服务和系统服务。Hermes 会检测并警告这种冲突，因为 start/stop/status 行为会变得不明确。

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。

提示

安装后如果安装了新工具（如通过 nvm 安装新 Node.js 版本，或通过 Homebrew 安装 ffmpeg），需要重新运行 hermes gateway install 以捕获更新后的 PATH。