Skip to content

[Bug]: Matrix plugin ignores agent-level mentionPatterns (buildMentionRegexes called without agentId) #51082

@vkrmch

Description

@vkrmch

Bug Description

The Matrix plugin's monitor builds mention regexes without passing the agentId, causing agent-level mentionPatterns (configured under agents.list[].groupChat.mentionPatterns) to be silently ignored. This means requireMention: true in rooms will skip all messages even when they contain valid mention patterns defined at the agent level.

Steps to Reproduce

  1. Configure an agent with mention patterns at the agent level:
{
  "agents": {
    "list": [{
      "id": "main",
      "name": "mybot",
      "groupChat": {
        "mentionPatterns": ["@mybot:example.org", "@mybot", "mybot"]
      }
    }]
  }
}
  1. Configure a Matrix room with requireMention: true:
{
  "channels": {
    "matrix": {
      "groups": {
        "*": {
          "requireMention": true,
          "mentionPatterns": ["@mybot:example.org", "@mybot", "mybot"]
        }
      }
    }
  }
}
  1. Send a message containing "mybot" or "@Mybot:example.org" in the room.
  2. The bot logs skipping room message with reason no-mention and never responds.

Root Cause

In extensions/matrix/src/matrix/monitor/index.ts line 298:

const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg);

No agentId is passed. The core function resolveMentionPatterns(cfg, undefined) then:

  1. Skips agents.list[].groupChat.mentionPatterns (requires agentId to resolve)
  2. Falls through to messages.groupChat.mentionPatterns (typically not set)
  3. Returns empty array → no regexes compiled → nothing matches → all room messages skipped

The channel-level groups.*.mentionPatterns are used for requireMention gating decisions but are not fed into the core regex builder — they appear to be separate config that doesn't participate in the actual text matching.

Expected Behavior

Agent-level mentionPatterns should be resolved and used for mention matching in Matrix rooms, consistent with how other channel plugins handle this.

Workaround

Add mention patterns at the global messages.groupChat level, which resolveMentionPatterns checks as its second fallback (no agentId needed):

openclaw config set messages.groupChat.mentionPatterns '["@mybot:example.org","@mybot","mybot"]'
openclaw gateway restart

Environment

  • OpenClaw version: 2026.3.13
  • Matrix plugin version: 2026.3.13 (stock/bundled)
  • OS: Debian 13 (x64)
  • Node: v24.14.0
  • Homeserver: Tuwunel (Conduit fork), though this is client-side logic and homeserver-independent

Debug Logs

With logging.level: "debug", the message evaluation flow shows the room passes all policy checks but fails silently at mention matching:

matrix: room.message recv room=!xxx:server type=m.room.message id=$eventid
matrix: dm check room=!xxx:server result=group members=3
matrix: allow room !xxx:server (matchKey=* matchSource=wildcard)
skipping room message   ← immediate skip, no mention evaluation logged

No debug line appears between "allow room" and "skipping room message" showing the mention regex evaluation — because the regex array is empty, the check is trivially false.

Suggested Fix

Pass the resolved agent ID to buildMentionRegexes in the Matrix monitor:

// extensions/matrix/src/matrix/monitor/index.ts ~line 298
// Before:
const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg);

// After:
const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, resolvedAgentId);

The agent ID is available from the routing/binding resolution that happens in the same initialization context.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions