Matrix 渠道让 OpenClaw 网关接入任意 Matrix 自托管服务器，支持 E2EE、DM 和房间消息。配置时提供 homeserver URL 和 access token（或密码），并通过 openclaw matrix verify 完成跨签名验证。注意 autoJoin 默认关闭，需显式启用才能自动接受邀请。

OpenClaw Matrix 渠道配置与E2EE加密指南

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

安装

从 ClawHub 安装 Matrix 插件后再进行渠道配置：

bash

openclaw plugins install @openclaw/matrix

裸插件规范会优先尝试 ClawHub，然后回退到 npm。如需强制指定注册来源，使用 openclaw plugins install clawhub:@openclaw/matrix 或 openclaw plugins install npm:@openclaw/matrix。

从本地仓库安装：

bash

openclaw plugins install ./path/to/local/matrix-plugin

plugins install 会注册并启用插件，因此无需单独执行 openclaw plugins enable matrix。但插件仍需完成下方渠道配置后才能生效。详见插件文档。

配置步骤

在您的 homeserver 上创建一个 Matrix 账号。
配置 channels.matrix，使用以下任一方式：
- homeserver + accessToken，或
- homeserver + userId + password
重启 Gateway。
向机器人发起私信，或邀请它加入房间（参见 auto-join - 新邀请只有在 autoJoin 允许时才会被接受）。

交互式配置

bash

openclaw channels add
openclaw configure --section channels

向导会依次询问：homeserver URL、认证方式（access token 或密码）、用户 ID（密码认证时才有）、可选的设备名称、是否启用 E2EE、是否配置房间访问权限和自动加入。

如果已存在匹配的 MATRIX_* 环境变量且所选账号尚未保存认证信息，向导会提供环境变量快捷方式。保存白名单前如需解析房间名称，运行 openclaw channels resolve --channel matrix "Project Room"。启用 E2EE 时，向导会写入配置并运行与 openclaw matrix encryption setup 相同的引导流程。

最小配置

基于 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",
    },
  },
}

自动加入 (auto-join)

channels.matrix.autoJoin 默认为 off。默认情况下，机器人不会自动出现在新房间或新邀请的私信中，需手动加入。

OpenClaw 在邀请时无法判断被邀请的房间是私信还是群组，因此所有邀请（包括私信风格邀请）都先经过 autoJoin 处理。dm.policy 只在机器人加入并分类房间后生效。

WARNING

设置 autoJoin: "allowlist" 并配合 autoJoinAllowlist 限制机器人接受的邀请，或 autoJoin: "always" 接受所有邀请。

autoJoinAllowlist 只接受稳定目标：!roomId:server、#alias:server 或 *。纯房间名称会被拒绝；别名条目会针对 homeserver 解析，而不是针对被邀请房间声明的状态。

json5

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

要接受所有邀请，使用 autoJoin: "always"。

白名单目标格式

私信和房间白名单最好使用稳定 ID 填充：

私信 (dm.allowFrom, groupAllowFrom, groups.<room>.users)：使用 @user:server。默认忽略显示名称，因为它们是可变的；只有在你明确需要兼容显示名称条目时，才设置 dangerouslyAllowNameMatching: true。
房间白名单键 (groups, 旧版 rooms)：使用 !room:server 或 #alias:server。默认忽略纯房间名称；只有在你明确需要兼容已加入房间的名称查询时，才设置 dangerouslyAllowNameMatching: true。
邀请白名单 (autoJoinAllowlist)：使用 !room:server、#alias:server 或 *。纯房间名称会被拒绝。

账号 ID 规范化

向导会将友好名称转换为规范化的账号 ID。例如 Ops Bot 会变成 ops-bot。标点符号会在作用域环境变量名中转义，避免两个账号冲突：- → _X2D_，因此 ops-prod 映射为 MATRIX_OPS_X2D_PROD_*。

缓存凭证

Matrix 将缓存凭证存放在 ~/.openclaw/credentials/matrix/：

默认账号：credentials.json
命名账号：credentials-<account>.json

当缓存凭证存在时，即使配置文件中没有 access token，OpenClaw 也会将 Matrix 视为已配置状态——这适用于 setup、openclaw doctor 和渠道状态探测。

环境变量

当未设置等效配置键时使用。默认账号使用无前缀名称；命名账号使用账号 ID 插入后缀前。

默认账号	命名账号 (`<ID>` 是规范化账号 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`
`MATRIX_RECOVERY_KEY`	`MATRIX_<ID>_RECOVERY_KEY`

对于账号 ops，名称变为 MATRIX_OPS_HOMESERVER、MATRIX_OPS_ACCESS_TOKEN 等。恢复密钥环境变量会被支持恢复的 CLI 流程（verify backup restore、verify device、verify bootstrap）读取，当你通过 --recovery-key-stdin 传入密钥时。

MATRIX_HOMESERVER 不能从工作区 .env 文件设置；参见工作区 .env 文件安全说明。

配置示例

一个实用的基础配置，包含私信配对、房间白名单和 E2EE：

json5

{
  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: "partial",
    },
  },
}

流式预览设置

Matrix 回复流式输出是 opt-in。streaming 控制 OpenClaw 如何递送正在生成的回复；blockStreaming 控制每个完成的块是否保留为自己的 Matrix 消息。

json5

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

要保留实时预览但隐藏中间的工具/进度条，使用对象形式：

json5

{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

`streaming`	行为
`"off"` (默认)	等待完整回复，一次性发送。`true` ↔ `"partial"`，`false` ↔ `"off"`。
`"partial"`	当模型写入当前块时，原地编辑一条普通文本消息。标准 Matrix 客户端可能对首次预览发出通知，而非最终编辑。
`"quiet"`	与 `"partial"` 相同，但消息是不发出提示的 notice。接收方只有在用户推送规则匹配最终编辑后才会收到通知（见下文）。

blockStreaming 独立于 streaming：

`streaming`	`blockStreaming: true`	`blockStreaming: false` (默认)
`"partial"` / `"quiet"`	当前块实时草稿，已完成块保留为消息	当前块实时草稿，最终在原地定型
`"off"`	每个完成的块一条带通知的 Matrix 消息	完整回复一条带通知的 Matrix 消息

注意：

如果预览超过 Matrix 的单事件大小限制，OpenClaw 会停止预览流式输出并回退为最终交付。
媒体回复始终以正常方式发送附件。如果旧预览无法再安全复用，OpenClaw 会在发送最终媒体回复前将其 redact。
工具进度预览更新在 Matrix 预览流式输出激活时默认启用。设置 streaming.preview.toolProgress: false 以保留答案文本的预览编辑，但工具进度走正常交付路径。
预览编辑会增加 Matrix API 调用。如果希望最保守的速率限制，保留 streaming: "off"。

审批元数据

Matrix 原生审批提示是以 OpenClaw 特定的自定义事件内容 com.openclaw.approval 发送的普通 m.room.message 事件。Matrix 允许自定义事件内容键，因此标准客户端仍可渲染文本正文，而支持 OpenClaw 的客户端可以读取结构化的审批 ID、类型、状态、可用决策和执行/插件详情。

当审批提示太长不能放在一个 Matrix 事件中时，OpenClaw 会分割可见文本，并将 com.openclaw.approval 仅附加到第一个分块。允许/拒绝决策的表情回应绑定到该第一个事件，因此长提示与单事件提示保持相同的审批目标。

自托管推送规则（安静最终预览）

streaming: "quiet" 仅在块或轮次最终定型时通知收件方——用户级推送规则必须匹配最终预览标记。完整方案参见 Matrix 安静预览推送规则（收件方 token、pusher 检查、规则安装、每个 homeserver 的注意事项）。

机器人间通信

默认情况下，来自其他已配置的 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 可为单个房间覆盖账号级设置。
接受的已配置机器人消息使用共享的机器人循环保护。配置 channels.defaults.botLoopProtection，然后使用 channels.matrix.botLoopProtection 或 channels.matrix.groups.<room>.botLoopProtection 覆盖。
OpenClaw 仍会忽略来自相同 Matrix 用户 ID 的消息以避免自回复循环。
Matrix 没有暴露原生的机器人标志；OpenClaw 将"机器人发送"视为"由此 OpenClaw Gateway 上另一个已配置的 Matrix 账号发送"。

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

E2EE 加密与验证

在加密（E2EE）房间中，出站图片事件使用 thumbnail_file 以便图片预览与完整附件一起加密。非加密房间仍使用 thumbnail_url。无需配置——插件会自动检测 E2EE 状态。

所有 openclaw matrix 命令都接受 --verbose（完整诊断）、--json（机器可读输出）和 --account <id>（多账号设置）。默认输出简洁，SDK 内部日志安静。下方示例展示标准形式；根据需要添加参数。

启用加密

bash

openclaw matrix encryption setup

引导密钥存储和跨签名，必要时创建房间密钥备份，然后打印状态和后续步骤。有用的参数：

--recovery-key <key> 在引导前应用恢复密钥（优先使用下方记录的 stdin 形式）
--force-reset-cross-signing 丢弃当前跨签名身份并创建新的（仅在有意识时使用）

对于新账号，在创建时启用 E2EE：

bash

openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

--encryption 是 --enable-e2ee 的别名。

等效手动配置：

json5

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

状态与信任信号

bash

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

verify status 报告三个独立的信任信号（--verbose 显示所有）：

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

Verified by owner 仅在 Cross-signing verified 为 yes 时变为 yes。仅本地信任或拥有者签名不足。

--allow-degraded-local-state 返回尽力诊断信息而不预先准备 Matrix 账号；适用于离线或部分配置的探测。

使用恢复密钥验证此设备

恢复密钥敏感——通过 stdin 传入而非命令行。设置 MATRIX_RECOVERY_KEY（或命名账号的 MATRIX_<ID>_RECOVERY_KEY）：

bash

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

该命令报告三种状态：

Recovery key accepted：Matrix 接受该密钥用于密钥存储或设备信任。
Backup usable：房间密钥备份可用受信任的恢复材料加载。
Device verified by owner：此设备具有完整的 Matrix 跨签名身份信任。

即使恢复密钥解锁了备份材料，如果完整身份信任不完整，它也会以非零退出。这种情况下，从另一个 Matrix 客户端完成自我验证：

bash

openclaw matrix verify self

verify self 等待 Cross-signing verified: yes 后才成功退出。使用 --timeout-ms <ms> 调整等待时间。

文字密钥形式 openclaw matrix verify device "<recovery-key>" 也接受，但密钥会暴露在 shell 历史中。

引导或修复跨签名

bash

openclaw matrix verify bootstrap

verify bootstrap 是加密账号的修复和配置命令。按顺序执行：

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

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

有用的参数：

--recovery-key-stdin（配合 printf '%s\n' "$MATRIX_RECOVERY_KEY" | …）或 --recovery-key <key>
--force-reset-cross-signing 丢弃当前跨签名身份（仅在有意识时使用）

房间密钥备份

bash

openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

backup status 显示服务端备份是否存在以及此设备能否解密。backup restore 将备份的房间密钥导入本地加密存储；如果恢复密钥已在磁盘上，可省略 --recovery-key-stdin。

替换损坏的备份为新的基线（接受丢失无法恢复的旧历史；如果当前备份密钥无法加载，也可重新创建密钥存储）：

bash

openclaw matrix verify backup reset --yes

仅当你有意让之前的恢复密钥无法解锁新备份基线时，才添加 --rotate-recovery-key。

列出、请求和响应验证

bash

openclaw matrix verify list

列出所选账号的待处理验证请求。

bash

openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

从此 OpenClaw 账号发送验证请求。--own-user 请求自我验证（您在另一个相同用户的 Matrix 客户端中接受提示）；--user-id/--device-id/--room-id 针对其他人。--own-user 不能与其他定位参数组合。

对于更底层的生命周期处理——通常在处理来自另一个客户端的入站请求时——这些命令作用于特定请求 <id>（由 verify list 和 verify request 打印）：

命令	用途
`openclaw matrix verify accept <id>`	接受入站请求
`openclaw matrix verify start <id>`	启动 SAS 流程
`openclaw matrix verify sas <id>`	打印 SAS 表情符号或十进制数
`openclaw matrix verify confirm-sas <id>`	确认 SAS 与另一个客户端显示的一致
`openclaw matrix verify mismatch-sas <id>`	当表情符号或十进制数不匹配时拒绝 SAS
`openclaw matrix verify cancel <id>`	取消；可选 `--reason <text>` 和 `--code <matrix-code>`

accept、start、sas、confirm-sas、mismatch-sas 和 cancel 都接受 --user-id 和 --room-id 作为私信后续提示，当验证锚定到特定直接消息房间时。

多账号注意事项

如果不加 --account <id>，Matrix CLI 命令使用隐式默认账号。如果您有多个命名账号且未设置 channels.matrix.defaultAccount，它们会拒绝猜测并要求您选择。当命名账号的 E2EE 禁用或不可用时，错误会指向该账号的配置键，例如 channels.matrix.accounts.assistant.encryption。

启动行为

启用 encryption: true 时，startupVerification 默认为 "if-unverified"。启动时，未验证的设备会在另一个 Matrix 客户端中请求自我验证，跳过重复并应用冷却时间（默认 24 小时）。使用 startupVerificationCooldownHours 调整，或使用 startupVerification: "off" 禁用。

启动时还会执行保守的加密引导流程，复用当前密钥存储和跨签名身份。如果引导状态损坏，OpenClaw 会尝试有保护的修复，即使没有 channels.matrix.password；如果 homeserver 需要密码 UIA，启动会记录警告并保持非致命。已由拥有者签名的设备会被保留。

参见 Matrix 迁移获取完整升级流程。

验证通知

Matrix 会在严格的私信验证房间中以 m.notice 消息发布验证生命周期通知：请求、就绪（带有"通过表情符号验证"指导）、开始/完成以及 SAS 详情。

来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自我验证，OpenClaw 会自动启动 SAS 流程并确认己方，一旦表情符号验证可用——您仍需在 Matrix 客户端中比较并确认"They match"。

验证系统通知不会转发到智能体聊天管道。

已删除或无效的 Matrix 设备

如果 verify status 显示当前设备不再列在 homeserver 上，请创建新的 OpenClaw Matrix 设备。对于密码登录：

bash

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway

对于 Token 认证，在 Matrix 客户端或管理 UI 中创建新的 access token，然后更新 OpenClaw：

bash

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'

将 assistant 替换为失败命令中的账号 ID，或忽略 --account 表示默认账号。

设备卫生

旧的 OpenClaw 管理的设备可能积累。列出并清理：

bash

openclaw matrix devices list
openclaw matrix devices prune-stale

加密存储

Matrix E2EE 使用官方 matrix-js-sdk 的 Rust 加密路径，使用 fake-indexeddb 作为 IndexedDB 垫片。加密状态持久化到 crypto-idb-snapshot.json（限制性文件权限）。

加密运行时状态存放在 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/，包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当 Token 改变但账号身份相同时，OpenClaw 会复用现有的最佳根目录，使先前的状态保持可见。

个人资料管理

更新所选账号的 Matrix 自我档案：

bash

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

两者可在一次调用中传入。Matrix 直接接受 mxc:// 头像 URL；当您传入 http:// 或 https:// 时，OpenClaw 会先上传文件，然后将解析后的 mxc:// URL 存储到 channels.matrix.avatarUrl（或每个账号的覆盖）。

线程绑定

Matrix 支持对自动回复和消息工具发送的原生 Matrix 线程。两个独立开关控制行为：

会话路由 (`sessionScope`)

dm.sessionScope 决定 Matrix 私信房间如何映射到 OpenClaw 会话：

"per-user"（默认）：所有与同一路由对等方的私信房间共享一个会话。
"per-room"：每个 Matrix 私信房间获得独立的会话键，即使对等方相同。

显式会话绑定始终优先于 sessionScope，因此绑定的房间和线程保持其选择的目标会话。

回复线程 (`threadReplies`)

threadReplies 决定机器人在何处发布回复：

"off"：回复在顶层。入站线程消息保留在父会话中。
"inbound"：仅当入站消息已经在线程中时，才在该线程内回复。
"always"：以触发消息为根回复线程；该对话从第一次触发开始通过匹配的线程作用域会话路由。

dm.threadReplies 可能覆盖此设置，仅对私信生效——例如，保持房间线程隔离而私信保持扁平。

线程继承与斜杠命令

入站线程消息包含线程根消息作为额外的智能体上下文。
消息工具发送自动继承当前 Matrix 线程（当目标为相同房间或相同私信用户时），除非显式提供了 threadId。
私信用户目标复用仅在当前会话元数据证明同一 Matrix 账号上的同一私信对等方时才生效；否则回退到正常的用户作用域路由。
/focus、/unfocus、/agents、/session idle、/session max-age 和线程绑定的 /acp spawn 在 Matrix 房间和私信中均可工作。
顶层 /focus 创建新的 Matrix 线程并绑定到目标会话，当 threadBindings.spawnSessions 启用时。
在现有 Matrix 线程内运行 /focus 或 /acp spawn --thread here 会就地绑定该线程。

当 OpenClaw 检测到 Matrix 私信房间与同一共享会话上的另一个私信房间冲突时，它会在该房间发布一次 m.notice 消息，指向 /focus 逃生舱并建议更改 dm.sessionScope。仅当线程绑定启用时，该通知才会出现。

ACP 会话绑定

Matrix 房间、私信和现有 Matrix 线程可以转换为持久的 ACP 工作区，无需更改聊天界面。

快速操作器流程：

在 Matrix 私信、房间或现有线程中运行 /acp spawn codex --bind here。
在顶层 Matrix 私信或房间中，当前的私信/房间保持为聊天界面，未来的消息路由到生成的 ACP 会话。
在现有 Matrix 线程中，--bind here 就地绑定当前线程。
/new 和 /reset 就地重置相同的绑定 ACP 会话。
/acp close 关闭 ACP 会话并移除绑定。

注意：

--bind here 不会创建子 Matrix 线程。
threadBindings.spawnSessions 控制 /acp spawn --thread auto|here，此时 OpenClaw 需要创建或绑定子 Matrix 线程。

线程绑定配置

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

threadBindings.enabled
threadBindings.idleHours
threadBindings.maxAgeHours
threadBindings.spawnSessions
threadBindings.defaultSpawnContext

Matrix 线程绑定的会话生成默认启用：

设置 threadBindings.spawnSessions: false 以阻止顶层 /focus 和 /acp spawn --thread auto|here 创建/绑定 Matrix 线程。
设置 threadBindings.defaultSpawnContext: "isolated" 使原生子智能体线程生成不派生父对话副本。

表情回应配置

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

出站表情回应工具由 channels.matrix.actions.reactions 控制：

react 向 Matrix 事件添加表情回应。
reactions 列出 Matrix 事件的当前回应汇总。
emoji="" 移除机器人对该事件的所有回应。
remove: true 仅移除机器人对该事件指定的表情回应。

解析顺序（第一个定义的值生效）：

设置	顺序
`ackReaction`	每账号 → 渠道 → `messages.ackReaction` → 智能体身份表情符号回退
`ackReactionScope`	每账号 → 渠道 → `messages.ackReactionScope` → 默认 `"group-mentions"`
`reactionNotifications`	每账号 → 渠道 → 默认 `"own"`

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

历史上下文

channels.matrix.historyLimit 控制当 Matrix 房间消息触发智能体时，作为 InboundHistory 包含的近期房间消息数量。回退到 messages.groupChat.historyLimit；如果两者都未设置，有效默认值为 0。设为 0 禁用。
Matrix 房间历史仅限房间。私信保持正常的会话历史。
Matrix 房间历史是待处理式的：OpenClaw 缓存尚未触发回复的房间消息，然后在提及其他触发事件到达时快照该窗口。
当前触发消息不包含在 InboundHistory 中；它保留在该轮的入站正文中。
相同 Matrix 事件的重试复用原始历史快照，而不是漂移到更新的房间消息。

上下文可见性

Matrix 支持共享的 contextVisibility 控制，用于补充房间上下文（如获取的回复文本、线程根和待处理历史）。

contextVisibility: "all" 是默认值。补充上下文按接收状态保留。
contextVisibility: "allowlist" 过滤补充上下文，仅包含活动房间/用户白名单检查允许的发送者。
contextVisibility: "allowlist_quote" 行为类似 allowlist，但仍保留一个显式引用的回复。

此设置影响补充上下文可见性，而非入站消息本身能否触发回复。触发授权仍来自 groupPolicy、groups、groupAllowFrom 和私信策略设置。

DM 与房间策略

json5

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

要完全禁用私信同时保持房间工作，设置 dm.enabled: false：

json5

{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

参见群组文档了解提及门控和白名单行为。

Matrix 私信配对示例：

bash

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

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

参见配对文档了解共享私信配对流程和存储结构。

直接房间修复

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

bash

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

修复映射：

bash

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

两个命令都接受 --account <id> 用于多账号设置。修复逻辑优先级：

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

它不会自动删除旧房间。它挑选健康的私信并更新映射，使未来的 Matrix 发送、验证通知和其他直接消息流指向正确的房间。

执行审批

Matrix 可以作为原生审批客户端。在 channels.matrix.execApprovals（或 channels.matrix.accounts.<account>.execApprovals 作为每账号覆盖）下配置：

enabled：通过 Matrix 原生提示交付审批。当未设置或为 "auto" 时，一旦可以解析至少一个审批者，Matrix 自动启用。设为 false 显式禁用。
approvers：允许审批执行请求的 Matrix 用户 ID（@owner:example.org）。可选——回退到 channels.matrix.dm.allowFrom。
target：提示发送位置。"dm"（默认）发送到审批者私信；"channel" 发送到原始的 Matrix 房间或私信；"both" 发送到两者。
agentFilter / sessionFilter：可选的白名单，用于哪些智能体/会话触发 Matrix 交付。

审批类型之间的授权略有不同：

执行审批 使用 execApprovals.approvers，回退到 dm.allowFrom。
插件审批 仅通过 dm.allowFrom 授权。

两种类型都共享 Matrix 表情回应快捷方式和消息更新。审批者会在主要审批消息上看到反应快捷方式：

✅ 允许一次
❌ 拒绝
♾️ 始终允许（当有效执行策略允许时）

回退斜杠命令：/approve <id> allow-once、/approve <id> allow-always、/approve <id> deny。

只有已解析的审批者可以批准或拒绝。执行审批的渠道交付包含命令文本——仅在受信任的房间中启用 channel 或 both。

斜杠命令

斜杠命令（/new、/reset、/model、/focus、/unfocus、/agents、/session、/acp、/approve 等）直接在私信中工作。在房间中，OpenClaw 也识别以机器人自己的 Matrix 提及为前缀的命令，因此 @bot:server /new 触发命令路径，无需自定义提及正则表达式。这使得机器人在用户通过 tab 补全机器人后发布 @mention /command 帖子时也能响应（如 Element 等客户端的行为）。

授权规则仍然适用：命令发送者必须满足与普通消息相同的私信或房间白名单/所有者策略。

多账号配置

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"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

继承：

顶层 channels.matrix 值作为命名账号的默认值，除非账号覆盖了它们。
使用 groups.<room>.account 将继承的房间条目限定到特定账号。没有 account 的条目在所有账号间共享；account: "default" 在默认账号配置在顶层时仍有效。

默认账号选择：

设置 defaultAccount 以选择隐式路由、探测和 CLI 命令偏好的命名账号。
如果您有多个账号且其中一个确实名为 default，即使未设置 defaultAccount，OpenClaw 也会隐式使用它。
如果您有多个命名账号且未选择默认，CLI 命令会拒绝猜测——设置 defaultAccount 或传递 --account <id>。
顶层 channels.matrix.* 块仅在其认证完整（homeserver + accessToken，或 homeserver + userId + password）时才被视为隐式 default 账号。一旦缓存凭证覆盖了认证，命名账号仍然可以从 homeserver + userId 发现。

提升：

当 OpenClaw 在修复或设置期间将单账号配置提升为多账号时，它保留现有的命名账号（如果存在）或 defaultAccount 已经指向的账号。只有 Matrix 认证/引导密钥移动到提升的账号中；共享的交付策略键保留在顶层。

参见配置参考了解共享的多账号模式。

私有/局域网 homeserver

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

如果您的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账号启用 network.dangerouslyAllowPrivateNetwork：

json5

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: 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

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

Matrix 代理配置

如果您的 Matrix 部署需要显式的出站 HTTP(S) 代理，设置 channels.matrix.proxy：

json5

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

命名账号可以使用 channels.matrix.accounts.<id>.proxy 覆盖顶层默认值。OpenClaw 对运行时 Matrix 流量和账号状态探测使用相同的代理设置。

目标格式解析

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 房间 ID 区分大小写。在配置显式交付目标、cron 任务、绑定或白名单时，使用来自 Matrix 的准确房间 ID 大小写。OpenClaw 保留内部会话键的规范形式用于存储，因此这些小写键不是 Matrix 交付 ID 的可靠来源。

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

用户查询在该 homeserver 上查询 Matrix 用户目录。
房间查询直接接受显式的房间 ID 和别名。已加入房间的名称查询是尽力而为，仅在设置 dangerouslyAllowNameMatching: true 时应用于运行时房间白名单。
如果房间名称无法解析为 ID 或别名，运行时白名单解析会忽略它。

配置参考

白名单风格的用户字段（groupAllowFrom、dm.allowFrom、groups.<room>.users）接受完整的 Matrix 用户 ID（最安全）。非 ID 用户条目默认被忽略。如果设置 dangerouslyAllowNameMatching: true，精确的 Matrix 目录显示名称匹配会在启动时以及白名单更改后（当监视器运行时）解析；无法解析的条目在运行时被忽略。

房间白名单键（groups、旧版 rooms）应该是房间 ID 或别名。纯房间名称键默认被忽略；dangerouslyAllowNameMatching: true 会恢复对已加入房间名称的尽力查找。

账号与连接

enabled：启用或禁用渠道。
name：账号的可选显示标签。
defaultAccount：配置多个 Matrix 账号时的首选账号 ID。
accounts：命名的每账号覆盖。顶层 channels.matrix 值继承为默认值。
homeserver：homeserver URL，例如 https://matrix.example.org。
network.dangerouslyAllowPrivateNetwork：允许此账号连接到 localhost、LAN/Tailscale IP 或内部主机名。
proxy：可选 HTTP(S) 代理 URL，用于 Matrix 流量。支持每账号覆盖。
userId：完整的 Matrix 用户 ID（@bot:example.org）。
accessToken：基于 Token 认证的 access token。支持明文和 SecretRef 值（环境/文件/执行提供商，参见密钥管理）。
password：基于密码登录的密码。支持明文和 SecretRef 值。
deviceId：显式 Matrix 设备 ID。
deviceName：密码登录时使用的设备显示名称。
avatarUrl：存储的自我头像 URL，用于档案同步和 profile set 更新。
initialSyncLimit：启动同步期间获取的最大事件数。

加密

encryption：启用 E2EE。默认：false。
startupVerification："if-unverified"（当 E2EE 开启时默认）或 "off"。启动时此设备未验证时自动请求自我验证。
startupVerificationCooldownHours：下次自动启动请求前的冷却时间。默认：24。

访问与策略

groupPolicy："open"、"allowlist" 或 "disabled"。默认："allowlist"。
groupAllowFrom：房间流量的用户 ID 白名单。
dm.enabled：设为 false 时忽略所有私信。默认：true。
dm.policy："pairing"（默认）、"allowlist"、"open" 或 "disabled"。在机器人加入并将房间分类为私信后应用；不影响邀请处理。
dm.allowFrom：私信流量的用户 ID 白名单。
dm.sessionScope："per-user"（默认）或 "per-room"。
dm.threadReplies：仅限私信的回复线程覆盖（"off"、"inbound"、"always"）。
allowBots：接受来自其他已配置 Matrix 机器人账号的消息（true 或 "mentions"）。
allowlistOnly：设为 true 时，强制所有活跃的私信策略（除 "disabled" 外）和 "open" 群组策略变为 "allowlist"。不会改变 "disabled" 策略。
dangerouslyAllowNameMatching：设为 true 时，允许 Matrix 显示名称目录查找用户白名单条目以及已加入房间名称查找房间白名单键。优先使用完整的 @user:server ID 和房间 ID 或别名。
autoJoin："always"、"allowlist" 或 "off"。默认："off"。应用于每个 Matrix 邀请，包括私信风格邀请。
autoJoinAllowlist：当 autoJoin 为 "allowlist" 时允许的房间/别名。别名条目针对 homeserver 解析，而非针对被邀请房间声明的状态。
contextVisibility：补充上下文可见性（"all" 默认、"allowlist"、"allowlist_quote"）。

回复行为

replyToMode："off"、"first"、"all" 或 "batched"。
threadReplies："off"、"inbound" 或 "always"。
threadBindings：每渠道覆盖线程绑定会话路由和生命周期。
streaming："off"（默认）、"partial"、"quiet" 或对象形式 { mode, preview: { toolProgress } }。true ↔ "partial"，false ↔ "off"。
blockStreaming：设为 true 时，完成的助理块保留为独立的进度消息。
markdown：可选 Markdown 渲染配置，用于出站文本。
responsePrefix：可选字符串，预置到出站回复。
textChunkLimit：当 chunkMode: "length" 时的出站分块字符数。默认：4000。
chunkMode："length"（默认，按字符数分割）或 "newline"（在行边界分割）。
historyLimit：当房间消息触发智能体时，作为 InboundHistory 包含的近期房间消息数量。回退到 messages.groupChat.historyLimit；有效默认 0（禁用）。
mediaMaxMb：媒体大小上限（MB），用于出站发送和入站处理。

表情回应设置

ackReaction：此渠道/账号的确认回应覆盖。
ackReactionScope：作用域覆盖（"group-mentions" 默认、"group-all"、"direct"、"all"、"none"、"off"）。
reactionNotifications：入站回应通知模式（"own" 默认、"off"）。

工具与每房间覆盖

actions：每操作工具控制（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。
groups：每房间策略映射。会话标识使用解析后的稳定房间 ID。（rooms 是旧版别名。）
- groups.<room>.account：将继承的房间条目限定到特定账号。
- groups.<room>.allowBots：每房间覆盖渠道级设置（true 或 "mentions"）。
- groups.<room>.users：每房间发送者白名单。
- groups.<room>.tools：每房间工具允许/拒绝覆盖。
- groups.<room>.autoReply：每房间提及门控覆盖。true 禁用该房间的提及要求；false 强制恢复。
- groups.<room>.skills：每房间技能过滤器。
- groups.<room>.systemPrompt：每房间系统提示片段。

执行审批设置

execApprovals.enabled：通过 Matrix 原生提示交付执行审批。
execApprovals.approvers：允许审批的 Matrix 用户 ID。回退到 dm.allowFrom。
execApprovals.target："dm"（默认）、"channel" 或 "both"。
execApprovals.agentFilter / execApprovals.sessionFilter：可选的智能体/会话白名单，用于交付。

常见问题

Matrix 渠道已配置但 Agent 无响应，是什么原因？

最常见的原因是 autoJoin 未启用——机器人被邀请进房间后默认不自动接受邀请，需要配置 channels.matrix.autoJoin = "always" 或 "allowlist"。另外检查 dm.policy 和 groupPolicy 是否允许了该用户。

E2EE 加密房间中消息能收到但无法解密，怎么处理？

确认 E2EE 配置正确且机器人的设备已完成跨签名验证。运行 openclaw matrix verify status 查看信任信号，若未验证则执行 openclaw matrix verify bootstrap 引导。如果设备密钥丢失（例如重装 Gateway），需先清理旧设备（openclaw matrix devices prune-stale）再重新验证。

如何配置多个 Matrix 账号（例如正式助理和告警机器人）？

在 channels.matrix.accounts 下定义多个命名账号，每个包含各自 homeserver、access token 和加密设置。设置 defaultAccount 为偏好的账号，并在 CLI 命令中使用 --account <id> 指定特定账号。账号间可以继承顶层策略但支持各自覆盖。

OpenClaw Matrix 渠道配置与E2EE加密指南 ​

安装 ​

配置步骤 ​

交互式配置 ​

最小配置 ​

自动加入 (auto-join) ​

白名单目标格式 ​

账号 ID 规范化 ​

缓存凭证 ​

环境变量 ​

配置示例 ​

流式预览设置 ​

审批元数据 ​

自托管推送规则（安静最终预览） ​

机器人间通信 ​

E2EE 加密与验证 ​

启用加密 ​

状态与信任信号 ​

使用恢复密钥验证此设备 ​

引导或修复跨签名 ​

房间密钥备份 ​

列出、请求和响应验证 ​

多账号注意事项 ​

个人资料管理 ​

线程绑定 ​

会话路由 (sessionScope) ​

回复线程 (threadReplies) ​

线程继承与斜杠命令 ​

ACP 会话绑定 ​

线程绑定配置 ​

表情回应配置 ​

历史上下文 ​

上下文可见性 ​

DM 与房间策略 ​

直接房间修复 ​

执行审批 ​

斜杠命令 ​

多账号配置 ​

私有/局域网 homeserver ​

Matrix 代理配置 ​

目标格式解析 ​

配置参考 ​

账号与连接 ​

加密 ​

访问与策略 ​

回复行为 ​

表情回应设置 ​

工具与每房间覆盖 ​

执行审批设置 ​

常见问题 ​

Matrix 渠道已配置但 Agent 无响应，是什么原因？ ​

E2EE 加密房间中消息能收到但无法解密，怎么处理？ ​

如何配置多个 Matrix 账号（例如正式助理和告警机器人）？ ​

OpenClaw Matrix 渠道配置与E2EE加密指南

安装

配置步骤

交互式配置

最小配置

自动加入 (auto-join)

白名单目标格式

账号 ID 规范化

缓存凭证

环境变量

配置示例

流式预览设置

审批元数据

自托管推送规则（安静最终预览）

机器人间通信

E2EE 加密与验证

启用加密

状态与信任信号

使用恢复密钥验证此设备

引导或修复跨签名

房间密钥备份

列出、请求和响应验证

多账号注意事项

个人资料管理

线程绑定

会话路由 (`sessionScope`)

回复线程 (`threadReplies`)

线程继承与斜杠命令

ACP 会话绑定

线程绑定配置

表情回应配置

历史上下文

上下文可见性

DM 与房间策略

直接房间修复

执行审批

斜杠命令

多账号配置

私有/局域网 homeserver

Matrix 代理配置

目标格式解析

配置参考

账号与连接

加密

访问与策略

回复行为

表情回应设置

工具与每房间覆盖

执行审批设置

常见问题

Matrix 渠道已配置但 Agent 无响应，是什么原因？

E2EE 加密房间中消息能收到但无法解密，怎么处理？

如何配置多个 Matrix 账号（例如正式助理和告警机器人）？