<!-- Source: https://hermesbible.com/docs/user-guide/messaging/index -->

章節：訊息平台 · URL: https://hermesbible.com/docs/user-guide/messaging/index

你可以從 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin、BlueBubbles (iMessage)、QQ、Yuanbao、Microsoft Teams、LINE、ntfy，或瀏覽器與 Hermes 聊天。閘道器是一個背景常駐程式，負責連接所有已設定的平台、管理對話工作階段、執行定時任務，以及傳送語音訊息。

關於完整的語音功能——包括 CLI 麥克風模式、訊息平台中的語音回覆，以及 Discord 語音頻道對話——請參閱語音模式和在 Hermes 中使用語音模式。

TIP

Bot 需要同時設定模型提供者和工具提供者（TTS、網路搜尋）。Nous Portal 訂閱方案包含了所有這些服務。

平台功能比較

語音 = TTS 語音回覆和/或語音訊息轉寫。圖片 = 傳送/接收圖片。檔案 = 傳送/接收檔案附件。討論串 = 討論串式對話。表情回應 = 對訊息使用表情符號回應。輸入指示 = 處理中顯示輸入指示。串流 = 透過編輯訊息實現漸進式更新。

架構

flowchart TB
    subgraph Gateway["Hermes 閘道器"]
        subgraph Adapters["平台適配器"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

每個平台適配器接收訊息，透過每個聊天的工作階段儲存進行路由，然後將訊息派送給 AI Agent 處理。閘道器同時執行定時排程器，每 60 秒觸發一次以執行到期的任務。

故意沉默 Token

針對群組聊天、hooks 和自動化流程，Hermes 支援明確的沉默 Token。如果 Agent 的最終回覆恰好是其中一個支援的 Token，閘道器會抑制外送訊息，不會向聊天室傳送任何內容。

支援的 Token：

• [SILENT]
• SILENT
• NO_REPLY
• NO REPLY

空白字元和大小寫會被標準化處理，但整個最終回覆必須是該 Token。像「當沒有變化時使用 [SILENT]」這樣的句子會正常傳送。

沉默僅影響傳送決定。Hermes 會將助手的沉默回合保留在工作階段對話記錄中，因此對話仍會正常交替：

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

失敗的回合仍然會顯示為錯誤；Hermes 不會因為文字類似沉默 Token 而隱藏失敗。

快速設定

設定訊息平台最簡單的方式是使用互動式設定精靈：

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：明確檢查系統服務狀態

聊天指令（訊息平台內使用）

工作階段管理

工作階段持久化

工作階段在訊息之間持續保存，直到被重置。Agent 會記住你的對話上下文。

重置策略

工作階段根據可設定的策略進行重置：

在 ~/.hermes/gateway.json 中設定各平台的覆寫：

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

安全性

預設情況下，閘道器會拒絕所有不在允許名單中或未透過私訊配對的使用者。 這對具有終端機存取權限的 Bot 來說是安全的預設設定。

# 限制特定使用者（建議）：
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
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

# 或允許全部
GATEWAY_ALLOWED_USERS=123456789,987654321

# 或明確允許所有使用者（不建議用於具有終端機存取權限的 Bot）：
GATEWAY_ALLOW_ALL_USERS=true

私訊配對（允許名單的替代方案）

與其手動設定使用者 ID，未知使用者在私訊 Bot 時會收到一次性配對碼：

# 使用者看到：「配對碼：XKGH5N7P」
# 你使用以下指令核准他們：
hermes pairing approve telegram XKGH5N7P

# 其他配對指令：
hermes pairing list          # 檢視待處理和已核准的使用者
hermes pairing revoke telegram 123456789  # 移除存取權限

配對碼在 1 小時後過期，有速率限制，並使用加密安全的隨機數。

管理者與一般使用者

允許名單回答的是「這個人能不能觸及 Bot？」的問題。管理者/使用者的區分回答的是「既然他們已經進來了，他們可以做什麼？」

每個已允許的使用者在每個範圍（私訊 vs 群組/頻道）中屬於兩個層級之一：

• 管理者 — 完全存取。可以執行所有已註冊的斜線指令（內建 + 外掛）並使用所有受控功能。
• 一般使用者 — 受限存取。可以正常與 Agent 對話，但只能執行你明確啟用的斜線指令。始終允許的最低限度是 /help 和 /whoami。

層級按各平台和各範圍分別設定。私訊的管理者身分並不意味著群組/頻道的管理者身分——每個範圍都有自己的管理者名單。

目前受控的功能： 斜線指令。區分機制運作於即時指令登錄表中，因此涵蓋了內建和外掛註冊的指令，無需逐一設定。普通聊天不受影響——非管理者仍可與 Agent 對話。

未來可能受控的功能： 更多功能面（工具存取、模型切換、高成本操作）將同樣基於管理者/使用者的區分機制。現在設定區分，意味著未來的限制可以無痛上線，無需重新規劃誰是管理者。

設定

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]

向後相容： 如果某個範圍未設定 allow_admin_from，該範圍的層級區分會被停用，所有已允許的使用者都擁有完整權限。現有安裝無需任何修改即可繼續運作——你想使用區分功能時再啟用即可。

檢視你的存取權限

從任何平台使用 /whoami 查看當前範圍、你的層級（admin / user / unrestricted）以及你可以執行的斜線指令。請參閱 Telegram 和 Discord 頁面了解各平台的具體範例。

中斷 Agent

在 Agent 執行中傳送任何訊息即可中斷它。主要行為：

• 進行中的終端機指令會立即被終止（先發送 SIGTERM，1 秒後發送 SIGKILL）
• 工具呼叫會被取消 — 只有目前正在執行的會繼續運行，其餘的會被跳過
• 多條訊息會被合併 — 中斷期間傳送的訊息會合併為一個提示詞
• /stop 指令 — 中斷但不會佇列後續訊息

佇列 vs 中斷 vs 導引（忙碌輸入模式）

預設情況下，向忙碌中的 Agent 傳送訊息會中斷它。另有兩種模式可用：

• queue — 後續訊息會等待，並在當前任務完成後作為下一個回合執行。
• steer — 後續訊息透過 /steer 注入到目前的執行中，在下一次工具呼叫後送達 Agent。不會中斷，不會產生新回合。如果 Agent 尚未開始執行，會退回為 queue 行為。

display:
  busy_input_mode: steer   # 或 queue，或 interrupt（預設）
  busy_ack_enabled: true   # 設為 false 可完全停用 ⚡/⏳/⏩ 聊天回覆

當你第一次在任何平台上向忙碌中的 Agent 傳送訊息時，Hermes 會在忙碌確認訊息後附加一行提示，說明此設定項（"💡 First-time tip — …"）。此提示僅執行一次——透過 onboarding.seen.busy_input_prompt 下的旗標鎖定。刪除該鍵即可再次看到提示。

如果你覺得忙碌確認訊息太吵——特別是使用語音輸入或快速連續發送訊息時——可以設定 display.busy_ack_enabled: false。你的輸入仍會正常佇列/導引/中斷，只是聊天回覆會被靜音。

工具進度通知

在 ~/.hermes/config.yaml 中控制工具活動的顯示程度：

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # 設為 true 可在訊息平台中使用 /verbose
  # 在支援訊息編輯的平台上如何分組顯示進度：
  #   accumulate（預設）— 工具執行時原地編輯同一個訊息泡泡
  #   separate             — 每個工具發送一條訊息（v0.9 之前的風格；較吵雜）
  # 僅在已啟用 tool_progress 時適用。
  tool_progress_grouping: accumulate   # accumulate | separate

模型上下文中的訊息時間戳

預設關閉。啟用後，Hermes 會在模型上下文中每則使用者訊息前加上一個人類可讀的時間戳（例如 [Tue 2026-04-28 13:40:53 CEST]），讓 Agent 知道訊息何時被傳送——這對時間推理很有幫助（「你今天早上問的……」、注意到長時間的間隔）。它不會添加到助手訊息或系統提示中。

gateway:
  message_timestamps:
    enabled: false   # 設為 true 可將傳送時間顯示給模型

持久化的對話記錄始終保持乾淨——時間戳作為訊息中繼資料儲存，不受此開關影響，因此稍後啟用也能顯示過去訊息的傳送時間，重播時不會累積重複的前綴。

啟用後，Bot 會在執行時傳送狀態訊息：

💻 `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

你也可以透過環境變數設定：

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               # 安裝為使用者服務
hermes gateway start                 # 啟動服務
hermes gateway stop                  # 停止服務
hermes gateway status                # 檢查狀態
journalctl --user -u hermes-gateway -f  # 檢視日誌

# 啟用 lingering（登出後持續運行）
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。

TIP — 無桌面 VM：使用者服務 + linger 可避免 root 提示

系統服務在每次重啟時都需要 root 權限——包括 hermes update 結束時的自動閘道器重啟。當 hermes update 以非 root 使用者執行時，它會嘗試無密碼的 sudo systemctl；如果不可用，它會跳過重啟並印出手動的 sudo systemctl restart hermes-gateway 指令（它永遠不會阻塞在互動式密碼提示上）。

對於你永遠不會登入的無桌面 VM，使用已啟用 lingering 的使用者服務可以提供相同的開機時啟動行為，完全不需要 root 參與：

hermes gateway install          # 使用者服務
sudo loginctl enable-linger $USER   # 一次性設定：開機時啟動，登出後持續運行

之後，hermes update 就可以在不需要任何權限的情況下重啟閘道器。如果你偏好使用系統服務，可以用 sudo hermes update 執行更新，或授予服務帳號對 systemctl 的無密碼 sudo 權限，例如在 sudo visudo -f /etc/sudoers.d/hermes-gateway 中設定：

hermes ALL=(root) NOPASSWD: /usr/bin/systemctl --no-ask-password reset-failed hermes-gateway*, /usr/bin/systemctl --no-ask-password start hermes-gateway*, /usr/bin/systemctl --no-ask-password restart hermes-gateway*

除非你確定需要，否則避免同時安裝使用者和系統閘道器服務。Hermes 在偵測到兩者共存時會發出警告，因為啟動/停止/狀態的行為會變得模糊。

INFO — 多重安裝

如果你在同一台機器上執行多個 Hermes 安裝（使用不同的 HERMES_HOME 目錄），每個安裝會有自己的 systemd 服務名稱。預設的 ~/.hermes 使用 hermes-gateway；其他安裝使用 hermes-gateway-<hash>。hermes gateway 指令會自動指向你目前 HERMES_HOME 的正確服務。

macOS (launchd)

hermes gateway install               # 安裝為 launchd 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，virtualenv 的 bin/ 和 node_modules/.bin 放在最前面。這確保了使用者安裝的工具（Node.js、ffmpeg 等）可供閘道器子程式（如 WhatsApp bridge）使用。
• VIRTUAL_ENV — 指向 Python virtualenv，讓工具能正確解析套件。
• HERMES_HOME — 將閘道器的作用範圍限定在你的 Hermes 安裝目錄。

TIP — 安裝後的 PATH 變更

launchd plist 是靜態的——如果你在設定閘道器後安裝了新工具（例如透過 nvm 安裝新版本的 Node.js，或透過 Homebrew 安裝 ffmpeg），請再次執行 hermes gateway install 以捕捉更新後的 PATH。閘道器會偵測到過時的 plist 並自動重新載入。

INFO — 多重安裝

與 Linux systemd 服務類似，每個 HERMES_HOME 目錄會有自己的 launchd 標籤。預設的 ~/.hermes 使用 ai.hermes.gateway；其他安裝使用 ai.hermes.gateway-<suffix>。

各平台專屬工具組

每個平台有自己的工具組：

操作多平台閘道器

一個閘道器通常同時運行多個適配器（Telegram + Discord + Slack 等）。以下章節涵蓋跨所有平台的日常運維操作。

/platform 指令

閘道器運行後，你可以從任何已連接的 CLI 工作階段或聊天使用 /platform 斷線指令來檢查和操控各個適配器，無需重啟整個閘道器：

/platform list                  # 顯示所有適配器及其狀態
/platform pause <name>          # 停止向某個適配器派送新訊息
/platform resume <name>         # 重新啟用已暫停的適配器

/platform list 顯示每個適配器是 running（運行中）、paused（手動暫停）還是 paused-by-breaker（見下文）。暫停會保持適配器載入且其背景迴圈存活——傳入的訊息會被丟棄，但連線本身保持開啟，因此恢復是即時的。

另請參閱更完整的狀態摘要指令 /platforms。

自動斷路器

每個適配器都被包裹在斷路器中。反覆發生的可重試失敗（網路閃斷、速率限制回應、5xx 上游回應、WebSocket 斷線）會導致斷路器跳閘——適配器會自動暫停，當另一個運行中的平台設定為主頻道時會傳送營運通知，並輸出結構化的日誌行。

斷路器不會自動恢復——它會保持開啟狀態，直到你手動執行 /platform resume <name>。這是刻意的設計：如果某個平台處於持續停機狀態，你不希望閘道器不斷嘗試重連。

平台暫停時的排查指南

當適配器被暫停時，請檢查：

1. 閘道器日誌（~/.hermes/logs/gateway.log 或 systemd / launchd 單元日誌）。搜尋平台名稱和 circuit breaker、paused 或 disabled。跳閘事件包含失敗次數和最後的錯誤。
2. /platform list 輸出——顯示目前狀態和最後原因。
3. 提供者的狀態頁面（Telegram Bot API 狀態、Discord 狀態等）。斷路器跳閘是因為平台不健康；在它恢復之前不要嘗試恢復。

當上游恢復正常後，/platform resume <name> 會清除斷路器並重新啟用適配器。

重啟通知

當閘道器重啟（或在有進行中工作階段時關閉），它會向每個平台的主頻道發送一次性訊息，告知「Agent 已恢復」或「Agent 被中斷」。這由 gateway-config.yaml 中各平台的 gateway_restart_notification 標誌控制，預設為 true：

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # 針對此平台停用
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification 省略 → 預設為 true

在嘈雜或低優先度的平台上停用它，同時在主要聊天上保持啟用。通知每次重啟時發送一次，不論有多少進行中的工作階段。

閘道器重啟後的工作階段恢復

當閘道器在有進行中的工具呼叫或生成時關閉，受影響的工作階段會被標記為 restart_interrupted。在下次啟動時，閘道器會為每個工作階段安排自動恢復——使用者會在聊天中收到簡短提示（「重啟後傳送任何訊息，我會嘗試恢復你上次的進度。」），當使用者回覆時，工作階段會從最後一次已提交的回合繼續。

此行為預設啟用，並在閘道器啟動時記錄：

Scheduled auto-resume for N restart-interrupted session(s)

無需設定。如果你不想要這個提示，可以在平台上設定 gateway_restart_notification: false。

行動裝置友善的進度預設值

Telegram 通常是行動裝置的收件匣，因此預設值針對此情境進行了調整：

• tool_progress 預設為 off — 不會有每個工具的面包屑串流填滿聊天。
• busy_ack_detail 預設為 off — 快速確認和長時間運行的心跳訊息保持簡潔（沒有 iteration 21/60 的除錯細節）。
• interim_assistant_messages 保持啟用 — 真實的回合中間助手評論（模型字面告訴你它接下來要做什麼）是有用的訊號，不是噪音。
• long_running_notifications 保持啟用 — 一個原地更新的「⏳ Working — N min」訊息泡泡每隔幾分鐘更新一次，讓你有心跳感，而不是盯著 typing… 看半小時。

你可以在各平台上選擇退出預設啟用的選項，或重新啟用詳細的進度顯示：

display:
  platforms:
    telegram:
      # 重新啟用工具進度串流
      tool_progress: new
      # 在心跳和忙碌確認中顯示「iteration N/M, running: tool」
      busy_ack_detail: true
      # 或完全靜音
      interim_assistant_messages: false
      long_running_notifications: false

進度泡泡清理（選擇啟用）

工具進度訊息、「仍在工作中……」的心跳和狀態回呼泡泡也可以在最終回覆送達後自動刪除。透過 display.platforms.<platform>.cleanup_progress 按平台啟用：

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

預設為 false。僅在適配器實作了 delete_message 的平台上生效（目前為 Telegram 和 Discord）。失敗的執行會跳過清理，因此泡泡會保留作為面包屑。

下一步

• Telegram 設定
• Discord 設定
• Slack 設定
• Google Chat 設定
• WhatsApp 設定
• WhatsApp Business Cloud API 設定
• Signal 設定
• SMS 設定 (Twilio)
• Email 設定
• Home Assistant 整合
• Mattermost 設定
• Matrix 設定
• DingTalk 設定
• Feishu/Lark 設定
• WeCom 設定
• WeCom Callback 設定
• Weixin 設定 (WeChat)
• BlueBubbles 設定 (iMessage)
• QQBot 設定
• Yuanbao 設定
• Microsoft Teams 設定
• Teams 會議管線
• Open WebUI + API Server
• Webhooks

---

---

Telegram