跳到主要內容

Matrix 配置

Hermes Agent 集成了 Matrix，這一開放的、聯邦式的消息協議。Matrix 允許你運行自己的主服務器（homeserver），或使用公開的服務器如 matrix.org —— 無論哪種方式，你都能掌控自己的通信。該機器人通過 matrix-nio Python SDK 連接，將消息通過 Hermes Agent 的處理管道（包括工具使用、記憶和推理）進行處理，並實時響應。它支持文本、文件附件、圖片、音頻、視頻，以及可選的端到端加密（E2EE）。

Hermes 可與任何 Matrix 主服務器配合使用 —— Synapse、Conduit、Dendrite 或 matrix.org。

在開始配置前，這裡是你最關心的部分：Hermes 連接後的行為表現。

Hermes 的行為表現​

上下文行為
私聊（DMs）Hermes 對每條消息都會響應，無需 @mention。每個私聊擁有獨立的會話。設置 MATRIX_DM_MENTION_THREADS=true 可在機器人被 @mentioned 時啟動線程。
房間（Rooms）默認情況下，Hermes 需要 @mention 才會響應。設置 MATRIX_REQUIRE_MENTION=false 或將房間 ID 添加到 MATRIX_FREE_RESPONSE_ROOMS 可啟用自由響應房間。房間邀請會自動接受。
線程（Threads）Hermes 支持 Matrix 線程（MSC3440）。如果你在某個線程中回覆，Hermes 會將線程上下文與主房間時間線隔離。對於機器人已參與過的線程，無需再次提及。
自動線程創建默認情況下，Hermes 會為每個在房間中回覆的消息自動創建一個線程。這有助於保持對話的隔離性。設置 MATRIX_AUTO_THREAD=false 可禁用此功能。
多人共享房間默認情況下，Hermes 在同一房間內為每個用戶保留獨立的會話歷史。兩個人在同一個房間聊天時，不會共享同一份對話記錄，除非你明確禁用此行為。
提示

機器人會在收到邀請時自動加入房間。只需將機器人的 Matrix 用戶邀請到任意房間，它就會加入並開始響應。

Matrix 中的會話模型​

默認情況下：

  • 每個私聊擁有獨立的會話
  • 每個線程擁有獨立的會話命名空間
  • 同一房間內的每個用戶擁有獨立的會話

這由 config.yaml 控制：

group_sessions_per_user: true

僅當你明確希望整個房間共享一個對話時，才將其設為 false：

group_sessions_per_user: false

共享會話在協作型房間中可能有用，但也意味著：

  • 用戶共享上下文增長和 Token 成本
  • 某個人的長時間工具任務可能導致其他人的上下文膨脹
  • 某個人正在進行的任務可能中斷另一個人在同個房間中的後續回覆

提及與線程配置​

你可以通過環境變量或 config.yaml 配置提及和自動線程行為：

matrix:
  require_mention: true           # 需要在房間中@提及（默認值：true）
  free_response_rooms:            # 免提及要求的客房
    - "!abc123:matrix.org"
  auto_thread: true               # 自動創建響應線程（默認值：true）
  dm_mention_threads: false       # 在 DM 中@提及時創建線程（默認值： false）

或通過環境變量：

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
備註

如果你是從一個不支持 MATRIX_REQUIRE_MENTION 的舊版本升級，機器人之前會在房間中對所有消息做出響應。為保留此行為，請設置 MATRIX_REQUIRE_MENTION=false。

本指南將帶你完成完整的設置流程 —— 從創建機器人賬戶到發送第一條消息。

第一步：創建機器人賬戶​

你需要一個 Matrix 用戶賬戶用於機器人。有幾種方式可以實現：

如果你運行自己的主服務器（Synapse、Conduit、Dendrite）：

  1. 使用管理員 API 或註冊工具創建新用戶：
# 突觸示例
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. 選擇一個用戶名，例如 hermes —— 完整的用戶 ID 將為 @hermes:your-server.org。

選項 B：使用 matrix.org 或其他公開主服務器​

  1. 訪問 Element Web 並創建新賬戶。
  2. 為你的機器人選擇一個用戶名（例如 hermes-bot）。

選項 C：使用你自己的賬戶​

你也可以以自己的用戶身份運行 Hermes。這意味著機器人將以你的身份發帖 —— 適用於個人助手場景。

第二步：獲取訪問令牌​

Hermes 需要一個訪問令牌來認證與主服務器的連接。你有兩個選擇：

獲取令牌最可靠的方式：

通過 Element：

  1. 使用機器人賬戶登錄 Element。
  2. 進入 設置 → 幫助與關於。
  3. 向下滾動並展開 高級 —— 訪問令牌會顯示在此處。
  4. 立即複製它。

通過 API：

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:your-server.org",
    "password": "your-password"
  }'

響應中包含 access_token 字段 —— 請複製該值。

請妥善保管你的訪問令牌

訪問令牌將賦予對機器人 Matrix 賬戶的完全訪問權限。切勿公開分享或提交到 Git。若被洩露，請通過註銷該用戶的全部會話來撤銷。

選項 B：密碼登錄​

你也可以不提供訪問令牌，而是提供機器人的用戶 ID 和密碼。Hermes 將在啟動時自動登錄。這種方式更簡單，但意味著密碼會存儲在你的 .env 文件中。

MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password

第三步：查找你的 Matrix 用戶 ID​

Hermes Agent 使用你的 Matrix 用戶 ID 來控制誰可以與機器人互動。Matrix 用戶 ID 的格式為 @username:server。

要查找你的用戶 ID：

  1. 打開 Element（或您偏好的 Matrix 客戶端）。
  2. 點擊您的頭像 → 設置。
  3. 您的用戶 ID 會顯示在個人資料頂部（例如：@alice:matrix.org）。
提示

Matrix 用戶 ID 始終以 @ 開頭，幷包含一個 : 後跟服務器名稱。例如：@alice:matrix.org、@bob:your-server.com。

第 4 步：配置 Hermes Agent​

運行引導式設置命令：

hermes gateway setup

當提示時選擇 Matrix，然後提供您的主服務器 URL、訪問令牌（或用戶 ID + 密碼），以及允許的用戶 ID。

選項 B：手動配置​

將以下內容添加到您的 ~/.hermes/.env 文件中：

使用訪問令牌：

# 必填
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# 可選：用戶 ID（如果省略，則從 token 自動檢測）
# MATRIX_USER_ID=@hermes:matrix.example.org

# 安全：限制哪些用戶可以與機器人交互
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# 多個允許用戶（用逗號分隔）
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

使用密碼登錄：

# 必填
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# 安全
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

可選的行為設置項，位於 ~/.hermes/config.yaml 中：

group_sessions_per_user: true
  • group_sessions_per_user: true 會在共享房間中為每位參與者保持上下文隔離

啟動網關​

配置完成後，啟動 Matrix 網關：

hermes gateway

機器人應在幾秒內連接到您的主服務器並開始同步。向它發送一條消息——無論是私信還是它已加入的房間中的消息——以進行測試。

提示

您可以將 hermes gateway 在後臺運行，或作為 systemd 服務運行以實現持久化操作。詳情請參閱部署文檔。

端到端加密（E2EE）​

Hermes 支持 Matrix 端到端加密，因此您可以在加密房間中與機器人聊天。

要求​

E2EE 需要安裝帶有加密擴展的 matrix-nio 庫以及 libolm C 庫：

# 安裝 matrix-nio 並支持 E2EE
pip install 'matrix-nio[e2e]'

# 或者使用 hermes extras 安裝
pip install 'hermes-agent[matrix]'

您還需要在系統上安裝 libolm：

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

啟用 E2EE​

將以下內容添加到您的 ~/.hermes/.env 文件中：

MATRIX_ENCRYPTION=true

啟用 E2EE 後，Hermes 將：

  • 將加密密鑰存儲在 ~/.hermes/platforms/matrix/store/ 目錄中（舊版安裝：~/.hermes/matrix/store/）
  • 在首次連接時上傳設備密鑰
  • 自動解密傳入消息並加密傳出消息
  • 在收到邀請時自動加入加密房間
注意

如果您刪除了 ~/.hermes/platforms/matrix/store/ 目錄，機器人將丟失其加密密鑰。您需要在 Matrix 客戶端中重新驗證該設備。若要保留加密會話，請備份此目錄。

信息

如果未安裝 matrix-nio[e2e] 或缺少 libolm，機器人將自動降級為非加密（明文）客戶端。您將在日誌中看到警告信息。

主房間​

您可以指定一個“主房間”，機器人將在其中發送主動消息（如定時任務輸出、提醒和通知）。有兩種設置方式：

使用斜槓命令​

在機器人所在的任意 Matrix 房間中輸入 /sethome。該房間將成為主房間。

手動配置​

將以下內容添加到您的 ~/.hermes/.env 文件中：

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org
提示

要查找房間 ID：在 Element 中，進入房間 → 設置 → 高級 → 顯示的 內部房間 ID 即為所求（以 ! 開頭）。

故障排除​

機器人未響應消息​

原因：機器人尚未加入房間，或 MATRIX_ALLOWED_USERS 中未包含您的用戶 ID。

解決方法：邀請機器人加入房間——它會在收到邀請後自動加入。確認您的用戶 ID 已包含在 MATRIX_ALLOWED_USERS 中（使用完整格式 @user:server）。重啟網關。

啟動時出現“認證失敗” / “whoami 失敗”​

原因：訪問令牌或主服務器 URL 錯誤。

解決方法：驗證 MATRIX_HOMESERVER 是否指向您的主服務器（請包含 https://，不要加尾部斜槓）。檢查 MATRIX_ACCESS_TOKEN 是否有效——嘗試使用 curl 測試：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/_matrix/client/v3/account/whoami

如果返回您的用戶信息，則令牌有效。如果返回錯誤，請生成新的令牌。

出現“matrix-nio 未安裝”錯誤​

原因：matrix-nio Python 包未安裝。

解決方法：安裝它：

pip install 'matrix-nio[e2e]'

或使用 Hermes 的附加組件安裝：

pip install 'hermes-agent[matrix]'

加密錯誤 / “無法解密事件”​

原因：缺少加密密鑰、libolm 未安裝，或機器人的設備未被信任。

解決方法：

  1. 確認系統上已安裝 libolm（參見上文 E2EE 部分）。
  2. 確保 .env 文件中設置了 MATRIX_ENCRYPTION=true。
  3. 在您的 Matrix 客戶端（Element）中，進入機器人的個人資料 → 會話 → 驗證/信任機器人的設備。
  4. 如果機器人剛剛加入加密房間，它只能解密在加入之後發送的消息。舊消息將無法訪問。

同步問題 / 機器人落後​

原因：長時間運行的工具執行會延遲同步循環，或主服務器響應緩慢。

解決方法：同步循環在出錯時會自動每 5 秒重試一次。檢查 Hermes 日誌中是否有與同步相關的警告。如果機器人持續落後，請確保您的主服務器具備足夠的資源。

機器人離線​

原因：Hermes 網關未運行，或連接失敗。

解決方法：檢查 hermes gateway 是否正在運行。查看終端輸出中的錯誤信息。常見問題包括：主服務器 URL 錯誤、訪問令牌過期、主服務器無法訪問。

“用戶不允許” / 機器人忽略你​

原因：你的用戶 ID 未包含在 MATRIX_ALLOWED_USERS 中。

解決方法：將你的用戶 ID 添加到 ~/.hermes/.env 文件中的 MATRIX_ALLOWED_USERS，然後重啟網關。請使用完整的 @user:server 格式。

安全性​

注意

始終設置 MATRIX_ALLOWED_USERS 以限制可以與機器人交互的用戶。如果沒有設置，網關會默認拒絕所有用戶，這是一種安全措施。僅添加你信任的用戶的用戶 ID —— 授權用戶將擁有對 Agent 所有功能的完全訪問權限，包括工具使用和系統訪問。

有關保護你的 Hermes Agent 部署的更多信息，請參閱 安全指南。

注意事項​

  • 任意主服務器：支持 Synapse、Conduit、Dendrite、matrix.org 或任何符合規範的 Matrix 主服務器。無需特定的主服務器軟件。
  • 聯邦通信：如果你使用的是聯邦主服務器，機器人可以與來自其他服務器的用戶通信 —— 只需將他們的完整 @user:server 用戶 ID 添加到 MATRIX_ALLOWED_USERS 即可。
  • 自動加入：機器人會自動接受房間邀請並加入。加入後立即開始響應。
  • 媒體支持：Hermes 可以發送和接收圖片、音頻、視頻和文件附件。媒體將通過 Matrix 內容倉庫 API 上傳至你的主服務器。
  • 原生語音消息（MSC3245）：Matrix 適配器會自動為傳出的語音消息標記 org.matrix.msc3245.voice 標誌。這意味著 TTS 響應和語音音頻將在 Element 及其他支持 MSC3245 的客戶端中以 原生語音氣泡 形式顯示，而非普通音頻文件附件。帶有 MSC3245 標誌的傳入語音消息也會被正確識別並路由至語音轉文本轉錄。無需任何配置 —— 此功能可自動生效。