本页内容

本页内容

主流消息传递

Matrix

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

Node 仍然是建议的运行时间。 Matrix 还接受 选择加入 Bun 运行时 ; E2EE 要求 Matrix SDK 的本机加密绑定可用于您的平台。

openclaw matrix verify status、verify bootstrap和verify device在本地网关运行时路由通过本地网关。如果旧网关不支持此路由,请更新它;失败的请求永远不会在本地重播。

其他openclaw matrix命令要求停止本地网关,包括设备诊断:准备帐户可以更新其加密状态。通过其服务所有者停止网关,运行命令,然后重新启动它。当网关拥有状态目录时,命令在加载帐户状态之前拒绝。离线所有权通过加密持久性和客户端关闭而持续。

加密会话中断后,openclaw matrix doctor inspect 报告需要显式快照恢复的帐户。清理会话保留其加密保护文件;不要删除它们。在接受快照回滚之前,请参阅 加密状态恢复。

每页涵盖的内容

  • Matrix setup — 安装插件,将其指向家庭服务器,选择身份验证,然后控制邀请和白名单。
  • 矩阵访问控制 — DM 和房间策略、允许列表、机器人到机器人流量、上下文可见性和命令授权。
  • 矩阵消息行为 — 流式预览、入站语音笔记转录和反应。
  • Matrix 丰富的消息和批准 — 结构化回复控件、批准事件元数据和执行批准提示。
  • 矩阵加密与验证 — E2EE设置、设备验证、交叉签名修复、房间密钥备份和加密存储布局。
  • Matrix 线程和会话 — 会话路由、回复线程、ACP 对话绑定和房间历史上下文。
  • Matrix 帐户和家庭服务器 — 多帐户布局、private/LAN 家庭服务器、代理、配置文件、直接房间修复和目标解析。

各部分移动的地方

先前单页版本的每个部分标题都保留其锚点,因此现有链接(例如 /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:基于令牌的身份验证的访问令牌。跨 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 时,忽略所有私信。默认值: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-style 邀请。
  • autoJoinAllowlist:当autoJoin为"allowlist"时允许rooms/aliases。仅房间 ID、别名或 * 可以匹配;运行时会警告并忽略其他条目(例如,属于 dm.allowFrom 的用户 ID)。别名条目根据主服务器进行解析,而不是根据受邀房间声明的状态进行解析。
  • 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"。旧版 scalar/boolean 拼写通过 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:此 channel/account. 的确认反应覆盖
  • ackReactionScope:范围覆盖(默认 "group-mentions",以及 "group-all"、"direct"、"all"、"none"、"off")。
  • reactionNotifications:入站反应通知模式(默认 "own",或 "off")。

工具与按房间覆盖

  • actions:按动作的工具门控(messages、reactions、pins、profile、memberInfo、channelInfo、verification)。
  • groups:每个房间的政策地图。会话标识使用解析后的稳定房间ID。 (rooms 是旧别名。)房间工具和提及策略使用从配置的键解析的房间 ID;入站显示名称永远不会选择另一个房间的策略。
    • groups.<room>.account:将继承的单个房间条目限制到特定账户。
    • groups.<room>.enabled:按房间开关。为 false 时,该房间会被忽略,仿佛不在映射中。
    • groups.<room>.requireMention:按房间覆盖通道级提及要求。
    • groups.<room>.allowBots:按房间覆盖通道级设置(true 或 "mentions")。
    • groups.<room>.botLoopProtection:按房间覆盖机器人间循环保护预算。
    • groups.<room>.users:按房间发送者允许名单。
    • groups.<room>.tools:每个房间工具 allow/deny 覆盖。
    • groups.<room>.autoReply:按房间提及门控覆盖。true 会禁用该房间的提及要求;false 会强制重新启用。
    • groups.<room>.skills:按房间技能过滤器。
    • groups.<room>.systemPrompt:按房间系统提示片段。

Exec 审批设置

  • execApprovals.enabled:通过 Matrix-native 提示提供执行批准。
  • execApprovals.approvers:允许批准的Matrix用户ID。回落至 dm.allowFrom。
  • execApprovals.target:"dm"(默认)、"channel" 或 "both"。
  • execApprovals.agentFilter / execApprovals.sessionFilter:可选的 agent/session 交付白名单。

相关内容

本页有帮助吗?