Matrix（插件）

Matrix 是一个开放的去中心化消息协议。OpenClaw 作为 Matrix 用户连接到任�?homeserver，因此您需要为机器人创�?Matrix 账户。登录后，您可以直接 DM 机器人或将其邀请到房间（Matrix”群组”）。Beeper 也是一个有效的客户端选项，但它需要启�?E2EE�?

状态：通过插件支持（@vector-im/matrix-bot-sdk）。支持直接消息、房间、线程、媒体、反应、投票（发�?+ 投票开始为文本）、位置和 E2EE（带加密支持）�?

所需插件

Matrix 作为插件发货，未与核心安装捆绑�?

通过 CLI 安装（npm 注册表）�?

openclaw plugins install @openclaw/matrix

本地检出（�?git 仓库运行时）�?

openclaw plugins install ./extensions/matrix

如果�?configure/onboarding 期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径�?

详情：插件

设置

安装 Matrix 插件�?
- �?npm：openclaw plugins install @openclaw/matrix
- 从本地检出：openclaw plugins install ./extensions/matrix
�?homeserver 上创�?Matrix 账户�?
- �?https://matrix.org/ecosystem/hosting/ 浏览托管选项
- 或自行托管�?
获取机器人账户的访问令牌�?
- 使用 Matrix 登录 API 通过 curl 在您�?home 服务器上�?
```
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"
}'
```
- �?matrix.example.org 替换为您�?homeserver URL�?
- 或设�?channels.matrix.userId + channels.matrix.password：OpenClaw 调用相同的登录端点，将访问令牌存储在 ~/.openclaw/credentials/matrix/credentials.json，并在下次启动时重用它�?
配置凭证�?
- 环境：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（或 MATRIX_USER_ID + MATRIX_PASSWORD�?
- 或配置：channels.matrix.*
- 如果两者都设置，配置优先�?
- 使用访问令牌：用�?ID 通过 /whoami 自动获取�?
- 设置时，channels.matrix.userId 应该是完整的 Matrix ID（例�?@bot:example.org）�?
重启 gateway（或完成入门）�?
从任�?Matrix 客户端（Element、Beeper 等；请参�?https://matrix.org/ecosystem/clients/）开始与机器�?DM 或将其邀请到房间。Beeper 需�?E2EE，因此设�?channels.matrix.encryption: true 并验证设备�?

最小配置（访问令牌，用�?ID 自动获取）：

{
  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,
    },
  },
}

访问控制

直接消息

默认：dmPolicy: "pairing"（未知用户获得配对代码）
批准配对�?

openclaw pairing approve matrix <CODE>

群组/房间

默认：groupPolicy: "open"
可以设置�?"allowlist" �?"disabled"

支持的消息类�?

接收

�?文本
�?图片
�?文件
�?音频
�?视频
�?位置
�?反应
�?线程

发�?

�?文本
�?图片
�?文件
�?音频
�?视频
�?位置
�?反应

配置参�?

请参�?Gateway 配置了解完整的配置选项�?

排查

机器人未连接

确认访问令牌有效
检�?homeserver URL 正确
检�?Gateway 日志

消息未接�?

确认机器人已添加到房�?
检查权限设�?
检�?Gateway 日志