设置

安装 Matrix 插件，将其指向一个 homeserver，并选择如何处理邀请、允许列表和凭据。

安装¶

openclaw plugins install @openclaw/matrix

@openclaw/matrix 会先从 npm 安装，只有当 npm 目标不可用时，才会回退到其声明的 ClawHub 包。使用 npm: 或 clawhub: 可强制指定来源。从本地检出安装：openclaw plugins install ./path/to/local/matrix-plugin。

plugins install 会注册并启用插件；无需单独的 enable 步骤。在完成以下配置之前，该通道仍不会执行任何操作。通用安装规则参见 插件。

设置¶

1. 在你的 homeserver 上创建一个 Matrix 账户。
2. 使用 homeserver + accessToken，或 homeserver + userId + password 配置 channels.matrix。在你的 Matrix 客户端或 homeserver 管理界面中创建访问令牌；密码认证会在首次登录时为你签发并缓存一个令牌。
3. 检查 openclaw channels status --probe；如果 Gateway 离线，请启动它。配置更改遵循 热重载。
4. 与机器人开始 DM，或邀请它加入房间。只有当 autoJoin 允许时，新邀请才会生效。

交互式设置¶

openclaw channels add
openclaw configure --section channels

向导会询问 homeserver URL、认证方式（令牌或密码）、用户 ID（仅密码认证）、可选的设备名称、是否启用 E2EE，以及房间访问/自动加入。如果已存在匹配的 MATRIX_* 环境变量，且账户没有已保存的认证信息，向导会提供环境变量快捷方式。在保存允许列表之前，使用 openclaw channels resolve --channel matrix "Project Room" 解析房间名称。在向导中启用 E2EE 会执行与 openclaw matrix encryption setup 相同的引导流程。

最小配置¶

基于令牌：

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

基于密码（首次登录后令牌会被缓存）：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

令牌和密码 SecretRefs 遵循共享的 特定来源的 provider-alias 规则，包括命名账户。显式匹配的 env provider 仍会执行其允许列表；空允许列表会拒绝所有变量。

自动加入¶

channels.matrix.autoJoin 默认为 "off"：在你手动加入之前，机器人不会出现在由新邀请产生的新房间或 DM 中。OpenClaw 在收到邀请时无法判断该邀请是 DM 还是群组，因此每个邀请都会先经过 autoJoin；dm.policy 只在机器人加入且房间被分类之后才生效。

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}

群组加入介绍¶

当机器人加入一个被允许的群组房间时，它会发布一条介绍，内容基于房间名称、主题以及最多 100 条可读的最近房间消息。如果读取历史失败，介绍将只使用可用元数据，并且不会虚构房间活动。

介绍默认启用。设置 channels.matrix.joinIntro: false 可禁用它们，或使用 channels.matrix.accounts.<accountId>.joinIntro 覆盖单个账户。直接房间永远不会收到介绍。只有实际的加入转换才会触发一次：未接受的邀请、现有房间的启动快照，或已加入时的个人资料更新都不会触发。这不会改变 autoJoin，其默认为 "off"。

有关房间准入、每房间一次的行为，以及将房间内容视为不可信的无工具回合，参见 群组加入介绍。

允许列表目标格式¶

Matrix 用户 ID 区分大小写。对于每个允许列表、审批人和审批目标字段，请复制 Matrix 报告的精确 @user:server 值。如果现有配置使用了不同的大小写，请手动更新；OpenClaw 无法安全地推断或重写目标账户，因为大小写不同的 ID 可能标识不同的用户。

• DM（dm.allowFrom、groupAllowFrom、groups.<room>.users）：使用 @user:server。显示名称默认被忽略（可修改）；仅在需要显式显示名称兼容性时设置 dangerouslyAllowNameMatching: true。
• 审批转发（approvals.exec.targets[].to 且 channel: "matrix"）：使用 user:@user:server，并保持 Matrix 的精确大小写。
• 房间允许列表键（groups，旧别名 rooms）：使用 !room:server（或房间版本 12+ 的无后缀 !room 形式）或 #alias:server。除非设置 dangerouslyAllowNameMatching: true，否则普通名称会被忽略。
• 邀请允许列表（autoJoinAllowlist）：使用 !room:server（或房间版本 12+ 的无后缀 !room）、#alias:server 或 *。普通名称始终被拒绝。

账户 ID 规范化¶

向导会将友好名称转换为规范化账户 ID（Ops Bot -> ops-bot）。作用域环境变量名称中的标点符号会进行十六进制转义，以避免账户冲突：-（0x2D）变为 _X2D_，因此 ops-prod 映射到环境变量前缀 MATRIX_OPS_X2D_PROD_。

缓存的凭据¶

Matrix 将账户凭据缓存在共享的 state/openclaw.sqlite 插件状态中。当存在缓存凭据时，即使配置文件中没有 accessToken，OpenClaw 也会将 Matrix 视为已配置——这涵盖设置、openclaw doctor 和通道状态探测。升级会通过 openclaw doctor --fix 导入已弃用的 ~/.openclaw/credentials/matrix/credentials*.json 文件，验证 SQLite 行，然后归档这些文件。

环境变量¶

由配置键支持的环境变量，在等效配置键未设置时使用。默认账户使用无前缀名称；命名账户会在后缀前插入账户令牌（参见规范化）。

对于账户 ops，名称变为 MATRIX_OPS_HOMESERVER、MATRIX_OPS_ACCESS_TOKEN 等。MATRIX_HOMESERVER（以及任何 *_HOMESERVER 作用域变体）不能从工作区 .env 中设置；参见工作区 .env 文件。

配置示例¶

一个包含 DM 配对、房间允许列表和 E2EE 的实用基线：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: { mode: "partial" },
    },
  },
}