Matrix 是一个开放的去中心化即时通讯协议，Element、Beeper 等客户端均基于 Matrix 构建。OpenClaw 通过 Matrix 插件，以普通用户身份登录 Matrix 主服务器，支持私信、房间（群组）、线程、端到端加密（E2EE）和媒体消息。
支持功能
- ✅ 私信（DM）
- ✅ 房间（群组）
- ✅ 消息线程
- ✅ 媒体消息
- ✅ 反应（Reactions）
- ✅ 投票（发送和接收，作为文本）
- ✅ 位置消息
- ✅ 端到端加密（E2EE）
- ✅ Beeper 客户端支持（需启用 E2EE）
第一步：安装 Matrix 插件
bash
openclaw plugins install @openclaw/matrix本地开发：
bash
openclaw plugins install ./extensions/matrix第二步：创建 Matrix 机器人账号
- 访问 matrix.org/ecosystem/hosting 浏览托管选项，或自行搭建主服务器
- 注册一个 Matrix 账号作为 Bot 使用
- 获取访问令牌（Access Token）：
bash
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-bot-username"
},
"password": "your-password"
}'将 matrix.example.org 替换为你的主服务器地址。
第三步：配置 OpenClaw
使用 Access Token（推荐）
json
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.example.org",
"accessToken": "syt_***",
"dm": { "policy": "pairing" }
}
}
}User ID 会通过 /whoami 接口自动获取。
使用用户名+密码（自动获取 Token）
json
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.example.org",
"userId": "@bot:example.org",
"password": "your-password"
}
}
}OpenClaw 会自动调用登录接口获取令牌，并将其存储在 ~/.openclaw/credentials/matrix/credentials.json。
使用环境变量
bash
export MATRIX_HOMESERVER="https://matrix.example.org"
export MATRIX_ACCESS_TOKEN="syt_***"
# 或使用账号密码方式
export MATRIX_USER_ID="@bot:example.org"
export MATRIX_PASSWORD="your-password"注意：配置文件中的设置优先于环境变量。
启用端到端加密（E2EE）
如果你或你的用户使用 Beeper，或对隐私有较高要求，需要启用 E2EE：
json
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.example.org",
"accessToken": "syt_***",
"encryption": true,
"dm": { "policy": "pairing" }
}
}
}启用后还需要在 Matrix 客户端（Element/Beeper）中验证 Bot 的设备，才能开始加密通信。
多账号配置
json
{
"channels": {
"matrix": {
"accounts": {
"personal": {
"homeserver": "https://matrix.org",
"accessToken": "syt_personal_***"
},
"work": {
"homeserver": "https://matrix.mycompany.com",
"accessToken": "syt_work_***"
}
}
}
}
}访问控制
私信策略
json
{
"channels": {
"matrix": {
"dm": {
"policy": "pairing",
"allowFrom": ["@alice:matrix.org", "@bob:example.com"]
}
}
}
}allowFrom 填写完整的 Matrix ID（@username:homeserver）。
房间（群组）策略
json
{
"channels": {
"matrix": {
"rooms": {
"*": {
"requireMention": true
}
}
}
}
}路由模型
OpenClaw 将不同的 Matrix 上下文路由到不同的 Agent：
- 私信：路由到私信 Agent
- 房间：路由到对应的群组 Agent
- 线程：每个线程维护独立的对话上下文
使用 Beeper 的注意事项
Beeper 要求所有通信都使用 E2EE，因此：
- 必须将
encryption设为true - 需要在 Beeper 中验证 Bot 设备
- 验证后才能正常接收和发送消息
原文：Matrix - OpenClaw | 来源：OpenClaw 官方文档