Matrix（插件）

Matrix is an open, decentralized messaging protocol. Matrix 是一个开放的去中心化消息协议。OpenClaw 以 Matrix 用户身份连接到任意主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix”群组”）。Beeper 也是一个有效的客户端选项，但它需要启用 E2EE。 Once it is logged in, you can DM the bot directly or invite it to rooms (Matrix “groups”). Beeper is a valid client option too, but it requires E2EE to be enabled. Status: supported via plugin (@vector-im/matrix-bot-sdk). Direct messages, rooms, threads, media, reactions, polls (send + poll-start as text), location, and E2EE (with crypto support).

需要插件

Matrix 作为插件提供，不包含在核心安装中。通过 CLI 安装（npm 仓库）：

openclaw plugins install @openclaw/matrix

本地检出（从 git 仓库运行时）：

openclaw plugins install ./extensions/matrix

如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。详情：插件

设置

安装 Matrix 插件：
- 从 npm：openclaw plugins install @openclaw/matrix
- 从本地检出：openclaw plugins install ./extensions/matrix
在主服务器上创建 Matrix 账户：
- 在 https://matrix.org/ecosystem/hosting/ 浏览托管选项
- Or host it yourself.
获取机器人账户的访问令牌：
- 在你的主服务器上使用 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 替换为你的主服务器 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）。
Restart the gateway (or finish onboarding).
从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要 E2EE，因此请设置 channels.matrix.encryption: true 并验证设备。 Beeper requires E2EE, so set channels.matrix.encryption: true and verify the device.

最小配置（访问令牌，用户 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 加密 SDK 支持端到端加密。使用 channels.matrix.encryption: true 启用：

如果加密模块加载成功，加密房间会自动解密。
发送到加密房间时，出站媒体会被加密。
首次连接时，OpenClaw 会向你的其他会话请求设备验证。
在另一个 Matrix 客户端（Element 等）中验证设备以启用密钥共享。 to enable key sharing.
如果无法加载加密模块，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 获取二进制文件。

Crypto state is stored per account + access token in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite database). Sync state lives alongside it in bot-storage.json. If the access token (device) changes, a new store is created and the bot must be re-verified for encrypted rooms. 设备验证： 启用 E2EE 时，机器人将在启动时向你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证后，机器人可以解密加密房间中的消息。 Open Element (or another client) and approve the verification request to establish trust. Once verified, the bot can decrypt messages in encrypted rooms.

多账户

多账户支持：使用 channels.matrix.accounts 并为每个账户配置凭据和可选的 name。参见 gateway/configuration 了解通用模式。每个账户在任意 homeserver 上作为独立的 Matrix 用户运行。每账户配置继承自顶层 channels.matrix 设置，并可覆盖任意选项（DM 策略、群组、加密等）。

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

注意：

为避免并发模块导入导致的竞争条件，账户启动过程采用串行化处理。
环境变量（MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN 等）仅适用于默认账户。
基础频道设置（DM 策略、群组策略、提及门控等）除非在单个账户中覆盖，否则将应用于所有账户。
使用 bindings[].match.accountId 将每个账户路由到不同的代理。
加密状态按账户 + access token 存储（每个账户使用独立的密钥存储）。

路由模型

回复始终返回到 Matrix。
DMs share the agent’s main session; rooms map to group sessions.

访问控制（私信）

1. 默认值：channels.matrix.dm.policy = "pairing"。 Unknown senders get a pairing code.
通过以下方式批准：
- openclaw pairing list matrix
- openclaw pairing approve matrix <CODE>
公开私信：channels.matrix.dm.policy="open" 加上 channels.matrix.dm.allowFrom=["*"]。
channels.matrix.dm.allowFrom 仅接受完整 Matrix 用户 ID（例如 @user:server）。向导仅在目录搜索得到唯一精确匹配时将显示名称解析为用户 ID。 The wizard resolves display names to user IDs when directory search finds a single exact match.
不要使用显示名称或仅本地部分（例如："Alice" 或 "alice"）。它们存在歧义，在 allowlist 匹配中会被忽略。请使用完整的 @user:server ID。

房间（群组）

默认：channels.matrix.groupPolicy = "allowlist"（提及门控）。使用 channels.defaults.groupPolicy 在未设置时覆盖默认值。 Use channels.defaults.groupPolicy to override the default when unset.
使用 channels.matrix.groups 配置房间允许列表（房间 ID 或别名；名称仅在目录搜索得到唯一精确匹配时解析为 ID）：

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

requireMention: false 启用该房间的自动回复。
groups."*" 可以设置跨房间的提及门控默认值。
groupAllowFrom 限制哪些发送者可以在房间中触发机器人（需完整 Matrix 用户 ID）。
每个房间的 users 允许列表可以进一步限制特定房间内的发送者（需完整 Matrix 用户 ID）。
配置向导会提示输入房间允许列表（房间 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

功能

功能	状态
Direct messages	✅ 支持
房间	✅ 支持
话题	✅ 支持
媒体	✅ 支持
E2EE	✅ 支持（需要加密模块）
表情回应	✅ 支持（通过工具发送/读取）
投票	✅ 支持发送；入站投票开始转换为文本（响应/结束被忽略）
位置	✅ 支持（geo URI；忽略海拔）
原生命令	✅ 支持

Troubleshooting

Run this ladder first:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Then confirm DM pairing state if needed:

openclaw pairing list matrix

Common failures:

Logged in but room messages ignored: room blocked by groupPolicy or room allowlist.
默认：channels.matrix.dm.policy = "pairing"。未知发送者会收到配对码。
Encrypted rooms fail: crypto support or encryption settings mismatch.

For triage flow: /channels/troubleshooting.

配置参考（Matrix）

完整配置：配置提供商选项：

channels.matrix.enabled：启用/禁用渠道启动。
channels.matrix.homeserver：主服务器 URL。
channels.matrix.userId：Matrix 用户 ID（使用访问令牌时可选）。
channels.matrix.accessToken：访问令牌。
channels.matrix.password：登录密码（令牌会被存储）。
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：私信允许列表（需完整 Matrix 用户 ID）。open 需要 "*"。向导在可能时将名称解析为 ID。 open requires "*". The wizard resolves names to IDs when possible.
channels.matrix.groupPolicy：allowlist | open | disabled（默认：allowlist）。
channels.matrix.groupAllowFrom：群组消息的允许发送者列表（需完整 Matrix 用户 ID）。
channels.matrix.allowlistOnly：强制私信 + 房间使用允许列表规则。
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.accounts：按账户 ID 进行键控的多账户配置（每个账户继承顶层设置）。
channels.matrix.actions：每个操作的工具限制（reactions/messages/pins/memberInfo/channelInfo）。

概览

消息平台

配置

Matrix

Matrix（插件）

需要插件

设置

加密（E2EE）

多账户

路由模型

访问控制（私信）

房间（群组）

话题

功能

Troubleshooting

配置参考（Matrix）

概览

消息平台

配置

​Matrix（插件）

​需要插件

​设置

​加密（E2EE）

​多账户

​路由模型

​访问控制（私信）

​房间（群组）

​话题

​功能

​Troubleshooting

​配置参考（Matrix）

Matrix（插件）

需要插件

设置

加密（E2EE）

多账户

路由模型

访问控制（私信）

房间（群组）

话题

功能

Troubleshooting

配置参考（Matrix）