线程与会话

Matrix 房间、DM 和线程如何映射到 OpenClaw 会话，以及每一轮携带多少房间历史。

线程¶

Matrix 支持原生线程，既可用于自动回复，也可用于 message-tool 发送。两个独立开关控制行为：

会话路由（sessionScope）¶

dm.sessionScope 决定 Matrix DM 房间如何映射到 OpenClaw 会话：

• "per-user"（默认）：与同一路由对等方相关的所有 DM 房间共享一个会话。
• "per-room"：每个 Matrix DM 房间拥有自己的会话键，即使对等方相同。

显式会话绑定始终优先于 sessionScope；已绑定的房间和线程会保留其选定的目标会话。

回复线程（threadReplies）¶

threadReplies 决定机器人将回复发布到哪里：

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

dm.threadReplies 仅对 DM 覆盖此设置——例如，保持房间线程隔离，同时保持 DM 为扁平结构。

在线程内选择回复目标会同时保留线程和所选消息。普通线程消息可以携带回复元数据以兼容旧版客户端；OpenClaw 不会将该兼容性回退视为代理上下文中的引用消息。

机器人创建线程中的提及¶

设置 channels.matrix.requireMentionInBotThreads: false 以接受在由接收机器人发送的事件为根的原生 Matrix 线程中未提及的后续消息。将其设置为 true 可在这些线程中要求提及，即使房间使用 requireMention: false 或 autoReply: true。省略该设置会保留房间现有的提及行为。

该设置也可在 accounts.<id> 以及每个 groups 或 rooms 条目下使用。房间条目会覆盖账户值。与其他 Matrix 房间设置一样，精确房间条目会替换通配符条目；精确条目中省略的字段会回退到账户，而不是通配符。

只有原生 m.thread 关系才符合条件。对机器人消息的普通回复不符合条件。OpenClaw 使用接收账户解析线程根，并缓存其已验证作者。Matrix 内容删除不会更改该作者，因此被删除的机器人创建根仍然符合条件。如果无法读取或验证根的身份，则应用现有提及行为。房间访问权限、发送者限制以及 allowBots: "mentions" 仍然适用。

线程继承与斜杠命令¶

• 入站线程消息会将线程根消息作为额外的代理上下文包含在内。
• 当目标为同一房间（或同一 DM 用户目标）时，message-tool 发送会自动继承当前 Matrix 线程，除非提供了显式 threadId。
• 仅当当前会话元数据证明同一 Matrix 账户上的同一 DM 对等方时，DM 用户目标复用才会生效；否则 OpenClaw 会回退到常规用户级路由。
• /session unbind、/agents、/session idle、/session max-age 以及线程绑定的 /acp spawn 均可在 Matrix 房间和 DM 中使用。
• 当启用 threadBindings.spawnSessions 时，/acp spawn --thread auto 会创建新的 Matrix 线程。
• 在现有 Matrix 线程内运行 /acp spawn --thread here 会就地绑定该线程。

当 OpenClaw 检测到 Matrix DM 房间与同一共享会话上的另一个 DM 房间发生冲突时，它会发布一次性 m.notice，建议将 dm.sessionScope: "per-room" 用于隔离房间。该通知仅在启用线程绑定时出现。

ACP 会话绑定¶

Matrix 房间、DM 和现有 Matrix 线程可以在不更改聊天界面的情况下成为持久 ACP 工作区。

快速操作员流程：

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

--bind here 不会创建子 Matrix 线程。threadBindings.spawnSessions 控制 /acp spawn --thread auto|here，即 OpenClaw 需要创建或绑定子线程的场景。

线程绑定配置¶

Matrix 从 session.threadBindings 继承全局默认值，并支持按通道覆盖：

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions：同时控制子代理和 ACP 线程生成。
• 已弃用的 threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions 键会通过 openclaw doctor --fix 迁移到 spawnSessions。
• threadBindings.defaultSpawnContext

Matrix 线程绑定会话生成默认开启。设置 threadBindings.spawnSessions: false 可阻止原生子代理和 ACP 线程生成创建/绑定 Matrix 线程。当原生子代理线程生成不应分叉父转录时，设置 threadBindings.defaultSpawnContext: "isolated"。

历史上下文¶

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