Matrix（插件）

Matrix 是一个开放的、去中心化的消息协议（messaging protocol）。OpenClaw 以 Matrix 用户（user） 身份连接到任何家庭服务器（homeserver），因此您需要为机器人创建一个 Matrix 账户。登录后，您可以直接私信机器人，或将其邀请到房间（Matrix "群组"）。Beeper 也是一个有效的客户端选项，但它需要启用端到端加密（E2EE）。

状态：通过插件（@vector-im/matrix-bot-sdk）支持。直接消息（direct messages）、房间（rooms）、线程（threads）、媒体、反应（reactions）、投票（发送 + poll-start 作为文本）、位置，以及端到端加密（E2EE，需要加密支持）。

需要插件

Matrix 作为插件提供，不包含在核心安装中。

通过 CLI 安装（npm 注册表）：

openclaw plugins install @openclaw/matrix

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

openclaw plugins install ./extensions/matrix

如果您在配置/入门（configure/onboarding）期间选择 Matrix 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。

详情：插件（Plugins）

设置

  1. 安装 Matrix 插件：

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

  2. 在家庭服务器（homeserver）上创建 Matrix 账户：

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

    • 在您的家庭服务器上使用 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，并在下次启动时重用。

  4. 配置凭据（credentials）：

    • 环境变量：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（或 MATRIX_USER_ID + MATRIX_PASSWORD）
    • 或配置：channels.matrix.*
    • 如果两者都设置，配置优先。
    • 使用访问令牌时：用户 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 并验证设备。

最小配置（访问令牌，用户 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 支持端到端加密（End-to-end encryption）。

使用 channels.matrix.encryption: true 启用：

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

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

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

路由模型（Routing model）

  • 回复始终返回到 Matrix。
  • 直接消息（DMs）共享代理的主会话（main session）；房间映射到群组会话（group sessions）。

访问控制（DMs）

  • 默认：channels.matrix.dm.policy = "pairing"。未知发送者会收到配对码（pairing code）。
  • 批准方式：
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • 公开直接消息（DMs）：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 将房间加入允许列表（allowlist）（房间 ID、别名或名称）：
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true }
      },
      groupAllowFrom: ["@owner:example.org"]
    }
  }
}
  • requireMention: false 在该房间启用自动回复（auto-reply）。
  • groups."*" 可以为所有房间设置提及门控（mention gating）的默认值。
  • groupAllowFrom 限制哪些发送者可以在房间中触发机器人（可选）。
  • 每个房间的 users 允许列表可以进一步限制特定房间内的发送者。
  • 配置向导会提示输入房间允许列表（房间 ID、别名或名称），并在可能时解析名称。
  • 启动时，OpenClaw 会将允许列表中的房间/用户名称解析为 ID 并记录映射；未解析的条目保持原样。
  • 默认自动加入邀请；使用 channels.matrix.autoJoin 和 channels.matrix.autoJoinAllowlist 控制。
  • 要不允许任何房间，设置 channels.matrix.groupPolicy: "disabled"（或保持空的允许列表）。
  • 旧版键：channels.matrix.rooms（与 groups 形状相同）。

线程（Threads）

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

功能

功能状态
直接消息（Direct messages）✅ 支持
房间（Rooms）✅ 支持
线程（Threads）✅ 支持
媒体（Media）✅ 支持
端到端加密（E2EE）✅ 支持（需要加密模块）
反应（Reactions）✅ 支持（通过工具发送/读取）
投票（Polls）✅ 支持发送；入站投票开始转换为文本（响应/结束被忽略）
位置（Location）✅ 支持（geo URI；忽略海拔）
原生命令（Native commands）✅ 支持

配置参考（Matrix）

完整配置：配置（Configuration）

提供商选项（Provider options）：

  • channels.matrix.enabled：启用/禁用频道启动。
  • channels.matrix.homeserver：家庭服务器（homeserver）URL。
  • channels.matrix.userId：Matrix 用户 ID（使用访问令牌时可选）。
  • channels.matrix.accessToken：访问令牌（access token）。
  • 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：直接消息（DM）允许列表（用户 ID 或显示名称）。open 需要 "*"。向导在可能时将名称解析为 ID。
  • channels.matrix.groupPolicy：allowlist | open | disabled（默认：allowlist）。
  • channels.matrix.groupAllowFrom：群组消息的允许发送者列表。
  • channels.matrix.allowlistOnly：强制直接消息（DMs）+ 房间的允许列表规则。
  • 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）。
← 返回文档首页