fix(matrix): multi-account identity routing, voice message support, and security hardening

Context

Matrix is the only open-protocol, self-hostable channel in OpenClaw. For deployments operating on local infrastructure — home labs, air-gapped networks, VPN meshes, or multi-agent architectures where each agent requires a distinct identity — Matrix with a self-hosted homeserver is the canonical choice. No vendor lock-in, no cloud dependency, no recurring API costs.

OpenClaw's Matrix plugin supports multi-account configuration via channels.matrix.accounts, enabling multiple bot identities on a single homeserver. However, during comprehensive testing of a production multi-account deployment, we identified that several code paths fail to propagate per-account context correctly. Additionally, voice message support (MSC3245) is fully implemented in the send layer but unreachable from every upstream caller. This PR resolves those routing deficiencies and introduces security hardening measures identified through a systematic audit of the Matrix plugin source.

Changes

Bug Fixes

1. Add missing keyed-async-queue build entry to tsdown.config.ts

package.json declares the subpath export ./plugin-sdk/keyed-async-queue mapping to dist/plugin-sdk/keyed-async-queue.js, and extensions/matrix/src/matrix/send-queue.ts imports from this path at runtime. However, tsdown.config.ts contains no corresponding entry for src/plugin-sdk/keyed-async-queue.ts, so the build pipeline never emits the output artifact. This produces a deterministic runtime import failure when the Matrix plugin initializes its send queue.

The fix adds an entry block following the identical pattern established by the existing account-id.ts entry. The source file and its vitest test alias both already exist upstream.

Files: tsdown.config.ts

2. Resolve agentId for buildMentionRegexes in Matrix monitor initialization

In extensions/matrix/src/matrix/monitor/index.ts, the monitor startup invokes buildMentionRegexes(cfg) without supplying an agentId argument. Consequently, per-agent mentionPatterns — configured via agents.list[].groupChat.mentionPatterns — are never resolved: the function cannot determine which agent's pattern set to compile into the regex cache.

The Discord monitor handler correctly resolves the bound agent ID from channel bindings before constructing mention regexes. The Matrix monitor omits this resolution step entirely.

The fix resolves boundAgentId by performing a binding lookup against the current account's monitored rooms, then passes the result to buildMentionRegexes(cfg, boundAgentId). This enables plain-text mention detection (e.g., @agent-name) in shared multi-agent rooms configured with requireMention: true.

Files: extensions/matrix/src/matrix/monitor/index.ts

3. Propagate accountId through the complete tool action dispatch chain

When an agent invokes the message tool to perform channel actions (react, edit, delete, send, pin, read, etc.), the execution path traverses actions.ts → handleMatrixAction() in tool-actions.ts → individual action functions. The ChannelMessageActionContext provided by the core runtime includes accountId, but actions.ts never destructures this field and handleMatrixAction never accepts it as a parameter.

The consequence: all tool-initiated actions resolve to resolveActionClient() with undefined accountId, which deterministically selects the primary (default) account. In a multi-account deployment, this means every agent's tool actions — reactions, edits, deletions, message sends — execute under the default bot identity regardless of the originating agent.

The fix comprises three coordinated changes:

• actions.ts: Destructures accountId from the action context and forwards it to all nine handleMatrixAction invocations
• tool-actions.ts: Accepts accountId as an optional third parameter and propagates it to every downstream action function
• matrix/send.ts: Extends reactMatrixMessage to accept an options object containing { client?, accountId? } alongside the existing MatrixClient parameter. Backward compatibility is preserved via runtime type detection ("doRequest" in clientOrOpts)

Note: Typing indicators, read receipts, and outbound reply delivery are unaffected by this deficiency — the monitor handler passes the per-account client instance directly for those operations, bypassing the action dispatch chain entirely.

Files: extensions/matrix/src/actions.ts, extensions/matrix/src/tool-actions.ts, extensions/matrix/src/matrix/send.ts

4. Forward audioAsVoice and accountId through the sendMatrixMessage wrapper

The Matrix plugin implements full MSC3245 voice message support in its send layer: sendMessageMatrix() in matrix/send.ts accepts audioAsVoice, resolves voice compatibility via resolveMatrixVoiceDecision(), and emits the required org.matrix.msc3245.voice and org.matrix.msc1767.audio event content fields. However, this capability is unreachable from any upstream caller due to three independent gaps in the call chain:

1. actions/messages.ts — The sendMatrixMessage convenience wrapper explicitly enumerates which options to forward to sendMessageMatrix. The allowlist includes mediaUrl, replyToId, threadId, client, and timeoutMs — but omits both audioAsVoice and accountId. Any caller passing these fields has them silently discarded.

2. actions.ts — The send action handler reads the media parameter but does not check the alternative parameter names (mediaUrl, filePath, path) that agents may use depending on their tool call conventions. It also does not read asVoice or audioAsVoice from the incoming params.

3. tool-actions.ts — The sendMessage case does not read or forward audioAsVoice from the action params object.

The fix addresses all three layers:

• actions/messages.ts: Extends the opts type to include audioAsVoice?: boolean and accountId?: string, and forwards both to sendMessageMatrix
• actions.ts: Reads asVoice/audioAsVoice from params, resolves media from media ∥ mediaUrl ∥ filePath ∥ path (matching the convention used by Telegram and Discord handlers), and passes audioAsVoice to handleMatrixAction
• tool-actions.ts: Reads audioAsVoice from the action params and forwards it to sendMatrixMessage

Verified end-to-end: voice messages sent via the message tool now arrive with correct MSC3245 metadata across OGG/Opus and MP3 formats.

Files: extensions/matrix/src/matrix/actions/messages.ts, extensions/matrix/src/actions.ts, extensions/matrix/src/tool-actions.ts

Security Hardening

5. Apply SSRF-guarded fetch to directory API calls

directory-live.ts issues HTTP requests to the configured homeserver URL using the unguarded fetch() API. The authentication flow in client/config.ts correctly employs fetchWithSsrFGuard from the plugin SDK, but the directory search and room listing endpoints do not.

If an attacker can influence the homeserver configuration value — or if a misconfigured deployment points at an internal service URL (e.g., a cloud instance metadata endpoint) — the bot will transmit authenticated HTTP requests bearing the Matrix access token to that endpoint.

The fix replaces fetch() with fetchWithSsrFGuard in fetchMatrixJson(), consistent with the pattern established in the login flow, specifying auditContext: "matrix.directory" for traceability.

Files: extensions/matrix/src/directory-live.ts

6. Restrict file permissions on credentials and storage metadata

credentials.ts and client/storage.ts persist sensitive files (credentials.json, storage-meta.json) using fs.writeFileSync without specifying an explicit file mode. This inherits the process umask (typically 0o022), yielding 0o644 permissions — world-readable on standard Linux configurations.

These files contain homeserver URLs, user IDs, and access token hashes. While not full-entropy tokens, they reveal which credentials are active and can facilitate targeted credential-stuffing or session hijacking attacks when combined with other information disclosure vectors.

The fix enforces restrictive permissions:

• fs.mkdirSync calls specify mode: 0o700 (owner-only directory traversal)
• fs.writeFileSync calls specify mode: 0o600 (owner-only read/write)
• Applied to saveMatrixCredentials, touchMatrixCredentials in credentials.ts
• Applied to writeStorageMeta and the legacy migration path in storage.ts

Files: extensions/matrix/src/matrix/credentials.ts, extensions/matrix/src/matrix/client/storage.ts

7. Change default autoJoin policy from "always" to "allowlist"

In auto-join.ts, the fallback behavior when autoJoin is omitted from the configuration defaults to "always", which registers the SDK's AutojoinRoomsMixin — causing the bot to unconditionally accept every room invitation.

For isolated local deployments where the homeserver exists on a trusted network segment, this may be acceptable. However, for any deployment where the bot's Matrix user ID is discoverable (federated homeservers, public directories, leaked room invitations), an adversary can create a room, invite the bot, and — if groupPolicy is also at its default value of "open" — interact directly with the agent.

The fix changes the default to "allowlist". Existing deployments that explicitly configure autoJoin: "always" are entirely unaffected — the new default only governs installations where the field is absent from the configuration.

Files: extensions/matrix/src/matrix/monitor/auto-join.ts

8. Sanitize login error responses in exception messages

In client/config.ts, when a Matrix login request returns a non-success HTTP status, the raw response body is interpolated directly into the thrown Error:

const errorText = await loginResponse.text();
throw new Error(`Matrix login failed: ${errorText}`);

Depending on the homeserver implementation (Synapse, Conduit, Dendrite), this response body may contain internal diagnostic messages, partial stack traces, rate-limit metadata, or session identifiers. These error messages propagate through the exception chain and are typically persisted in application logs.

The fix replaces the raw error body with a deterministic status-based message: "invalid credentials" for HTTP 403, "rate limited" for HTTP 429, or "HTTP {statusCode}" for all other failure modes.

Files: extensions/matrix/src/matrix/client/config.ts

9. Add TTL and size bounds to the room info cache

room-info.ts employs an unbounded Map as an in-memory cache for room name and alias lookups. Entries are inserted but never evicted. On long-running gateway processes with exposure to many rooms (multi-account deployments, rooms with frequent renames, or federated environments), this cache exhibits two pathological behaviors:

1. Unbounded memory growth — The cache grows monotonically with the number of unique room IDs encountered over the process lifetime.
2. Stale data persistence — Room renames, alias changes, and permission updates are never reflected until the gateway process is restarted.

The fix introduces:

• A 5-minute TTL (ROOM_INFO_CACHE_TTL_MS = 300_000) with staleness checks on read
• A maximum cache capacity of 500 entries with FIFO eviction on write
• A CachedRoomInfo type wrapping entries with a cachedAt timestamp

Files: extensions/matrix/src/matrix/monitor/room-info.ts

Summary of Changed Files

Related Issues

• Closes Matrix multi-account: tool-action message may send from wrong account #26457 — Matrix multi-account: tool-action dispatches under wrong identity (Fix 3)
• Closes [Bug] Matrix plugin fails to load in v2026.3.2: missing keyed-async-queue.js in plugin-sdk exports #32772 — Matrix plugin fails to load: missing keyed-async-queue artifact (Fix 1)
• Closes Matrix plugin fails to load after upgrade to 2026.3.2: missing 'keyed-async-queue' in plugin-sdk dist #33105 — Matrix plugin fails to load after upgrade to 2026.3.2 (Fix 1)
• Closes [Bug]: Matrix message tool ignores audioAsVoice parameter #32489 — Voice messages via Matrix lack MSC3245 metadata (Fix 4)
• Fixes [Bug]: matrix media routing #25854 — Matrix media routing uses wrong account identity (Fix 3, same root cause as Matrix multi-account: tool-action message may send from wrong account #26457)
• Related to Feature request: Multi-account Matrix support #12040 — Feature request: multi-account Matrix support (Fixes 2–4 make it work correctly)
• Alternative to Matrix: resolve mention patterns per routed agent #33028 — Mention patterns per routed agent (different approach — Fix 2 resolves at monitor startup per-account rather than per-message in handler)
• Alternative to Matrix: fix KeyedAsyncQueue import #32826 — KeyedAsyncQueue import path workaround (Fix 1 addresses the root cause in build config rather than patching the import path)

Testing

All fixes were verified on a live multi-account deployment with a self-hosted homeserver, multiple bot identities, and shared rooms using mention-based routing.