Matrix（插件）

Matrix 是一个开放的去中心化即时通讯协议。OpenClaw 作为 Matrix 用户连接到任意 homeserver，因此需要一个 Matrix 账号。登录后，你可以直接给机器人发私信，或邀请它加入房间（Matrix 的”群组”）。Beeper 也是可用的客户端选项，但需要启用端到端加密。

状态：通过插件（@vector-im/matrix-bot-sdk）支持。支持私信、房间、线程、媒体、表情回应、投票（发送 + poll-start 转文本）、位置和端到端加密（需加密模块）。

需要安装插件

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

通过 CLI（npm 仓库）安装：

openclaw plugins install @openclaw/matrix

本地代码安装（从 Git 仓库运行时）：

openclaw plugins install ./extensions/matrix

在引导过程中选择 Matrix 并检测到 Git 仓库时，OpenClaw 会自动提供本地安装路径。

详情：插件

设置

  1. 安装 Matrix 插件：

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

  2. 在 homeserver 上创建 Matrix 账号：

  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/）给机器人发私信或邀请它加入房间。Beeper 需要启用端到端加密，请设置 channels.matrix.encryption: true 并验证设备。

最小配置（access token，用户 ID 自动获取）：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

端到端加密配置：

{
  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 等）中验证设备以启用密钥共享。
  • 如果加密模块无法加载，端到端加密将被禁用，加密房间无法解密；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（设备）变更，将创建新的存储，机器人需要在加密房间中重新验证。

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

多账户

多账户支持：使用 channels.matrix.accounts 配置每个账户的凭证和可选的 name。参见 gateway/configuration 了解通用模式。

每个账户作为独立的 Matrix 用户运行在任意 homeserver 上。每账户配置继承顶层 channels.matrix 设置，并可覆盖任何选项（私信策略、群组、加密等）。

{
  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 等）仅对默认账户生效。
  • 基础频道设置（私信策略、群组策略、提及过滤等）对所有账户生效，除非按账户覆盖。
  • 使用 bindings[].match.accountId 将每个账户路由到不同代理。
  • 加密状态按账户 + access token 分开存储。

路由模型

  • 回复始终返回 Matrix。
  • 私信共享代理的主会话；房间映射为群组会话。

访问控制（私信）

  • 默认：channels.matrix.dm.policy = "pairing"。未知发送者收到配对码。
  • 审批方式：
    • 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。
  • 不要使用显示名称或纯本地部分（如 "Alice" 或 "alice"）。它们有歧义，在白名单匹配中会被忽略。请使用完整的 @user:server ID。

房间（群组）

  • 默认：channels.matrix.groupPolicy = "allowlist"（需提及）。未设置时使用 channels.defaults.groupPolicy 覆盖默认值。
  • 运行时说明：如果 channels.matrix 完全缺失，运行时对房间检查回退为 groupPolicy="allowlist"（即使设置了 channels.defaults.groupPolicy）。
  • 使用 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

功能支持

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

故障排查

先运行以下诊断命令：

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

然后根据需要确认私信配对状态：

openclaw pairing list matrix

常见故障：

  • 已登录但房间消息被忽略：房间被 groupPolicy 或房间白名单阻止。
  • 私信被忽略：channels.matrix.dm.policy="pairing" 时发送者等待审批。
  • 加密房间失败：加密支持或加密设置不匹配。

诊断流程：/channels/troubleshooting。

配置参考（Matrix）

完整配置：配置

频道选项：

  • channels.matrix.enabled：启用/禁用频道启动。
  • 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：启用端到端加密（默认：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。
  • 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）。
arrow_back
上一页
Line
下一页
Mattermost
arrow_forward