Skip to main content

消息网关

通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles (iMessage) 或您的浏览器与 Hermes 聊天。网关是一个单一的后台进程，连接到所有配置的平台，处理会话，运行 cron 作业，并传递语音消息。

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

平台比较​

平台语音图片文件主题反应输入状态流式传输
Telegram✅✅✅✅—✅✅
Discord✅✅✅✅✅✅✅
Slack✅✅✅✅✅✅✅
WhatsApp—✅✅——✅✅
Signal—✅✅——✅✅
SMS———————
Email—✅✅✅———
Home Assistant———————
Mattermost✅✅✅✅—✅✅
Matrix✅✅✅✅✅✅✅
DingTalk—————✅✅
Feishu/Lark✅✅✅✅✅✅✅
WeCom✅✅✅——✅✅
Weixin✅✅✅——✅✅
BlueBubbles—✅✅—✅✅—

语音 = TTS 音频回复和/或语音消息转录。图片 = 发送/接收图片。文件 = 发送/接收文件附件。主题 = 主题对话。反应 = 消息上的表情反应。输入状态 = 处理时的输入指示。流式传输 = 通过编辑进行渐进式消息更新。

架构​

每个平台适配器接收消息，通过每个聊天的会话存储进行路由，并将其分派给 AIAgent 进行处理。网关还运行 cron 调度器，每 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停止运行中的 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 会记住您的对话上下文。

重置策略​

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

策略默认描述
每日4:00 AM每天特定小时重置
空闲1440 minN 分钟无活动后重置
两者(combined)以先触发者为准

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

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

安全性​

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

# 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

# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321

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

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

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

# 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 小时后过期，受速率限制，并使用加密随机性。

中断 Agent​

在 agent 工作时发送任何消息以中断它。关键行为：

  • 进行中的终端命令会立即被杀死（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...

后台会话​

在单独的后台会话中运行提示，以便 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 提示生成一个 单独的 agent 实例 异步运行：

  • 隔离会话 — 后台 agent 拥有自己的会话和对话历史。它不了解您当前的聊天上下文，仅接收您提供的提示。
  • 相同配置 — 从当前网关设置继承模型、提供商、工具集、推理设置和提供商路由。
  • 非阻塞 — 主聊天保持完全交互。发送消息、运行其他命令或启动更多后台任务。
  • 结果交付 — 任务完成后，结果发送回发出命令的 同一聊天或频道，前缀为 "✅ Background task complete"。如果失败，您将看到 "❌ Background task failed" 及错误信息。

后台进程通知​

当运行后台会话的 agent 使用 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 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"
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，并前置了 venv bin/ 和 node_modules/.bin。这确保用户安装的工具（Node.js、ffmpeg 等）可用于网关子进程，如 WhatsApp 桥接。
  • VIRTUAL_ENV — 指向 Python virtualenv，以便工具可以正确解析包。
  • 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>。

平台特定工具集​

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

平台工具集能力
CLIhermes-cli完全访问
Telegramhermes-telegram完整工具（包括终端）
Discordhermes-discord完整工具（包括终端）
WhatsApphermes-whatsapp完整工具（包括终端）
Slackhermes-slack完整工具（包括终端）
Signalhermes-signal完整工具（包括终端）
SMShermes-sms完整工具（包括终端）
Emailhermes-email完整工具（包括终端）
Home Assistanthermes-homeassistant完整工具 + HA 设备控制 (ha_list_entities, ha_get_state, ha_call_service, ha_list_services)
Mattermosthermes-mattermost完整工具（包括终端）
Matrixhermes-matrix完整工具（包括终端）
DingTalkhermes-dingtalk完整工具（包括终端）
Feishu/Larkhermes-feishu完整工具（包括终端）
WeComhermes-wecom完整工具（包括终端）
Weixinhermes-weixin完整工具（包括终端）
BlueBubbleshermes-bluebubbles完整工具（包括终端）
API Serverhermes (默认)完整工具（包括终端）
Webhookshermes-webhook完整工具（包括终端）

下一步​