matrix-js: require explicit thread-bound spawn config

docs/channels/matrix-js.md

@@ -242,7 +242,7 @@ Matrix-js supports native Matrix threads for both automatic replies and message-
 - Inbound threaded messages include the thread root message as extra agent context.
 - Message-tool sends now auto-inherit the current Matrix thread when the target is the same room, or the same DM user target, unless an explicit `threadId` is provided.
 - Runtime thread bindings are supported for Matrix-js. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, and thread-bound `/acp spawn` now work in Matrix rooms and DMs.
-- Top-level Matrix room/DM `/focus` creates a new Matrix thread and binds it to the target session.
+- Top-level Matrix room/DM `/focus` creates a new Matrix thread and binds it to the target session when `threadBindings.spawnSubagentSessions=true`.
 - Running `/focus` or `/acp spawn --thread here` inside an existing Matrix thread binds that current thread instead.
 
 ### Thread Binding Config
@@ -255,7 +255,10 @@ Matrix-js inherits global defaults from `session.threadBindings`, and also suppo
 - `threadBindings.spawnSubagentSessions`
 - `threadBindings.spawnAcpSessions`
 
-For Matrix-js, spawn flags default to enabled unless you turn them off explicitly.
+Matrix-js thread-bound spawn flags are opt-in:
+
+- Set `threadBindings.spawnSubagentSessions: true` to allow top-level `/focus` to create and bind new Matrix threads.
+- Set `threadBindings.spawnAcpSessions: true` to allow `/acp spawn --thread auto|here` to bind ACP sessions to Matrix threads.
 
 ## Reactions
 

docs/gateway/configuration-reference.md

@@ -651,6 +651,7 @@ Run multiple accounts per channel (each with its own `accountId`):
 ### Other extension channels
 
 Many extension channels are configured as `channels.<id>` and documented in their dedicated channel pages (for example Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, and Twitch).
+Matrix-js also supports top-level `bindings[]` entries with `type: "acp"` for persistent ACP bindings. Use the Matrix room id or Matrix thread root event id in `match.peer.id`.
 See the full channel index: [Channels](/channels).
 
 ### Group chat mention gating
@@ -1358,7 +1359,7 @@ Run multiple isolated agents inside one Gateway. See [Multi-Agent](/concepts/mul
 
 Within each tier, the first matching `bindings` entry wins.
 
-For `type: "acp"` entries, OpenClaw resolves by exact conversation identity (`match.channel` + account + `match.peer.id`) and does not use the route binding tier order above.
+For `type: "acp"` entries, OpenClaw resolves by exact conversation identity (`match.channel` + account + `match.peer.id`) and does not use the route binding tier order above. For example, use a Discord channel/thread id, a Matrix room id or thread root event id, or a Telegram canonical topic id.
 
 ### Per-agent access profiles
 

docs/tools/acp-agents.md

@@ -79,6 +79,7 @@ Required feature flags for thread-bound ACP:
 - `acp.dispatch.enabled` is on by default (set `false` to pause ACP dispatch)
 - Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
   - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
+  - Matrix-js: `channels["matrix-js"].threadBindings.spawnAcpSessions=true`
   - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
 
 ### Thread supporting channels
@@ -86,6 +87,7 @@ Required feature flags for thread-bound ACP:
 - Any channel adapter that exposes session/thread binding capability.
 - Current built-in support:
   - Discord threads/channels
+  - Matrix-js room threads and DMs
   - Telegram topics (forum topics in groups/supergroups and DM topics)
 - Plugin channels can add support through the same binding interface.
 
@@ -98,6 +100,7 @@ For non-ephemeral workflows, configure persistent ACP bindings in top-level `bin
 - `bindings[].type="acp"` marks a persistent ACP conversation binding.
 - `bindings[].match` identifies the target conversation:
   - Discord channel or thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
+  - Matrix room or thread: `match.channel="matrix-js"` + `match.peer.id="<roomIdOrThreadRootEventId>"`
   - Telegram forum topic: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
 - `bindings[].agentId` is the owning OpenClaw agent id.
 - Optional ACP overrides live under `bindings[].acp`:
@@ -375,6 +378,7 @@ Notes:
 - On non-thread binding surfaces, default behavior is effectively `off`.
 - Thread-bound spawn requires channel policy support:
   - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
+  - Matrix-js: `channels["matrix-js"].threadBindings.spawnAcpSessions=true`
   - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
 
 ## ACP controls
@@ -477,7 +481,7 @@ Core ACP baseline:
 }
 ```
 
-Thread binding config is channel-adapter specific. Example for Discord:
+Thread binding config is channel-adapter specific. Example for Discord and Matrix-js:
 
 ```json5
 {
@@ -495,6 +499,12 @@ Thread binding config is channel-adapter specific. Example for Discord:
         spawnAcpSessions: true,
       },
     },
+    "matrix-js": {
+      threadBindings: {
+        enabled: true,
+        spawnAcpSessions: true,
+      },
+    },
   },
 }
 ```
@@ -502,6 +512,7 @@ Thread binding config is channel-adapter specific. Example for Discord:
 If thread-bound ACP spawn does not work, verify the adapter feature flag first:
 
 - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
+- Matrix-js: `channels["matrix-js"].threadBindings.spawnAcpSessions=true`
 
 See [Configuration Reference](/gateway/configuration-reference).
 

docs/tools/subagents.md

@@ -99,7 +99,11 @@ When thread bindings are enabled for a channel, a sub-agent can stay bound to a
 
 ### Thread supporting channels
 
-- Discord (currently the only supported channel): supports persistent thread-bound subagent sessions (`sessions_spawn` with `thread: true`), manual thread controls (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`), and adapter keys `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`, and `channels.discord.threadBindings.spawnSubagentSessions`.
+- `sessions_spawn` with `thread: true`: currently supported on Discord only.
+- Manual thread/conversation controls:
+  - Discord: `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`
+  - Matrix-js: `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`
+  - Telegram: `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`
 
 Quick flow: