Matrix (plugin)

Matrix 是一个开放的、去中心化的消息协议。OpenClaw 以 Matrix 用户身份连接到任何 homeserver（主服务器），所以你需要为机器人创建一个 Matrix 账号。登录后，你可以直接给机器人发 DM，或者把它邀请到房间（Matrix 的”群组”）。Beeper 也是一个有效的客户端选项，但它需要启用 E2EE。

状态：通过 Plugin 支持（@vector-im/matrix-bot-sdk）。支持私信、房间、话题串、媒体、表情回应、投票（发送 + poll-start 转为文本）、位置和 E2EE（需要加密支持）。

需要安装 Plugin

Matrix 以 Plugin 形式提供，不包含在核心安装中。

通过 CLI 安装（npm 仓库）：

openclaw plugins install @openclaw/matrix

本地安装（从 git 仓库运行时）：

openclaw plugins install ./extensions/matrix

如果你在配置/引导过程中选择 Matrix，并且检测到 git 仓库，OpenClaw 会自动提供本地安装路径。

详情：Plugins

设置

1. 安装 Matrix Plugin：

   • 从 npm：openclaw plugins install @openclaw/matrix
   • 从本地：openclaw plugins install ./extensions/matrix

2. 在 homeserver 上创建 Matrix 账号：

   • 浏览托管选项：https://matrix.org/ecosystem/hosting/
   • 或者自己搭建。

3. 获取机器人账号的 access token（访问令牌）：

   • 在你的 homeserver 上用 curl 调用 Matrix 登录 API：

   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 会调用同样的登录接口，把 access token 存到 ~/.openclaw/credentials/matrix/credentials.json，下次启动时复用。

4. 配置凭证：

   • 环境变量：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（或 MATRIX_USER_ID + MATRIX_PASSWORD）
   • 或配置文件：channels.matrix.*
   • 如果两者都设置了，配置文件优先。
   • 使用 access token 时：用户 ID 会通过 /whoami 自动获取。
   • 设置时，channels.matrix.userId 应该是完整的 Matrix ID（例如：@bot:example.org）。

5. 重启 Gateway（或完成引导）。

6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）给机器人发 DM 或邀请它进房间。Beeper 需要 E2EE，所以要设置 channels.matrix.encryption: true 并验证设备。

最小配置（access token，用户 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,
      dm: { policy: "pairing" },
    },
  },
}

加密 (E2EE)

通过 Rust crypto SDK 支持端到端加密。

用 channels.matrix.encryption: true 启用：

• 如果加密模块加载成功，加密房间会自动解密。
• 发送到加密房间时，出站媒体会被加密。
• 首次连接时，OpenClaw 会向你的其他 Session 请求设备验证。
• 在另一个 Matrix 客户端（Element 等）中验证设备，以启用密钥共享。
• 如果加密模块无法加载，E2EE 会被禁用，加密房间无法解密；OpenClaw 会记录警告。
• 如果你看到缺少加密模块的错误（例如 @matrix-org/matrix-sdk-crypto-nodejs-*），允许 @matrix-org/matrix-sdk-crypto-nodejs 的构建脚本并运行 pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs，或用 node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js 获取二进制文件。

加密状态按账号 + access token 存储在 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLite 数据库）。同步状态存在旁边的 bot-storage.json 中。如果 access token（设备）改变，会创建新的存储，机器人必须为加密房间重新验证。

设备验证： 启用 E2EE 时，机器人会在启动时向你的其他 Session 请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证后，机器人就能解密加密房间中的消息。

Routing 模型

• 回复总是返回到 Matrix。
• DM 共享 Agent 的主 Session；房间映射到群组 Session。

访问控制 (DM)

• 默认：channels.matrix.dm.policy = "pairing"。未知发送者会收到 Pairing 码。
• 批准方式：
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• 公开 DM：channels.matrix.dm.policy="open" 加上 channels.matrix.dm.allowFrom=["*"]。
• channels.matrix.dm.allowFrom 接受用户 ID 或显示名称。向导会在目录搜索可用时将显示名称解析为用户 ID。

房间（群组）

• 默认：channels.matrix.groupPolicy = "allowlist"（需要 @ 提及）。用 channels.defaults.groupPolicy 可以覆盖未设置时的默认值。
• 用 channels.matrix.groups 添加房间到白名单（房间 ID、别名或名称）：

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

• requireMention: false 在该房间启用自动回复。
• groups."*" 可以为所有房间设置提及门控的默认值。
• groupAllowFrom 限制哪些发送者可以在房间中触发机器人（可选）。
• 每个房间的 users 白名单可以进一步限制特定房间内的发送者。
• 配置向导会提示输入房间白名单（房间 ID、别名或名称），并在可能时解析名称。
• 启动时，OpenClaw 会将白名单中的房间/用户名称解析为 ID 并记录映射；未解析的条目保持原样。
• 默认自动接受邀请；用 channels.matrix.autoJoin 和 channels.matrix.autoJoinAllowlist 控制。
• 要不允许任何房间，设置 channels.matrix.groupPolicy: "disabled"（或保持空白名单）。
• 旧配置键：channels.matrix.rooms（与 groups 结构相同）。

话题串

• 支持回复话题串。
• channels.matrix.threadReplies 控制回复是否保持在话题串中：
  • off、inbound（默认）、always
• channels.matrix.replyToMode 控制不在话题串中回复时的 reply-to 元数据：
  • off（默认）、first、all

功能

配置参考 (Matrix)

完整配置：配置

Provider 选项：

• channels.matrix.enabled：启用/禁用 Channel 启动。
• channels.matrix.homeserver：homeserver URL。
• channels.matrix.userId：Matrix 用户 ID（有 access token 时可选）。
• channels.matrix.accessToken：access token。
• channels.matrix.password：登录密码（token 会被存储）。
• channels.matrix.deviceName：设备显示名称。
• channels.matrix.encryption：启用 E2EE（默认：false）。
• channels.matrix.initialSyncLimit：初始同步限制。
• channels.matrix.threadReplies：off | inbound | always（默认：inbound）。
• channels.matrix.textChunkLimit：出站文本分块大小（字符数）。
• channels.matrix.chunkMode：length（默认）或 newline，在长度分块前按空行（段落边界）分割。
• channels.matrix.dm.policy：pairing | allowlist | open | disabled（默认：pairing）。
• channels.matrix.dm.allowFrom：DM 白名单（用户 ID 或显示名称）。open 需要 "*"。向导会在可能时将名称解析为 ID。
• channels.matrix.groupPolicy：allowlist | open | disabled（默认：allowlist）。
• channels.matrix.groupAllowFrom：群组消息的白名单发送者。
• channels.matrix.allowlistOnly：强制 DM + 房间使用白名单规则。
• channels.matrix.groups：群组白名单 + 每个房间的设置映射。
• channels.matrix.rooms：旧的群组白名单/配置。
• channels.matrix.replyToMode：话题串/标签的 reply-to 模式。
• channels.matrix.mediaMaxMb：入站/出站媒体上限（MB）。
• channels.matrix.autoJoin：邀请处理（always | allowlist | off，默认：always）。
• channels.matrix.autoJoinAllowlist：自动加入允许的房间 ID/别名。
• channels.matrix.actions：每个操作的工具门控（reactions/messages/pins/memberInfo/channelInfo）。