Matrix Mentions Patch

Use when a user reports Matrix @mentions not working, notifications not triggering, asks to fix/update the mentions patch, or asks to install/apply the patch...

Security Scan

The skill's code matches its stated purpose (patching OpenClaw's Matrix handling of @mentions), but the patch is brittle, has small inconsistencies and a bug that could break the gateway — review and test before applying.

Purpose & Capability

Name/description align with the included script: it locates OpenClaw's distributed JS and injects mention-handling logic. There are no unrelated credentials, network calls, or external endpoints requested. Minor inconsistency: SKILL.md's 'Patch Status Check' greps a TypeScript source file under extensions/src (formatting.ts), while the script actually modifies compiled auth-profiles-*.js in OpenClaw's dist/ — this is plausible (source vs compiled) but could confuse users if their installation layout differs.

Instruction Scope

Instructions are narrow and explicit: run the included node script, restart the gateway, and verify. They correctly tell the user to only apply when requested. The script does modify files under global node_modules (OpenClaw's dist), which is within the stated purpose but is a system-level change that requires write privileges. The SKILL.md check path and the script target differ (source vs dist), which may cause users to believe the patch is present when it is not.

Install Mechanism

No external downloads or installers — the skill is instruction-only plus a local Node script. The script uses fs and child_process but only for local filesystem operations (ls, npm root -g, file copy/write). This is low-risk compared with remote downloads.

Credentials

The skill requests no environment variables, credentials, or external tokens. It does assume a Node runtime and access to global node_modules (may require elevated privileges), which is reasonable for a file-patching script.

Persistence & Privilege

The script makes persistent, system-wide edits to OpenClaw's distributed JS files and requires write permissions to node_modules (potentially root). This is expected for a patch, but it is privileged — a faulty patch could break the gateway; updates may overwrite it and re-applying is required. The skill does not run autonomously by default, but the persistent modification is significant and should be applied with caution.

What to consider before installing

What to consider before installing/applying: - The code does what it claims (adds mention extraction and attaches m.mentions) and does not phone home or require secrets, but it modifies core OpenClaw files in your global node_modules — you need write permissions and this change is persistent. - The patch is brittle and implementation has issues: the injected formatting function references escapeRegex (used in the replacement) but the script does not insert an escapeRegex definition into the patched file, which will likely cause runtime errors in the patched code. Also the script matches specific compiled strings; if your OpenClaw build differs the patch may fail or do nothing. - Recommended steps: (1) Inspect the script yourself; (2) Back up the target file (the script already creates a .bak, but keep an external copy); (3) Test on a staging instance first; (4) If you proceed, confirm Node global path and permissions (the script assumes certain paths and uses npm root -g fallback); (5) Consider patching the script to also insert a safe escapeRegex implementation into the target file or adjust the patching logic to match your build. - If you are unsure, ask the maintainer for an upstream fix or a proper plugin update instead of in-place patching.

Patches OpenClaw's Matrix plugin to attach m.mentions to outbound messages so clients like Element properly notify mentioned users.

When to Use

• User reports @mentions not triggering notifications
• User asks to "fix Matrix mentions" or "update the mentions patch"
• User asks to "install" or "apply" the mentions patch

Only apply when requested. Do not auto-apply.

Patch Status Check

Before applying, check if already patched:

grep -l "extractMentionsFromText" ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/extensions/matrix/src/matrix/send/formatting.ts

• Already patched: Output will show the file. No action needed — just use correct @mention format.
• Not patched: No output. Proceed to apply the patch.

How to Apply (First-time Setup)

Step 1: Run the patch script

node ~/.openclaw/workspace/skills/matrix-mentions-patch/patch-matrix-mentions.mjs

The script will:

1. Locate auth-profiles-*.js in OpenClaw's dist/
2. Create a .bak backup automatically
3. Patch in-place

Step 2: Restart the gateway

openclaw gateway restart

Step 3: Verify

Send a message with a full Matrix ID mention:

@username:matrix.biochao.cc

The mentioned user should see a notification.

Routine Use (After Patched)

Once patched, no further action needed. Just ensure correct @mention format:

正确格式：

@username:matrix.biochao.cc

错误格式：

• Markdown link: [](https://matrix.to/#/@user)
• HTML span: <span>@user</span>
• 任何包装格式

直接发送纯文本 Matrix ID，客户端即可正确识别并通知。

Re-applying After Updates

Every openclaw update may overwrite the patch. Re-apply by running:

node ~/.openclaw/workspace/skills/matrix-mentions-patch/patch-matrix-mentions.mjs
openclaw gateway restart

Undoing the Patch

Restore from backup:

cp ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/auth-profiles-*.js.bak \
 ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/auth-profiles-*.js
openclaw gateway restart

Target File

~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/auth-profiles-*.js

Requirements

• OpenClaw core
• Matrix plugin configured and working
• Node.js runtime