Matrix（插件）

Matrix 是 OpenClaw 的 Matrix 渠道插件。它使用官方 matrix-js-sdk，支持私信、房间、线程、媒体、表情回应、投票、位置和 E2EE 端对端加密。

安装插件

Matrix 是插件，不包含在 OpenClaw 核心包中。

从 npm 安装：

bash

openclaw plugins install @openclaw/matrix

从本地代码仓库安装：

bash

openclaw plugins install ./extensions/matrix

详见插件说明。

配置步骤

安装插件。
在你的 homeserver 上创建一个 Matrix 账号。
配置 channels.matrix，使用以下任一方式：
- homeserver + accessToken，或
- homeserver + userId + password。
重启 Gateway。
向机器人发起私信，或邀请它加入房间。

交互式配置方式：

bash

openclaw channels add
openclaw configure --section channels

Matrix 向导会依次询问：

homeserver URL
认证方式：Access Token 或密码
选择密码认证时才需要填写用户 ID
可选的设备名称
是否启用 E2EE
是否现在配置 Matrix 房间访问权限

向导行为说明：

如果所选账号的 Matrix 认证环境变量已存在且配置中尚未保存该账号的认证信息，向导会提供环境变量快捷方式，只写入 enabled: true。
交互式添加 Matrix 账号时，输入的账号名会被规范化为配置和环境变量中使用的 ID，例如 Ops Bot 会变为 ops-bot。
私信白名单提示支持直接输入完整 @user:server 格式。显示名称只有在目录查询唯一匹配时才有效，否则向导会要求重试并填写完整 Matrix ID。
房间白名单提示支持直接填写房间 ID 和别名。也可以实时解析已加入的房间名称，但未解析的名称仅在配置时保留，运行时白名单解析会忽略它们，建议优先使用 !room:server 或 #alias:server。
运行时的房间/会话标识使用稳定的 Matrix 房间 ID；房间声明的别名仅用于查询，不作为长期会话键。
保存前如需解析房间名称，可使用 openclaw channels resolve --channel matrix "Project Room"。

基于 Token 的最小配置：

json5

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

基于密码的配置（登录后 Token 会被缓存）：

json5

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

Matrix 会将缓存凭证存放在 ~/.openclaw/credentials/matrix/。默认账号使用 credentials.json；命名账号使用 credentials-<account>.json。

对应的环境变量（未设置配置键时使用）：

MATRIX_HOMESERVER
MATRIX_ACCESS_TOKEN
MATRIX_USER_ID
MATRIX_PASSWORD
MATRIX_DEVICE_ID
MATRIX_DEVICE_NAME

非默认账号使用账号作用域的环境变量：

MATRIX_<ACCOUNT_ID>_HOMESERVER
MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
MATRIX_<ACCOUNT_ID>_USER_ID
MATRIX_<ACCOUNT_ID>_PASSWORD
MATRIX_<ACCOUNT_ID>_DEVICE_ID
MATRIX_<ACCOUNT_ID>_DEVICE_NAME

账号 ops 的示例：

MATRIX_OPS_HOMESERVER
MATRIX_OPS_ACCESS_TOKEN

规范化账号 ID ops-bot 的示例：

MATRIX_OPS_BOT_HOMESERVER
MATRIX_OPS_BOT_ACCESS_TOKEN

只有当相应的认证环境变量已存在且所选账号在配置中尚未保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。

配置示例

以下是一个实用的基础配置，启用了私信配对、房间白名单和 E2EE：

json5

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

      dm: {
        policy: "pairing",
      },

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

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

E2EE 加密配置

机器人间通信

默认情况下，来自其他已配置的 OpenClaw Matrix 账号的消息会被忽略。

如需启用智能体之间的 Matrix 通信，使用 allowBots：

json5

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

allowBots: true：在允许的房间和私信中接受来自其他已配置 Matrix 机器人账号的消息。
allowBots: "mentions"：仅当消息在房间中明确 @提及本机器人时才接受；私信仍然允许。
groups.<room>.allowBots 可覆盖账号级设置，针对单个房间生效。
OpenClaw 仍然会忽略来自相同 Matrix 用户 ID 的消息，以避免自回复循环。
Matrix 没有原生的"机器人标志"；OpenClaw 将"机器人发送"定义为"由本 OpenClaw Gateway 上另一个已配置的 Matrix 账号发送"。

在共享房间中启用机器人间通信时，请使用严格的房间白名单和提及要求。

启用加密：

json5

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

检查验证状态：

bash

openclaw matrix verify status

详细状态（完整诊断信息）：

bash

openclaw matrix verify status --verbose

在机器可读输出中包含存储的恢复密钥：

bash

openclaw matrix verify status --include-recovery-key --json

引导跨签名和验证状态：

bash

openclaw matrix verify bootstrap

多账号支持：使用 channels.matrix.accounts 配置每个账号的凭证和可选的 name。详见配置参考。

详细引导诊断：

bash

openclaw matrix verify bootstrap --verbose

在引导前强制重置跨签名身份：

bash

openclaw matrix verify bootstrap --force-reset-cross-signing

使用恢复密钥验证设备：

bash

openclaw matrix verify device "<your-recovery-key>"

查看房间密钥备份健康状态：

bash

openclaw matrix verify backup status

从服务器备份恢复房间密钥：

bash

openclaw matrix verify backup restore

删除当前服务器备份并创建新的备份基线：

bash

openclaw matrix verify backup reset --yes

所有 verify 命令默认输出简洁信息（包括屏蔽 SDK 内部日志），加 --verbose 显示详细诊断。使用 --json 获取完整机器可读输出，便于脚本处理。

多账号时，Matrix CLI 命令默认使用隐式的 Matrix 默认账号，可传入 --account <id> 指定。如果配置了多个命名账号，请先设置 channels.matrix.defaultAccount，否则隐式 CLI 操作会停下来询问你选择账号。需要显式指定账号时，使用 --account：

bash

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

"已验证"的含义

OpenClaw 仅在该 Matrix 设备被你自己的跨签名身份验证后才视为已验证。实际上，openclaw matrix verify status --verbose 会展示三个信任信号：

Locally trusted：该设备仅被当前客户端信任
Cross-signing verified：SDK 报告该设备通过跨签名验证
Signed by owner：该设备被你自己的自签名密钥签名

只有当跨签名验证或拥有者签名存在时，Verified by owner 才会显示为 yes。仅有本地信任不足以让 OpenClaw 视该设备为完全验证状态。

bootstrap 做了什么

openclaw matrix verify bootstrap 是加密 Matrix 账号的修复和配置命令。按顺序执行以下操作：

引导密钥存储，尽可能复用现有恢复密钥
引导跨签名并上传缺失的公共跨签名密钥
尝试标记并交叉签名当前设备
如果服务端没有房间密钥备份，则创建新的备份

如果 homeserver 要求交互式认证才能上传跨签名密钥，OpenClaw 会先尝试无认证上传，然后尝试 m.login.dummy，再尝试 m.login.password（需配置 channels.matrix.password）。

只有在你明确想要丢弃当前跨签名身份并创建新身份时，才使用 --force-reset-cross-signing。

如果你想保留未来的加密消息功能并接受丢失无法恢复的旧历史记录，使用 openclaw matrix verify backup reset --yes。只有在你接受旧的加密历史记录将永久不可用时才执行此操作。

建立新的备份基线

如果你希望保留未来加密消息的正常工作并接受丢失无法恢复的旧历史，按顺序执行：

bash

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

如需针对命名 Matrix 账号执行，每条命令都加上 --account <id>。

启动行为

当 encryption: true 时，Matrix 默认将 startupVerification 设为 "if-unverified"。启动时，如果设备仍未验证，Matrix 会向另一个 Matrix 客户端发起自验证请求，跳过已有待处理请求的重复请求，并在重启后重试前应用本地冷却时间。请求失败后的重试间隔默认短于成功发起请求后的间隔。设置 startupVerification: "off" 可禁用启动时的自动验证请求，或通过 startupVerificationCooldownHours 调整重试窗口时长。

启动时还会自动执行保守的加密引导步骤。该步骤优先复用现有的密钥存储和跨签名身份，除非你运行了显式的引导修复流程，否则不会重置跨签名。

如果启动时发现引导状态损坏，且配置了 channels.matrix.password，OpenClaw 可以尝试更严格的修复路径。如果当前设备已被拥有者签名，OpenClaw 会保留该身份，而不是自动重置。

从旧版 Matrix 插件升级：

OpenClaw 会在可能的情况下自动复用相同的 Matrix 账号、Access Token 和设备身份。
在任何实质性的 Matrix 迁移变更执行前，OpenClaw 会在 ~/Backups/openclaw-migrations/ 下创建或复用恢复快照。
如果你使用多个 Matrix 账号，请在从旧版扁平存储结构升级前设置 channels.matrix.defaultAccount，以便 OpenClaw 知道哪个账号应该接收共享的旧版状态。
如果旧版插件在本地存储了 Matrix 房间密钥备份解密密钥，启动时或 openclaw doctor --fix 会自动将其导入新的恢复密钥流程。
如果迁移准备后 Matrix Access Token 发生了变化，启动时会扫描同级 token-hash 存储根以查找待恢复的旧版状态，再决定放弃自动备份恢复。
如果同一账号、homeserver 和用户的 Access Token 随后发生变化，OpenClaw 会优先复用现有的最完整的 token-hash 存储根，而不是从空的 Matrix 状态目录开始。
下次启动 Gateway 时，已备份的房间密钥会自动恢复到新的加密存储中。
如果旧版插件有从未备份的本地房间密钥，OpenClaw 会明确发出警告。这些密钥无法从旧版 Rust 加密存储自动导出，部分旧的加密历史记录可能需要手动恢复。
完整升级流程、限制、恢复命令和常见迁移消息详见 Matrix 迁移。

加密运行时状态存放在： ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/。该目录包含同步存储（bot-storage.json）、加密存储（crypto/）、恢复密钥文件（recovery-key.json）、IndexedDB 快照（crypto-idb-snapshot.json）、线程绑定（thread-bindings.json）和启动验证状态（startup-verification.json）。当 Token 改变但账号身份不变时，OpenClaw 会为该账号/homeserver/用户组合复用最佳的现有根目录，使旧的同步状态、加密状态、线程绑定和启动验证状态保持可见。

Node 加密存储模型

本插件中的 Matrix E2EE 使用官方 matrix-js-sdk 的 Rust 加密路径（在 Node.js 中运行）。该路径在需要加密状态在重启后持久化时，依赖基于 IndexedDB 的持久化存储。

OpenClaw 在 Node.js 中通过以下方式实现：

使用 fake-indexeddb 作为 SDK 所需的 IndexedDB API 垫片
在 initRustCrypto 前从 crypto-idb-snapshot.json 恢复 Rust 加密 IndexedDB 内容
在初始化后和运行时将更新后的 IndexedDB 内容持久化回 crypto-idb-snapshot.json

这是兼容性/存储管道，而非自定义加密实现。快照文件是敏感的运行时状态，以受限文件权限存储。在 OpenClaw 的安全模型下，Gateway 宿主机和本地 OpenClaw 状态目录已在受信任的运营者边界内，因此这主要是运营可靠性问题，而非独立的远程信任边界。

计划改进：

为持久化 Matrix 密钥材料添加 SecretRef 支持，使恢复密钥和相关存储加密密钥可从 OpenClaw 密钥提供商获取，而不只是本地文件

自动验证通知

Matrix 现在会直接在严格私信验证房间中以 m.notice 消息的形式发布验证生命周期通知，包括：

验证请求通知
验证就绪通知（附带明确的"通过表情验证"引导）
验证开始和完成通知
SAS 详情（表情和十进制）（如可用）

来自其他 Matrix 客户端的验证请求会被 OpenClaw 跟踪并自动接受。对于自我验证流程，当表情验证可用时，OpenClaw 也会自动发起 SAS 流程并确认己方。对于来自其他 Matrix 用户/设备的验证请求，OpenClaw 自动接受请求，然后等待 SAS 流程正常进行。你仍然需要在 Matrix 客户端中比对表情或十进制 SAS，并确认"匹配"才能完成验证。

OpenClaw 不会盲目自动接受自发起的重复流程。如果自验证请求已在等待中，启动时会跳过新请求的创建。

验证协议/系统通知不会转发到智能体聊天管道，因此不会产生 NO_REPLY。

设备清理

旧的 OpenClaw 管理的 Matrix 设备可能会在账号上积累，使加密房间的信任关系难以理清。查看设备列表：

bash

openclaw matrix devices list

删除过期的 OpenClaw 管理设备：

bash

openclaw matrix devices prune-stale

直接房间修复

如果私信状态不同步，OpenClaw 可能会产生指向旧独立房间而非活跃私信的陈旧 m.direct 映射。检查某个联系人的当前映射：

bash

openclaw matrix direct inspect --user-id @alice:example.org

修复映射：

bash

openclaw matrix direct repair --user-id @alice:example.org

修复逻辑优先级：

优先选择已在 m.direct 中映射的严格 1:1 私信
其次回退到与该用户当前已加入的任何严格 1:1 私信
如果没有健康的私信，则创建新的私信房间并更新 m.direct 映射

修复流程不会自动删除旧房间，只会选出健康的私信并更新映射，让新的 Matrix 发送、验证通知等直接消息流指向正确的房间。

线程（Threads）

Matrix 支持自动回复和消息工具发送的原生 Matrix 线程。

threadReplies: "off"：回复保持在顶层。
threadReplies: "inbound"：仅当入站消息本身在线程中时，才在该线程内回复。
threadReplies: "always"：将房间回复保持在以触发消息为根的线程中。
入站线程消息会将线程根消息作为额外的智能体上下文。
消息工具发送现在会自动继承当前 Matrix 线程（目标为相同房间或相同私信用户时），除非显式提供了 threadId。
Matrix 支持运行时线程绑定。/focus、/unfocus、/agents、/session idle、/session max-age 和线程绑定的 /acp spawn 现在可在 Matrix 房间和私信中使用。
顶层 Matrix 房间/私信的 /focus 会在 threadBindings.spawnSubagentSessions=true 时创建新的 Matrix 线程并绑定到目标会话。
在现有 Matrix 线程内运行 /focus 或 /acp spawn --thread here 会绑定到当前线程。

线程绑定配置

Matrix 继承 session.threadBindings 的全局默认值，也支持每渠道覆盖：

threadBindings.enabled
threadBindings.idleHours
threadBindings.maxAgeHours
threadBindings.spawnSubagentSessions
threadBindings.spawnAcpSessions

Matrix 线程绑定的派生标志是可选启用的：

设置 threadBindings.spawnSubagentSessions: true 以允许顶层 /focus 创建并绑定新的 Matrix 线程。
设置 threadBindings.spawnAcpSessions: true 以允许 /acp spawn --thread auto|here 将 ACP 会话绑定到 Matrix 线程。

表情回应

Matrix 支持出站表情回应操作、入站表情回应通知和入站确认回应。

出站表情回应工具受 channels["matrix"].actions.reactions 控制。
react 向特定 Matrix 事件添加表情回应。
reactions 列出特定 Matrix 事件的当前回应汇总。
emoji="" 移除机器人账号对该事件的所有回应。
remove: true 仅移除机器人账号对该事件指定的表情回应。

确认回应遵循 OpenClaw 的标准解析顺序：

channels["matrix"].accounts.<accountId>.ackReaction
channels["matrix"].ackReaction
messages.ackReaction
智能体身份 emoji 兜底

确认回应作用域解析顺序：

channels["matrix"].accounts.<accountId>.ackReactionScope
channels["matrix"].ackReactionScope
messages.ackReactionScope

回应通知模式解析顺序：

channels["matrix"].accounts.<accountId>.reactionNotifications
channels["matrix"].reactionNotifications
默认：own

当前行为：

reactionNotifications: "own"：转发针对机器人发送的 Matrix 消息的新增 m.reaction 事件。
reactionNotifications: "off"：禁用回应系统事件。
回应删除仍未合成为系统事件，因为 Matrix 将其作为 redaction 处理，而非独立的 m.reaction 删除事件。

私信和房间策略示例

json5

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

详见群组消息中的提及门控和白名单行为说明。

Matrix 私信配对示例：

bash

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

如果未审批的 Matrix 用户在批准前持续发消息，OpenClaw 会复用相同的待处理配对码，并在短暂冷却后可能再次发送提醒回复，而不是生成新的配对码。

详见配对中的共享私信配对流程和存储结构。

多账号示例

json5

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
          },
        },
      },
    },
  },
}

顶层 channels.matrix 的值作为命名账号的默认值，除非账号覆盖了它们。当你希望 OpenClaw 优先使用某个命名 Matrix 账号进行隐式路由、探测和 CLI 操作时，设置 defaultAccount。如果配置了多个命名账号，请设置 defaultAccount 或在依赖隐式账号选择的 CLI 命令中传入 --account <id>。

私有/局域网 homeserver

默认情况下，OpenClaw 会阻止私有/内部 Matrix homeserver 连接（防止 SSRF），除非你明确为每个账号选择启用。

如果你的 homeserver 运行在 localhost、局域网/Tailscale IP 或内部主机名上，为该 Matrix 账号启用 allowPrivateNetwork：

json5

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}

CLI 配置示例：

bash

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

此选项只允许受信任的私有/内部目标，公开的明文 homeserver（如 http://matrix.example.org:8008）仍被阻止。建议尽可能使用 https://。

目标解析

Matrix 在 OpenClaw 要求你提供房间或用户目标时，接受以下格式：

用户：@user:server、user:@user:server 或 matrix:user:@user:server
房间：!room:server、room:!room:server 或 matrix:room:!room:server
别名：#alias:server、channel:#alias:server 或 matrix:channel:#alias:server

实时目录查询使用已登录的 Matrix 账号：

用户查询在该 homeserver 上查询 Matrix 用户目录。
房间查询直接接受明确的房间 ID 和别名，然后回退到搜索该账号已加入的房间名称。
已加入房间的名称查询仅为尽力而为。如果房间名称无法解析为 ID 或别名，运行时白名单解析会忽略它。

配置参考

enabled：启用或禁用渠道。
name：账号的可选标签。
defaultAccount：配置多个 Matrix 账号时的首选账号 ID。
homeserver：homeserver URL，例如 https://matrix.example.org。
allowPrivateNetwork：允许该 Matrix 账号连接到私有/内部 homeserver。当 homeserver 解析为 localhost、局域网/Tailscale IP 或内部主机（如 matrix-synapse）时启用。
userId：完整的 Matrix 用户 ID，例如 @bot:example.org。
accessToken：基于 Token 认证的 Access Token。
password：基于密码登录的密码。
deviceId：显式 Matrix 设备 ID。
deviceName：密码登录时的设备显示名称。
avatarUrl：存储的自我头像 URL，用于档案同步和 set-profile 更新。
initialSyncLimit：启动同步事件限制。
encryption：启用 E2EE。
allowlistOnly：对私信和房间强制执行仅白名单行为。
groupPolicy：open、allowlist 或 disabled。
groupAllowFrom：房间流量的用户 ID 白名单。条目应为完整的 Matrix 用户 ID，未解析的名称在运行时会被忽略。
replyToMode：off、first 或 all。
threadReplies：off、inbound 或 always。
threadBindings：线程绑定会话路由和生命周期的每渠道覆盖。
startupVerification：启动时的自动自验证请求模式（if-unverified、off）。
startupVerificationCooldownHours：重试自动启动验证请求前的冷却时间。
textChunkLimit：出站消息分块大小。
chunkMode：length 或 newline。
responsePrefix：出站回复的可选消息前缀。
ackReaction：该渠道/账号的可选确认回应覆盖。
ackReactionScope：可选确认回应作用域覆盖（group-mentions、group-all、direct、all、none、off）。
reactionNotifications：入站回应通知模式（own、off）。
mediaMaxMb：出站媒体大小上限（MB）。
autoJoin：邀请自动加入策略（always、allowlist、off）。默认：off。
autoJoinAllowlist：autoJoin 为 allowlist 时允许的房间/别名。别名条目在处理邀请时解析为房间 ID；OpenClaw 不信任被邀请房间声明的别名状态。
dm：私信策略块（enabled、policy、allowFrom）。dm.allowFrom 条目应为完整的 Matrix 用户 ID，除非已通过实时目录查询解析。
accounts：命名的每账号覆盖。顶层 channels.matrix 的值作为这些条目的默认值。
groups：每房间策略映射。优先使用房间 ID 或别名；未解析的房间名称在运行时被忽略。解析后的会话/群组标识使用稳定的房间 ID，可读标签仍来自房间名称。
rooms：groups 的旧版别名。
actions：每操作工具控制（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。

Matrix（插件） ​

安装插件 ​

配置步骤 ​

配置示例 ​

E2EE 加密配置 ​

机器人间通信 ​

"已验证"的含义 ​

bootstrap 做了什么 ​

建立新的备份基线 ​

启动行为 ​

Node 加密存储模型 ​

自动验证通知 ​

设备清理 ​

直接房间修复 ​

线程（Threads） ​

线程绑定配置 ​

表情回应 ​

私信和房间策略示例 ​

多账号示例 ​

私有/局域网 homeserver ​

目标解析 ​

配置参考 ​

Matrix（插件）

安装插件

配置步骤

配置示例

E2EE 加密配置

机器人间通信

"已验证"的含义

bootstrap 做了什么

建立新的备份基线

启动行为

Node 加密存储模型

自动验证通知

设备清理

直接房间修复

线程（Threads）

线程绑定配置

表情回应

私信和房间策略示例

多账号示例

私有/局域网 homeserver

目标解析

配置参考