消息網關

通過 Telegram、Discord、Slack、WhatsApp、Signal、短信、電子郵件、Home Assistant、Mattermost、Matrix、釘釘、飛書（Lark）、企業微信、微信、BlueBubbles（iMessage）或您的瀏覽器與 Hermes 進行聊天。該網關是一個單一的後臺進程，可連接到您配置的所有平臺，管理會話，運行定時任務，併發送語音消息。

如需完整語音功能集——包括 CLI 麥克風模式、消息中的語音回覆以及 Discord 語音頻道對話——請參閱語音模式和使用語音模式與 Hermes。

平臺對比

平臺	語音	圖片	文件	線程	表情反應	正在輸入提示	流式傳輸
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
短信	—	—	—	—	—	—	—
電子郵件	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	—	✅	✅
釘釘	—	—	—	—	—	✅	✅
飛書（Lark）	✅	✅	✅	✅	✅	✅	✅
企業微信	✅	✅	✅	—	—	✅	✅
微信	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—

語音 = TTS 語音回覆和/或語音消息轉錄。圖片 = 發送/接收圖片。文件 = 發送/接收文件附件。線程 = 線程化對話。表情反應 = 消息上的表情反應。鍵入指示 = 處理時的鍵入指示。流式傳輸 = 通過編輯實現漸進式消息更新。

架構

每個平臺適配器接收消息，通過按聊天劃分的 Session 存儲進行路由，並將消息分發給 AIAgent 進行處理。網關還運行定時調度器，每 60 秒觸發一次，執行所有到期的任務。

快速設置

配置消息平臺最簡單的方法是使用交互式嚮導：

hermes gateway setup        # 適用於所有消息平臺的交互式設置

該向導支持使用方向鍵選擇，並會引導您完成各個平臺的配置，顯示哪些平臺已配置，並在完成後提供啟動/重啟網關的選項。

網關命令

hermes gateway              # 在前臺運行
hermes gateway setup        # 交互配置消息傳遞平臺
hermes gateway install      # 安裝為用戶服務 (Linux) / 啟動服務 (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]`	顯示或更改模型（支持 `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	每天特定時間重置
空閒	1440 分鐘	無操作 N 分鐘後重置
兩者	（組合）	任一條件先觸發即重置

可在 ~/.hermes/gateway.json 中為各平臺配置覆蓋設置：

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

安全性

默認情況下，網關會拒絕所有未在允許列表中或未通過私信配對的用戶。 這是具有終端訪問權限的機器人最安全的默認設置。

# 限制特定用戶（推薦）：
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

# 或者允許
GATEWAY_ALLOWED_USERS=123456789,987654321

# 或者明確允許所有用戶（對於具有終端訪問權限的機器人，建議使用 NOT）：
GATEWAY_ALLOW_ALL_USERS=true

私信配對（允許列表的替代方案）

無需手動配置用戶 ID，未知用戶在向機器人發送私信時會收到一次性配對碼：

# 用戶看到："Pairing code: XKGH5N7P"
# 你用下面的命令批准：
hermes pairing approve telegram XKGH5N7P

# 其他配對命令：
hermes pairing list          # 查看待處理+已批准的用戶
hermes pairing revoke telegram 123456789  # 刪除訪問權限

配對碼 1 小時後過期，受速率限制，並使用加密隨機性生成。

中斷 Agent

當 Agent 正在工作時，發送任何消息即可中斷它。關鍵行為如下：

正在進行的終端命令會立即終止（先發送 SIGTERM，1 秒後發送 SIGKILL）
工具調用會被取消 — 僅執行當前正在運行的調用，其餘調用將被跳過
多條消息會被合併 — 中斷期間發送的消息將合併為一條提示
/stop 命令 — 中斷操作且不排隊後續消息

工具執行進度通知

通過 ~/.hermes/config.yaml 控制在聊天中顯示多少工具活動信息：

display:
  tool_progress: all    # 關閉 |新 |全部 |冗長的
  tool_progress_command: false  # 設置為 true 以在消息傳遞中啟用“0”

啟用後，機器人在執行任務時會發送狀態消息：

💻 `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 擁有獨立的會話和獨立的對話歷史。它不瞭解你當前聊天的上下文，僅接收你提供的提示。
相同配置 — 繼承當前網關設置中的模型、提供商、工具集、推理設置和提供商路由。
非阻塞 — 主聊天保持完全可交互。在後臺任務運行時，你仍可發送消息、執行其他命令或啟動更多後臺任務。
結果交付 — 任務完成後，結果將發送回你發出命令的同一聊天或頻道，並以“✅ 後臺任務完成”為前綴。如果失敗，你會看到“❌ 後臺任務失敗”及錯誤信息。

後臺進程通知

當運行後臺會話的 Agent 使用 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 linger。

除非你確實需要，否則避免同時安裝用戶和服務級網關單元。Hermes 檢測到兩者共存時會發出警告，因為啟動/停止/狀態行為會變得模糊。

多次安裝

如果你在同一臺機器上運行多個 Hermes 安裝（使用不同的 HERMES_HOME 目錄），每個安裝都會擁有自己的 systemd 服務名稱。默認的 ~/.hermes 使用 hermes-gateway；其他安裝使用 hermes-gateway-<hash>。hermes gateway 命令會自動針對當前 HERMES_HOME 選擇正確的服務。

macOS（launchd）

hermes gateway install               # 安裝為啟動 agent
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>。

平臺特定工具集

每個平臺都有其專屬的工具集：

平臺	工具集	功能特性
命令行界面 (CLI)	`hermes-cli`	完全訪問權限
Telegram	`hermes-telegram`	完整工具集，包括終端
Discord	`hermes-discord`	完整工具集，包括終端
WhatsApp	`hermes-whatsapp`	完整工具集，包括終端
Slack	`hermes-slack`	完整工具集，包括終端
Signal	`hermes-signal`	完整工具集，包括終端
短信 (SMS)	`hermes-sms`	完整工具集，包括終端
郵件	`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`	完整工具集，包括終端
釘釘	`hermes-dingtalk`	完整工具集，包括終端
飛書 / Lark	`hermes-feishu`	完整工具集，包括終端
企業微信	`hermes-wecom`	完整工具集，包括終端
微信	`hermes-weixin`	完整工具集，包括終端
BlueBubbles	`hermes-bluebubbles`	完整工具集，包括終端
API 服務器	`hermes`（默認）	完整工具集，包括終端
Webhooks	`hermes-webhook`	完整工具集，包括終端

平臺對比​

架構​

快速設置​

網關命令​

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

會話管理​

會話持久化​

重置策略​

安全性​

私信配對（允許列表的替代方案）​

中斷 Agent​

工具執行進度通知​

後臺會話​

工作原理​

後臺進程通知​

使用場景​

服務管理​

Linux（systemd）​

macOS（launchd）​

平臺特定工具集​

後續步驟​