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

章節：通訊平台 · 網址：https://hermesbible.com/docs/user-guide/messaging/matrix

Matrix 設定

Hermes Agent 整合了 Matrix — 一套開放式的聯邦通訊協定。Matrix 讓你可以架設自己的 homeserver，或使用 matrix.org 等公共伺服器 — 無論哪種方式，你都能保有通訊的控制權。機器人透過 mautrix Python SDK 連線，透過 Hermes Agent 管線（包含工具使用、記憶體和推理）處理訊息，並即時回應。支援文字、檔案附件、圖片、音訊、影片，以及可選的端對端加密（E2EE）。

Hermes 可搭配任何 Matrix homeserver 運作 — Synapse、Conduit、Dendrite 或 matrix.org。

在設定之前，以下是大多數人最想知道的：Hermes 連線後的行為方式。

Hermes 的行為

提示

機器人會在收到邀請時自動加入聊天室。只要將機器人的 Matrix 使用者邀請至任何聊天室，它就會加入並開始回應。

功能矩陣

此表格由 Matrix 適配器功能宣告和 Matrix 測試覆蓋率支持。E2EE 為模式制，因為部署者需選擇加密聊天室是停用、可選還是強制。

Matrix 中的 Session 模型

預設情況下：

• 每則私訊有自己的 session
• 每個討論串有自己的 session 命名空間
• 共享聊天室中的每位使用者在該聊天室中有自己的 session

這由 config.yaml 控制：

group_sessions_per_user: true

僅在你明確希望整個聊天室共用一個對話時才設為 false：

group_sessions_per_user: false

共享 session 對協作聊天室很有用，但也代表：

• 使用者共享 context 增長和 token 成本
• 某人長時間、大量使用工具的任務會膨脹其他人的 context
• 某人正在進行中的執行可能會打斷同聊天室中其他人的後續操作

提及和討論串設定

你可以透過環境變數或 config.yaml 設定提及和自動討論串行為：

matrix:
  require_mention: true           # 在聊天室中要求 @提及（預設：true）
  allowed_users:                  # 允許觸發 agent 回合的 Matrix 使用者
    - "@alice:matrix.org"
  allowed_rooms:                  # 允許觸發 agent 回合的 Matrix 聊天室
    - "!abc123:matrix.org"
  free_response_rooms:            # 免除提及要求的聊天室
    - "!abc123:matrix.org"
  ignore_user_patterns:           # 橋接器/應用服務幽靈使用者忽略清單
    - "^@telegram_"
    - "^@whatsapp_"
  process_notices: false          # 預設忽略 m.notice
  session_scope: room             # auto|room|thread；推薦用於專案聊天室的 room
  auto_thread: true               # 為回應自動建立討論串（預設：true）
  dm_mention_threads: false       # 在私訊中被 @提及時建立討論串（預設：false）

或透過環境變數：

MATRIX_REQUIRE_MENTION=true
MATRIX_ALLOWED_USERS=@alice:matrix.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.org
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@whatsapp_'
MATRIX_PROCESS_NOTICES=false
MATRIX_SESSION_SCOPE=room       # 推薦用於穩定的專案聊天室 context
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # 預設：true — 處理過程中的表情回應
MATRIX_ALLOW_ROOM_MENTIONS=false

提示 — 停用表情回應

MATRIX_REACTIONS=false 會關閉機器人在收到訊息時發布的處理生命週期表情回應（👀/✅/❌）。適用於表情回應事件嘈雜或所有參與客戶端不支援的聊天室。

提示 — 全聊天室提及

Hermes 會為如 @alice:example.org 等明確的 Matrix ID 發送結構化的 Matrix 使用者提及。全聊天室的 @room 通知預設停用；僅在機器人被允許通知所有人時才設定 MATRIX_ALLOW_ROOM_MENTIONS=true。

備註

如果你從未包含 MATRIX_REQUIRE_MENTION 的版本升級，機器人先前會回應聊天室中的所有訊息。如要保留此行為，請設定 MATRIX_REQUIRE_MENTION=false。

專案聊天室隔離

如果你在同一 Matrix 機器人用於多個專案聊天室，請設定穩定的聊天室範圍 session：

MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=false

MATRIX_SESSION_SCOPE 接受以下值：

Hermes 現在在 agent 提示中包含當前 Matrix 聊天室名稱、聊天室 ID、主題、訊息 ID，以及 Matrix 聊天室邊界說明。/status 也會顯示當前 Matrix 聊天室/session 範圍，而 /resume 不會靜默地從另一個 Matrix 聊天室恢復命名 session，除非你明確使用 /resume --cross-room <session 名稱>。

MATRIX_SESSION_SCOPE=room 控制聊天室/討論串通道。現有的 group_sessions_per_user 設定仍控制該聊天室內的使用者是否共用通道。當 group_sessions_per_user: true（預設）時，Alice 和 Bob 在專案 B 中有各自的 session。當 group_sessions_per_user: false 時，該聊天室有一份共用的專案 B 對話記錄。

本指南將引導你完成完整的設定流程 — 從建立機器人帳號到發送第一則訊息。

步驟 1：建立機器人帳號

你需要一個 Matrix 使用者帳號作為機器人。有幾種方式可以達成：

選項 A：在你的 Homeserver 上註冊（推薦）

如果你架設自己的 homeserver（Synapse、Conduit、Dendrite）：

1. 使用管理 API 或註冊工具建立新使用者：

# Synapse 範例
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

2. 選擇像 hermes 這樣的使用者名稱 — 完整的使用者 ID 將為 @hermes:your-server.org。

選項 B：使用 matrix.org 或其他公共 Homeserver

1. 前往 Element Web 並建立新帳號。
2. 為你的機器人選擇一個使用者名稱（例如 hermes-bot）。

選項 C：使用你自己的帳號

你也可以將 Hermes 作為自己的使用者來運行。這代表機器人會以你的身份發送訊息 — 適合個人助理用途。

步驟 2：取得 Access Token

Hermes 需要一個 access token 來向 homeserver 驗證身份。你有兩個選項：

選項 A：Access Token（推薦）

取得 token 最可靠的方式：

透過 Element：

1. 使用機器人帳號登入 Element。
2. 前往 設定 → 說明與關於。
3. 向下捲展開 進階 — access token 會顯示在那裡。
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 欄位 — 將它複製起來。

:::warning[妥善保管你的 access token] Access token 可完整存取機器人的 Matrix 帳號。絕對不要公開分享或提交到 Git。如果洩露，請透過登出該使用者的所有 session 來撤銷它。 :::

選項 B：密碼登入

你不必提供 access token，而是提供機器人的使用者 ID 和密碼。Hermes 會在啟動時自動登入。這比較簡單，但代表密碼會儲存在你的 .env 檔案中。

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

步驟 3：找出你的 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

選項 A：互動式設定（推薦）

執行引導設定指令：

hermes gateway setup

在提示時選擇 Matrix，然後在詢問時提供你的 homeserver URL、access token（或使用者 ID + 密碼）以及允許的使用者 ID。

選項 B：手動設定

在你的 ~/.hermes/.env 檔案中加入以下內容：

使用 access token：

# 必要
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_ROOMS=!abc123: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

私有部署強化

對於私有 Matrix 部署，請同時設定使用者和聊天室允許清單。如果 MATRIX_ALLOWED_USERS 未設定，任何在已加入聊天室中能觸及機器人的發送者都能觸發 agent 回合。如果 MATRIX_ALLOWED_ROOMS 未設定，機器人加入的任何聊天室都能觸發 agent 回合。嚴格的部署應同時設定兩者：

MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
MATRIX_ALLOWED_ROOMS=!ops:matrix.example.org,!dmroom:matrix.example.org

橋接器和應用服務部署需要額外的迴圈保護。Hermes 預設會忽略自己的事件、localpart 以 _ 開頭的 Matrix 應用服務使用者、重複事件 ID、舊的啟動事件、編輯替換事件以及 m.notice 事件。當你的橋接器使用不同的命名慣例時，新增部署專用的橋接器幽靈模式：

MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@slack_,^@whatsapp_'

僅在可信的人工工作流程確實發送 m.notice 時才啟用通知：

MATRIX_PROCESS_NOTICES=true

出站的全聊天室通知預設停用。除非機器人被明確允許以 @room 喚醒整個聊天室，否則請保持 MATRIX_ALLOW_ROOM_MENTIONS=false。

診斷和偵錯載荷會編輯 Matrix access token、恢復金鑰、裝置識別碼和訊息本文。媒體下載僅限於 Matrix mxc:// 內容 URI，並在超過 MATRIX_MAX_MEDIA_BYTES 時被拒絕。將聯邦聊天室和不受信任的 homeserver 視為不受信任的輸入：保持聊天室允許清單嚴格，對大量使用工具的工作優先使用私訊或私人聊天室，並避免授權橋接器幽靈或應用服務傀儡為允許的使用者。

~/.hermes/config.yaml 中的選擇性行為設定：

group_sessions_per_user: true

• group_sessions_per_user: true 在共享聊天室中保持每位參與者的 context 隔離

啟動閘道

設定完成後，啟動 Matrix 閘道：

hermes gateway

機器人應在幾秒內連線到你的 homeserver 並開始同步。發送一則訊息 — 私訊或在它已加入的聊天室中 — 來測試。

提示

你可以將 hermes gateway 在背景執行或作為 systemd 服務以持續運作。詳情請參閱部署文件。

端對端加密（E2EE）

Hermes 支援 Matrix 端對端加密，讓你可以在加密聊天室中與機器人對話。

需求

E2EE 需要包含加密額外元件的 mautrix 函式庫和 libolm C 函式庫：

# 安裝具備 E2EE 支援的 mautrix
pip install 'mautrix[encryption]'

# 或使用 hermes 額外元件安裝
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_E2EE_MODE=required

MATRIX_E2EE_MODE 接受以下值：

Optional 模式在加密設定不可用時可能回退至非 E2EE 運作。Required 模式會直接失敗而非靜默降級。

為向後相容，MATRIX_ENCRYPTION=true 仍會啟用 required E2EE 行為。

啟用 E2EE 時，Hermes 會：

• 將加密金鑰儲存在 ~/.hermes/platforms/matrix/store/（舊版安裝：~/.hermes/matrix/store/）
• 首次連線時上傳裝置金鑰
• 自動解密收到的訊息並加密發送的訊息
• 收到邀請時自動加入加密聊天室

Matrix 工具和控制

在 Matrix 對話中，Hermes 會向 agent 暴露 Matrix 專用工具：

• matrix_send_reaction
• matrix_redact_message
• matrix_create_room
• matrix_invite_user
• matrix_fetch_history
• matrix_set_presence

這些工具限定於 Matrix 情境，在非 Matrix 工具集中不可用。管理員類型工具預設停用：編輯需要 MATRIX_TOOLS_ALLOW_REDACTION=true，邀請需要 MATRIX_TOOLS_ALLOW_INVITES=true，建立聊天室需要 MATRIX_TOOLS_ALLOW_ROOM_CREATE=true。建立公開聊天室還需要 MATRIX_ALLOW_PUBLIC_ROOMS=true。 Matrix 工具預設僅限於當前 Matrix 聊天室。明確的跨聊天室目標需要 MATRIX_TOOLS_ALLOW_CROSS_ROOM=true；編輯和邀請類型的跨聊天室操作還需要 MATRIX_TOOLS_ALLOW_CROSS_ROOM_DESTRUCTIVE=true。如果設定了 MATRIX_ALLOWED_ROOMS，Matrix 工具可能僅能針對這些聊天室。

回應控制使用：

• ✅ 一次核准
• ♾️ 永遠核准
• ❌ 拒絕
• 數字回應用於 /model 選擇

設定 MATRIX_APPROVAL_REQUIRE_SENDER=false 可讓聊天室中任何已授權的 Matrix 使用者操作核准/模型選擇器提示。預設為綁定請求者，當 Hermes 知道是誰發起請求時。

媒體限制

Hermes 透過 Matrix 媒體 API 上傳和下載 Matrix 圖片、檔案、音訊和影片。多張生成的圖片會作為一個有序的邏輯批次發送，跨批次保留說明文字和討論串脈絡。

預設情況下，超過 100 MB 的 Matrix 媒體會在上傳/下載前被拒絕。可透過以下方式覆蓋：

MATRIX_MAX_MEDIA_BYTES=104857600

入站媒體必須使用 Matrix mxc:// 內容 URI。Hermes 會拒絕 Matrix 事件中的任意 HTTP(S) 媒體 URL，以避免將聯邦聊天室變成不受限制的下載器。

Synapse 整合測試

Hermes 包含一個可選用的 Synapse 測試框架，用於本地驗證：

docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml up -d
HERMES_MATRIX_SYNAPSE_INTEGRATION=1 \
  scripts/run_tests.sh -m "integration and matrix_synapse" \
  tests/e2e/matrix_synapse_gateway/test_gateway.py
docker compose -f tests/e2e/matrix_synapse_gateway/docker-compose.yml down -v

該框架透過 Synapse shared-secret 註冊建立臨時使用者，涵蓋私人聊天室的發送/接收、命名聊天室的邀請/加入、媒體上傳/下載、機器人回應傳遞，以及啟動時的舊事件過濾。E2EE 冒煙測試覆蓋率另外以 matrix_e2ee 標記，以便在開發者機器上保持可選用。

交叉簽署驗證（推薦）

如果你的 Matrix 帳號啟用了交叉簽署（Element 中的預設設定），請設定恢復金鑰，讓機器人在啟動時能自行簽署其裝置。如果沒有設定，其他 Matrix 客戶端在裝置金鑰輪換後可能會拒絕與機器人共用加密 session。

MATRIX_RECOVERY_KEY=EsT... your recovery key here

在哪裡找到它： 在 Element 中，前往 設定 → 安全性與隱私 → 加密 → 你的恢復金鑰（也稱為「安全金鑰」）。這是你在首次設定交叉簽署時被要求儲存的金鑰。

每次啟動時，如果設定了 MATRIX_RECOVERY_KEY，Hermes 會從 homeserver 的安全密鑰儲存中匯入交叉簽署金鑰並簽署當前裝置。這是冪等的，可以永久啟用。

如果 Hermes 建立了新的 Matrix 恢復金鑰，它永遠不會記錄原始金鑰。在啟動前設定 MATRIX_RECOVERY_KEY_OUTPUT_FILE=/secure/path/matrix-recovery-key.txt 可將生成的金鑰寫入一次，檔案模式為 0600；如果檔案已存在則不會被覆蓋。

:::warning[刪除加密儲存] 如果你刪除 ~/.hermes/platforms/matrix/store/crypto.db，機器人會失去其加密身份。僅使用相同的裝置 ID 重新啟動不會完全恢復 — homeserver 仍然持有以舊身份金鑰簽署的一次性金鑰，且對等端無法建立新的 Olm session。

Hermes 在啟動時會偵測此情況並拒絕啟用 E2EE，記錄：device XXXX has stale one-time keys on the server signed with a previous identity key。

最簡單的恢復方式：產生新的 access token（這會獲得一個沒有過時金鑰歷史的新裝置 ID）。請參閱下方「從先前版本升級（含 E2EE）」章節。這是最可靠的方式，無需觸碰 homeserver 資料庫。

手動恢復（進階 — 保留相同的裝置 ID）：

1. 停止 Synapse 並從資料庫中刪除舊裝置：

   sudo systemctl stop matrix-synapse
   sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
     DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
     DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
   "
   sudo systemctl start matrix-synapse
   

   或透過 Synapse 管理 API（注意 URL 編碼的使用者 ID）：

   curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
     'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID'
   

   注意：透過管理 API 刪除裝置可能也會使相關的 access token 失效。你可能需要之後產生新的 token。

2. 刪除本地加密儲存並重啟 Hermes：

   rm -f ~/.hermes/platforms/matrix/store/crypto.db*
   # 重啟 hermes
   

其他 Matrix 客戶端（Element、matrix-commander）可能會快取舊的裝置金鑰。恢復後，在 Element 中輸入 /discardsession 以強制與機器人建立新的加密 session。 :::

資訊

如果未安裝 mautrix[encryption] 或缺少 libolm，機器人會自動回退為一般（未加密）客戶端。你會在日誌中看到警告。

主聊天室

你可以指定一個「主聊天室」，機器人會在其中發送主動訊息（例如定時工作輸出、提醒和通知）。有兩種設定方式：

使用斜線指令

在機器人所在的任何 Matrix 聊天室中輸入 /sethome。該聊天室就會成為主聊天室。 如果你的 Matrix 客戶端攔截了斜線指令，請改輸入 !sethome。

手動設定

在你的 ~/.hermes/.env 中加入：

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

聊天室允許清單（allowed_rooms）

限制機器人僅限於一組固定的 Matrix 聊天室。設定後，機器人僅在 ID 出現於清單中的聊天室回應 — 來自其他聊天室的訊息會被靜默忽略，即使機器人被提及。

私訊（直接聊天室）不受此過濾器限制，因此已授權的使用者始終可以一對一觸及機器人。

matrix:
  allowed_rooms:
    - "!abc123def456:matrix.example.org"
    - "!opsroom789:matrix.example.org"

或透過環境變數（逗號分隔）：

MATRIX_ALLOWED_ROOMS="!abc123def456:matrix.example.org,!opsroom789:matrix.example.org"

行為：

• 空 / 未設定 → 無限制（預設）。
• 非空 → 聊天室 ID 必須在清單中。檢查在任何其他門檻（提及要求、發送者允許清單等）之前執行。
• 使用聊天室的內部 ID（!abc...:server），而非其別名（#room:server）。你可以在 Element 中透過 聊天室 → 設定 → 進階 找到聊天室的內部 ID。

另請參閱：管理員/使用者斜線指令分割。

提示

要找出聊天室 ID：在 Element 中，前往聊天室 → 設定 → 進階 → 內部聊天室 ID 顯示在那裡（以 ! 開頭）。

Matrix 中的指令

Hermes 在 Matrix 中支援與其他通訊平台相同的閘道指令，包括 /commands、/model、/stop、/queue、/steer、/goal、/subgoal、/background、/bg、/btw、/tasks 和 /yolo。

部分 Matrix 客戶端將前導 / 保留給本地客戶端指令，可能不會將未知的斜線指令發送到聊天室。在這種情況下，使用 ! 作為 Matrix 安全的別名：

!commands
!model
!model gpt-5.5 --provider openrouter
!queue continue with the next task
!stop

Hermes 僅在指令是閘道已知的指令、已註冊的外掛指令或已安裝的技能指令時才標準化 !command。一般的驚嘆語句如 !important 仍為普通聊天訊息。

疑難排解

機器人不回應訊息

原因：機器人未加入聊天室、MATRIX_ALLOWED_USERS 不包含你的使用者 ID、MATRIX_ALLOWED_ROOMS 不包含該聊天室，或聊天室訊息未提及機器人。

修正：將機器人邀請到聊天室 — 它會在收到邀請時自動加入。驗證你的使用者 ID 在 MATRIX_ALLOWED_USERS 中（使用完整的 @user:server 格式），且聊天室 ID 在 MATRIX_ALLOWED_ROOMS 中（如果設定了該允許清單）。在聊天室中，提及機器人或將聊天室加入 MATRIX_FREE_RESPONSE_ROOMS。重啟閘道。

機器人加入聊天室但靜默丟棄所有訊息（時鐘偏差）

原因：主機的系統時鐘設定超前於實際時間。Matrix 適配器套用 5 秒的啟動寬限過濾器（event_ts < startup_ts - 5）來忽略從初始同步重播的事件。當牆上時鐘超前時，每個傳入事件看起來都「比啟動更舊」，在到達訊息處理器之前就被丟棄 — 機器人看似已連線但從不回覆。請參閱 #12614。

症狀：閘道日誌顯示 Matrix: dropped N live events as 'too old' more than 30s after startup。

修正：使用 NTP 同步主機時鐘並重啟機器人：

# Debian/Ubuntu
sudo timedatectl set-ntp true
timedatectl status   # 確認 "System clock synchronized: yes"

# macOS
sudo sntp -sS time.apple.com

啟動時出現「Failed to authenticate」或「whoami failed」

原因：access token 或 homeserver URL 不正確。

修正：驗證 MATRIX_HOMESERVER 指向你的 homeserver（包含 https://，無尾部斜線）。檢查 MATRIX_ACCESS_TOKEN 是否有效 — 用 curl 試試：

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

如果回傳你的使用者資訊，token 就是有效的。如果回傳錯誤，請產生新的 token。

「mautrix not installed」錯誤

原因：未安裝 mautrix Python 套件。

修正：安裝它：

pip install 'mautrix[encryption]'

或使用 Hermes 額外元件：

pip install 'hermes-agent[matrix]'

加密錯誤 / 「could not decrypt event」

原因：缺少加密金鑰、未安裝 libolm，或機器人的裝置未受信任。

修正：

1. 驗證 libolm 已安裝在你的系統上（請參閱上方 E2EE 章節）。
2. 確認 .env 中已設定 MATRIX_ENCRYPTION=true。
3. 在你的 Matrix 客戶端（Element）中，前往機器人的個人頁面 -> Sessions -> 驗證/信任機器人的裝置。
4. 如果機器人剛加入加密聊天室，它只能解密在它加入之後發送的訊息。較舊的訊息無法存取。

從先前版本升級（含 E2EE）

提示

如果你也手動刪除了 crypto.db，請參閱上方 E2EE 章節中的「刪除加密儲存」警告 — 有額外步驟需要從 homeserver 清除過時的一次性金鑰。

如果你先前使用過帶有 MATRIX_ENCRYPTION=true 的 Hermes，且正在升級到使用新的 SQLite 加密儲存的版本，機器人的加密身份已變更。你的 Matrix 客戶端（Element）可能會快取舊的裝置金鑰，並拒絕與機器人共用加密 session。

症狀：機器人連線並在日誌中顯示「E2EE enabled」，但所有訊息都顯示「could not decrypt event」，且機器人從不回覆。

發生的原因：舊的加密狀態（來自先前的 matrix-nio 或基於序列化的 mautrix 後端）與新的 SQLite 加密儲存不相容。機器人建立了全新的加密身份，但你的 Matrix 客戶端仍然快取著舊金鑰，且不會與金鑰已變更的裝置共用聊天室的加密 session。這是 Matrix 的安全功能 — 客戶端會將相同裝置的身份金鑰變更視為可疑行為。

修正（一次性遷移）：

1. 產生新的 access token 以取得新的裝置 ID。最簡單的方式：

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

   複製新的 access_token 並更新 ~/.hermes/.env 中的 MATRIX_ACCESS_TOKEN。

2. 刪除舊的加密狀態：

   rm -f ~/.hermes/platforms/matrix/store/crypto.db
   rm -f ~/.hermes/platforms/matrix/store/crypto_store.*
   

3. 設定你的恢復金鑰（如果你使用交叉簽署 — 大多數 Element 使用者皆如此）。在 ~/.hermes/.env 中加入：

   MATRIX_RECOVERY_KEY=EsT... your recovery key here
   

   這讓機器人能在啟動時使用交叉簽署金鑰自行簽署，使 Element 立即信任新裝置。如果沒有設定，Element 可能會將新裝置視為未驗證，並拒絕共用加密 session。在 Element 中的 設定 → 安全性與隱私 → 加密 找到你的恢復金鑰。

4. 強制你的 Matrix 客戶端輪換加密 session。在 Element 中，開啟與機器人的私訊聊天室並輸入 /discardsession。這會強制 Element 建立新的加密 session 並與機器人的新裝置共用。

5. 重啟閘道：

   hermes gateway run
   

   如果設定了 MATRIX_RECOVERY_KEY，你應該會在日誌中看到 Matrix: cross-signing verified via recovery key。

6. 發送新訊息。機器人應該能正常解密並回應。

備註

遷移後，升級前發送的訊息無法解密 — 舊的加密金鑰已不存在。這僅影響過渡期間；新訊息正常運作。

提示

新安裝不受影響。 此遷移僅在你先前有可用的 E2EE 設定並使用過先前版本的 Hermes，且正在升級時才需要。

為什麼需要新的 access token？ 每個 Matrix access token 都綁定於特定的裝置 ID。重複使用相同裝置 ID 搭配新加密金鑰會導致其他 Matrix 客戶端不信任該裝置（它們將身份金鑰的變更視為潛在的安全性漏洞）。新的 access token 會獲得一個沒有過時金鑰歷史的新裝置 ID，因此其他客戶端會立即信任它。

代理模式（macOS 上的 E2EE）

Matrix E2EE 需要 libolm，但 libolm 無法在 macOS ARM64（Apple Silicon）上編譯。hermes-agent[matrix] 額外元件僅限 Linux。如果你使用 macOS，代理模式讓你可以在 Linux VM 上的 Docker 容器中運行 E2EE，而實際的 agent 在 macOS 上原生運行，完全存取你的本地檔案、記憶體和技能。

運作方式

macOS（主機）：
  └─ hermes gateway
       ├─ api_server adapter ← 監聽 0.0.0.0:8642
       ├─ AIAgent ← 唯一的事實來源
       ├─ Sessions、記憶體、技能
       └─ 本地檔案存取（Obsidian、專案等）

Linux VM（Docker）：
  └─ hermes gateway（代理模式）
       ├─ Matrix adapter ← E2EE 解密/加密
       └─ HTTP 轉發 → macOS:8642/v1/chat/completions
           （無 LLM API 金鑰、無 agent、無推理）

Docker 容器僅處理 Matrix 協定 + E2EE。當訊息到達時，它會解密並將文字透過標準 HTTP 請求轉發到主機。主機運行 agent、呼叫工具、產生回應並將其串流回去。容器加密並將回應發送到 Matrix。所有 session 是統一的 — CLI、Matrix、Telegram 和任何其他平台共用相同的記憶體和對話歷史。

步驟 1：設定主機（macOS）

啟用 API 伺服器，使主機接受來自 Docker 容器的傳入請求。

在 ~/.hermes/.env 中加入：

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

• API_SERVER_HOST=0.0.0.0 綁定到所有介面，讓 Docker 容器可以連到它。
• API_SERVER_KEY 在非迴圈綁定時為必要。選擇一個強的隨機字串。
• API 伺服器預設在連接埠 8642 上執行（如需變更可使用 API_SERVER_PORT）。

啟動閘道：

hermes gateway

你應該會看到 API 伺服器與其他已設定的平台一起啟動。從 VM 驗證它可達：

# 從 Linux VM
curl http://<mac-ip>:8642/health

步驟 2：設定 Docker 容器（Linux VM）

容器需要 Matrix 憑證和代理 URL。它不需要 LLM API 金鑰。

docker-compose.yml：

services:
  hermes-matrix:
    build: .
    environment:
      # Matrix 憑證
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # 代理模式 — 轉發到主機 agent
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
    volumes:
      - ./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile：

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN pip install 'hermes-agent[matrix]'

CMD ["hermes", "gateway"]

這就是整個容器。不需要 OpenRouter、Anthropic 或任何推理提供者的 API 金鑰。

步驟 3：啟動兩者

1. 先啟動主機閘道：

   hermes gateway
   

2. 啟動 Docker 容器：

   docker compose up -d
   

3. 在加密 Matrix 聊天室中發送訊息。容器解密後轉發到主機，然後將回應串流回來。

設定參考

代理模式在容器端（輕量閘道）設定：

主機端需要：

適用於任何平台

代理模式不限於 Matrix。任何平台適配器都可以使用它 — 在任何閘道實例上設定 GATEWAY_PROXY_URL，它就會轉發到遠端 agent，而非在本地運行。這對任何平台適配器需要與 agent 在不同環境中運行的部署很有用（網路隔離、E2EE 需求、資源限制）。

提示

Session 連續性透過 X-Hermes-Session-Id 標頭維護。主機的 API 伺服器根據此 ID 追蹤 session，因此對話會跨訊息持續存在，就像使用本地 agent 時一樣。

備註

限制（v1）： 遠端 agent 的工具進度訊息不會被轉傳 — 使用者僅能看到串流的最終回應，而非單獨的工具呼叫。危險指令核准提示在主機端處理，不會轉傳給 Matrix 使用者。這些可以在未來的更新中解決。

機器人已連線並可發送，但忽略入站訊息

原因：Matrix 事件處理器僅在同步載荷透過 mautrix 的 handle_sync() 機制分派時才觸發。原始的 client.sync() 輪詢如果從未呼叫 handle_sync()，可能使適配器保持連線（發送有效），但入站訊息永遠不會到達 _on_room_message。

修正：Hermes 使用一個明確的同步迴圈，在初始同步和每個增量同步回應上呼叫 client.handle_sync()。這符合上游 issue #7914 和已關閉的 PR #37807 中的診斷，但保留了 Hermes 自己的背景維護任務（已加入聊天室追蹤、邀請處理、E2EE 金鑰共享），而非將完整生命週期委託給 client.start()。如果閘道重啟後入站訊息仍然失敗，請驗證處理器在第一次同步之前已註冊，並檢查日誌中的 sync event dispatch error。

同步問題 / 機器人落後

原因：長時間運行的工具執行可能延遲同步迴圈，或 homeserver 速度緩慢。

修正：同步迴圈在錯誤時自動每 5 秒重試。檢查 Hermes 日誌中的同步相關警告。如果機器人持續落後，請確保你的 homeserver 有足夠的資源。

機器人離線

原因：Hermes 閘道未運行，或連線失敗。

修正：檢查 hermes gateway 是否正在執行。查看終端機輸出的錯誤訊息。常見問題：錯誤的 homeserver URL、過期的 access token、homeserver 無法連線。

「User not allowed」/ 機器人忽略你

原因：你的使用者 ID 不在 MATRIX_ALLOWED_USERS 中。

修正：在 ~/.hermes/.env 中將你的使用者 ID 加入 MATRIX_ALLOWED_USERS 並重啟閘道。使用完整的 @user:server 格式。

機器人忽略整個聊天室

原因：MATRIX_ALLOWED_ROOMS 已設定且當前聊天室 ID 未列在其中，或聊天室要求提及但訊息未提及機器人。

修正：將聊天室 ID 加入 MATRIX_ALLOWED_ROOMS，或如果是個人部署則移除聊天室允許清單。在 Element 中找尋聊天室 ID：開啟聊天室設定並查看 進階。

橋接器訊息迴圈或回音

原因：橋接器/應用服務傀儡將機器人輸出作為新的使用者訊息轉傳回去，或橋接器使用非標準的幽靈使用者 ID。

修正：將橋接器幽靈排除在 MATRIX_ALLOWED_USERS 之外，新增匹配的 MATRIX_IGNORE_USER_PATTERNS 條目，並保持 MATRIX_PROCESS_NOTICES=false，除非通知是可信工作流程的一部分。

安全性

警告

務必設定 MATRIX_ALLOWED_USERS，對於共享/私人部署也要設定 MATRIX_ALLOWED_ROOMS。如果沒有設定，任何能在已加入聊天室中向機器人發送訊息的人都可能觸發 agent。僅授權你信任的人和聊天室 — 已授權的使用者可以完整存取 agent 的功能，包括工具使用和系統存取。

如需更多關於保護 Hermes Agent 部署安全的資訊，請參閱安全性指南。

備註

• 任何 homeserver：可與 Synapse、Conduit、Dendrite、matrix.org 或任何符合規範的 Matrix homeserver 運作。不需要特定的 homeserver 軟體。
• 聯邦：如果你使用聯邦 homeserver，機器人可以與來自其他伺服器的使用者通訊 — 只要將他們完整的 @user:server ID 加入 MATRIX_ALLOWED_USERS。
• 自動加入：機器人會自動接受聊天室邀請並加入。加入後立即開始回應。
• 媒體支援：Hermes 可以發送和接收圖片、音訊、影片和檔案附件。媒體透過 Matrix 內容倉儲 API 上傳到你的 homeserver。
• 原生語音訊息（MSC3245）：Matrix 適配器會自動為發送的語音訊息標記 org.matrix.msc3245.voice 標誌。這意味著 TTS 回應和語音音訊在 Element 和其他支援 MSC3245 的客戶端中會渲染為原生語音氣泡，而非通用的音訊檔案附件。帶有 MSC3245 標誌的傳入語音訊息也會被正確識別並路由到語音轉文字轉錄。不需要任何設定 — 這會自動運作。

---

---

Mattermost