Matrix

Matrix 是一个基于官方 matrix-js-sdk 构建的可下载渠道插件（@openclaw/matrix）。它支持私信、房间、话题串、媒体、表情回应、投票、位置和 E2EE。

安装

openclaw plugins install @openclaw/matrix

未指定来源的插件说明会先尝试 ClawHub，再回退到 npm。使用 openclaw plugins install clawhub:@openclaw/matrix 或 npm:@openclaw/matrix 强制指定来源。从本地检出安装：openclaw plugins install ./path/to/local/matrix-plugin。

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

设置

1. 在你的主服务器上创建 Matrix 账户。
2. 使用 homeserver + accessToken，或 homeserver + userId + password 配置 channels.matrix。
3. 重启 Gateway 网关。
4. 与 Bot 发起私信，或邀请它加入房间。只有在 autoJoin 允许时，新的邀请才会生效。

交互式设置

openclaw channels addopenclaw configure --section channels

向导会询问主服务器 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",    },  },}

自动加入

channels.matrix.autoJoin 默认为 "off"：在你手动加入之前，Bot 不会因新的邀请而出现在新房间或私信中。OpenClaw 无法在收到邀请时判断它属于私信还是群组，因此每个邀请都会先经过 autoJoin；dm.policy 仅在之后生效，即 Bot 加入且房间完成分类后。

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

允许列表目标格式

• 私信（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）。限定范围的环境变量名称会对标点符号进行十六进制转义，以避免账户冲突：-（0x2D）会变为 _X2D_，因此 ops-prod 会映射到环境变量前缀 MATRIX_OPS_X2D_PROD_。

缓存的凭据

Matrix 将凭据缓存在 ~/.openclaw/credentials/matrix/ 下：默认账户使用 credentials.json，命名账户使用 credentials-<account>.json。存在缓存凭据时，即使配置文件中没有 accessToken，OpenClaw 也会将 Matrix 视为已配置——这适用于设置、openclaw doctor 和渠道状态探测。

环境变量

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

对于账户 ops，名称会变为 MATRIX_OPS_HOMESERVER、MATRIX_OPS_ACCESS_TOKEN，依此类推。MATRIX_HOMESERVER（以及任何限定范围的 *_HOMESERVER 变体）不能通过工作区 .env 设置；请参阅工作区 .env 文件。

配置示例

包含私信配对、房间允许列表和 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" },    },  },}

流式预览

Matrix 回复流式传输需要主动启用。streaming.mode 控制 OpenClaw 如何传递正在生成的智能体回复；streaming.block.enabled 控制是否将每个已完成的分块分别保留为一条 Matrix 消息。

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

若要保留实时答案预览，但隐藏中间的工具/进度行：

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

完整配置接受 { mode, chunkMode, block, preview, progress }：

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // pick from configured or built-in labels (false to hide)          labels: ["Thinking", "Writing", "Searching"], // candidates for label: "auto"          maxLines: 8, // max rolling progress lines (default: 8)          maxLineChars: 120, // max chars per line before truncation (default: 120)          toolProgress: true, // show tool/progress activity (default: true)        },      },    },  },}

• progress.label：自定义标签；使用 "auto"/不设置可选择已配置或内置标签，使用 false 可隐藏标签。
• progress.labels：仅当 label 为 "auto" 或未设置时使用的候选项。
• progress.maxLines：草稿中保留的最大滚动进度行数；超出后会裁剪较旧的行。
• progress.maxLineChars：每条紧凑进度行在截断前允许的最大字符数。
• progress.toolProgress：当为 true（默认）时，草稿中会显示实时工具/进度活动。

streaming.block.enabled（默认 false）独立于 streaming.mode：

注意：

• 如果预览内容超出 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退到仅传递最终结果。
• 媒体回复始终会正常发送附件；如果无法安全复用过期预览，OpenClaw 会在发送最终媒体回复前将其撤回。
• 启用预览流式传输时，默认会更新工具进度预览。设置 streaming.preview.toolProgress: false 可继续通过预览编辑显示答案文本，但让工具进度沿用正常传递路径。
• 预览编辑会产生额外的 Matrix API 调用。保留 streaming.mode: "off" 可获得最保守的速率限制配置。
• 旧版标量/布尔值 streaming 以及扁平的 blockStreaming / chunkMode 键会由 openclaw doctor --fix 重写为此嵌套结构。

语音消息

入站 Matrix 语音消息会在房间提及检查之前转写，因此在 requireMention: true 房间中，提及 Bot 名称的语音消息可以触发智能体，并且智能体会收到转写文本，而不只是音频附件占位符。

Matrix 使用 tools.media.audio 下的共享音频媒体提供商，例如 OpenAI gpt-4o-mini-transcribe。有关提供商设置和限制，请参阅媒体工具概览。

• m.audio 事件和 MIME 类型为 audio/* 的 m.file 事件符合条件。
• 在加密房间中，OpenClaw 会先通过现有的 Matrix 媒体路径解密附件，再进行转录。
• 在智能体提示词中，转录文本会被标记为由机器生成且不可信。
• 附件会被标记为已转录，以防下游媒体工具再次转录。
• 将 tools.media.audio.enabled: false 设置为禁用全局音频转录。

审批元数据

Matrix 原生审批提示是普通的 m.room.message 事件，其 OpenClaw 特定内容位于 com.openclaw.approval 键下。标准客户端仍会呈现文本正文；支持 OpenClaw 的客户端则可以读取结构化的审批 ID、类型、状态、决定以及 Exec/插件详细信息。

当提示过长、无法放入单个 Matrix 事件时，OpenClaw 会对可见文本进行分块，并且仅将 com.openclaw.approval 附加到第一个块。允许/拒绝表情回应会绑定到第一个事件，因此长提示与单事件提示仍使用同一个审批目标。

用于静默最终预览的自托管推送规则

streaming.mode: "quiet" 仅在分块或轮次完成后通知接收者——必须由每用户推送规则匹配最终预览标记。完整配置方法请参阅 Matrix 静默预览推送规则。

Bot 间房间

默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。使用 allowBots 可有意允许智能体间通信：

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

• allowBots: true 接受允许房间和私信中来自其他已配置 Matrix Bot 账户的消息。
• allowBots: "mentions" 仅在这些消息于房间中明确提及此 Bot 时才接受；私信无论是否提及都会被接受。
• groups.<room>.allowBots 会针对单个房间覆盖账户级设置。
• 已接受的配置 Bot 消息使用共享的 Bot 循环保护。配置 channels.defaults.botLoopProtection，然后通过 channels.matrix.botLoopProtection 按账户覆盖，或通过 channels.matrix.groups.<room>.botLoopProtection 按房间覆盖。
• OpenClaw 仍会忽略来自同一 Matrix 用户 ID 的消息，以避免自回复循环。
• Matrix 没有原生 Bot 标志；OpenClaw 将“由 Bot 编写”视为“由此 OpenClaw Gateway 网关上的另一个已配置 Matrix 账户发送”。

在共享房间中启用 Bot 间通信时，请使用严格的房间允许列表和提及要求。

加密和验证

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

所有 openclaw matrix 命令都接受 --verbose（完整诊断）、--json（机器可读输出）和 --account <id>（多账户设置）。默认输出简洁。

启用加密

openclaw matrix encryption setup

引导设置秘密存储和交叉签名，在需要时创建房间密钥备份，然后输出状态和后续步骤。实用标志：

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

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

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

--encryption 是 --enable-e2ee 的别名。等效的手动配置：

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

状态和信任信号

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

verify status 会报告三个相互独立的信任信号（--verbose 会显示全部信号）：

• Locally trusted：仅受此客户端信任
• Cross-signing verified：SDK 报告已通过交叉签名验证
• Signed by owner：由你自己的自签名密钥签名（仅用于诊断）

仅当 Cross-signing verified 为 yes 时，Verified by owner 才为 yes；仅有本地信任或所有者签名并不足够。

--allow-degraded-local-state 会在不先准备 Matrix 账户的情况下返回尽力而为的诊断信息；适用于离线或部分配置的探测。

使用恢复密钥验证此设备

通过 stdin 管道传入恢复密钥，而不是在命令行中传递：

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 客户端完成自我验证：

openclaw matrix verify self

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

字面密钥形式 openclaw matrix verify device "<recovery-key>" 也可使用，但密钥会保留在 shell 历史记录中。

引导设置或修复交叉签名

openclaw matrix 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 用于丢弃当前交叉签名身份（仅限有意使用；需要已存储有效恢复密钥，或通过 --recovery-key-stdin 提供）

房间密钥备份

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

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

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

openclaw matrix verify backup reset --yes

仅当希望旧恢复密钥有意停止解锁全新备份基线时，才添加 --rotate-recovery-key。

列出、请求和响应验证

openclaw matrix verify list

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

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

从此账户发送验证请求。--own-user 请求自我验证（在同一用户的另一个 Matrix 客户端中接受提示）；--user-id/--device-id/--room-id 以其他用户为目标。--own-user 不能与其他目标标志组合使用。

对于更底层的生命周期处理——通常用于跟踪来自另一个客户端的入站请求——以下命令会作用于特定请求 <id>（由 verify list 和 verify request 输出）：

当验证锚定到特定私信房间时，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。

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

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

openclaw matrix devices listopenclaw matrix devices prune-stale

个人资料管理

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

在一次调用中同时传入这两个选项。Matrix 可直接接受 mxc:// 头像 URL；传入 http:///https:// 时，会先上传文件，然后将解析后的 mxc:// URL 存入 channels.matrix.avatarUrl（或对应的账户级覆盖项）。

线程

Matrix 对自动回复和消息工具发送都支持原生线程。两个相互独立的选项控制其行为：

会话路由（sessionScope）

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

• "per-user"（默认）：路由到同一对端的所有私信房间共享一个会话。
• "per-room"：每个 Matrix 私信房间都获得独立的会话键，即使对端相同也是如此。

显式会话绑定始终优先于 sessionScope；已绑定的房间和线程会保留其选定的目标会话。

回复线程（threadReplies）

threadReplies 决定机器人在哪里发布回复：

• "off"：回复位于顶层。入站线程消息仍归入父会话。
• "inbound"：仅当入站消息已位于某个线程中时，才在线程内回复。
• "always"：在以触发消息为根的线程内回复；从首次触发开始，该对话将通过匹配的线程范围会话进行路由。

dm.threadReplies 仅对私信覆盖此行为——例如，在保持私信扁平化的同时隔离房间线程。

线程继承和斜杠命令

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

当 OpenClaw 检测到某个 Matrix 私信房间与同一共享会话上的另一个私信房间发生冲突时，会发布一次性的 m.notice，其中指向 /focus 这一解决途径，并建议更改 dm.sessionScope。该通知仅在线程绑定已启用时出现。

ACP 对话绑定

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

快速操作流程：

• 在 Matrix 私信、房间或现有线程中运行 /acp spawn codex --bind here，以继续使用。
• 在顶层私信或房间中，当前私信/房间会继续作为聊天界面，后续消息将路由到新生成的 ACP 会话。
• 在现有线程中，--bind here 会就地绑定当前线程。
• /new 和 /reset 会就地重置同一个已绑定 ACP 会话。
• /acp close 会关闭 ACP 会话并移除绑定。

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

线程绑定配置

Matrix 会继承 session.threadBindings 中的全局默认值，并支持按渠道覆盖：

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions：同时控制子智能体和 ACP 线程的生成。
• threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions：仅针对子智能体或仅针对 ACP 生成的更精细覆盖项。
• 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 仅移除机器人指定的表情符号回应。

解析顺序（首个已定义的值优先）：

当新增的 m.reaction 事件以机器人编写的 Matrix 消息为目标时，reactionNotifications: "own" 会转发这些事件；"off" 会禁用表情回应系统事件。移除表情回应不会被合成为系统事件——Matrix 会将其呈现为修订，而不是独立的 m.reaction 移除事件。

历史上下文

• channels.matrix.historyLimit 控制当房间消息触发智能体时，有多少条近期房间消息会作为 InboundHistory 包含在内。回退到 messages.groupChat.historyLimit；如果两者均未设置，则有效默认值为 0（禁用）。
• Matrix 房间历史记录仅限房间；私信继续使用常规会话历史记录。
• 房间历史记录仅包含待处理消息：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发条件到来时创建该窗口的快照。
• 当前触发消息不包含在 InboundHistory 中；在该轮次中，它仍保留在主要入站正文中。
• 重试同一个 Matrix 事件时，会复用原始历史快照，而不会向前漂移到更新的房间消息。

上下文可见性

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

• contextVisibility: "all" 为默认值。补充上下文会按接收时的状态保留。
• contextVisibility: "allowlist" 会筛选补充上下文，仅保留当前房间/用户允许列表检查所允许的发送者。
• contextVisibility: "allowlist_quote" 的行为类似于 allowlist，但仍会保留一条显式引用回复。

这仅影响补充上下文的可见性，不影响入站消息本身能否触发回复。触发授权仍由 groupPolicy、groups、groupAllowFrom 和私信策略设置决定。

私信和房间策略

{  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：

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

有关提及门控和允许列表行为，请参阅群组。

Matrix 私信的配对示例：

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

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

有关共享私信配对流程和存储布局，请参阅配对。

直接房间修复

如果私信状态发生漂移，OpenClaw 最终可能出现过时的 m.direct 映射，指向旧的单人房间，而不是当前有效的私信。检查某个对端的当前映射：

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

修复映射：

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

对于多账户设置，这两个命令都接受 --account <id>。修复流程：

• 优先选择已在 m.direct 中映射的严格 1:1 私信
• 回退到当前已加入且包含该用户的任意严格 1:1 私信
• 如果不存在健康的私信，则创建新的直接房间并重写 m.direct

它不会自动删除旧房间。它会选择健康的私信并更新映射，以便后续 Matrix 发送、验证通知和其他私信流程以正确的房间为目标。

Exec 审批

Matrix 可以充当原生审批客户端。在 channels.matrix.execApprovals 下配置（或使用 channels.matrix.accounts.<account>.execApprovals 进行按账户覆盖）：

• enabled：通过 Matrix 原生提示发送审批。未设置或设为 "auto" 时，只要能解析出至少一名审批者，就会自动启用；设为 false 可显式禁用。
• approvers：允许审批 Exec 请求的 Matrix 用户 ID（@owner:example.org）。回退到 channels.matrix.dm.allowFrom。
• target：提示的发送位置。"dm"（默认）发送到审批者私信；"channel" 发送到发起请求的房间或私信；"both" 同时发送到两者。
• agentFilter / sessionFilter：可选允许列表，用于指定哪些智能体/会话会触发 Matrix 发送。

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

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

这两种审批共享 Matrix 表情回应快捷方式和消息更新。审批者可以在主要审批消息上看到表情回应快捷方式：

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

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

只有解析出的审批者才能批准或拒绝。Exec 审批的渠道投递内容包含命令文本——仅在可信房间中启用 channel 或 both。

相关内容：Exec 审批。

斜杠命令

斜杠命令（/new、/reset、/model、/focus、/unfocus、/agents、/session、/acp、/approve 等）可直接在私信中使用。在房间中，OpenClaw 还会识别以机器人自身 Matrix 提及开头的命令，因此 @bot:server /new 无需自定义提及正则表达式即可触发命令路径——这样，当用户先通过 Tab 补全机器人再输入命令时，机器人仍能响应 Element 和类似客户端发出的房间样式 @mention /command 消息。

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

多账户

{  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 身份验证/引导键会移入提升后的账户；共享投递策略键仍保留在顶层。

有关共享多账户模式，请参阅配置参考。

私有/LAN 主服务器

默认情况下，为防范 SSRF，OpenClaw 会阻止私有/内部 Matrix 主服务器，除非你为每个账户明确选择启用。

如果主服务器运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该账户启用 network.dangerouslyAllowPrivateNetwork：

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

CLI 设置示例：

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

此选择仅允许受信任的私有/内部目标。http://matrix.example.org:8008 等公共明文主服务器仍会被阻止。请尽可能优先使用 https://。

代理 Matrix 流量

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

{  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 流量和账户状态探测使用相同的代理设置。

目标解析

在 OpenClaw 要求提供房间或用户目标的任何位置，Matrix 均接受以下目标格式：

• 用户：@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 账户：

• 用户查找会查询该主服务器上的 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：主服务器 URL，例如 https://matrix.example.org。
• network.dangerouslyAllowPrivateNetwork：允许此账户连接到 localhost、LAN/Tailscale IP 或内部主机名。
• proxy：Matrix 流量的可选 HTTP(S) 代理 URL。支持账户级覆盖。
• userId：完整的 Matrix 用户 ID（@bot:example.org）。
• accessToken：基于令牌的身份验证所用的访问令牌。支持来自 env/file/exec 提供商的明文和 SecretRef 值（密钥管理）。
• password：基于密码登录所用的密码。支持明文和 SecretRef 值。
• deviceId：显式 Matrix 设备 ID。
• deviceName：基于密码登录时使用的设备显示名称。
• avatarUrl：为个人资料同步和 profile set 更新存储的自身头像 URL。
• initialSyncLimit：启动同步期间获取的最大事件数。

加密

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

访问和策略

• groupPolicy："open"、"allowlist" 或 "disabled"。默认值："allowlist"。
• groupAllowFrom：房间流量所允许的用户 ID 列表。
• mentionPatterns：房间提及的限定作用域正则表达式模式。包含 { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] } 的对象。控制配置的 agents.list[].groupChat.mentionPatterns 是否按房间应用。
• 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" 时允许的房间/别名。别名条目根据主服务器解析，而不是根据受邀房间声明的状态解析。
• contextVisibility：补充上下文可见性（默认值 "all"、"allowlist"、"allowlist_quote"）。

回复行为

• replyToMode: "off"（默认）、"first"、"all" 或 "batched"。
• threadReplies: "off"（除非显式设置，否则顶层默认值解析为 "inbound"）、"inbound" 或 "always"。
• threadBindings: 针对绑定到线程的会话路由和生命周期的各渠道覆盖设置。
• streaming: 嵌套对象 { mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }。mode 可为 "off"（默认）、"partial"、"quiet" 或 "progress"。旧版标量/布尔值写法通过 openclaw doctor --fix 迁移。
• streaming.block.enabled: 当为 true 时，已完成的助手内容块会保留为独立的进度消息。默认值：false。
• markdown: 出站文本的可选 Markdown 渲染配置。
• responsePrefix: 添加到出站回复开头的可选字符串。
• textChunkLimit: 当 streaming.chunkMode: "length" 时，出站分块的字符数。默认值：4000。
• streaming.chunkMode: "length"（默认，按字符数拆分）或 "newline"（按行边界拆分）。
• historyLimit: 房间消息触发智能体时，以 InboundHistory 形式包含的最近房间消息数量。回退到 messages.groupChat.historyLimit；实际默认值为 0（已禁用）。
• mediaMaxMb: 出站发送和入站处理的媒体大小上限（MB）。默认值：20。

表情回应设置

• 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>.enabled: 各房间开关。当为 false 时，将忽略该房间，如同它不在映射中一样。
  • groups.<room>.requireMention: 覆盖特定房间的渠道级提及要求。
  • groups.<room>.allowBots: 覆盖特定房间的渠道级设置（true 或 "mentions"）。
  • groups.<room>.botLoopProtection: 覆盖特定房间的机器人间循环防护预算。
  • groups.<room>.users: 各房间发送者允许列表。
  • groups.<room>.tools: 各房间工具允许/拒绝覆盖设置。
  • groups.<room>.autoReply: 各房间提及门控覆盖设置。true 会禁用该房间的提及要求；false 会强制重新启用这些要求。
  • groups.<room>.skills: 各房间 Skills 筛选器。
  • groups.<room>.systemPrompt: 各房间系统提示词片段。

Exec 审批设置

• execApprovals.enabled: 通过 Matrix 原生提示传递 Exec 审批。
• execApprovals.approvers: 允许执行审批的 Matrix 用户 ID。回退到 dm.allowFrom。
• execApprovals.target: "dm"（默认）、"channel" 或 "both"。
• execApprovals.agentFilter / execApprovals.sessionFilter: 用于传递的可选智能体/会话允许列表。

相关内容

• 渠道概览 - 所有支持的渠道
• 配对 - 私信身份验证和配对流程
• 群组 - 群聊行为和提及门控
• 频道路由 - 消息的会话路由
• 安全性 - 访问模型和安全加固