Matrix

​

安装

openclaw plugins install @openclaw/matrix

​

设置

1. 在你的 homeserver 上创建一个 Matrix 账户。
2. 使用 homeserver + accessToken，或者 homeserver + userId + password 配置 channels.matrix。
3. 重启网关。
4. 与机器人发起私信，或将其邀请到某个房间。只有在 autoJoin 允许时，新邀请才会被加入。

​

交互式设置

openclaw channels add
openclaw configure --section channels

​

最小配置

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw 网关",
    },
  },
}

​

自动加入

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}

​

Allowlist 目标格式

• DM（dm.allowFrom、groupAllowFrom、groups.<room>.users）：使用 @user:server。默认会忽略显示名称（可变）；只有在需要明确兼容显示名称时才设置 dangerouslyAllowNameMatching: true。
• 房间 allowlist 键（groups、旧别名 rooms）：使用 !room:server 或 #alias:server。除非设置了 dangerouslyAllowNameMatching: true，否则普通名称会被忽略。
• 邀请 allowlist（autoJoinAllowlist）：使用 !room:server、#alias:server 或 *。普通名称始终会被拒绝。

​

账户 ID 规范化

​

缓存的凭据

​

环境变量

​

配置示例

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: { mode: "partial" },
    },
  },
}

​

流式预览

{
  channels: {
    matrix: {
      streaming: { mode: "partial" },
    },
  },
}

{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

{
  channels: {
    matrix: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto", // 从已配置或内置标签中选择（false 表示隐藏）
          labels: ["思考中", "写作中", "搜索中"], // 当 label 为 "auto" 时的候选标签
          maxLines: 8, // 保留的最大滚动进度行数（默认：8）
          maxLineChars: 120, // 每行在截断前的最大字符数（默认：120）
          toolProgress: true, // 显示工具/进度活动（默认：true）
        },
      },
    },
  },
}

• progress.label：自定义标签，"auto"/未设置时从已配置或内置标签中选择，或设为 false 以隐藏。
• progress.labels：仅当 label 为 "auto" 或未设置时使用的候选项。
• progress.maxLines：草稿中保留的最大滚动进度行数；更早的行会被裁剪。
• progress.maxLineChars：每条紧凑进度行在截断前的最大字符数。
• progress.toolProgress：当为 true（默认）时，实时工具/进度活动会显示在草稿中。

• 如果预览超过了 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退为仅最终结果的传递。
• 媒体回复始终会正常发送附件；如果无法安全复用过时的预览，OpenClaw 会在发送最终媒体回复前将其清除。
• 当预览流式传输处于活动状态时，工具进度预览更新默认开启。将 streaming.preview.toolProgress: false 设为仅保留答案文本的预览编辑，而让工具进度走正常传递路径。
• 预览编辑会额外消耗 Matrix API 调用。若要获得最保守的速率限制配置，请保持 streaming.mode: "off"。
• 旧的标量/布尔值 streaming 以及扁平的 blockStreaming / chunkMode 键，会被 openclaw doctor --fix 重写为这种嵌套结构。

​

语音消息

• m.audio 事件和带有 audio/* MIME 类型的 m.file 事件都符合条件。
• 在加密房间中，OpenClaw 会在转写之前通过现有的 Matrix 媒体路径解密附件。
• 转写文本会在代理提示中被标记为机器生成且不可信。
• 该附件会被标记为已转写，因此下游媒体工具不会再次对其进行转写。
• 将 tools.media.audio.enabled: false 设为禁用全局音频转写。

​

审批元数据

​

用于静默最终化预览的自托管推送规则

​

Bot 到 Bot 房间

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true 会在允许的房间和 DM 中接受来自其他已配置 Matrix 机器人账号的消息。
• allowBots: "mentions" 仅在这些消息在房间中明显提及了该机器人时才接受；DM 仍然始终允许。
• groups.<room>.allowBots 会覆盖单个房间的账号级设置。
• 被接受的已配置机器人消息会使用共享的 bot loop protection。先配置 channels.defaults.botLoopProtection，然后通过 channels.matrix.botLoopProtection 按账号覆盖，或通过 channels.matrix.groups.<room>.botLoopProtection 按房间覆盖。
• OpenClaw 仍会忽略来自同一个 Matrix 用户 ID 的消息，以避免自我回复循环。
• Matrix 没有原生的机器人标志；OpenClaw 将“由机器人发送”视为“由此 OpenClaw 网关上的另一个已配置 Matrix 账号发送”。

​

加密与验证

​

启用加密

openclaw matrix encryption setup
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix encryption setup --recovery-key-stdin

• --recovery-key-stdin 从 stdin 读取恢复密钥，而不会将其暴露在进程参数中；--recovery-key <key> 仍可用于兼容性
• --force-reset-cross-signing 丢弃当前交叉签名身份并创建新的身份（仅限有意使用）

openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

​

状态与信任信号

openclaw matrix verify status
openclaw matrix verify status --include-recovery-key --json

• Locally trusted：仅被此客户端信任
• Cross-signing verified：SDK 报告已通过交叉签名验证
• Signed by owner：由你自己的自签名密钥签名（仅用于诊断）

​

使用恢复密钥验证此设备

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

• Recovery key accepted：Matrix 已接受该密钥用于 secret 存储或设备信任。
• Backup usable：可使用受信任的恢复材料加载房间密钥备份。
• Device verified by owner：此设备拥有完整的 Matrix 交叉签名身份信任。

openclaw matrix verify self

​

初始化或修复交叉签名

openclaw matrix verify bootstrap

• 初始化 secret 存储，尽可能复用现有恢复密钥
• 初始化交叉签名并上传缺失的公钥
• 标记并对当前设备进行交叉签名
• 如果服务器端尚不存在房间密钥备份，则创建一个

• --recovery-key-stdin（配合 printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...）或 --recovery-key <key>
• --force-reset-cross-signing 丢弃当前交叉签名身份（仅限有意使用；需要已存储或通过 --recovery-key-stdin 提供当前恢复密钥）

​

房间密钥备份

openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

openclaw matrix verify backup reset --yes

​

列出、请求和响应验证

openclaw matrix verify list

openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

​

多账户说明

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'

openclaw matrix devices list
openclaw matrix devices prune-stale

​

个人资料管理

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

​

线程

​

会话路由（sessionScope）

• "per-user"（默认）：具有相同路由对端的所有 DM 房间共享一个会话。
• "per-room"：每个 Matrix DM 房间都有自己的会话键，即使对端相同也是如此。

​

回复线程化（threadReplies）

• "off"：回复为顶层消息。传入的线程消息会停留在父会话中。
• "inbound"：仅当传入消息本身已经位于该线程中时，才在该线程内回复。
• "always"：在由触发消息为根的线程中回复；从第一次触发开始，该对话会通过匹配的线程作用域会话进行路由。

​

线程继承与斜杠命令

• 传入的线程消息会将线程根消息作为额外的代理上下文包含进来。
• 当目标是同一房间（或同一 DM 用户目标）时，消息工具发送会自动继承当前的 Matrix 线程，除非显式提供了 threadId。
• 仅当当前会话元数据证明是在同一个 Matrix 账号上的同一个 DM 对端时，DM 用户目标复用才会生效；否则 OpenClaw 会回退到正常的按用户作用域路由。
• /focus、/unfocus、/agents、/session idle、/session max-age 以及线程绑定的 /acp spawn 都可在 Matrix 房间和 DMs 中使用。
• 顶层 /focus 会创建一个新的 Matrix 线程，并在启用 threadBindings.spawnSessions 时将其绑定到目标会话。
• 在现有 Matrix 线程中运行 /focus 或 /acp spawn --thread here 会就地绑定该线程。

​

ACP 会话绑定

• 在 Matrix DM、房间或现有线程中运行 /acp spawn codex --bind here，以继续使用。
• 在顶层 DM 或房间中，当前 DM/房间保持为聊天界面，未来消息会路由到新生成的 ACP 会话。
• 在现有线程中，--bind here 会就地绑定当前线程。
• /new 和 /reset 会就地重置同一个已绑定的 ACP 会话。
• /acp close 会关闭 ACP 会话并移除绑定。

​

线程绑定配置

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions：同时限制子代理和 ACP 线程的创建。
• 已弃用的 threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions 键会由 openclaw doctor --fix 迁移为 spawnSessions。
• threadBindings.defaultSpawnContext

​

反应

• react 向某个 Matrix 事件添加反应。
• reactions 列出某个 Matrix 事件当前的反应摘要。
• emoji="" 移除机器人在该事件上的自身反应。
• remove: true 仅移除机器人指定的表情反应。

​

历史上下文

• channels.matrix.historyLimit 控制当房间消息触发代理时，作为 InboundHistory 包含多少条最近的房间消息。若未设置，则回退到 messages.groupChat.historyLimit；如果两者都未设置，最终默认值为 0（禁用）。
• Matrix 房间历史仅适用于房间；DM 仍然使用正常的对话历史。
• 房间历史仅适用于待处理消息：OpenClaw 会缓冲尚未触发回复的房间消息，然后在出现提及或其他触发条件时对该窗口进行快照。
• 当前触发消息不包含在 InboundHistory 中；它仍保留在该轮的主入站正文中。
• 同一 Matrix 事件的重试会复用原始历史快照，而不是随着新的房间消息继续向前漂移。

​

上下文可见性

• contextVisibility: "all" 是默认值。附加上下文会按接收时的内容保留。
• contextVisibility: "allowlist" 会过滤附加上下文，使其仅对当前房间／用户允许列表检查所允许的发送者可见。
• contextVisibility: "allowlist_quote" 的行为类似于 allowlist，但仍会保留明确引用的回复。

​

DM 和房间策略

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },
    },
  },
}

{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

直接房间修复

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

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

• 优先使用已在 m.direct 中映射的严格 1:1 DM
• 其次回退到当前已加入的、与该用户对应的任意严格 1:1 DM
• 如果不存在健康的 DM，则创建一个新的直接房间并重写 m.direct

​

Exec 批准

• enabled：通过 Matrix 原生提示传递批准。未设置或设为 "auto" 时，一旦至少能解析出一个批准者就会自动启用；设为 false 可显式禁用。
• approvers：允许批准 exec 请求的 Matrix 用户 ID（@owner:example.org）。回退到 channels.matrix.dm.allowFrom。
• target：提示发送到哪里。"dm"（默认）发送到批准者的私信；"channel" 发送到发起的房间或私信；"both" 同时发送到两者。
• agentFilter / sessionFilter：可选的允许列表，用于指定哪些 agent/session 触发 Matrix 投递。

• Exec 批准 使用 execApprovals.approvers，回退到 dm.allowFrom。
• 插件批准 仅通过 dm.allowFrom 授权。

• ✅ 仅允许一次
• ❌ 拒绝
• ♾️ 始终允许（当有效 exec 策略允许时）

​

斜杠命令

​

多账户

{
  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

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

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

​

代理 Matrix 流量

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

​

目标解析

• 用户：@user:server、user:@user:server 或 matrix:user:@user:server
• 房间：!room:server、room:!room:server 或 matrix:room:!room:server
• 别名：#alias:server、channel:#alias:server 或 matrix:channel:#alias:server

• 用户查找会查询该 homeserver 上的 Matrix 用户目录。
• 房间查找直接接受显式房间 ID 和别名。已加入房间的名称查找尽力而为，并且仅在设置了 dangerouslyAllowNameMatching: true 时适用于运行时房间允许名单。
• 如果房间名称无法解析为 ID 或别名，则会在运行时允许名单解析中忽略它。

​

配置参考

​

账户与连接

• 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.allowFrom：用于私信流量的用户 ID 允许名单。
• dm.sessionScope："per-user"（默认）或 "per-room"。
• dm.threadReplies：仅用于私信的回复线程覆盖（"off"、"inbound"、"always"）。
• allowBots：接受来自其他已配置 Matrix 机器人账户的消息（true 或 "mentions"）。
• allowlistOnly：为 true 时，强制将所有启用的私信策略（"disabled" 除外）以及 "open" 群组策略设为 "allowlist"。不会更改 "disabled" 策略。
• dangerouslyAllowNameMatching：为 true 时，允许通过 Matrix 显示名称目录查找用户允许名单条目，并查找已加入房间的名称以解析房间允许名单键。优先使用完整的 @user:server ID 以及房间 ID 或别名。
• autoJoin："always"、"allowlist" 或 "off"。默认值："off"。适用于所有 Matrix 邀请，包括私信形式的邀请。
• autoJoinAllowlist：当 autoJoin 为 "allowlist" 时允许加入的房间/别名。别名会根据 homeserver 进行解析，而不是根据受邀房间声明的状态进行解析。
• contextVisibility：补充上下文可见性（默认值为 "all"，也可以是 "allowlist"、"allowlist_quote"）。

​

回复行为

• replyToMode："off"（默认）、"first"、"all" 或 "batched"。
• threadReplies："off"（顶层默认值会解析为 "inbound"，除非显式设置）、"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：用于投递的可选代理/会话白名单。

​

相关内容

• 通道概览 - 所有支持的通道
• 配对 - DM 认证与配对流程
• 群组 - 群聊行为与提及门控
• 通道路由 - 消息的会话路由
• 安全性 - 访问模型与加固。