matrix-js-sdk，并支持私信、房间、线程、媒体、反应、投票、位置和 E2EE。
安装
在配置渠道之前，从 ClawHub 安装 Matrix：openclaw plugins install clawhub:@openclaw/matrix 或 openclaw plugins install npm:@openclaw/matrix。
从本地 checkout 安装：
plugins install 会注册并启用插件，因此不需要单独执行 openclaw plugins enable matrix 步骤。在你按下面方式配置渠道之前，该插件仍然不会做任何事。常规插件行为和安装规则见 插件。
设置
- 在你的 homeserver 上创建一个 Matrix 账户。
- 使用
homeserver+accessToken，或homeserver+userId+password配置channels.matrix。 - 重启 Gateway 网关。
- 与机器人发起私信，或邀请它加入房间（见 自动加入 - 只有当
autoJoin允许时，新邀请才会进入）。
交互式设置
MATRIX_* 环境变量已存在，并且所选账户没有已保存的认证，向导会提供环境变量快捷方式。若要在保存允许列表前解析房间名称，请运行 openclaw channels resolve --channel matrix "Project Room"。启用 E2EE 时，向导会写入配置，并运行与 openclaw matrix encryption setup 相同的引导流程。
最小配置
基于令牌：自动加入
channels.matrix.autoJoin 默认为 off。使用默认值时，在你手动加入之前，机器人不会出现在来自新邀请的新房间或私信中。
OpenClaw 在收到邀请时无法判断被邀请的房间是私信还是群组，因此所有邀请（包括私信风格的邀请）都会先经过 autoJoin。dm.policy 只会在稍后应用，也就是机器人加入并且房间已完成分类之后。
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
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，依此类推。当你通过 --recovery-key-stdin 管道传入密钥时，支持恢复的 CLI 流程（verify backup restore、verify device、verify bootstrap）会读取恢复密钥环境变量。
MATRIX_HOMESERVER 不能从工作区 .env 设置；见 工作区 .env 文件。
配置示例
一个包含私信配对、房间允许列表和 E2EE 的实用基线：流式预览
Matrix 回复流式传输需要主动启用。streaming 控制 OpenClaw 如何交付进行中的助手回复；blockStreaming 控制每个已完成的块是否保留为自己的 Matrix 消息。
{ mode, preview, progress }：
progress.label：自定义标签、"auto"或未设置时会从已配置或内置标签中选择，或设为false以隐藏标签行。progress.labels：仅当label为"auto"或未设置时使用的候选标签。保持未设置则使用内置默认值。progress.maxLines：草稿中保留的最大滚动进度行数。超过此限制后，较旧的行会被裁剪。progress.maxLineChars：每条紧凑进度行在截断前的最大字符数。progress.toolProgress：当为true（默认）时，实时工具/进度活动会出现在草稿中。
streaming | 行为 |
|---|---|
"off"（默认） | 等待完整回复，然后发送一次。true ↔ "partial"，false ↔ "off"。 |
"partial" | 在模型写入当前块时，原地编辑一条普通文本消息。标准 Matrix 客户端可能会在第一次预览时通知，而不是在最终编辑时通知。 |
"quiet" | 与 "partial" 相同，但消息是不会触发通知的 notice。只有当每用户推送规则匹配最终编辑后，接收者才会收到通知（见下文）。 |
"progress" | 使用进度草稿发送单独的紧凑进度行。 |
blockStreaming 独立于 streaming：
streaming | blockStreaming: true | blockStreaming: false（默认） |
|---|---|---|
"partial" / "quiet" | 当前块的实时草稿，已完成块保留为消息 | 当前块的实时草稿，并原地最终确定 |
"off" | 每个完成块发送一条会触发通知的 Matrix 消息 | 对完整回复发送一条会触发通知的 Matrix 消息 |
- 如果预览增长超过 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退到仅最终交付。
- 媒体回复始终正常发送附件。如果过期预览无法再安全复用，OpenClaw 会在发送最终媒体回复前撤回它。
- 当 Matrix 预览流式传输处于活动状态时，默认启用工具进度预览更新。设置
streaming.preview.toolProgress: false可以保留回答文本的预览编辑，但让工具进度走常规交付路径。 - 预览编辑会消耗额外的 Matrix API 调用。如果你想要最保守的速率限制配置，请保持
streaming: "off"。
语音消息
入站 Matrix 语音留言会在房间提及门控之前转录。这使得说出机器人名称的语音留言可以在requireMention: true 房间中触发智能体，并向智能体提供转录文本，而不仅仅是一个音频附件占位符。
Matrix 使用在 tools.media.audio 下配置的共享音频媒体提供商，例如 OpenAI gpt-4o-mini-transcribe。提供商设置和限制见 媒体工具概览。
行为细节：
- 符合条件的是 MIME 类型为
audio/*的m.audio事件和m.file事件。 - 在加密房间中，OpenClaw 会先通过现有的 Matrix 媒体路径解密附件，再进行转录。
- 转录文本会在智能体提示中标记为机器生成且不受信任。
- 附件会标记为已转录，所以下游媒体工具不会再次转录同一条语音留言。
- 设置
tools.media.audio.enabled: false可全局禁用音频转录。
审批元数据
Matrix 原生审批提示是普通的m.room.message 事件，并在 com.openclaw.approval 下带有 OpenClaw 特定的自定义事件内容。Matrix 允许自定义事件内容键，因此标准客户端仍会渲染文本正文，而支持 OpenClaw 的客户端可以读取结构化的审批 ID、类型、状态、可用决策以及 exec/插件详情。
当审批提示过长，无法放入一个 Matrix 事件时，OpenClaw 会将可见文本分块，并且只把 com.openclaw.approval 附加到第一个分块。允许/拒绝决策的反应会绑定到第一个事件，因此长提示和单事件提示会保持相同的审批目标。
用于静默最终预览的自托管推送规则
streaming: "quiet" 只会在分块或轮次最终确定后通知接收者 - 每用户推送规则必须匹配最终预览标记。完整方案见 Matrix 静默预览推送规则（接收者令牌、推送器检查、规则安装、按 homeserver 的说明）。
Bot 到 bot 房间
默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。 当你有意需要智能体间 Matrix 流量时，使用allowBots：
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 账户发送”。
加密和验证
在加密（E2EE）房间中，出站图片事件使用thumbnail_file，因此图片预览会和完整附件一起加密。未加密房间仍使用普通的 thumbnail_url。无需配置 - 插件会自动检测 E2EE 状态。
所有 openclaw matrix 命令都接受 --verbose（完整诊断）、--json（机器可读输出）和 --account <id>（多账户设置）。默认输出简洁，并使用安静的内部 SDK 日志。下面的示例展示规范形式；按需添加这些标志。
启用加密
--recovery-key <key>在引导前应用恢复密钥（优先使用下文记录的 stdin 形式）--force-reset-cross-signing丢弃当前交叉签名身份并创建新的身份（仅在有意这样做时使用）
--encryption 是 --enable-e2ee 的别名。
等效的手动配置：
状态和信任信号
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 管道传入，而不是在命令行上传入。设置MATRIX_RECOVERY_KEY（或为命名账户设置 MATRIX_<ID>_RECOVERY_KEY）：
Recovery key accepted：Matrix 已接受该密钥，用于密钥存储或设备信任。Backup usable：可以使用受信任的恢复材料加载房间密钥备份。Device verified by owner：此设备具有完整的 Matrix 交叉签名身份信任。
verify self 会等待 Cross-signing verified: yes，然后才成功退出。使用 --timeout-ms <ms> 调整等待时间。
也接受字面密钥形式 openclaw matrix verify device "<recovery-key>"，但该密钥会进入你的 shell 历史记录。
引导或修复交叉签名
verify bootstrap 是加密账户的修复和设置命令。它会按顺序：
- 引导密钥存储，尽可能复用现有恢复密钥
- 引导交叉签名并上传缺失的公钥
- 标记并交叉签名当前设备
- 如果服务器端房间密钥备份尚不存在，则创建一个
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提供）
房间密钥备份
backup status 显示服务器端备份是否存在，以及此设备能否解密它。backup restore 会将已备份的房间密钥导入本地加密存储；如果恢复密钥已在磁盘上，可以省略 --recovery-key-stdin。
要用新的基线替换损坏的备份（接受丢失无法恢复的旧历史；如果当前备份密钥无法加载，也可以重新创建密钥存储）：
--rotate-recovery-key。
列出、请求和响应验证
--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 emoji 或十进制数字 |
openclaw matrix verify confirm-sas <id> | 确认 SAS 与另一个客户端显示的内容匹配 |
openclaw matrix verify mismatch-sas <id> | 当 emoji 或十进制数字不匹配时拒绝 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。
Startup behavior
Startup behavior
设置
encryption: true 后，startupVerification 默认为 "if-unverified"。启动时，未验证设备会在另一个 Matrix 客户端中请求自验证，跳过重复请求并应用冷却时间（默认 24 小时）。使用 startupVerificationCooldownHours 调整，或使用 startupVerification: "off" 禁用。启动时还会运行一轮保守的加密引导流程，复用当前密钥存储和交叉签名身份。如果引导状态损坏，即使没有 channels.matrix.password，OpenClaw 也会尝试受保护的修复；如果 homeserver 要求密码 UIA，启动会记录警告并保持非致命。已由所有者签名的设备会保留。完整升级流程见 Matrix 迁移。Verification notices
Verification notices
Matrix 会将验证生命周期通知作为
m.notice 消息发布到严格私信验证房间：请求、就绪（带有“通过 emoji 验证”指引）、开始/完成，以及可用时的 SAS（emoji/十进制）详情。来自另一个 Matrix 客户端的传入请求会被跟踪并自动接受。对于自验证，OpenClaw 会自动启动 SAS 流程，并在 emoji 验证可用后确认自己这一侧 - 你仍需要在你的 Matrix 客户端中比较并确认“They match”。验证系统通知不会转发到智能体聊天流水线。Deleted or invalid Matrix device
Deleted or invalid Matrix device
如果 对于 token 凭证，请在你的 Matrix 客户端或管理 UI 中创建新的访问 token，然后更新 OpenClaw：将
verify status 表示当前设备不再列在 homeserver 上，请创建新的 OpenClaw Matrix 设备。对于密码登录：assistant 替换为失败命令中的 account ID，或省略 --account 以使用默认账号。Device hygiene
Device hygiene
旧的 OpenClaw 管理设备可能会累积。列出并清理：
Crypto store
Crypto store
Matrix E2EE 使用官方
matrix-js-sdk Rust 加密路径，并将 fake-indexeddb 作为 IndexedDB 兼容层。加密状态会持久化到 crypto-idb-snapshot.json（限制性文件权限）。加密运行时状态位于 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ 下，包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当 token 变化但账号身份保持不变时，OpenClaw 会复用最佳的现有根目录，这样先前状态仍然可见。单个较旧的 token-hash 根目录可能是正常的 token 轮换连续性路径。如果 OpenClaw 记录 matrix: multiple populated token-hash storage roots detected，请检查账号目录，并且只有在确认所选活动根目录健康后，才归档过时的同级根目录。建议先将过时根目录移入 _archive/ 目录，而不是立即删除。个人资料管理
更新所选账号的 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 账号上的同一私信对端时，才会触发私信用户目标复用；否则 OpenClaw 会回退到普通的用户作用域路由。
/focus、/unfocus、/agents、/session idle、/session max-age和线程绑定的/acp spawn都可在 Matrix 房间和私信中使用。- 当
threadBindings.spawnSessions启用时，顶层/focus会创建新的 Matrix 线程并将其绑定到目标会话。 - 在现有 Matrix 线程内运行
/focus或/acp spawn --thread here会就地绑定该线程。
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.enabledthreadBindings.idleHoursthreadBindings.maxAgeHoursthreadBindings.spawnSessionsthreadBindings.defaultSpawnContext
- 设置
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仅从机器人移除指定的 emoji 反应。
| 设置 | 顺序 |
|---|---|
ackReaction | 每账号 → 渠道 → messages.ackReaction → 智能体身份 emoji 回退 |
ackReactionScope | 每账号 → 渠道 → messages.ackReactionScope → 默认 "group-mentions" |
reactionNotifications | 每账号 → 渠道 → 默认 "own" |
reactionNotifications: "own" 会在新增的 m.reaction 事件以机器人创作的 Matrix 消息为目标时转发这些事件；"off" 会禁用反应系统事件。反应移除不会合成为系统事件，因为 Matrix 将其呈现为撤回，而不是独立的 m.reaction 移除。
历史上下文
channels.matrix.historyLimit控制当 Matrix 房间消息触发智能体时，有多少最近的房间消息会作为InboundHistory包含进来。会回退到messages.groupChat.historyLimit；如果两者都未设置，有效默认值为0。设置为0可禁用。- Matrix 房间历史仅限房间。私信继续使用普通会话历史。
- Matrix 房间历史仅限待处理消息：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到达时快照该窗口。
- 当前触发消息不包含在
InboundHistory中；它会保留在该轮次的主入站正文中。 - 同一 Matrix 事件的重试会复用原始历史快照，而不是向前漂移到更新的房间消息。
上下文可见性
Matrix 支持共享的contextVisibility 控制，用于补充房间上下文，例如获取的回复文本、线程根和待处理历史。
contextVisibility: "all"是默认值。补充上下文会按收到的形式保留。contextVisibility: "allowlist"会过滤补充上下文，只发送通过活动房间/用户 allowlist 检查的发送者内容。contextVisibility: "allowlist_quote"的行为类似allowlist，但仍保留一条显式引用回复。
groupPolicy、groups、groupAllowFrom 和私信策略设置。
私信和房间策略
dm.enabled: false：
直接房间修复
如果直接消息状态不同步，OpenClaw 最终可能会出现过时的m.direct 映射，指向旧的单人房间而不是实时私信。检查某个对端的当前映射：
--account <id>，用于多账号设置。修复流程：
- 优先选择已经映射在
m.direct中的严格 1:1 私信 - 回退到当前已加入的、与该用户对应的任何严格 1:1 私信
- 如果不存在健康私信，则创建新的直接房间并重写
m.direct
Exec 审批
Matrix 可以充当原生审批客户端。在channels.matrix.execApprovals 下配置（或使用 channels.matrix.accounts.<account>.execApprovals 作为按账号覆盖项）：
enabled：通过 Matrix 原生提示交付审批。未设置或为"auto"时，只要至少能解析出一个审批人，Matrix 就会自动启用。设置为false可显式禁用。approvers：允许审批 exec 请求的 Matrix 用户 ID（@owner:example.org）。可选，回退到channels.matrix.dm.allowFrom。target：提示发送位置。"dm"（默认）发送到审批人私信；"channel"发送到发起的 Matrix 房间或私信；"both"同时发送到两者。agentFilter/sessionFilter：可选 allowlist，用于限制哪些智能体/会话触发 Matrix 交付。
- Exec 审批使用
execApprovals.approvers，并回退到dm.allowFrom。 - 插件审批仅通过
dm.allowFrom授权。
✅允许一次❌拒绝♾️始终允许（当有效 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 也会识别以 Bot 自身 Matrix 提及为前缀的命令，因此 @bot:server /new 会触发命令路径，无需自定义提及正则。这让 Bot 能响应 Element 和类似客户端在用户先用 Tab 补全 Bot、再输入命令时发出的房间风格 @mention /command 消息。
授权规则仍然适用：命令发送者必须满足与普通消息相同的私信或房间 allowlist/owner 策略。
多账号
- 顶层
channels.matrix值会作为具名账号的默认值，除非某个账号覆盖它们。 - 使用
groups.<room>.account将继承的房间条目限定到特定账号。没有account的条目会在账号之间共享；当默认账号在顶层配置时，account: "default"仍然可用。
- 设置
defaultAccount，以选择隐式路由、探测和 CLI 命令优先使用的具名账号。 - 如果你有多个账号，且其中一个字面名称为
default，即使未设置defaultAccount，OpenClaw 也会隐式使用它。 - 如果你有多个具名账号但未选择默认账号，CLI 命令会拒绝猜测 - 请设置
defaultAccount或传入--account <id>。 - 只有在认证信息完整时（
homeserver+accessToken，或homeserver+userId+password），顶层channels.matrix.*块才会被视为隐式default账号。一旦缓存凭证已覆盖认证，具名账号仍可通过homeserver+userId被发现。
- 当 OpenClaw 在修复或设置期间将单账号配置提升为多账号配置时，如果现有具名账号存在，或
defaultAccount已指向某个账号，它会保留该账号。只有 Matrix 认证/引导键会移入提升后的账号；共享投递策略键会保留在顶层。
私有/LAN homeserver
默认情况下，OpenClaw 会阻止私有/内部 Matrix homeserver 以防止 SSRF，除非你为每个账号显式选择启用。 如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账号启用network.dangerouslyAllowPrivateNetwork：
http://matrix.example.org:8008）仍会被阻止。尽可能优先使用 https://。
代理 Matrix 流量
如果你的 Matrix 部署需要显式出站 HTTP(S) 代理，请设置channels.matrix.proxy：
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
- 用户查找会查询该 homeserver 上的 Matrix 用户目录。
- 房间查找会直接接受显式房间 ID 和别名。已加入房间的名称查找是尽力而为的，并且仅在设置
dangerouslyAllowNameMatching: true时适用于运行时房间 allowlist。 - 如果房间名称无法解析为 ID 或别名，运行时 allowlist 解析会忽略它。
配置参考
Allowlist 风格的用户字段（groupAllowFrom、dm.allowFrom、groups.<room>.users）接受完整 Matrix 用户 ID（最安全）。默认情况下，非 ID 用户条目会被忽略。如果你设置 dangerouslyAllowNameMatching: true，精确的 Matrix 目录显示名称匹配会在启动时解析，并在监视器运行期间 allowlist 发生变化时解析；无法解析的条目会在运行时被忽略。
房间 allowlist 键（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：Matrix 流量的可选 HTTP(S) 代理 URL。支持按账号覆盖。userId：完整 Matrix 用户 ID（@bot:example.org）。accessToken：基于令牌认证的访问令牌。支持跨 env/file/exec 提供商的明文和 SecretRef 值（Secrets Management）。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 allowlist。mentionPatterns：房间提及的作用域正则模式。对象格式为{ mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }。控制已配置的agents.list[].groupChat.mentionPatterns是否按房间应用。dm.enabled：当为false时，忽略所有私信。默认：true。dm.policy："pairing"（默认）、"allowlist"、"open"或"disabled"。在 Bot 已加入并将房间分类为私信后应用；它不影响邀请处理。dm.allowFrom：私信流量的用户 ID allowlist。dm.sessionScope："per-user"（默认）或"per-room"。dm.threadReplies：仅私信的回复串接覆盖项（"off"、"inbound"、"always"）。allowBots：接受来自其他已配置 Matrix Bot 账号的消息（true或"mentions"）。allowlistOnly：当为true时，将所有活跃私信策略（除"disabled"外）和"open"群组策略强制改为"allowlist"。不会更改"disabled"策略。dangerouslyAllowNameMatching：当为true时，允许对用户 allowlist 条目进行 Matrix 显示名称目录查找，并允许对房间 allowlist 键进行已加入房间名称查找。优先使用完整@user:serverID 以及房间 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"、"progress"，或对象形式{ mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, 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>.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：用于发送的可选智能体/会话允许列表。