openclaw - 💡(How to fix) Fix [Bug]: Matrix outbound mention rendering — agent auto-reply ships @<name> without matrix.to pill or m.mentions when target is a sibling account [1 comments, 2 participants]

Summary

When an OpenClaw agent's auto-reply mentions a sibling agent's Matrix account by name (e.g. `@alice` where `alice` is another configured `channels.matrix.accounts.<id>`), the outgoing message body contains the textual `@alice` but no `matrix.to` pill in `formatted_body` and no `m.mentions.user_ids` entry. The recipient bot's mention-gated dispatch (`allowBots: "mentions"`, `requireMention: true`) therefore never fires, and Element clients show the @-text as plain text without the avatar/pill.

The runtime clearly has full outbound rendering machinery (`resolveMatrixMentionsForBody`, `createMentionLinkTokens`, `m.mentions` builder visible in `dist/send-C-KjCmRI.js`) — but it's invoked via `deriveMentionPatterns(identity)` from `dist/mentions-BjQQPi4h.js`, which builds regexes from the sending agent's own `identity.name` only. There's no teamwide / sibling roster fed in, so cross-agent mentions in the agent's output never match and never get rendered.

Repro

OpenClaw `2026.5.6`. Two Matrix accounts on the same gateway, both `enabled: true` in `channels.matrix.accounts`, both joined to room R.

1. Account A's agent generates an auto-reply containing `@b — confirmed.`
2. Captured outgoing event in room R:

```json { "msgtype": "m.text", "body": "@b — confirmed. ...", "format": "org.matrix.custom.html", "formatted_body": "<p>@b — confirmed. ...</p>", "m.mentions": {} } ```

1. Expected: `formatted_body` contains `<a href="https://matrix.to/#/@b:server\">@b</a>` and `m.mentions.user_ids` contains `@b:server`.

Compared to a hand-built reply from a standalone Python daemon (using the same access token) that constructs all three fields explicitly: the daemon's messages fire pings + render the pill correctly. So the homeserver and the recipient bot's dispatch logic are fine — the gap is in the sending agent's outbound formatting.

What's documented vs what's missing

`docs/channels/matrix.md` documents `allowBots`, `groups.<room>.requireMention`, per-account fields (`reactionNotifications`, `contextVisibility`, `streaming`, etc.), but no teamwide mention roster under `channels.matrix.mentions` or similar. Searched the dist source and the docs; no documented opt-in for cross-agent mention rendering.

Suggested fix

Two reasonable paths:

1. Auto-derive a teamwide roster from `channels.matrix.accounts` keys (each account's `userId` + `name`) and feed it into the outbound markdown → mention resolver alongside the sending agent's own identity. Zero new config surface; "if you've configured these accounts on the same gateway, they're a team."

2. Documented `channels.matrix.mentions.roster` config for explicit @-key → MXID mapping, opt-in. More flexible (lets you alias `@b` to a non-OpenClaw account) but adds config surface.

Option 1 covers the multi-agent same-gateway case, which I'd guess is the common one.

Related

• #52146 "Inject sibling agent list into session system prompt" — same underlying gap (no teamwide roster), but for prompt context, not Matrix outbound rendering. Both could share an underlying `teamRoster` accessor.
• #45766 (closed) was about the Matrix Message Tool path; this issue is about the agent auto-reply path, which appears to still ship without mention metadata.
• #45184 (open) is about inbound dispatch-skip when a mention targets a sibling; this issue is about the outbound rendering that makes such mentions detectable in the first place.

Workaround (local)

Edit-shim daemon watches the room and post-processes outgoing events from configured agent accounts: when text-form `@<name>` is present but `m.mentions` is empty, it sends an `m.replace` edit (using the original sender's access token) with proper `matrix.to` pill in `formatted_body` and populated `m.mentions.user_ids`. Works end-to-end on Synapse but leaves an "(edited)" marker on every retrofit, which is ugly. Happy to share the pattern if it helps inform a runtime fix.

Versions

• openclaw `2026.5.6` (installed via npm)
• Latest stable on npm at filing time: `2026.5.7`
• Synapse homeserver (Tuwunel build), local