本页内容
本页内容
主流消息传递
Matrix 帐户和家庭服务器
帐户布局、家庭服务器可达性和目标表单OpenClaw接受为Matrix房间和用户。
个人资料管理
在一次调用中传递两个选项。 Matrix 直接接受mxc://头像URL；传递 http:///https:// 首先上传文件并将解析的 mxc:// URL 存储到 channels.matrix.avatarUrl （或每个帐户覆盖）。
直接房间修复
如果直接消息状态发生漂移，OpenClaw 可能会最终保留指向旧单人房间而不是当前 DM 的过时 m.direct 映射。检查某个对端的当前映射：
修复它：
这两个命令都接受 --account <id>，用于多账户配置。修复流程：
- 优先使用已在
m.direct中映射的严格 1:1 DM - 其次回退到当前已加入的、与该用户对应的任意严格 1:1 DM
- 如果不存在健康的 DM，则创建一个新的直接房间并重写
m.direct
它不会自动删除旧房间。它会选取健康的 DM 并更新映射，使未来的 Matrix 发送、验证通知和其他直接消息流程指向正确的房间。
映射更新在写入之前读取现有帐户数据。如果读取失败，更新将停止，而不替换现有映射。帐户数据读取恢复后重试修复。
多账户
继承：
- 顶层
channels.matrix的值会作为命名账户的默认值，除非某个账户覆盖它们。 - 使用
groups.<room>.account将继承的房间条目限定到特定账户。未设置account的条目在各账户之间共享；当默认账户配置在顶层时，account: "default"仍然有效。
默认账户选择：
- 设置
defaultAccount以选择隐式路由、检查和 CLI 命令首选的命名帐户。 - 如果你有多个账户，并且其中一个确实名为
default，即使未设置defaultAccount，OpenClaw 也会隐式使用它。 - 如果存在多个命名账户但未选择默认账户，CLI 命令将拒绝猜测——请设置
defaultAccount或传入--account <id>。 - 顶级
channels.matrix.*块仅在其身份验证完成时被视为隐式default帐户（homeserver+accessToken，或homeserver+userId+password）。一旦缓存的凭据覆盖身份验证，命名帐户仍然可以从homeserver+userId中发现。
提升：
- 当 OpenClaw 在修复或设置期间将单帐户配置提升为多帐户时，如果存在或
defaultAccount已指向一个帐户，它将保留现有的命名帐户。只有 Matrix auth/bootstrap 密钥才会移入升级帐户；共享的交付策略密钥保留在顶层。
有关共享的多账户模式，请参见配置参考。
Private/LAN 家庭服务器
默认情况下，OpenClaw 会阻止 private/internal Matrix 家庭服务器以实现 SSRF 保护，除非您选择按帐户加入。
如果你的 homeserver 运行在 localhost、LAN/Tailscale IP，或内部主机名上，请为该账号启用 network.dangerouslyAllowPrivateNetwork：
CLI 设置示例：
此选择仅允许受信任的 private/internal 目标。公共明文家庭服务器（例如 http://matrix.example.org:8008）仍然被阻止。尽可能首选 https://。
代理 Matrix 流量
如果你的 Matrix 部署需要显式的出站 HTTP(S) 代理，请设置 channels.matrix.proxy：
命名帐户可以使用 channels.matrix.accounts.<id>.proxy 覆盖顶级默认值。 OpenClaw 使用相同的代理设置进行运行时 Matrix 流量和帐户状态检查。
目标解析
Matrix 在 OpenClaw 需要房间或用户目标的任何地方都接受以下目标形式：
- 用户：
@user:server、user:@user:server或matrix:user:@user:server - 房间：
!room:server、room:!room:server或matrix:room:!room:server（房间版本 12+ 房间 ID 没有:server后缀 —!room、room:!room、matrix:room:!room— 并且是以同样的方式接受） - 别名：
#alias:server、channel:#alias:server或matrix:channel:#alias:server
Matrix 房间 ID 区分大小写。配置显式传送目标、cron 作业、绑定或白名单时，请使用 Matrix 中的确切房间 ID 大小写。 OpenClaw 将内部会话密钥标准化为小写以便存储，因此这些小写密钥不是 Matrix 传递 ID 的可靠来源。
配置支持的对等和组列表使用所选帐户的允许列表和配置的房间，而无需加载存储的 Matrix 凭据。
实时目录查询使用已登录的 Matrix 账户：
- 用户查找会查询该 homeserver 上的 Matrix 用户目录。
- 房间查找直接接受显式房间 ID 和别名。加入的房间名称查找是尽力而为的，并且仅在设置
dangerouslyAllowNameMatching: true时适用于运行时房间允许列表。 - 如果房间名称无法解析为 ID 或别名，则会在运行时允许名单解析中忽略它。