消息网关

你可以通过 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles（iMessage）、QQ，或者浏览器与 Hermes 对话。网关是一个统一的后台进程：它连接你配置的所有平台、管理会话、运行 cron 任务，并负责投递语音消息。

完整语音能力（包括 CLI 麦克风模式、消息平台中的语音回复，以及 Discord 语音频道对话）请参见 Voice Mode 和 Use Voice Mode with Hermes。

平台对比

Platform	Voice	Images	Files	Threads	Reactions	Typing	Streaming
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
SMS	—	—	—	—	—	—	—
Email	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	✅	✅	✅
DingTalk	—	✅	✅	—	✅	—	✅
Feishu/Lark	✅	✅	✅	✅	✅	✅	✅
WeCom	✅	✅	✅	—	—	✅	✅
WeCom Callback	—	—	—	—	—	—	—
Weixin	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—
QQ	✅	✅	✅	—	—	✅	—

Voice = TTS 音频回复和/或语音消息转写。Images = 收发图片。Files = 收发文件附件。Threads = 线程式对话。Reactions = 对消息添加表情反馈。Typing = 处理时显示“正在输入”。Streaming = 通过编辑消息进行渐进式更新。

架构

每个平台适配器都会接收消息，通过“每个聊天一份”的会话存储做路由，然后把请求交给 AIAgent 处理。网关还会运行 cron 调度器，每 60 秒 tick 一次，执行到期任务。

快速设置

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

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

聊天命令（消息平台内）

Command	Description
`/new` or `/reset`	开始一段全新对话
`/model [provider:model]`	查看或切换模型（支持 `provider:model` 语法）
`/provider`	显示可用大模型提供商（provider）及鉴权状态
`/personality [name]`	设置人格
`/retry`	重试上一条消息
`/undo`	删除上一轮往返
`/status`	显示会话信息
`/stop`	停止正在运行的 agent
`/approve`	批准待确认的危险命令
`/deny`	拒绝待确认的危险命令
`/sethome`	将当前聊天设置为 home channel
`/compress`	手动压缩对话上下文
`/title [name]`	设置或查看会话标题
`/resume [name]`	恢复先前命名的会话
`/usage`	显示该会话的 token 用量
`/insights [days]`	显示用量洞察和分析
`/reasoning [level\|show\|hide]`	调整推理强度或切换 reasoning 显示
`/voice [on\|off\|tts\|join\|leave\|status]`	控制语音回复与 Discord 语音频道行为
`/rollback [number]`	列出或恢复文件系统检查点
`/background <prompt>`	在独立后台会话中运行一个 prompt
`/reload-mcp`	从配置重新加载 MCP 服务器
`/update`	将 Hermes Agent 更新到最新版本
`/help`	显示可用命令
`/<skill-name>`	调用任意已安装技能

会话管理

会话持久化

会话会在消息之间持续存在，直到被重置。agent 会记住你的对话上下文。

重置策略

会话按照可配置策略自动重置：

Policy	Default	Description
Daily	4:00 AM	每天在指定时间重置
Idle	1440 min	空闲 N 分钟后重置
Both	(combined)	以先触发者为准

你可以在 ~/.hermes/gateway.json 中设置按平台覆盖：

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

安全

默认情况下，网关会拒绝所有未在 allowlist 中、也未通过 DM 配对的用户。 对于具备终端访问能力的 bot，这是最安全的默认配置。

# 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

DM 配对（allowlist 的替代方案）

你也可以不手动维护用户 ID。未知用户首次私聊 bot 时，会收到一个一次性配对码：

# 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）
工具调用会被取消，只有当前正在执行的那个会继续，其余跳过
多条消息会被合并，中断期间发来的消息会拼成一个后续 prompt
/stop 命令 只中断，不会排队新的后续消息

工具进度通知

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

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

开启后，bot 在工作时会发送状态消息，例如：

💻 `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
继承相同配置：沿用当前网关下的模型、大模型提供商（provider）、工具集、reasoning 设置和路由配置
非阻塞：主聊天保持完全可交互，你可以继续发消息、执行其他命令，或再启动更多后台任务
结果回传：任务完成后，结果会回发到你发起命令的同一聊天或频道，前缀为 “✅ 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

Mode	What you receive
`all`	运行中输出更新以及最终完成消息（默认）
`result`	只接收最终完成消息（无论退出码）
`error`	仅在退出码非 0 时接收最终消息
`off`	完全关闭进程 watcher 消息

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

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

提示

消息平台中的后台任务是 fire-and-forget。你无需额外等待或轮询；任务完成后，结果会自动回到当前聊天。

服务管理

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

笔记本和开发机通常用 user service；VPS 或无头主机则更适合 system service，这样即使不依赖 systemd linger 也能在开机后自动恢复。

除非你非常明确需要同时安装 user 与 system 两套 unit，否则不建议并存。Hermes 检测到两者同时存在时会发出警告，因为 start/stop/status 的行为会变得含糊。

Multiple installations

如果同一台机器上运行了多个 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，其中包含 3 个关键环境变量：

PATH：安装时捕获的完整 shell PATH，并在前面追加 venv bin/ 与 node_modules/.bin，以确保 Node.js、ffmpeg 等用户级工具可被网关子进程使用
VIRTUAL_ENV：指向 Python 虚拟环境，方便工具正确解析依赖
HERMES_HOME：将网关绑定到当前 Hermes 安装实例

PATH changes after install

launchd plist 是静态文件。如果你在设置完网关后又新装了工具（例如用 nvm 安装新的 Node.js，或用 Homebrew 安装 ffmpeg），请重新运行 hermes gateway install 以更新 PATH。网关会检测陈旧 plist 并自动 reload。

Multiple installations

和 Linux 的 systemd service 一样，每个 HERMES_HOME 目录都拥有自己的 launchd label。默认 ~/.hermes 使用 ai.hermes.gateway；其他安装则使用 ai.hermes.gateway-<suffix>。

平台专属工具集

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

Platform	Toolset	Capabilities
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 Callback	`hermes-wecom-callback`	含终端在内的完整工具
Weixin	`hermes-weixin`	含终端在内的完整工具
BlueBubbles	`hermes-bluebubbles`	含终端在内的完整工具
QQBot	`hermes-qqbot`	含终端在内的完整工具
API Server	`hermes` (default)	含终端在内的完整工具
Webhooks	`hermes-webhook`	含终端在内的完整工具

平台对比​

架构​

快速设置​

网关命令​

聊天命令（消息平台内）​

会话管理​

会话持久化​

重置策略​

安全​

DM 配对（allowlist 的替代方案）​

中断 agent​

工具进度通知​

后台会话​

工作方式​

后台进程通知​

使用场景​

服务管理​

Linux（systemd）​

macOS（launchd）​

平台专属工具集​

下一步​