跳转至

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 账户和 homeserver — 多账户布局、私有/局域网 homeserver、代理、个人资料、直接房间修复和目标解析。

各章节迁移位置

来自之前单页版本的每个章节标题都在此处保留其锚点,因此现有链接(如 /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:homeserver URL,例如 https://matrix.example.org。
  • network.dangerouslyAllowPrivateNetwork:允许此账户连接到 localhost、LAN/Tailscale IP 或内部主机名。
  • proxy:用于 Matrix 流量的可选 HTTP(S) 代理 URL。支持按账户覆盖。
  • userId:完整的 Matrix 用户 ID(@bot:example.org)。
  • accessToken:基于 token 的身份验证所使用的访问 token。支持跨 env/file/exec/store 提供方的明文和 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 允许列表。
  • 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" 时允许的房间/别名。只有房间 ID、别名或 * 可以匹配;运行时会对其他条目发出警告并忽略它们(例如用户 ID,它应放在 dm.allowFrom 中)。别名词条针对 homeserver 解析,而不是针对被邀请房间声称的状态。
  • 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 审批设置

  • execApprovals.enabled:通过 Matrix 原生提示传递 exec 审批。
  • execApprovals.approvers:允许批准的 Matrix 用户 ID。回退到 dm.allowFrom。
  • execApprovals.target:"dm"(默认)、"channel" 或 "both"。
  • execApprovals.agentFilter / execApprovals.sessionFilter:用于投递的可选 agent/session 允许列表。

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