@openclaw/matrix 2026.1.29 → 2026.2.2

package/src/matrix/monitor/index.ts

@@ -1,11 +1,8 @@
 import { format } from "node:util";
-
-import {
-  mergeAllowlist,
-  summarizeMapping,
-  type RuntimeEnv,
-} from "openclaw/plugin-sdk";
+import { mergeAllowlist, summarizeMapping, type RuntimeEnv } from "openclaw/plugin-sdk";
 import type { CoreConfig, ReplyToMode } from "../../types.js";
+import { resolveMatrixTargets } from "../../resolve-targets.js";
+import { getMatrixRuntime } from "../../runtime.js";
 import { setActiveMatrixClient } from "../active-client.js";
 import {
   isBunRuntime,
@@ -13,13 +10,12 @@ import {
   resolveSharedMatrixClient,
   stopSharedClient,
 } from "../client.js";
+import { normalizeMatrixUserId } from "./allowlist.js";
 import { registerMatrixAutoJoin } from "./auto-join.js";
 import { createDirectRoomTracker } from "./direct.js";
 import { registerMatrixMonitorEvents } from "./events.js";
 import { createMatrixRoomMessageHandler } from "./handler.js";
 import { createMatrixRoomInfoResolver } from "./room-info.js";
-import { resolveMatrixTargets } from "../../resolve-targets.js";
-import { getMatrixRuntime } from "../../runtime.js";
 
 export type MonitorMatrixOpts = {
   runtime?: RuntimeEnv;
@@ -38,7 +34,9 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   }
   const core = getMatrixRuntime();
   let cfg = core.config.loadConfig() as CoreConfig;
-  if (cfg.channels?.matrix?.enabled === false) return;
+  if (cfg.channels?.matrix?.enabled === false) {
+    return;
+  }
 
   const logger = core.logging.getChildLogger({ module: "matrix-auto-reply" });
   const formatRuntimeMessage = (...args: Parameters<RuntimeEnv["log"]>) => format(...args);
@@ -54,75 +52,111 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
     },
   };
   const logVerboseMessage = (message: string) => {
-    if (!core.logging.shouldLogVerbose()) return;
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
     logger.debug(message);
   };
 
   const normalizeUserEntry = (raw: string) =>
-    raw.replace(/^matrix:/i, "").replace(/^user:/i, "").trim();
+    raw
+      .replace(/^matrix:/i, "")
+      .replace(/^user:/i, "")
+      .trim();
   const normalizeRoomEntry = (raw: string) =>
-    raw.replace(/^matrix:/i, "").replace(/^(room|channel):/i, "").trim();
+    raw
+      .replace(/^matrix:/i, "")
+      .replace(/^(room|channel):/i, "")
+      .trim();
   const isMatrixUserId = (value: string) => value.startsWith("@") && value.includes(":");
-
-  const allowlistOnly = cfg.channels?.matrix?.allowlistOnly === true;
-  let allowFrom = cfg.channels?.matrix?.dm?.allowFrom ?? [];
-  let roomsConfig = cfg.channels?.matrix?.groups ?? cfg.channels?.matrix?.rooms;
-
-  if (allowFrom.length > 0) {
-    const entries = allowFrom
+  const resolveUserAllowlist = async (
+    label: string,
+    list?: Array<string | number>,
+  ): Promise<string[]> => {
+    let allowList = list ?? [];
+    if (allowList.length === 0) {
+      return allowList;
+    }
+    const entries = allowList
       .map((entry) => normalizeUserEntry(String(entry)))
       .filter((entry) => entry && entry !== "*");
-    if (entries.length > 0) {
-      const mapping: string[] = [];
-      const unresolved: string[] = [];
-      const additions: string[] = [];
-      const pending: string[] = [];
-      for (const entry of entries) {
-        if (isMatrixUserId(entry)) {
-          additions.push(entry);
-          continue;
-        }
-        pending.push(entry);
+    if (entries.length === 0) {
+      return allowList;
+    }
+    const mapping: string[] = [];
+    const unresolved: string[] = [];
+    const additions: string[] = [];
+    const pending: string[] = [];
+    for (const entry of entries) {
+      if (isMatrixUserId(entry)) {
+        additions.push(normalizeMatrixUserId(entry));
+        continue;
       }
-      if (pending.length > 0) {
-        const resolved = await resolveMatrixTargets({
-          cfg,
-          inputs: pending,
-          kind: "user",
-          runtime,
-        });
-        for (const entry of resolved) {
-          if (entry.resolved && entry.id) {
-            additions.push(entry.id);
-            mapping.push(`${entry.input}→${entry.id}`);
-          } else {
-            unresolved.push(entry.input);
-          }
+      pending.push(entry);
+    }
+    if (pending.length > 0) {
+      const resolved = await resolveMatrixTargets({
+        cfg,
+        inputs: pending,
+        kind: "user",
+        runtime,
+      });
+      for (const entry of resolved) {
+        if (entry.resolved && entry.id) {
+          const normalizedId = normalizeMatrixUserId(entry.id);
+          additions.push(normalizedId);
+          mapping.push(`${entry.input}→${normalizedId}`);
+        } else {
+          unresolved.push(entry.input);
         }
       }
-      allowFrom = mergeAllowlist({ existing: allowFrom, additions });
-      summarizeMapping("matrix users", mapping, unresolved, runtime);
     }
-  }
+    allowList = mergeAllowlist({ existing: allowList, additions });
+    summarizeMapping(label, mapping, unresolved, runtime);
+    if (unresolved.length > 0) {
+      runtime.log?.(
+        `${label} entries must be full Matrix IDs (example: @user:server). Unresolved entries are ignored.`,
+      );
+    }
+    return allowList;
+  };
+
+  const allowlistOnly = cfg.channels?.matrix?.allowlistOnly === true;
+  let allowFrom = cfg.channels?.matrix?.dm?.allowFrom ?? [];
+  let groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
+  let roomsConfig = cfg.channels?.matrix?.groups ?? cfg.channels?.matrix?.rooms;
+
+  allowFrom = await resolveUserAllowlist("matrix dm allowlist", allowFrom);
+  groupAllowFrom = await resolveUserAllowlist("matrix group allowlist", groupAllowFrom);
 
   if (roomsConfig && Object.keys(roomsConfig).length > 0) {
-    const entries = Object.keys(roomsConfig).filter((key) => key !== "*");
     const mapping: string[] = [];
     const unresolved: string[] = [];
-    const nextRooms = { ...roomsConfig };
-    const pending: Array<{ input: string; query: string }> = [];
-    for (const entry of entries) {
+    const nextRooms: Record<string, (typeof roomsConfig)[string]> = {};
+    if (roomsConfig["*"]) {
+      nextRooms["*"] = roomsConfig["*"];
+    }
+    const pending: Array<{ input: string; query: string; config: (typeof roomsConfig)[string] }> =
+      [];
+    for (const [entry, roomConfig] of Object.entries(roomsConfig)) {
+      if (entry === "*") {
+        continue;
+      }
       const trimmed = entry.trim();
-      if (!trimmed) continue;
+      if (!trimmed) {
+        continue;
+      }
       const cleaned = normalizeRoomEntry(trimmed);
-      if (cleaned.startsWith("!") && cleaned.includes(":")) {
+      if ((cleaned.startsWith("!") || cleaned.startsWith("#")) && cleaned.includes(":")) {
         if (!nextRooms[cleaned]) {
-          nextRooms[cleaned] = roomsConfig[entry];
+          nextRooms[cleaned] = roomConfig;
+        }
+        if (cleaned !== entry) {
+          mapping.push(`${entry}→${cleaned}`);
         }
-        mapping.push(`${entry}→${cleaned}`);
         continue;
       }
-      pending.push({ input: entry, query: trimmed });
+      pending.push({ input: entry, query: trimmed, config: roomConfig });
     }
     if (pending.length > 0) {
       const resolved = await resolveMatrixTargets({
@@ -133,10 +167,12 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
       });
       resolved.forEach((entry, index) => {
         const source = pending[index];
-        if (!source) return;
+        if (!source) {
+          return;
+        }
         if (entry.resolved && entry.id) {
           if (!nextRooms[entry.id]) {
-            nextRooms[entry.id] = roomsConfig[source.input];
+            nextRooms[entry.id] = source.config;
           }
           mapping.push(`${source.input}→${entry.id}`);
         } else {
@@ -146,6 +182,25 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
     }
     roomsConfig = nextRooms;
     summarizeMapping("matrix rooms", mapping, unresolved, runtime);
+    if (unresolved.length > 0) {
+      runtime.log?.(
+        "matrix rooms must be room IDs or aliases (example: !room:server or #alias:server). Unresolved entries are ignored.",
+      );
+    }
+  }
+  if (roomsConfig && Object.keys(roomsConfig).length > 0) {
+    const nextRooms = { ...roomsConfig };
+    for (const [roomKey, roomConfig] of Object.entries(roomsConfig)) {
+      const users = roomConfig?.users ?? [];
+      if (users.length === 0) {
+        continue;
+      }
+      const resolvedUsers = await resolveUserAllowlist(`matrix room users (${roomKey})`, users);
+      if (resolvedUsers !== users) {
+        nextRooms[roomKey] = { ...roomConfig, users: resolvedUsers };
+      }
+    }
+    roomsConfig = nextRooms;
   }
 
   cfg = {
@@ -158,6 +213,7 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
           ...cfg.channels?.matrix?.dm,
           allowFrom,
         },
+        ...(groupAllowFrom.length > 0 ? { groupAllowFrom } : {}),
         ...(roomsConfig ? { groups: roomsConfig } : {}),
       },
     },
@@ -256,7 +312,10 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
         logger.info("matrix: device verification requested - please verify in another client");
       }
     } catch (err) {
-      logger.debug({ error: String(err) }, "Device verification request failed (may already be verified)");
+      logger.debug(
+        { error: String(err) },
+        "Device verification request failed (may already be verified)",
+      );
     }
   }
 

package/src/matrix/monitor/location.ts

@@ -1,5 +1,4 @@
 import type { LocationMessageEventContent } from "@vector-im/matrix-bot-sdk";
-
 import {
   formatLocationText,
   toLocationContext,
@@ -20,25 +19,37 @@ type GeoUriParams = {
 
 function parseGeoUri(value: string): GeoUriParams | null {
   const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (!trimmed.toLowerCase().startsWith("geo:")) return null;
+  if (!trimmed) {
+    return null;
+  }
+  if (!trimmed.toLowerCase().startsWith("geo:")) {
+    return null;
+  }
   const payload = trimmed.slice(4);
   const [coordsPart, ...paramParts] = payload.split(";");
   const coords = coordsPart.split(",");
-  if (coords.length < 2) return null;
+  if (coords.length < 2) {
+    return null;
+  }
   const latitude = Number.parseFloat(coords[0] ?? "");
   const longitude = Number.parseFloat(coords[1] ?? "");
-  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return null;
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    return null;
+  }
 
   const params = new Map<string, string>();
   for (const part of paramParts) {
     const segment = part.trim();
-    if (!segment) continue;
+    if (!segment) {
+      continue;
+    }
     const eqIndex = segment.indexOf("=");
     const rawKey = eqIndex === -1 ? segment : segment.slice(0, eqIndex);
     const rawValue = eqIndex === -1 ? "" : segment.slice(eqIndex + 1);
     const key = rawKey.trim().toLowerCase();
-    if (!key) continue;
+    if (!key) {
+      continue;
+    }
     const valuePart = rawValue.trim();
     params.set(key, valuePart ? decodeURIComponent(valuePart) : "");
   }
@@ -61,11 +72,17 @@ export function resolveMatrixLocation(params: {
   const isLocation =
     eventType === EventType.Location ||
     (eventType === EventType.RoomMessage && content.msgtype === EventType.Location);
-  if (!isLocation) return null;
+  if (!isLocation) {
+    return null;
+  }
   const geoUri = typeof content.geo_uri === "string" ? content.geo_uri.trim() : "";
-  if (!geoUri) return null;
+  if (!geoUri) {
+    return null;
+  }
   const parsed = parseGeoUri(geoUri);
-  if (!parsed) return null;
+  if (!parsed) {
+    return null;
+  }
   const caption = typeof content.body === "string" ? content.body.trim() : "";
   const location: NormalizedLocation = {
     latitude: parsed.latitude,

package/src/matrix/monitor/media.test.ts

@@ -1,6 +1,5 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
 import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { setMatrixRuntime } from "../../runtime.js";
 import { downloadMatrixMedia } from "./media.js";
 

package/src/matrix/monitor/media.ts

@@ -1,5 +1,4 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
 import { getMatrixRuntime } from "../../runtime.js";
 
 // Type for encrypted file info
@@ -24,7 +23,9 @@ async function fetchMatrixMediaBuffer(params: {
 }): Promise<{ buffer: Buffer; headerType?: string } | null> {
   // @vector-im/matrix-bot-sdk provides mxcToHttp helper
   const url = params.client.mxcToHttp(params.mxcUrl);
-  if (!url) return null;
+  if (!url) {
+    return null;
+  }
 
   // Use the client's download method which handles auth
   try {
@@ -34,7 +35,7 @@ async function fetchMatrixMediaBuffer(params: {
     }
     return { buffer: Buffer.from(buffer) };
   } catch (err) {
-    throw new Error(`Matrix media download failed: ${String(err)}`);
+    throw new Error(`Matrix media download failed: ${String(err)}`, { cause: err });
   }
 }
 
@@ -74,10 +75,7 @@ export async function downloadMatrixMedia(params: {
   placeholder: string;
 } | null> {
   let fetched: { buffer: Buffer; headerType?: string } | null;
-  if (
-    typeof params.sizeBytes === "number" &&
-    params.sizeBytes > params.maxBytes
-  ) {
+  if (typeof params.sizeBytes === "number" && params.sizeBytes > params.maxBytes) {
     throw new Error("Matrix media exceeds configured size limit");
   }
 
@@ -97,7 +95,9 @@ export async function downloadMatrixMedia(params: {
     });
   }
 
-  if (!fetched) return null;
+  if (!fetched) {
+    return null;
+  }
   const headerType = fetched.headerType ?? params.contentType ?? undefined;
   const saved = await getMatrixRuntime().channel.media.saveMediaBuffer(
     fetched.buffer,

package/src/matrix/monitor/replies.ts

@@ -1,8 +1,7 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
 import type { MarkdownTableMode, ReplyPayload, RuntimeEnv } from "openclaw/plugin-sdk";
-import { sendMessageMatrix } from "../send.js";
 import { getMatrixRuntime } from "../../runtime.js";
+import { sendMessageMatrix } from "../send.js";
 
 export async function deliverMatrixReplies(params: {
   replies: ReplyPayload[];
@@ -62,7 +61,9 @@ export async function deliverMatrixReplies(params: {
         chunkMode,
       )) {
         const trimmed = chunk.trim();
-        if (!trimmed) continue;
+        if (!trimmed) {
+          continue;
+        }
         await sendMessageMatrix(params.roomId, trimmed, {
           client: params.client,
           replyToId: shouldIncludeReply(replyToId) ? replyToId : undefined,

package/src/matrix/monitor/room-info.ts

@@ -11,14 +11,14 @@ export function createMatrixRoomInfoResolver(client: MatrixClient) {
 
   const getRoomInfo = async (roomId: string): Promise<MatrixRoomInfo> => {
     const cached = roomInfoCache.get(roomId);
-    if (cached) return cached;
+    if (cached) {
+      return cached;
+    }
     let name: string | undefined;
     let canonicalAlias: string | undefined;
     let altAliases: string[] = [];
     try {
-      const nameState = await client
-        .getRoomStateEvent(roomId, "m.room.name", "")
-        .catch(() => null);
+      const nameState = await client.getRoomStateEvent(roomId, "m.room.name", "").catch(() => null);
       name = nameState?.name;
     } catch {
       // ignore
@@ -37,10 +37,7 @@ export function createMatrixRoomInfoResolver(client: MatrixClient) {
     return info;
   };
 
-  const getMemberDisplayName = async (
-    roomId: string,
-    userId: string,
-  ): Promise<string> => {
+  const getMemberDisplayName = async (roomId: string, userId: string): Promise<string> => {
     try {
       const memberState = await client
         .getRoomStateEvent(roomId, "m.room.member", userId)

package/src/matrix/monitor/rooms.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixRoomConfig } from "./rooms.js";
+
+describe("resolveMatrixRoomConfig", () => {
+  it("matches room IDs and aliases, not names", () => {
+    const rooms = {
+      "!room:example.org": { allow: true },
+      "#alias:example.org": { allow: true },
+      "Project Room": { allow: true },
+    };
+
+    const byId = resolveMatrixRoomConfig({
+      rooms,
+      roomId: "!room:example.org",
+      aliases: [],
+      name: "Project Room",
+    });
+    expect(byId.allowed).toBe(true);
+    expect(byId.matchKey).toBe("!room:example.org");
+
+    const byAlias = resolveMatrixRoomConfig({
+      rooms,
+      roomId: "!other:example.org",
+      aliases: ["#alias:example.org"],
+      name: "Other Room",
+    });
+    expect(byAlias.allowed).toBe(true);
+    expect(byAlias.matchKey).toBe("#alias:example.org");
+
+    const byName = resolveMatrixRoomConfig({
+      rooms: { "Project Room": { allow: true } },
+      roomId: "!different:example.org",
+      aliases: [],
+      name: "Project Room",
+    });
+    expect(byName.allowed).toBe(false);
+    expect(byName.config).toBeUndefined();
+  });
+});

package/src/matrix/monitor/rooms.ts

@@ -1,5 +1,5 @@
-import type { MatrixRoomConfig } from "../../types.js";
 import { buildChannelKeyCandidates, resolveChannelEntryMatch } from "openclaw/plugin-sdk";
+import type { MatrixRoomConfig } from "../../types.js";
 
 export type MatrixRoomConfigResolved = {
   allowed: boolean;
@@ -22,9 +22,13 @@ export function resolveMatrixRoomConfig(params: {
     params.roomId,
     `room:${params.roomId}`,
     ...params.aliases,
-    params.name ?? "",
   );
-  const { entry: matched, key: matchedKey, wildcardEntry, wildcardKey } = resolveChannelEntryMatch({
+  const {
+    entry: matched,
+    key: matchedKey,
+    wildcardEntry,
+    wildcardKey,
+  } = resolveChannelEntryMatch({
     entries: rooms,
     keys: candidates,
     wildcardKey: "*",

package/src/matrix/monitor/threads.ts

@@ -28,7 +28,9 @@ export function resolveMatrixThreadTarget(params: {
   isThreadRoot?: boolean;
 }): string | undefined {
   const { threadReplies, messageId, threadRootId } = params;
-  if (threadReplies === "off") return undefined;
+  if (threadReplies === "off") {
+    return undefined;
+  }
   const isThreadRoot = params.isThreadRoot === true;
   const hasInboundThread = Boolean(threadRootId && threadRootId !== messageId && !isThreadRoot);
   if (threadReplies === "inbound") {
@@ -45,7 +47,9 @@ export function resolveMatrixThreadRootId(params: {
   content: RoomMessageEventContent;
 }): string | undefined {
   const relates = params.content["m.relates_to"];
-  if (!relates || typeof relates !== "object") return undefined;
+  if (!relates || typeof relates !== "object") {
+    return undefined;
+  }
   if ("rel_type" in relates && relates.rel_type === RelationType.Thread) {
     if ("event_id" in relates && typeof relates.event_id === "string") {
       return relates.event_id;

package/src/matrix/poll-types.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, it } from "vitest";
-
 import { parsePollStartContent } from "./poll-types.js";
 
 describe("parsePollStartContent", () => {

package/src/matrix/poll-types.ts

@@ -77,18 +77,25 @@ export function isPollStartType(eventType: string): boolean {
 }
 
 export function getTextContent(text?: TextContent): string {
-  if (!text) return "";
+  if (!text) {
+    return "";
+  }
   return text["m.text"] ?? text["org.matrix.msc1767.text"] ?? text.body ?? "";
 }
 
 export function parsePollStartContent(content: PollStartContent): PollSummary | null {
-  const poll = (content as Record<string, PollStartSubtype | undefined>)[M_POLL_START]
-    ?? (content as Record<string, PollStartSubtype | undefined>)[ORG_POLL_START]
-    ?? (content as Record<string, PollStartSubtype | undefined>)["m.poll"];
-  if (!poll) return null;
+  const poll =
+    (content as Record<string, PollStartSubtype | undefined>)[M_POLL_START] ??
+    (content as Record<string, PollStartSubtype | undefined>)[ORG_POLL_START] ??
+    (content as Record<string, PollStartSubtype | undefined>)["m.poll"];
+  if (!poll) {
+    return null;
+  }
 
   const question = getTextContent(poll.question);
-  if (!question) return null;
+  if (!question) {
+    return null;
+  }
 
   const answers = poll.answers
     .map((answer) => getTextContent(answer))
@@ -124,7 +131,9 @@ function buildTextContent(body: string): TextContent {
 }
 
 function buildPollFallbackText(question: string, answers: string[]): string {
-  if (answers.length === 0) return question;
+  if (answers.length === 0) {
+    return question;
+  }
   return `${question}\n${answers.map((answer, idx) => `${idx + 1}. ${answer}`).join("\n")}`;
 }
 

package/src/matrix/send/client.ts

@@ -1,5 +1,5 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
+import type { CoreConfig } from "../types.js";
 import { getMatrixRuntime } from "../../runtime.js";
 import { getActiveMatrixClient } from "../active-client.js";
 import {
@@ -8,7 +8,6 @@ import {
   resolveMatrixAuth,
   resolveSharedMatrixClient,
 } from "../client.js";
-import type { CoreConfig } from "../types.js";
 
 const getCore = () => getMatrixRuntime();
 
@@ -31,9 +30,13 @@ export async function resolveMatrixClient(opts: {
   timeoutMs?: number;
 }): Promise<{ client: MatrixClient; stopOnDone: boolean }> {
   ensureNodeRuntime();
-  if (opts.client) return { client: opts.client, stopOnDone: false };
+  if (opts.client) {
+    return { client: opts.client, stopOnDone: false };
+  }
   const active = getActiveMatrixClient();
-  if (active) return { client: active, stopOnDone: false };
+  if (active) {
+    return { client: active, stopOnDone: false };
+  }
   const shouldShareClient = Boolean(process.env.OPENCLAW_GATEWAY_PORT);
   if (shouldShareClient) {
     const client = await resolveSharedMatrixClient({