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

本页目录