# Matrix threads and sessions > Session routing, reply threading, ACP bindings, and room history context - 网址：https://funcoding.ai/agents/openclaw/channels/matrix/threads-and-sessions/ - 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/channels/matrix/threads-and-sessions --- How Matrix rooms, DMs, and threads map onto OpenClaw sessions, and how much room history each turn carries. ## Threads Matrix supports native threads for both automatic replies and message-tool sends. Two independent knobs control behavior: ### Session routing (`sessionScope`) `dm.sessionScope` decides how Matrix DM rooms map to OpenClaw sessions: - `"per-user"` (default): all DM rooms with the same routed peer share one session. - `"per-room"`: each Matrix DM room gets its own session key, even for the same peer. Explicit conversation bindings always win over `sessionScope`; bound rooms and threads keep their chosen target session. ### Reply threading (`threadReplies`) `threadReplies` decides where the bot posts its reply: - `"off"`: replies are top-level. Inbound threaded messages stay on the parent session. - `"inbound"`: reply inside a thread only when the inbound message was already in that thread. - `"always"`: reply inside a thread rooted at the triggering message; that conversation routes through a matching thread-scoped session from the first trigger onward. `dm.threadReplies` overrides this for DMs only - for example, keep room threads isolated while keeping DMs flat. Selecting a reply target inside a thread preserves both the thread and the selected message. Ordinary threaded messages can carry reply metadata for older clients; OpenClaw does not treat that compatibility fallback as a quoted message in the agent's context. ### Mentions in bot-created threads Set `channels.matrix.requireMentionInBotThreads: false` to accept unmentioned follow-ups in native Matrix threads rooted in an event sent by the receiving bot. Set it to `true` to require mentions in those threads even when the room uses `requireMention: false` or `autoReply: true`. Omitting it preserves the room's existing mention behavior. The setting is also available under `accounts.` and each `groups` or `rooms` entry. Room entries override the account value. As with other Matrix room settings, an exact room entry replaces the wildcard entry; omitted fields in an exact entry fall back to the account, not the wildcard. Only a native `m.thread` relationship qualifies. An ordinary reply to a bot message does not. OpenClaw resolves the thread root using the receiving account and caches its verified author. Matrix content redaction does not change that author, so a redacted bot-authored root still qualifies. If the root's identity cannot be read or verified, the existing mention behavior applies. Room access, sender restrictions, and `allowBots: "mentions"` still apply. ### Thread inheritance and slash commands - Inbound threaded messages include the thread root message as extra agent context. - Message-tool sends auto-inherit the current Matrix thread when targeting the same room (or the same DM user target), unless an explicit `threadId` is provided. - DM user-target reuse only kicks in when current session metadata proves the same DM peer on the same Matrix account; otherwise OpenClaw falls back to normal user-scoped routing. - `/session unbind`, `/agents`, `/session idle`, `/session max-age`, and thread-bound `/acp spawn` all work in Matrix rooms and DMs. - `/acp spawn --thread auto` creates a new Matrix thread when `threadBindings.spawnSessions` is enabled. - Running `/acp spawn --thread here` inside an existing Matrix thread binds that thread in place. When OpenClaw detects a Matrix DM room colliding with another DM room on the same shared session, it posts a one-time `m.notice` suggesting `dm.sessionScope: "per-room"` to isolate the rooms. The notice only appears when thread bindings are enabled. ## ACP conversation bindings Matrix rooms, DMs, and existing Matrix threads can become durable ACP workspaces without changing the chat surface. Fast operator flow: - Run `/acp spawn codex --bind here` inside the Matrix DM, room, or existing thread to keep using. - In a top-level DM or room, the current DM/room stays the chat surface and future messages route to the spawned ACP session. - Inside an existing thread, `--bind here` binds that current thread in place. - `/new` and `/reset` reset the same bound ACP session in place. - `/acp close` closes the ACP session and removes the binding. `--bind here` does not create a child Matrix thread. `threadBindings.spawnSessions` gates `/acp spawn --thread auto|here`, where OpenClaw needs to create or bind a child thread. ### Thread binding config Matrix inherits global defaults from `session.threadBindings` and supports per-channel overrides: - `threadBindings.enabled` - `threadBindings.idleHours` - `threadBindings.maxAgeHours` - `threadBindings.spawnSessions`: gates both subagent and ACP thread spawns. - Deprecated `threadBindings.spawnSubagentSessions` / `threadBindings.spawnAcpSessions` keys are migrated to `spawnSessions` by `openclaw doctor --fix`. - `threadBindings.defaultSpawnContext` Matrix thread-bound session spawns default on. Set `threadBindings.spawnSessions: false` to block native subagent and ACP thread spawns from creating/binding Matrix threads. Set `threadBindings.defaultSpawnContext: "isolated"` when native subagent thread spawns should not fork the parent transcript. ## History context - `channels.matrix.historyLimit` controls how many recent room messages are included as `InboundHistory` when a room message triggers the agent. Falls back to `messages.groupChat.historyLimit`; effective default `0` if both are unset (disabled). - Matrix room history is room-only; DMs keep using normal session history. - Room history is pending-only: OpenClaw buffers room messages that did not trigger a reply yet, then snapshots that window when a mention or other trigger arrives. - The current trigger message is not included in `InboundHistory`; it stays in the main inbound body for that turn. - Retries of the same Matrix event reuse the original history snapshot instead of drifting forward to newer room messages.