跳转至

设置

安装 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 管理界面中创建 access token;密码认证会在首次登录时为你签发并缓存一个。
  3. 检查 openclaw channels status --probe;如果 Gateway 处于离线状态,请启动它。配置更改遵循热重载。
  4. 与机器人开始一个 DM,或将其邀请到房间中。新邀请只有在 autoJoin 允许时才会送达。

交互式设置

openclaw channels add
openclaw configure --section channels

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

最小配置

基于 Token:

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

基于密码(首次登录后 token 会被缓存):

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

Token 和密码 SecretRefs 遵循共享的特定来源的 provider-alias 规则,包括命名账户。显式匹配的 env provider 仍会强制应用其允许列表;空允许列表会拒绝所有变量。

自动加入

channels.matrix.autoJoin 默认为 "off":在你手动加入之前,机器人不会出现在来自新邀请的新房间或 DM 中。OpenClaw 无法在收到邀请时判断该邀请是 DM 还是群组,因此每个邀请都会先经过 autoJoin;dm.policy 只在之后应用,即机器人已加入且房间被分类之后。

Warning

设置 autoJoin: "allowlist" 并配合 autoJoinAllowlist 以限制接受的邀请,或设置 autoJoin: "always" 以接受所有邀请。

autoJoinAllowlist 仅接受字面房间 ID(!roomId:server,或 房间版本 12 及更高版本使用的无后缀 !roomId 形式)、#alias:server 或 *。普通房间名称和 Matrix 用户 ID(@user:server)不是房间目标:设置向导会拒绝它们,运行时也会记录一条警告,指出任何此类已保存条目并忽略它。请改用 dm.allowFrom 或 groupAllowFrom 授权发送者。别名会针对 homeserver 解析,而不是针对被邀请房间声称的状态。

{
  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"):使用具有精确 Matrix 大小写的 user:@user:server。
  • 房间允许列表键(groups、旧版别名 rooms):使用 !room:server(或房间版本 12+ 上的无后缀 !room 形式)或 #alias:server。除非设置 dangerouslyAllowNameMatching: true,否则普通名称会被忽略。
  • 邀请允许列表(autoJoinAllowlist):使用 !room:server(或房间版本 12+ 上的无后缀 !room)、#alias:server 或 *。普通名称和用户 ID 无法匹配房间;运行时会警告并忽略它们,因此请使用 dm.allowFrom 进行发送者匹配。

账户 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 行,然后归档这些文件。

环境变量

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

默认账户 命名账户(<ID> = 账户令牌)
MATRIX_HOMESERVER MATRIX_<ID>_HOMESERVER
MATRIX_ACCESS_TOKEN MATRIX_<ID>_ACCESS_TOKEN
MATRIX_USER_ID MATRIX_<ID>_USER_ID
MATRIX_PASSWORD MATRIX_<ID>_PASSWORD
MATRIX_DEVICE_ID MATRIX_<ID>_DEVICE_ID
MATRIX_DEVICE_NAME MATRIX_<ID>_DEVICE_NAME

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

Note

恢复密钥不是由配置支持的环境变量:OpenClaw 本身从不从环境中读取它。CLI 引导文本建议通过名为 MATRIX_RECOVERY_KEY 的 shell 变量传递它(用于默认账户),或通过 MATRIX_RECOVERY_KEY_<ID>(普通大写账户 ID,不进行十六进制转义)传递(用于命名账户)——参见使用恢复密钥验证此设备。

配置示例

一个包含 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" },
    },
  },
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw