前言
Matrix 是一个开放的去中心化通讯协议，支持联邦化部署和端到端加密。OpenClaw 通过官方插件 @openclaw/matrix 实现与 Matrix 网络的无缝对接。
前置要求
- 已安装并运行 OpenClaw
- 一个 Matrix 账号（用于机器人）
- Matrix Homeserver 地址（如 matrix.org 或自建服务器）
安装 Matrix 插件
openclaw plugins install @openclaw/matrix
安装完成后验证：
openclaw plugins list
# 应显示 @openclaw/matrix
创建 Matrix 机器人账号
在公共服务器注册
如果使用 matrix.org 等公共服务器，可以通过 Element 客户端注册一个新账号专门用于机器人。
在自建服务器注册
如果你运行自己的 Homeserver（如 Synapse），可以通过管理员 API 创建账号：
# Synapse 管理员命令
register_new_matrix_user -c /etc/synapse/homeserver.yaml \
-u openclaw-bot -p 你的密码 --no-admin \
http://localhost:8008
获取 Access Token
通过 Matrix 登录 API 获取 Access Token：
curl -X POST "https://matrix.example.com/_matrix/client/v3/login" \
-H "Content-Type: application/json" \
-d '{
"type": "m.login.password",
"user": "openclaw-bot",
"password": "你的密码"
}'
返回结果中包含 access_token 字段，复制保存。
注意：Access Token 等同于账号密码，请妥善保管，不要提交到版本控制中。
配置环境变量
# 在 .env 文件或系统环境变量中设置
export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_ACCESS_TOKEN="syt_xxxxxxxxxxxxxxxxxxxxxxxx"
OpenClaw 频道配置
channels:
- type: matrix
homeserver: "${MATRIX_HOMESERVER}"
accessToken: "${MATRIX_ACCESS_TOKEN}"
dmPolicy: "paired"
encryption: true
allowedRooms:
- "!roomid1:example.com"
- "!roomid2:example.com"
端到端加密（E2EE）
Matrix 的核心优势之一是端到端加密支持。启用 encryption: true 后，OpenClaw 能够在加密房间中正常收发消息：
encryption: true # 启用 E2EE 支持
设备验证
首次连接时，其他用户可能需要验证机器人设备。可以在 Element 客户端中手动完成交叉验证，或者配置自动信任：
matrix:
autoVerify: true # 自动接受设备验证请求
DM 配对策略
dmPolicy: "open" # 接受所有私聊
dmPolicy: "paired" # 需要配对审批
dmPolicy: "off" # 关闭私聊
房间白名单
通过 allowedRooms 限制机器人只在指定房间中工作：
allowedRooms:
- "!abc123:matrix.org"
- "!def456:example.com"
获取房间 ID 的方法：在 Element 客户端中，进入房间设置 → 高级 → 内部房间 ID。
支持的功能
Matrix 插件支持丰富的消息类型和交互方式：
| 功能 | 支持状态 |
|---|---|
| 私聊 (DM) | 支持 |
| 房间消息 | 支持 |
| 消息线程 | 支持 |
| 媒体文件 | 支持 |
| Emoji 回应 | 支持 |
| 投票 | 支持 |
| 位置分享 | 支持 |
实际使用场景
团队内部 AI 助手
在团队的 Matrix 房间中部署 AI 助手，成员可以 @ 机器人提问：
@openclaw-bot:example.com 帮我写一个 Python 脚本来处理 CSV 文件
跨组织协作
利用 Matrix 的联邦化特性，不同组织可以在各自的 Homeserver 上部署 OpenClaw，同时在联邦房间中协作。
常见问题
加密房间中无法收发消息
确认 encryption: true 已开启，并完成设备验证。检查日志中是否有 Olm/Megolm 相关错误。
Access Token 失效
Token 过期后需要重新通过登录 API 获取。建议使用长期有效的 Token 或配置自动刷新机制。
机器人无法加入房间
确认机器人账号已被邀请到目标房间，或房间设置允许任何人加入。检查 allowedRooms 配置是否包含目标房间 ID。
# 通过命令行邀请机器人
curl -X POST "https://matrix.example.com/_matrix/client/v3/rooms/!roomid:example.com/invite" \
-H "Authorization: Bearer 管理员Token" \
-H "Content-Type: application/json" \
-d '{"user_id": "@openclaw-bot:example.com"}'
总结
Matrix 的去中心化和端到端加密特性使其成为注重隐私的团队的理想选择。通过 @openclaw/matrix 插件，OpenClaw 能够充分利用 Matrix 协议的丰富功能，同时保持通信的安全性和可控性。