Matrix - 去中心化通讯协议接入

Matrix 是一个开放的去中心化通讯协议（Decentralized Communication Protocol），任何人都可以搭建自己的 Homeserver（家服务器）并与全球 Matrix 网络互联。OpenClaw 通过 Matrix Client-Server API 实现接入。

前置要求

• 一个 Matrix 账号（可在 matrix.org 注册）
• 账号的 Access Token（访问令牌）
• OpenClaw Gateway（网关）已安装并运行

安装插件

openclaw plugins install @openclaw/matrix

获取 Access Token

Element Web

# 在 Element 客户端中：Settings > Help & About > Access Token
# 点击展开即可复制

命令行

curl -XPOST 'https://matrix.org/_matrix/client/r0/login' \
  -H 'Content-Type: application/json' \
  -d '{"type":"m.login.password","user":"@yourbot:matrix.org","password":"your-password"}'

安全提示

Access Token 等同于账号密码，请妥善保管。建议为 Bot 创建专用账号，不要使用个人账号。

配置 OpenClaw

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.org",       // Homeserver URL
      accessToken: "syt_xxx",                 // Access Token
      dmPolicy: "pairing"                     // DM Policy（私信策略）
    }
  }
}

也可以通过 Environment Variable（环境变量）设置：

export MATRIX_HOMESERVER="https://matrix.org"
export MATRIX_ACCESS_TOKEN="syt_xxx"

启动与验证

openclaw gateway restart

在 Matrix 客户端（如 Element）向 Bot 账号发送私聊消息，获取 Pairing Code（配对码）后批准：

openclaw pairing approve matrix <pairing-code>

End-to-End Encryption（端到端加密）

Matrix 支持 E2EE（End-to-End Encryption，端到端加密），启用后消息在客户端加密，Homeserver 无法读取。

{
  channels: {
    matrix: {
      encryption: true,
      storePass: "your-crypto-store-password"   // 加密存储密码
    }
  }
}

重要

启用 E2EE 后，必须完成 Device Verification（设备验证）。在 Element 中打开与 Bot 的对话，点击 Bot 头像 > Verify 完成交叉签名验证。

加密密钥存储在本地，丢失将导致无法解密历史消息。请定期备份 ~/.openclaw/matrix-store/ 目录。

Device Verification（设备验证）

1. Bot 启动后会在 Matrix 网络上创建一个新设备
2. 在 Element 客户端中会看到 "New login" 提示
3. 点击验证并完成 Emoji 比对或 QR 扫码

Room（房间）与 Group（群组）

{
  channels: {
    matrix: {
      rooms: {
        allowAll: false,
        allowRooms: ["!roomid:matrix.org"],      // 允许的 Room ID
        requireMention: true                      // 需要 @机器人
      }
    }
  }
}

获取 Room ID

在 Element 中：Room Settings > Advanced > Internal room ID，格式如 !abc123:matrix.org

DM Policy（私信策略）

策略	说明
pairing	用户需先获取 Pairing Code（配对码）验证
allowlist	仅允许指定 Matrix ID 私聊
open	所有人均可私聊（谨慎使用）

{
  channels: {
    matrix: {
      dmPolicy: "allowlist",
      allowFrom: ["@user1:matrix.org", "@user2:matrix.org"]
    }
  }
}

自建 Homeserver

Matrix 最大的优势是可以自建 Homeserver，实现数据完全自控。

Synapse（官方参考实现）

# Docker 部署
docker run -d --name synapse \
  -v /data/synapse:/data \
  -p 8008:8008 \
  matrixdotorg/synapse:latest

Dendrite（下一代实现）

Dendrite 使用 Go 编写，资源占用更低，适合小型部署：

docker run -d --name dendrite \
  -v /data/dendrite:/etc/dendrite \
  -p 8008:8008 \
  matrixdotorg/dendrite-monolith:latest

自建 Homeserver 后，将 OpenClaw 配置中的 homeserver 指向你的服务器地址即可。

常见问题

Bot 不响应加密房间消息

1. 确认 encryption: true 已启用
2. 完成 Device Verification
3. 检查加密密钥存储是否完整

加入房间失败

1. 确认房间设置允许 Bot 加入（Room Settings > Security > Who can join）
2. 如果是 Invite-only（仅邀请）房间，需先邀请 Bot

同步缓慢

首次启动时 Bot 需要进行 Initial Sync（初始同步），大型账号可能耗时较长。后续启动将使用增量同步。

🇨🇳 中国用户须知

Matrix 是一个开源（Open Source）且可自建的协议，非常适合对数据主权和隐私有要求的中国组织。

自建推荐：将 Synapse 或 Dendrite 部署在国内服务器上，数据不出境，满足信创和等保要求。

公共服务器：matrix.org 等公共 Homeserver 在中国大陆可能访问缓慢，建议自建或使用亚洲节点。

适用场景：政企内部通讯、对数据安全有高要求的团队协作、开源社区运营。

客户端：Element 客户端支持全平台（Web、iOS、Android、桌面），中国用户可正常使用自建服务器。