Matrix 设置

安装 Matrix 插件，将其指向家庭服务器，然后选择如何处理邀请、许可名单和凭据。

安装

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. 配置channels.matrix和homeserver + accessToken， or homeserver + userId + password。在您的中创建访问令牌Matrix客户端或家庭服务器管理员UI；密码验证会在您第一次登录时为您铸造并缓存一个密码。
3. 检查openclaw channels status --probe；如果网关离线，则启动网关。配置更改遵循 hot reload。
4. 与机器人启动 DM，或邀请其进入房间。新邀请仅在 autoJoin 允许时才会登陆。

交互式设置

openclaw channels addopenclaw configure --section channels

向导要求家庭服务器URL、身份验证方法（令牌或密码）、用户ID（仅限密码验证），可选设备名称，是否启用E2EE，和房间access/auto-join.如果匹配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" },    },  },}

基于密码（首次登录后会缓存 token）：

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

令牌和密码 SecretRefs 遵循共享的 源特定提供商别名规则 ，包括命名帐户。显式匹配的 env 提供程序仍然强制执行其白名单；空的允许列表拒绝所有变量。

自动加入

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

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

当帐户停止或重新加载时，Matrix 在 30 秒没有任务进展的情况下停止等待后台任务。来自已退休监视器的延迟任务无法启动连接或通过仍在为另一个监视器提供服务的客户端发送。

集团加盟介绍

当机器人加入允许的群组房间时，它会发布一条基于房间名称、主题和最多 100 条可读的最近房间消息的介绍。如果读取历史记录失败，则介绍仅使用可用的元数据，并且不会发明房间活动。

默认情况下启用介绍。设置 channels.matrix.joinIntro: false 以禁用它们，或使用 channels.matrix.accounts.<accountId>.joinIntro 覆盖一个帐户。直接房间从来不接受介绍。只有实际的加入转换才会触发以下情况：未接受的邀请、现有房间的启动快照或已加入的个人资料更新不会触发。这不会更改 autoJoin，默认为 "off"。

请参阅 群组加入介绍 了解房间准入、每个房间一次的行为以及将房间内容视为不可信的无工具转向。

Allowlist 目标格式

Matrix用户 ID 区分大小写。准确复制@user:server价值Matrix每个白名单、审批者和审批目标字段的报告。如果现有配置使用不同的大小写，请手动更新；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 无法匹配房间；运行时会发出警告并忽略它们，因此请使用 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 行，然后归档文件。

环境变量

基于配置键的环境变量：当对应的配置键未设置时会使用它们。默认账户使用不带前缀的名称；命名账户会在后缀前插入账户令牌（见规范化）。

对于账户 ops，名称会变为 MATRIX_OPS_HOMESERVER、MATRIX_OPS_ACCESS_TOKEN 等。MATRIX_HOMESERVER（以及任何 *_HOMESERVER 作用域变体）不能从 workspace .env 中设置；见Workspace .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" },    },  },}