Summary

When requireMention: true is set for a Matrix group room, messages containing valid m.mentions metadata are not detected as mentions, causing all agents to ignore the message. This effectively makes requireMention: true unusable for rooms where messages may come from non-OpenClaw Matrix clients or bots.

Environment

• OpenClaw: 2026.4.9
• Matrix homeserver: Synapse (Docker, localhost)
• Node: 25.9.0

Steps to Reproduce

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

"groups": {
  "!roomId:localhost": {
    "requireMention": true,
    "enabled": true
  }
}

2. From a non-OpenClaw Matrix client (e.g., Element, or a standalone bot using matrix-bot-sdk), send a message to the room with proper m.mentions:

{
  "msgtype": "m.text",
  "body": "@欢欢 please reply",
  "format": "org.matrix.custom.html",
  "formatted_body": "<a href=\"https://matrix.to/#/@huanhuan:localhost\">@欢欢</a> please reply",
  "m.mentions": {
    "user_ids": ["@huanhuan:localhost"]
  }
}

3. Observe: no agent responds. The mentioned agent (@huanhuan:localhost) does not get triggered.

4. Set requireMention: false → the same message triggers all agents (including unmentioned ones).

Expected Behavior

With requireMention: true, the agent whose userId appears in m.mentions.user_ids AND whose name/userId appears in the formatted_body matrix.to link should be triggered. Other agents should remain silent.

Actual Behavior

No agent is triggered. The message is silently dropped for all agents.

Analysis

Looking at extensions/matrix/src/matrix/monitor/mentions.ts, resolveMentions() checks:

1. m.mentions.user_ids contains the agent's userId AND formatted_body or text contains a matching pattern (line 166-170)
2. formatted_body has a matrix.to link for the agent (line 158-165)
3. Text matches mentionRegexes (line 150-153)

The message I sent satisfies conditions 1 and 2. Possible causes:

• The sender (@eventbridge:localhost) is in groupAllowFrom but is not an OpenClaw-managed account — perhaps inbound message processing skips mention resolution for certain senders
• The mentionRegexes auto-generated from identity.name may not match CJK display names correctly
• There may be an earlier filter that drops the message before resolveMentions() is called

Impact

requireMention: true is the only way to prevent agents from responding to every message in a group chat. Without it, multi-agent rooms suffer from:

• Agents responding to messages not directed at them ("插嘴" / interrupting)
• Unnecessary API calls and token consumption
• Potential cascading loops when error messages trigger all agents

Currently the only workaround is requireMention: false + adding "only respond to messages addressed to you" in each agent's SOUL.md, which is unreliable (LLM-based filtering).

Related

• PR fix(matrix): emit spec-compliant mentions #59323 (fix: emit spec-compliant mentions) — fixed the outbound side, but the inbound mention detection appears broken
• PR feat(plugin): rate-limit-circuit-breaker to prevent death loops in group chats #64031 (rate-limit-circuit-breaker) — a workaround for cascading loops caused by requireMention: false

🤖 Generated with Claude Code