Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道Matrix

Matrix（插件）

Matrix 是开放、去中心化的消息协议。Moltbot 以 Matrix 用户身份连接任意 homeserver，因此需要为机器人准备一个 Matrix 账号。登录后，可直接私信机器人或将机器人邀请到房间（Matrix 的“群组”）。Beeper 也可作为客户端，但需启用 E2EE。状态：通过插件（@vector-im/matrix-bot-sdk）支持。私信、房间、线程、媒体、表态、投票（发送 + 以文本形式接收 poll-start）、位置与 E2EE（需加密支持）均已支持。

需要安装插件

Matrix 以插件形式提供，不随核心安装打包。通过 CLI 安装（npm 源）：

moltbot plugins install @moltbot/matrix

本地代码库（从 git 仓库运行时）：

moltbot plugins install ./extensions/matrix

在配置/入门中选择 Matrix 且检测到 git 仓库时，Moltbot 会自动提示本地安装路径。详见 插件。

设置

  1. 安装 Matrix 插件
    • 从 npm：moltbot plugins install @moltbot/matrix
    • 从本地代码库：moltbot plugins install ./extensions/matrix
  2. 在 homeserver 上创建 Matrix 账号
  3. 获取机器人账号的 access token
    • 在 homeserver 上使用 Matrix 登录 API（curl）：
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：Moltbot 会调用同一登录端点，将 access token 存入 ~/.clawdbot/credentials/matrix/credentials.json，下次启动时复用。
  1. 配置凭据
    • 环境变量：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（或 MATRIX_USER_ID + MATRIX_PASSWORD）
    • 或配置：channels.matrix.*
    • 若两者都设，以配置为准。
    • 使用 access token 时，用户 ID 会通过 /whoami 自动获取。
    • 若设置，channels.matrix.userId 应为完整 Matrix ID（例如 @bot:example.org）。
  2. 重启网关（或完成入门向导）。
  3. 从任意 Matrix 客户端（Element、Beeper 等，见 https://matrix.org/ecosystem/clients/ ）与机器人发起私信或将机器人邀请到房间。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：

  • 若加密模块加载成功，加密房间会自动解密。
  • 发往加密房间的出站媒体会加密。
  • 首次连接时，Moltbot 会向你的其他会话请求设备验证。
  • 在另一 Matrix 客户端（如 Element）中验证设备以启用密钥共享。
  • 若加密模块无法加载，E2EE 关闭，加密房间将无法解密；Moltbot 会记录警告。
  • 若出现加密模块缺失错误（例如 @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 存储在 ~/.clawdbot/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLite 数据库）。同步状态同在 bot-storage.json。若 access token（设备）变更，会创建新存储，机器人需在加密房间中重新验证。设备验证： 启用 E2EE 后，机器人会在启动时向你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证通过后，机器人即可解密加密房间中的消息。

路由模型

  • 回复始终发回 Matrix。
  • 私信共享 agent 主会话；房间映射到群组会话。

访问控制（私信）

  • 默认：channels.matrix.dm.policy = "pairing"。未知发件人会收到配对码。
  • 批准方式：moltbot pairing list matrix、moltbot pairing approve matrix <CODE>。
  • 开放私信：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、别名或名称），在可能时解析名称。
  • 启动时，Moltbot 将白名单中的房间/用户名解析为 ID 并记录映射；无法解析的条目保持原样。
  • 邀请默认自动加入；通过 channels.matrix.autoJoin 与 channels.matrix.autoJoinAllowlist 控制。
  • 若要禁止所有房间，设 channels.matrix.groupPolicy: "disabled"（或保持空白名单）。
  • 旧版键：channels.matrix.rooms（与 groups 结构相同）。

线程

  • 支持回复进线程。
  • channels.matrix.threadReplies 控制回复是否保持在线程内：off、inbound（默认）、always。
  • channels.matrix.replyToMode 控制非线程回复时的“回复给”元数据：off（默认）、first、all。

能力

功能状态
私信✅ 支持
房间✅ 支持
线程✅ 支持
媒体✅ 支持
E2EE✅ 支持（需加密模块）
表态✅ 支持（通过工具发送/读取）
投票✅ 发送支持；入站 poll-start 转为文本（responses/ends 忽略）
位置✅ 支持（geo URI；海拔忽略）
原生命令✅ 支持

配置参考（Matrix）

完整配置见 配置。本频道选项包括：channels.matrix.enabled、homeserver、userId、accessToken、password、deviceName、encryption、initialSyncLimit、threadReplies、textChunkLimit、chunkMode、dm.policy、dm.allowFrom、groupPolicy、groupAllowFrom、allowlistOnly、groups、rooms、replyToMode、mediaMaxMb、autoJoin、autoJoinAllowlist、actions（按动作的工具门控：reactions/messages/pins/memberInfo/channelInfo）。

最后更新于:
Location 位置Mattermost