跳转至

账户和 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 认证/引导密钥会移动到提升后的账户中;共享的投递策略密钥保留在顶层。

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

私有/LAN homeserver

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

如果你的 homeserver 运行在 localhost、LAN/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 流量和账户状态检查使用相同的代理设置。

目标解析

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 或别名,它会被运行时允许列表解析忽略。

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