账户和 homeservers

账户布局、homeserver 可达性，以及 OpenClaw 为 Matrix 房间和用户接受的目标形式。

个人资料管理¶

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

在一次调用中同时传入这两个选项。Matrix 可直接接受 mxc:// 头像 URL；传入 http:///https:// 时会先上传文件，并将解析后的 mxc:// URL 存储到 channels.matrix.avatarUrl（或按账户覆盖项）。

直接消息房间修复¶

如果直接消息状态发生漂移，OpenClaw 可能会保留过时的 m.direct 映射，指向旧的单人房间而非当前活跃的直接消息房间。检查某个对端的当前映射：

openclaw matrix direct inspect --user-id @alice:example.org

修复它：

openclaw matrix direct repair --user-id @alice:example.org

这两个命令都接受 --account <id>，用于多账户设置。修复流程：

• 优先选择已在 m.direct 中映射的严格 1:1 直接消息房间
• 回退到当前已加入的与该用户的任意严格 1:1 直接消息房间
• 如果不存在健康的直接消息房间，则创建新的直接消息房间并重写 m.direct

它不会自动删除旧房间。它会选择健康的直接消息房间并更新映射，以便未来的 Matrix 发送、验证通知和其他直接消息流程都指向正确的房间。

多账户¶

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

继承：

• 顶层 channels.matrix 值作为命名账户的默认值，除非某个账户对其进行覆盖。
• 使用 groups.<room>.account 将继承的房间条目限定到特定账户。未包含 account 的条目在所有账户之间共享；当默认账户在顶层配置时，account: "default" 仍然有效。

默认账户选择：

• 设置 defaultAccount 以选择隐式路由、探测和 CLI 命令优先使用的命名账户。
• 如果你有多个账户，且其中一个字面命名为 default，即使未设置 defaultAccount，OpenClaw 也会隐式使用它。
• 如果存在多个命名账户且未选择默认账户，CLI 命令不会猜测——请设置 defaultAccount 或传入 --account <id>。
• 只有当顶层 channels.matrix.* 块的认证信息完整时（homeserver + accessToken，或 homeserver + userId + password），它才会被视为隐式 default 账户。一旦缓存凭据可覆盖认证，命名账户仍可从 homeserver + userId 被发现。

升级：

• 当 OpenClaw 在修复或设置过程中将单账户配置升级为多账户配置时，如果已存在命名账户或 defaultAccount 已指向某个账户，它会保留现有命名账户。只有 Matrix 认证/引导密钥会移动到升级后的账户中；共享的投递策略密钥仍保留在顶层。

有关共享的多账户模式，请参阅配置参考。

私有/局域网 homeserver¶

默认情况下，出于 SSRF 保护，OpenClaw 会阻止私有/内部 Matrix homeserver，除非你按账户选择加入。

如果你的 homeserver 运行在 localhost、局域网/Tailscale IP 或内部主机名上，请为该账户启用 network.dangerouslyAllowPrivateNetwork：

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}

CLI 设置示例：

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

此选择加入仅允许受信任的私有/内部目标。公共明文 homeserver（例如 http://matrix.example.org:8008）仍会被阻止。尽可能优先使用 https://。

代理 Matrix 流量¶

如果你的 Matrix 部署需要显式的出站 HTTP(S) 代理，请设置 channels.matrix.proxy：

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

命名账户可以使用 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（房间版本 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 或别名，运行时允许列表解析会忽略它。