openclaw - 💡(How to fix) Fix Matrix: valid m.mentions.user_ids mention can be skipped when visible label is @[Display Name] [2 pull requests]

Summary

The Matrix channel plugin (@openclaw/matrix) can skip a room message as no-mention even when the event contains a valid Matrix m.mentions.user_ids entry for the bot user.

This appears to happen when the message comes from a client that renders the visible HTML label as @[Display Name] instead of Display Name. The event still includes the correct Matrix mention metadata.

Why this looks like a Matrix mention parsing issue

Matrix v1.7+ defines content["m.mentions"].user_ids as the protocol-level user mention signal.

The installed @openclaw/[email protected] logic appears to require both:

• content["m.mentions"].user_ids contains the bot MXID
• and the visible body / formatted HTML label is recognized as a mention

The relevant bundled logic is equivalent to:

const mentionedUsers = Array.isArray(mentions?.user_ids) ? new Set(mentions.user_ids) : new Set();
const mentionedInFormattedBody = checkFormattedBodyMention(...);
const metadataBackedUserMention = Boolean(
  userId &&
  mentionedUsers.has(userId) &&
  (mentionedInFormattedBody || textMentioned)
);

This can reject a protocol-valid Matrix mention if the visible label uses a client-specific mention syntax.

Sanitized reproduction data

Client A, accepted:

{
  "content": {
    "body": "[Display Name](https://matrix.to/#/@bot:example.org) hello",
    "formatted_body": "<a href=\"https://matrix.to/#/@bot:example.org\">Display Name</a> hello",
    "m.mentions": {
      "user_ids": ["@bot:example.org"]
    },
    "msgtype": "m.text",
    "format": "org.matrix.custom.html"
  },
  "sender": "@sender:example.org",
  "type": "m.room.message"
}

Client B, skipped as no-mention:

{
  "content": {
    "body": "@[Display Name] hello",
    "formatted_body": "<a href=\"https://matrix.to/#/@bot:example.org\">@[Display Name]</a> hello",
    "m.mentions": {
      "user_ids": ["@bot:example.org"]
    },
    "msgtype": "m.text",
    "format": "org.matrix.custom.html"
  },
  "sender": "@sender:example.org",
  "type": "m.room.message"
}

Both events mention the same user via m.mentions.user_ids.

Expected behavior

OpenClaw should treat a Matrix room message as mentioning the bot when content["m.mentions"].user_ids contains the bot MXID.

If OpenClaw intentionally wants a visible-label safety check, it should accept @[Display Name] as visible mention text because this form is emitted by some Matrix clients / SDKs.

Suggested fix

Minimal compatibility fix: extend the visible label candidates to include:

displayName ? `@[${displayName}]` : null

More spec-aligned fix: let m.mentions.user_ids be sufficient for Matrix mention gating, and reserve visible-label heuristics for events that lack m.mentions.

Environment

• OpenClaw: 2026.5.12
• Matrix plugin: @openclaw/[email protected]