8.13 Matrix集成

通讯渠道通讯渠道

Matrix（插件）：OpenClaw 作为 Matrix 用户连接到任何主服务器；需要 Matrix 账户。

概述

状态：通过插件支持

Matrix 集成允许 OpenClaw 连接到去中心化的 Matrix 网络。支持私信、房间、线程、媒体、反应、投票、位置和端到端加密（E2EE）。

安装插件

# 从 npm 安装
openclaw plugins install @openclaw/matrix

# 本地开发（从 git 仓库运行时）
openclaw plugins install ./extensions/matrix

设置步骤

  1. 安装 Matrix 插件
  2. 创建 Matrix 账户（在任何主服务器上，如 matrix.org）
  3. 获取访问令牌（通过 curl 或配置）
  4. 配置凭据（环境变量或配置文件）
  5. 重启网关
  6. 私信或邀请机器人到房间

获取访问令牌

使用 curl 获取访问令牌：

curl -X POST https://matrix.org/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "your_username",
    "password": "your_password"
  }'

配置

最小配置

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@your_bot:matrix.org",
      "accessToken": "YOUR_ACCESS_TOKEN"
    }
  }
}

环境变量

  • MATRIX_HOMESERVER
  • MATRIX_USER_ID
  • MATRIX_ACCESS_TOKEN

完整配置示例

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@bot:matrix.org",
      "accessToken": "syt_...",
      "encryption": true,
      "dm": {
        "policy": "pairing"
      },
      "groupPolicy": "allowlist",
      "autoJoin": true,
      "mediaMaxMb": 20
    }
  }
}

端到端加密（E2EE）

启用加密支持：

{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}

设备验证：首次使用加密时，需要验证设备。在 Matrix 客户端中：

  1. 查找来自机器人的验证请求
  2. 确认表情符号或数字匹配
  3. 接受验证

消息路由

  • 私信（DM）：使用主会话
  • 房间：映射到群组会话（agent::matrix:room:）
  • 回复始终返回到 Matrix

访问控制

私信策略

私信默认使用 "pairing" 策略。未知发件人会收到配对码。

# 列出配对请求
openclaw pairing list matrix

# 批准配对
openclaw pairing approve matrix <code>

房间策略

房间策略默认为 "allowlist"（提及门控）：

  • "allowlist"：仅响应提及（@机器人）
  • "open"：响应所有消息
  • "disabled"：禁用房间
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!roomId:matrix.org": {
          "policy": "open",
          "allowFrom": ["@user1:matrix.org", "@user2:matrix.org"]
        }
      }
    }
  }
}

自动加入

自动加入功能默认启用。机器人会自动接受房间邀请：

{
  "channels": {
    "matrix": {
      "autoJoin": true
    }
  }
}

线程支持

Matrix 支持回复线程功能：

  • threadReplies：off/inbound/always
  • replyToMode：off/first/all
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "first"
    }
  }
}

功能支持

功能 支持状态
私信（DM） ✅ 支持
房间 ✅ 支持
线程 ✅ 支持
媒体文件 ✅ 支持
反应 ✅ 支持
投票 ✅ 支持（仅发送；入站投票开始转为文本）
位置 ✅ 支持
端到端加密（E2EE） ✅ 支持

配置参考

核心选项

  • enabled：启用 Matrix 集成
  • homeserver：主服务器 URL
  • userId：Matrix 用户 ID（格式：@username:server）
  • accessToken：访问令牌
  • encryption：启用 E2EE（默认 false）

访问控制

  • dm.policy：私信策略（pairing/allowlist/open/disabled）
  • groupPolicy：房间策略（allowlist/open/disabled）
  • groups：每个房间的配置对象
  • autoJoin：自动接受邀请（默认 true）

消息选项

  • mediaMaxMb：媒体文件最大大小（默认 10 MB）
  • threadReplies：线程回复模式
  • replyToMode：回复引用模式

故障排除

  • 连接失败：检查主服务器 URL 和访问令牌
  • 无法加入房间：确保 autoJoin: true 或手动邀请
  • 加密消息无法读取：启用 encryption: true 并验证设备
  • 消息未收到：检查房间策略和允许列表
  • 媒体上传失败：检查 mediaMaxMb 限制

常用命令

# 安装 Matrix 插件
openclaw plugins install @openclaw/matrix

# 检查渠道状态
openclaw channels status

# 列出配对请求
openclaw pairing list matrix

# 批准配对
openclaw pairing approve matrix <code>

# 运行诊断
openclaw doctor
提示
Matrix 是一个去中心化的通讯协议，您可以选择任何 Matrix 主服务器（如 matrix.org、element.io 等）或自建主服务器。
安全提示
  • 妥善保管访问令牌，不要泄露给他人
  • 建议使用专用账户作为机器人，而非个人账户
  • 启用加密时，确保备份加密密钥
  • 定期轮换访问令牌以提高安全性

相关资源