openclaw - 💡(How to fix) Fix Feature: opt-in to bypass requireMention for in-thread replies when the bot has an active per-thread session binding [1 pull requests]

Summary

The most common Matrix bot UX — "mention the bot to open a thread, then have a free-form conversation inside that thread without re-mentioning every line" — is currently impossible on rooms configured with requireMention: true. Every in-thread reply that omits the mention is dropped as skipping room message: no-mention even when the thread is one the bot is actively engaged in (i.e. there is a runtime per-thread session binding from threadBindings).

threadBindings.enabled today provides session continuity for the agent (per-thread session keys, idleHours window, spawnSessions, etc.) but never feeds back into the mention gate at extensions/matrix/src/matrix/monitor/handler.ts ~line 1003. The result is awkward UX:

• User: @bot what's the family budget for groceries this month? → bot opens a thread, replies inside it
• User (in the thread): and how about last month? → silently dropped
• User: @bot and how about last month? → bot continues

For requireMention rooms specifically, this means the only way to have a thread conversation is to @bot every single message — the very mention enforcement that's appropriate at the top level becomes friction inside threads.

Reproduction

1. Configure a Matrix group room with requireMention: true:

   "channels.matrix.groups": {
     "!room:server": {
       "requireMention": true,
       "skills": ["actual-budget"]
     }
   }

2. Enable thread bindings + always-thread replies:

   "channels.matrix": {
     "threadReplies": "always",
     "threadBindings": { "enabled": true, "idleHours": 24, "spawnSessions": true, "defaultSpawnContext": "fork" }
   }

3. As a user, @openclaw what's our balance? → bot replies in a new thread.

4. Reply inside that thread without @openclaw → bot ignores the message.

   Bot's gateway log shows:

   skipping room message  { roomId: "!room:server", reason: "no-mention" }

5. Reply with @openclaw again → bot continues.

Root cause

In extensions/matrix/src/matrix/monitor/handler.ts:

const shouldRequireMention = isRoom
  ? roomConfig?.autoReply === true ? false
    : roomConfig?.autoReply === false ? true
      : typeof roomConfig?.requireMention === "boolean" ? roomConfig?.requireMention
        : true
  : false;
const shouldBypassMention =
  allowTextCommands &&
  isRoom &&
  shouldRequireMention &&
  !wasMentioned &&
  !hasExplicitMention &&
  commandAuthorized &&
  hasControlCommandInMessage;
if (isRoom && shouldRequireMention && !wasMentioned && !shouldBypassMention) {
  // skip
}

The shouldRequireMention calculation is purely per-room. The only existing bypass is for authorized control commands. There is no signal from thread state at all, even though by the time we get here resolveMatrixInboundRoute has already determined the per-thread session binding (_runtimeBindingId).

Existing test at extensions/matrix/src/matrix/monitor/handler.test.ts:1617 ("does not refresh bound Matrix thread bindings for room messages dropped before routing") explicitly pins the current contract — runtime thread bindings do NOT bypass mention. That makes the change opt-in or a behavior change.

Proposed change

Add channels.matrix.threadBindings.bypassMentionInBoundThreads: boolean (optional, default false). When set true, the inbound handler additionally bypasses requireMention when:

• threadRootId !== undefined && threadRootId !== messageId — the message is a reply INSIDE an existing thread (not a top-level message that would become a thread root under threadReplies: "always")
• _runtimeBindingId !== null — sessionBindingService.resolveByConversation already returned a binding for this thread (the bot has prior activity bound here, via threadBindings.enabled's per-thread session creation)

Off by default — preserves the line-1617 contract exactly for users who haven't opted in.

PR with implementation + two new handler tests (one for the bypass path, one pinning the off-by-default legacy behavior) incoming.

Why opt-in rather than always-on

ClawSweeper's review of #85018 made the case clearly for keeping routing-precedence changes deliberately user-opted. The existing contract — "mention enforcement applies regardless of thread binding state" — is reasonable for setups where the bot is just one participant among many and threads aren't necessarily the bot's domain. The opt-in flag lets operators who want bot-thread-conversation semantics (the family/team-room pattern from #85017) turn it on without changing behavior for everyone else.

Environment

• OpenClaw: 2026.5.19 (ghcr.io/openclaw/openclaw:latest)
• Matrix homeserver: Synapse via ghcr.io/junkerderprovinz/matrix:latest
• Reproduced today on a live Unraid deployment; user feedback chain leading into this report is in #85017's deployment thread.