跳转至

Matrix

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

Node 仍然是推荐的运行时。Matrix 也接受可选的 Bun 运行时；E2EE 要求 Matrix SDK 的原生加密绑定在你的平台上可用。

设置

安装插件并连接 homeserver 账户。

加密

启用 E2EE 并验证网关设备。

Matrix 迁移

加密状态恢复限制和升级流程。

各页面涵盖的内容

  • Matrix 设置 — 安装插件，将其指向 homeserver，选择认证方式，并控制邀请和允许列表。
  • Matrix 访问控制 — 私信和房间策略、允许列表、机器人之间流量、上下文可见性以及命令授权。
  • Matrix 消息行为 — 流式预览、传入语音消息转写以及表情回应。
  • Matrix 富消息和审批 — 结构化回复控制、审批事件元数据以及 exec 审批提示。
  • Matrix 加密和验证 — E2EE 设置、设备验证、交叉签名修复、房间密钥备份以及加密存储布局。
  • Matrix 线程和会话 — 会话路由、回复线程、ACP 会话绑定以及房间历史上下文。
  • Matrix 账户和 homeservers — 多账户布局、私有/LAN homeservers、代理、个人资料、直接房间修复以及目标解析。

各章节迁移位置

来自之前单页版本的每个章节标题都会在此保留其锚点，因此现有链接（例如 /channels/matrix#streaming-previews）仍然可以解析。每个条目都指向现在承载该内容的页面。

配置参考

允许列表式用户字段（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/store 提供程序使用明文和 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.entries.*.groupChat.mentionPatterns 是否按房间应用。
  • dm.enabled：当为 false 时，忽略所有 DM。默认：true。
  • dm.policy："pairing"（默认）、"allowlist"、"open" 或 "disabled"。在机器人加入并将房间分类为 DM 后应用；它不影响邀请处理。
  • dm.allowFrom：DM 流量的用户 ID 允许列表。
  • dm.sessionScope："per-user"（默认）或 "per-room"。
  • dm.threadReplies：仅限 DM 的回复线程覆盖（"off"、"inbound"、"always"）。
  • allowBots：接受来自其他已配置 Matrix 机器人账户的消息（true 或 "mentions"）。
  • allowlistOnly：当为 true 时，强制所有活动 DM 策略（除 "disabled" 外）和 "open" 群组策略为 "allowlist"。不会更改 "disabled" 策略。
  • dangerouslyAllowNameMatching：当为 true 时，允许对用户允许列表条目进行 Matrix 显示名称目录查找，并对房间允许列表键进行已加入房间名称查找。优先使用完整 @user:server ID 以及房间 ID 或别名。
  • autoJoin："always"、"allowlist" 或 "off"。默认："off"。适用于每个 Matrix 邀请，包括 DM 式邀请。
  • autoJoinAllowlist：当 autoJoin 为 "allowlist" 时允许的房间/别名。别名词条针对家庭服务器解析，而不是针对被邀请房间声称的状态。
  • contextVisibility：补充上下文可见性（"all" 默认、"allowlist"、"allowlist_quote"）。

回复行为

  • joinIntro：当机器人加入允许的群组房间时进行介绍。默认：true。按账户覆盖：accounts.<accountId>.joinIntro。
  • replyToMode："off"（默认）、"first"、"all" 或 "batched"。
  • threadReplies："off"、"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：按房间技能过滤器。
  • groups.<room>.systemPrompt：按房间系统提示片段。

Exec approval settings

  • execApprovals.enabled：通过 Matrix 原生提示传递 exec 审批。
  • execApprovals.approvers：允许批准 exec 的 Matrix 用户 ID。回退到 dm.allowFrom。
  • execApprovals.target："dm"（默认）、"channel" 或 "both"。
  • execApprovals.agentFilter / execApprovals.sessionFilter：用于投递的可选代理/会话允许列表。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw