Matrix

基於客戶端-服務器 API 的聯邦 Matrix 協議。入站通過長輪詢守護進程運行，無 HTTP webhook 入口。

🟡 出站即用，入站依賴長輪詢守護進程。 Matrix 採用聯邦架構，不存在單一 webhook URL。Minara 運行 /sync 守護進程，將事件流式傳輸到 Agent。僅支持明文房間；端到端加密 (E2EE) 房間暫不支持。

功能概覽

出站文本，通過客戶端-服務器 API： PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId} 攜帶 Authorization: Bearer <access_token> 和 {msgtype:"m.text", body}。
入站通過長輪詢守護進程。 設置 MESSAGING_MATRIX_INBOUND=1 後， Minara 開啟 GET /sync?since=<batch>&timeout=30000 循環。事件僅過濾來自 MATRIX_DEFAULT_ROOM_ID 的消息（codex-round-1 安全修復；守護進程不會從所有已加入房間發出事件）。
游標持久化到磁盤，路徑為 <dataDir>/matrix-sync.json；重啟後從上次的 next_batch 續傳，不會重放歷史記錄。
僅支持文本。 圖片和文件事件會被丟棄。
文本上限 65000 字符（Matrix 本身的限制）。

配置步驟

1. 創建或使用已有 Matrix 賬號

任意 homeserver 均可使用：matrix.org、自建 Synapse、Dendrite 等。先通過 Matrix 客戶端（Element、Cinny 等）登錄一次。

2. 生成長效訪問令牌

最簡單的方式是從 Element 複製：

Element 桌面端 / 網頁端：設置 → 幫助與關於 → 訪問令牌（在"高級"下方，展開即可看到）

或使用 curl：

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

返回 {access_token, user_id, ...}。

保存以下內容：

MATRIX_HOMESERVER（URL，例如 https://matrix.org）
MATRIX_ACCESS_TOKEN（Bearer 令牌）
MATRIX_USER_ID（例如 @bot:matrix.org）

3. 加入目標房間

用 bot 賬號加入想讓 Agent 監聽的房間。記錄房間 ID（Element：房間 → 設置 → 高級 → "內部房間 ID"），格式如 !abc:matrix.org，保存為 MATRIX_DEFAULT_ROOM_ID。

4. 配置 Minara

minara auth messaging add
# 从列表中选择 `matrix`，粘贴 homeserver URL、访问令牌、
# 用户 ID 和默认房间 ID。

或直接設置環境變量：

MATRIX_HOMESERVER=https://matrix.org
MATRIX_ACCESS_TOKEN=syt_...
MATRIX_USER_ID=@bot:matrix.org
MATRIX_DEFAULT_ROOM_ID=!abc:matrix.org

5. 啟用入站（可選）

MESSAGING_MATRIX_INBOUND=1

設置後，Agent 啟動時會開啟長輪詢守護進程。不設置此標誌時，Matrix 僅支持推送。

6. 測試

minara auth messaging test matrix

`/sync` 工作原理（長輪詢守護進程）

守護進程在後臺運行，向 homeserver 發起長輪詢請求：

GET /sync?timeout=30000&since=<next_batch>&filter={"room":{"timeline":{"types":["m.room.message"]}}}

homeserver 保持連接，直到有新事件到達或 30 秒超時，然後返回事件及新的 next_batch 游標。

三項安全保障：

首次同步丟棄歷史記錄。 全新安裝沒有游標，/sync 通常會返回房間完整時間線。守護進程會丟棄這批初始數據，僅持久化 next_batch token，防止首次啟動時重放數月前的消息。
房間範圍過濾。 只有 MATRIX_DEFAULT_ROOM_ID 中的事件才會轉發給 Agent。否則，bot 加入的每個房間都可能觸發回覆，在共享場景下存在隱私和範圍風險。
自發消息過濾。 sender === MATRIX_USER_ID 的事件會被過濾，避免 bot 自身的出站消息經 /sync 往返後觸發入站。

重連策略：守護進程在網絡故障時使用帶抖動的指數退避（1s 到 30s），通過共享的 daemon-runner 實現。

限制與注意事項

不支持端到端加密。 守護進程忽略 m.room.encrypted 事件，請僅使用明文房間。添加 olm / matrix-rust-sdk 以支持 E2EE 是較大的後續工作。
無聯邦握手。 bot 作為 Matrix 客戶端運行；未加入的房間不會收到事件。
Bearer 放在 Header，不在查詢參數中。 Matrix 的 ?access_token= 查詢參數形式已廢棄，Minara 使用 Authorization: Bearer。
帶寬佔用。 長輪詢會全天候保持一個 HTTP 連接。多數 homeserver 能輕鬆應對；但防火牆和負載均衡器配置需注意，不要在低於約 60 秒時斷開空閒連接。

故障排查

"守護進程無法啟動"

未設置 MESSAGING_MATRIX_INBOUND，將其設為 1 後重啟。

"守護進程沒有事件輸出"

bot 未加入 MATRIX_DEFAULT_ROOM_ID。請通過 Element 或 GET /joined_rooms 重新確認。
房間已加密，請使用明文房間。

"啟動時重放所有舊消息"

<dataDir>/matrix-sync.json 缺失或 next_batch 為 null。停止守護進程，刪除該文件後重啟；刪除後的首次同步會正確丟棄歷史記錄。

"出站返回 401 (M_UNKNOWN_TOKEN)"

訪問令牌已過期或被撤銷，按上方登錄流程重新生成。

參考資料

環境變量：MATRIX_*、MESSAGING_MATRIX_INBOUND
出站：apps/agent/src/messaging/matrix.ts
入站守護進程：apps/agent/src/messaging/inbound/matrix-daemon.ts
Daemon runner：apps/agent/src/messaging/inbound/daemon-runner.ts
客戶端-服務器 API 規範：spec.matrix.org / latest / client-server-api

本頁目錄