Matrix 是开放的去中心化消息协议。OpenClaw 以 Matrix 用户身份连接到任意 Homeserver，支持 DM、房间（群组）、线程、媒体和端对端加密（E2EE）。
安装插件
openclaw plugins install @openclaw/matrix快速接入（6 步）
1. 安装 Matrix 插件
2. 创建 Matrix 账号
在任意 Homeserver 上注册账号，可选托管方案：https://matrix.org/ecosystem/hosting/ 或自托管。
3. 获取 Access Token
curl --request POST \
--url https://matrix.example.org/_matrix/client/v3/login \
--header 'Content-Type: application/json' \
--data '{
"type": "m.login.password",
"identifier": { "type": "m.id.user", "user": "your-user-name" },
"password": "your-password"
}'也可以直接在配置中填写 userId + password，OpenClaw 会自动登录并缓存 Token。
4. 配置 OpenClaw
最简配置（Access Token）：
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.example.org",
"accessToken": "syt_***",
"dm": { "policy": "pairing" }
}
}
}E2EE 加密配置：
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.example.org",
"accessToken": "syt_***",
"encryption": true,
"dm": { "policy": "pairing" }
}
}
}环境变量方式：
export MATRIX_HOMESERVER=https://matrix.example.org
export MATRIX_ACCESS_TOKEN=syt_***5. 重启 Gateway
openclaw gateway restart6. 完成配对
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>用 Element、Beeper 等任意 Matrix 客户端向 Bot 发送 DM 或邀请 Bot 进入房间。
注意：Beeper 需要启用 E2EE。
E2EE 端对端加密
{
"channels": {
"matrix": {
"encryption": true
}
}
}启用后：
- 加密房间的消息自动解密
- 向加密房间发送媒体时自动加密
- 首次连接时，OpenClaw 向其他 Session 请求设备验证
- 在 Element 等客户端中批准验证请求，建立信任后 Bot 才能解密消息
Crypto 状态存储位置：
~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/
如果出现
@matrix-org/matrix-sdk-crypto-nodejs-*模块缺失错误，运行：pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs
多账号配置
{
"channels": {
"matrix": {
"enabled": true,
"dm": { "policy": "pairing" },
"accounts": {
"assistant": {
"name": "Main assistant",
"homeserver": "https://matrix.example.org",
"accessToken": "syt_assistant_***",
"encryption": true
},
"alerts": {
"name": "Alerts bot",
"homeserver": "https://matrix.example.org",
"accessToken": "syt_alerts_***",
"dm": { "policy": "allowlist", "allowFrom": ["@admin:example.org"] }
}
}
}
}
}多账号注意事项：
- 环境变量（
MATRIX_HOMESERVER等）只对默认账号生效 - 顶层配置对所有账号生效，可在各账号下覆盖
- 使用
bindings[].match.accountId将不同账号路由到不同 Agent - 每个账号+Token 有独立的 Crypto 密钥存储
访问控制
DM 访问
{
"channels": {
"matrix": {
"dm": {
"policy": "allowlist",
"allowFrom": ["@user:example.org"]
}
}
}
}重要：只接受完整的 Matrix 用户 ID（
@user:server），不接受显示名或短用户名。
| 策略 | 说明 |
|---|---|
pairing（默认） | 未知用户收到配对码 |
allowlist | 仅白名单用户（完整 Matrix ID） |
open | allowFrom: ["*"] 时开放 |
房间（群组）控制
{
"channels": {
"matrix": {
"groupPolicy": "allowlist",
"groups": {
"!roomId:example.org": { "allow": true },
"#alias:example.org": { "allow": true, "requireMention": false }
},
"groupAllowFrom": ["@owner:example.org"]
}
}
}requireMention: false：无需 @ 提及 Bot 即自动回复groups."*"：设置所有房间的默认 mention 策略- 房间 ID 和别名都支持（别名会自动解析为 ID）
Session 路由模型
| 场景 | Session Key |
|---|---|
| DM | agent:<id>:matrix:dm:<userId> |
| 房间 | agent:<id>:matrix:group:<roomId> |
| 线程 | agent:<id>:matrix:group:<roomId>:thread:<eventId> |
支持的功能
| 功能 | 支持 |
|---|---|
| 文字消息 | ✅ |
| 媒体（图片/文件/音频） | ✅ |
| E2EE 端对端加密 | ✅ |
| 线程（Threads） | ✅ |
| Reactions | ✅ |
| 投票（Poll） | ✅（发送/接收） |
| 位置信息 | ✅ |
| Beeper 兼容 | ✅（需开启 E2EE） |
故障排查
Bot 无响应：确认插件已安装；检查 homeserver 和 accessToken 正确；openclaw logs --follow
加密消息无法解密：确认 encryption: true；在 Element 中批准设备验证请求；检查 Crypto 模块是否正确安装
DM 被忽略：openclaw pairing list matrix 查看待审批请求；检查 dm.allowFrom 使用完整 Matrix ID
房间消息被忽略：检查房间 ID 在 groups 白名单中；确认 requireMention 设置
原文：Matrix - OpenClaw | 来源：OpenClaw 官方文档