Matrix (plugin)

适用范围

在以下情况使用此页面：

• 在 Matrix 通道功能上工作

Matrix 是一个开放的去中心化消息传递协议。Moltbot 在任何主服务器上作为 Matrix 用户连接，因此您需要机器人的 Matrix 帐户。登录后，您可以直接向机器人发送 DM 或将其邀请到房间（Matrix"群组"）。Beeper 也是一个有效的客户端选项，但它需要启用 E2EE。

状态：通过插件支持（matrix-bot-sdk）。直接消息、房间、线程、媒体、反应、投票（发送 + 以文本开始轮询）、位置和 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. 在主服务器上创建 Matrix 帐户：

   • 在 https://matrix.org/ecosystem/hosting/ 浏览托管选项
   • 或自己托管。

3. 获取机器人帐户的访问令牌：

   • 使用 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 替换为您的主服务器 URL。
   • 或设置 channels.matrix.userId + channels.matrix.password：Moltbot 调用相同的登录端点，将访问令牌存储在 ~/.moltbot/credentials/matrix/credentials.json 中，并在下次启动时重用它。

4. 配置凭据：

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

5. 重启网关（或完成入门）。

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 支持端到端加密。

通过 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 获取二进制文件。

加密状态每个帐户 + 访问令牌存储在 ~/.moltbot/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLite 数据库）中。同步状态与其一起位于 bot-storage.json 中。如果访问令牌（设备）更改，则会创建新存储，并且必须为加密房间重新验证机器人。

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

路由模型

• 回复总是回到 Matrix。
• DM 共享代理的主会话；房间映射到群组会话。

访问控制（DM）

• 默认：channels.matrix.dm.policy = "pairing"。未知发送者获得配对代码。
• 通过以下方式批准：
  • moltbot pairing list matrix
  • moltbot 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、别名或名称）并在可能时解析名称。
• 启动时，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

功能

配置参考（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：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：线程/标签的回复到模式。
• channels.matrix.mediaMaxMb：入站/出站媒体上限（MB）。
• channels.matrix.autoJoin：邀请处理（always | allowlist | off，默认：always）。
• channels.matrix.autoJoinAllowlist：用于自动加入的允许房间 ID/别名。
• channels.matrix.actions：每操作工具门控（反应/消息/固定/memberInfo/channelInfo）。