Matrix
Matrix 支持状态、能力与配置
Matrix 是一个开放的去中心化消息协议。OpenClaw 以 Matrix 用户（user） 的身份连接到任意 homeserver，因此你需要为 bot 准备一个 Matrix 账号。登录后，你可以直接私信 bot，或把它邀请进房间（Matrix 的"群聊"/rooms）。Beeper 也可以作为客户端，但它通常要求启用 E2EE。
状态：通过插件支持（@vector-im/matrix-bot-sdk）。支持私信、rooms、threads、媒体、reactions、投票（发送 + 入站 poll-start 转文本）、位置、以及带 crypto 支持的端到端加密（E2EE）。
需要安装插件
Matrix 以插件形式提供，不随 core 安装打包。
通过 CLI 安装（npm registry）：
openclaw plugins install @openclaw/matrix
本地安装（当你从 git 仓库运行时）：
openclaw plugins install ./extensions/matrix
如果你在 configure/onboarding 中选择 Matrix 且检测到 git checkout，OpenClaw 会自动提供本地安装路径。
详情：''/plugin''
设置
1. 安装 Matrix 插件：
- npm：openclaw plugins install @openclaw/matrix
- 本地 checkout：openclaw plugins install ./extensions/matrix
2. 在某个 homeserver 上创建一个 Matrix 账号：
- For hosted options, see: <https://matrix.org/ecosystem/hosting/>
- 或自行托管
3. 获取 bot 账号的 access token：
- 使用 homeserver 的 Matrix login API（curl）：
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_***",
dm: { policy: "pairing" },
},
},
}{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_***",
encryption: true,
dm: { policy: "pairing" },
},
},
}加密（E2EE）
端到端加密 已支持（使用 Rust crypto SDK）。
设置 channels.matrix.encryption: true 后：
- crypto 模块加载成功时，加密房间会被自动解密。
- 向加密房间发送媒体时会进行加密。
- 首次连接时，OpenClaw 会向你的其他会话发起设备验证请求。
- 在另一个 Matrix 客户端（例如 Element）中批准验证请求，以启用密钥共享。
- 如果 crypto 模块无法加载，会禁用 E2EE，加密房间不会被解密；OpenClaw 会记录 warning。
- 如果看到缺少 crypto module 的错误（例如 @matrix-org/matrix-sdk-crypto-nodejs-*），需要允许 @matrix-org/matrix-sdk-crypto-nodejs 的 build scripts，并运行：
- pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs，或
- node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js（拉取二进制）
crypto 状态会按账号 + access token 存到：
~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/
（SQLite 数据库）。sync 状态保存在同目录下的 bot-storage.json。
如果 access token（设备）发生变化，会创建新的 store，bot 需要重新验证才能读取加密房间消息。
设备验证：
启用 E2EE 后，bot 启动时会向你其他会话请求验证。在 Element（或其他客户端）中批准请求建立信任关系。验证完成后，bot 才能解密加密房间消息。
路由模型
- 回复始终回到 Matrix。
- 私信（DM）共享 agent 主会话；rooms 映射为群会话（独立 session key）。
访问控制（私信）
- 默认：channels.matrix.dm.policy = "pairing"。未知发送者会收到配对码。
- 批准：
- openclaw pairing list matrix
- openclaw pairing approve matrix <CODE>
- 公开私信：channels.matrix.dm.policy="open" 且 channels.matrix.dm.allowFrom=["*"]。
- channels.matrix.dm.allowFrom 支持 user IDs 或 display names。目录搜索可用时，向导会把 display names 解析为 user IDs。
Rooms（群聊）
- 默认：channels.matrix.groupPolicy = "allowlist"（并默认启用 mention 门禁）。未设置时可用 channels.defaults.groupPolicy 覆盖默认值。
- 用 channels.matrix.groups 对房间做 allowlist（可用 room IDs、aliases 或名称）：
{
channels: {
matrix: {
groupPolicy: "allowlist",
groups: {
"!roomId:example.org": { allow: true },
"#alias:example.org": { allow: true },
},
groupAllowFrom: ["@owner:example.org"],
},
},
}- requireMention: false 会让该房间自动回复。
- groups."*" 可为所有房间设置默认的 mention 行为。
- groupAllowFrom（可选）限制哪些发送者可以在房间里触发 bot。
- 每个房间的 users allowlists 可以进一步限制房间内的触发者。
- configure/onboarding 会提示填写 room allowlists，并在可能时解析名称。
- 启动时 OpenClaw 会尽力把 allowlists 里的 room/user 名称解析为 IDs，并把映射写日志；解析失败的条目会保留为原样。
- 默认会自动加入 invites；用 channels.matrix.autoJoin 与 channels.matrix.autoJoinAllowlist 控制。
- 若希望 完全不处理 rooms，设置 channels.matrix.groupPolicy: "disabled"（或保持空 allowlist）。
- 旧键：channels.matrix.rooms（与 groups 结构相同）。
Threads
- 支持 reply threading。
- channels.matrix.threadReplies 控制是否把回复留在 thread：
- off、inbound（默认）、always
- channels.matrix.replyToMode 控制当不在 thread 中回复时的 reply-to 元数据：
- off（默认）、first、all
能力
| 功能 | 状态 |
| ----- |
| 私信 | ✅ 支持 |
| Rooms | ✅ 支持 |
| Threads | ✅ 支持 |
| 媒体 | ✅ 支持 |
| E2EE | ✅ 支持（需要 crypto module） |
| Reactions | ✅ 支持（通过工具发送/读取） |
| 投票 | ✅ 支持发送；入站 poll-start 会转为文本（忽略 responses/ends） |
| 位置 | ✅ 支持（geo URI；忽略海拔） |
| 原生命令 | ✅ 支持 |
配置参考（Matrix）
完整配置：''/gateway/configuration''
Provider 选项：
- channels.matrix.enabled：是否启用通道
- channels.matrix.homeserver：homeserver URL
- channels.matrix.userId：Matrix user ID（使用 access token 时可选）
- channels.matrix.accessToken：access token
- channels.matrix.password：用于登录的密码（token 会被持久化）
- channels.matrix.deviceName：设备显示名
- channels.matrix.encryption：是否启用 E2EE（默认 false）
- channels.matrix.initialSyncLimit：初始同步条数
- channels.matrix.threadReplies：off | inbound | always（默认 inbound）
- channels.matrix.textChunkLimit：出站文本分段大小（字符）
- channels.matrix.chunkMode：length（默认）或 newline（先按空行分段，再按长度分段）
- channels.matrix.dm.policy：pairing | allowlist | open | disabled（默认 pairing）
- channels.matrix.dm.allowFrom：私信 allowlist（user IDs 或 display names）；open 需要 "*"；可解析时会自动转为 IDs
- channels.matrix.groupPolicy：allowlist | open | disabled（默认 allowlist）
- channels.matrix.groupAllowFrom：群消息发送者 allowlist
- channels.matrix.allowlistOnly：强制对私信 + rooms 都使用 allowlist 规则
- channels.matrix.groups：rooms allowlist + 每房间设置
- channels.matrix.rooms：旧 rooms allowlist/config
- channels.matrix.replyToMode：threads/tags 的 reply-to 模式
- channels.matrix.mediaMaxMb：入站/出站媒体上限（MB）
- channels.matrix.autoJoin：invite 自动加入策略（always | allowlist | off，默认 always）
- channels.matrix.autoJoinAllowlist：允许 auto-join 的房间 IDs/aliases
- channels.matrix.actions：按动作工具开关（reactions/messages/pins/memberInfo/channelInfo）