@openclaw/matrix 2026.1.29 → 2026.2.2

package/CHANGELOG.md

@@ -1,53 +1,81 @@
 # Changelog
 
+## 2026.2.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.31
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.30
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.1.29
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.23
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.22
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.21
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.20
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.17-1
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.17
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.16
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.15
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.1.14
 
 ### Features
+
 - Version alignment with core OpenClaw release numbers.
 - Matrix channel plugin with homeserver + user ID auth (access token or password login with device name).
 - Direct messages with pairing/allowlist/open/disabled policies and allowFrom support.

package/index.ts

@@ -1,6 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-
 import { matrixPlugin } from "./src/channel.js";
 import { setMatrixRuntime } from "./src/runtime.js";
 

package/openclaw.plugin.json

@@ -1,8 +1,6 @@
 {
   "id": "matrix",
-  "channels": [
-    "matrix"
-  ],
+  "channels": ["matrix"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.1.29",
-  "type": "module",
+  "version": "2026.2.2",
   "description": "OpenClaw Matrix channel plugin",
+  "type": "module",
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
+    "markdown-it": "14.1.0",
+    "music-metadata": "^11.11.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
   "openclaw": {
     "extensions": [
       "./index.ts"
@@ -22,15 +32,5 @@
       "localPath": "extensions/matrix",
       "defaultChoice": "npm"
     }
-  },
-  "dependencies": {
-    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
-    "markdown-it": "14.1.0",
-    "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
-    "music-metadata": "^11.10.6",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "openclaw": "workspace:*"
   }
 }

package/src/actions.ts

@@ -7,14 +7,16 @@ import {
   type ChannelMessageActionName,
   type ChannelToolSend,
 } from "openclaw/plugin-sdk";
+import type { CoreConfig } from "./types.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { handleMatrixAction } from "./tool-actions.js";
-import type { CoreConfig } from "./types.js";
 
 export const matrixMessageActions: ChannelMessageActionAdapter = {
   listActions: ({ cfg }) => {
     const account = resolveMatrixAccount({ cfg: cfg as CoreConfig });
-    if (!account.enabled || !account.configured) return [];
+    if (!account.enabled || !account.configured) {
+      return [];
+    }
     const gate = createActionGate((cfg as CoreConfig).channels?.matrix?.actions);
     const actions = new Set<ChannelMessageActionName>(["send", "poll"]);
     if (gate("reactions")) {
@@ -31,16 +33,24 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
       actions.add("unpin");
       actions.add("list-pins");
     }
-    if (gate("memberInfo")) actions.add("member-info");
-    if (gate("channelInfo")) actions.add("channel-info");
+    if (gate("memberInfo")) {
+      actions.add("member-info");
+    }
+    if (gate("channelInfo")) {
+      actions.add("channel-info");
+    }
     return Array.from(actions);
   },
   supportsAction: ({ action }) => action !== "poll",
   extractToolSend: ({ args }): ChannelToolSend | null => {
     const action = typeof args.action === "string" ? args.action.trim() : "";
-    if (action !== "sendMessage") return null;
+    if (action !== "sendMessage") {
+      return null;
+    }
     const to = typeof args.to === "string" ? args.to : undefined;
-    if (!to) return null;
+    if (!to) {
+      return null;
+    }
     return { to };
   },
   handleAction: async (ctx: ChannelMessageActionContext) => {

package/src/channel.directory.test.ts

@@ -1,8 +1,6 @@
-import { beforeEach, describe, expect, it } from "vitest";
-
 import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it } from "vitest";
 import type { CoreConfig } from "./types.js";
-
 import { matrixPlugin } from "./channel.js";
 import { setMatrixRuntime } from "./runtime.js";
 
@@ -34,7 +32,12 @@ describe("matrix directory", () => {
     expect(matrixPlugin.directory?.listGroups).toBeTruthy();
 
     await expect(
-      matrixPlugin.directory!.listPeers({ cfg, accountId: undefined, query: undefined, limit: undefined }),
+      matrixPlugin.directory!.listPeers({
+        cfg,
+        accountId: undefined,
+        query: undefined,
+        limit: undefined,
+      }),
     ).resolves.toEqual(
       expect.arrayContaining([
         { kind: "user", id: "user:@alice:example.org" },
@@ -45,7 +48,12 @@ describe("matrix directory", () => {
     );
 
     await expect(
-      matrixPlugin.directory!.listGroups({ cfg, accountId: undefined, query: undefined, limit: undefined }),
+      matrixPlugin.directory!.listGroups({
+        cfg,
+        accountId: undefined,
+        query: undefined,
+        limit: undefined,
+      }),
     ).resolves.toEqual(
       expect.arrayContaining([
         { kind: "group", id: "room:!room1:example.org" },

package/src/channel.ts

@@ -9,11 +9,14 @@ import {
   setAccountEnabledInConfigSection,
   type ChannelPlugin,
 } from "openclaw/plugin-sdk";
-
+import type { CoreConfig } from "./types.js";
 import { matrixMessageActions } from "./actions.js";
 import { MatrixConfigSchema } from "./config-schema.js";
-import { resolveMatrixGroupRequireMention, resolveMatrixGroupToolPolicy } from "./group-mentions.js";
-import type { CoreConfig } from "./types.js";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
+import {
+  resolveMatrixGroupRequireMention,
+  resolveMatrixGroupToolPolicy,
+} from "./group-mentions.js";
 import {
   listMatrixAccountIds,
   resolveDefaultMatrixAccountId,
@@ -21,16 +24,12 @@ import {
   type ResolvedMatrixAccount,
 } from "./matrix/accounts.js";
 import { resolveMatrixAuth } from "./matrix/client.js";
-import { normalizeAllowListLower } from "./matrix/monitor/allowlist.js";
+import { normalizeMatrixAllowList, normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
 import { probeMatrix } from "./matrix/probe.js";
 import { sendMessageMatrix } from "./matrix/send.js";
 import { matrixOnboardingAdapter } from "./onboarding.js";
 import { matrixOutbound } from "./outbound.js";
 import { resolveMatrixTargets } from "./resolve-targets.js";
-import {
-  listMatrixDirectoryGroupsLive,
-  listMatrixDirectoryPeersLive,
-} from "./directory-live.js";
 
 const meta = {
   id: "matrix",
@@ -45,7 +44,9 @@ const meta = {
 
 function normalizeMatrixMessagingTarget(raw: string): string | undefined {
   let normalized = raw.trim();
-  if (!normalized) return undefined;
+  if (!normalized) {
+    return undefined;
+  }
   const lowered = normalized.toLowerCase();
   if (lowered.startsWith("matrix:")) {
     normalized = normalized.slice("matrix:".length).trim();
@@ -108,8 +109,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
   configSchema: buildChannelConfigSchema(MatrixConfigSchema),
   config: {
     listAccountIds: (cfg) => listMatrixAccountIds(cfg as CoreConfig),
-    resolveAccount: (cfg, accountId) =>
-      resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId }),
+    resolveAccount: (cfg, accountId) => resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId }),
     defaultAccountId: (cfg) => resolveDefaultMatrixAccountId(cfg as CoreConfig),
     setAccountEnabled: ({ cfg, accountId, enabled }) =>
       setAccountEnabledInConfigSection({
@@ -144,7 +144,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
     }),
     resolveAllowFrom: ({ cfg }) =>
       ((cfg as CoreConfig).channels?.matrix?.dm?.allowFrom ?? []).map((entry) => String(entry)),
-    formatAllowFrom: ({ allowFrom }) => normalizeAllowListLower(allowFrom),
+    formatAllowFrom: ({ allowFrom }) => normalizeMatrixAllowList(allowFrom),
   },
   security: {
     resolveDmPolicy: ({ account }) => ({
@@ -153,15 +153,16 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
       policyPath: "channels.matrix.dm.policy",
       allowFromPath: "channels.matrix.dm.allowFrom",
       approveHint: formatPairingApproveHint("matrix"),
-      normalizeEntry: (raw) => raw.replace(/^matrix:/i, "").trim().toLowerCase(),
+      normalizeEntry: (raw) => normalizeMatrixUserId(raw),
     }),
     collectWarnings: ({ account, cfg }) => {
       const defaultGroupPolicy = (cfg as CoreConfig).channels?.defaults?.groupPolicy;
-      const groupPolicy =
-        account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
-      if (groupPolicy !== "open") return [];
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") {
+        return [];
+      }
       return [
-        "- Matrix rooms: groupPolicy=\"open\" allows any room to trigger (mention-gated). Set channels.matrix.groupPolicy=\"allowlist\" + channels.matrix.groups (and optionally channels.matrix.groupAllowFrom) to restrict rooms.",
+        '- Matrix rooms: groupPolicy="open" allows any room to trigger (mention-gated). Set channels.matrix.groupPolicy="allowlist" + channels.matrix.groups (and optionally channels.matrix.groupAllowFrom) to restrict rooms.',
       ];
     },
   },
@@ -170,16 +171,13 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
     resolveToolPolicy: resolveMatrixGroupToolPolicy,
   },
   threading: {
-    resolveReplyToMode: ({ cfg }) =>
-      (cfg as CoreConfig).channels?.matrix?.replyToMode ?? "off",
+    resolveReplyToMode: ({ cfg }) => (cfg as CoreConfig).channels?.matrix?.replyToMode ?? "off",
     buildToolContext: ({ context, hasRepliedRef }) => {
       const currentTarget = context.To;
       return {
         currentChannelId: currentTarget?.trim() || undefined,
         currentThreadTs:
-          context.MessageThreadId != null
-            ? String(context.MessageThreadId)
-            : context.ReplyToId,
+          context.MessageThreadId != null ? String(context.MessageThreadId) : context.ReplyToId,
         hasRepliedRef,
       };
     },
@@ -189,8 +187,12 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
     targetResolver: {
       looksLikeId: (raw) => {
         const trimmed = raw.trim();
-        if (!trimmed) return false;
-        if (/^(matrix:)?[!#@]/i.test(trimmed)) return true;
+        if (!trimmed) {
+          return false;
+        }
+        if (/^(matrix:)?[!#@]/i.test(trimmed)) {
+          return true;
+        }
         return trimmed.includes(":");
       },
       hint: "<room|alias|user>",
@@ -205,13 +207,17 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
 
       for (const entry of account.config.dm?.allowFrom ?? []) {
         const raw = String(entry).trim();
-        if (!raw || raw === "*") continue;
+        if (!raw || raw === "*") {
+          continue;
+        }
         ids.add(raw.replace(/^matrix:/i, ""));
       }
 
       for (const entry of account.config.groupAllowFrom ?? []) {
         const raw = String(entry).trim();
-        if (!raw || raw === "*") continue;
+        if (!raw || raw === "*") {
+          continue;
+        }
         ids.add(raw.replace(/^matrix:/i, ""));
       }
 
@@ -219,7 +225,9 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
       for (const room of Object.values(groups)) {
         for (const entry of room.users ?? []) {
           const raw = String(entry).trim();
-          if (!raw || raw === "*") continue;
+          if (!raw || raw === "*") {
+            continue;
+          }
           ids.add(raw.replace(/^matrix:/i, ""));
         }
       }
@@ -230,7 +238,9 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         .map((raw) => {
           const lowered = raw.toLowerCase();
           const cleaned = lowered.startsWith("user:") ? raw.slice("user:".length).trim() : raw;
-          if (cleaned.startsWith("@")) return `user:${cleaned}`;
+          if (cleaned.startsWith("@")) {
+            return `user:${cleaned}`;
+          }
           return cleaned;
         })
         .filter((id) => (q ? id.toLowerCase().includes(q) : true))
@@ -255,8 +265,12 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         .map((raw) => raw.replace(/^matrix:/i, ""))
         .map((raw) => {
           const lowered = raw.toLowerCase();
-          if (lowered.startsWith("room:") || lowered.startsWith("channel:")) return raw;
-          if (raw.startsWith("!")) return `room:${raw}`;
+          if (lowered.startsWith("room:") || lowered.startsWith("channel:")) {
+            return raw;
+          }
+          if (raw.startsWith("!")) {
+            return `room:${raw}`;
+          }
           return raw;
         })
         .filter((id) => (q ? id.toLowerCase().includes(q) : true))
@@ -284,8 +298,12 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         name,
       }),
     validateInput: ({ input }) => {
-      if (input.useEnv) return null;
-      if (!input.homeserver?.trim()) return "Matrix requires --homeserver";
+      if (input.useEnv) {
+        return null;
+      }
+      if (!input.homeserver?.trim()) {
+        return "Matrix requires --homeserver";
+      }
       const accessToken = input.accessToken?.trim();
       const password = input.password?.trim();
       const userId = input.userId?.trim();
@@ -293,8 +311,12 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         return "Matrix requires --access-token or --password";
       }
       if (!accessToken) {
-        if (!userId) return "Matrix requires --user-id when using --password";
-        if (!password) return "Matrix requires --password when using --user-id";
+        if (!userId) {
+          return "Matrix requires --user-id when using --password";
+        }
+        if (!password) {
+          return "Matrix requires --password when using --user-id";
+        }
       }
       return null;
     },
@@ -339,7 +361,9 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
     collectStatusIssues: (accounts) =>
       accounts.flatMap((account) => {
         const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
-        if (!lastError) return [];
+        if (!lastError) {
+          return [];
+        }
         return [
           {
             channel: "matrix",
@@ -359,7 +383,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
-    probeAccount: async ({ account, timeoutMs, cfg }) => {
+    probeAccount: async ({ timeoutMs, cfg }) => {
       try {
         const auth = await resolveMatrixAuth({ cfg: cfg as CoreConfig });
         return await probeMatrix({
@@ -399,9 +423,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         accountId: account.accountId,
         baseUrl: account.homeserver,
       });
-      ctx.log?.info(
-        `[${account.accountId}] starting provider (${account.homeserver ?? "matrix"})`,
-      );
+      ctx.log?.info(`[${account.accountId}] starting provider (${account.homeserver ?? "matrix"})`);
       // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
       const { monitorMatrixProvider } = await import("./matrix/index.js");
       return monitorMatrixProvider({

package/src/directory-live.ts

@@ -1,5 +1,4 @@
 import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk";
-
 import { resolveMatrixAuth } from "./matrix/client.js";
 
 type MatrixUserResult = {
@@ -55,7 +54,9 @@ export async function listMatrixDirectoryPeersLive(params: {
   limit?: number | null;
 }): Promise<ChannelDirectoryEntry[]> {
   const query = normalizeQuery(params.query);
-  if (!query) return [];
+  if (!query) {
+    return [];
+  }
   const auth = await resolveMatrixAuth({ cfg: params.cfg as never });
   const res = await fetchMatrixJson<MatrixUserDirectoryResponse>({
     homeserver: auth.homeserver,
@@ -71,7 +72,9 @@ export async function listMatrixDirectoryPeersLive(params: {
   return results
     .map((entry) => {
       const userId = entry.user_id?.trim();
-      if (!userId) return null;
+      if (!userId) {
+        return null;
+      }
       return {
         kind: "user",
         id: userId,
@@ -123,13 +126,17 @@ export async function listMatrixDirectoryGroupsLive(params: {
   limit?: number | null;
 }): Promise<ChannelDirectoryEntry[]> {
   const query = normalizeQuery(params.query);
-  if (!query) return [];
+  if (!query) {
+    return [];
+  }
   const auth = await resolveMatrixAuth({ cfg: params.cfg as never });
   const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 20;
 
   if (query.startsWith("#")) {
     const roomId = await resolveMatrixRoomAlias(auth.homeserver, auth.accessToken, query);
-    if (!roomId) return [];
+    if (!roomId) {
+      return [];
+    }
     return [
       {
         kind: "group",
@@ -160,15 +167,21 @@ export async function listMatrixDirectoryGroupsLive(params: {
 
   for (const roomId of rooms) {
     const name = await fetchMatrixRoomName(auth.homeserver, auth.accessToken, roomId);
-    if (!name) continue;
-    if (!name.toLowerCase().includes(query)) continue;
+    if (!name) {
+      continue;
+    }
+    if (!name.toLowerCase().includes(query)) {
+      continue;
+    }
     results.push({
       kind: "group",
       id: roomId,
       name,
       handle: `#${name}`,
     });
-    if (results.length >= limit) break;
+    if (results.length >= limit) {
+      break;
+    }
   }
 
   return results;

package/src/group-mentions.ts

@@ -1,7 +1,6 @@
 import type { ChannelGroupContext, GroupToolPolicyConfig } from "openclaw/plugin-sdk";
-
-import { resolveMatrixRoomConfig } from "./matrix/monitor/rooms.js";
 import type { CoreConfig } from "./types.js";
+import { resolveMatrixRoomConfig } from "./matrix/monitor/rooms.js";
 
 export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
   const rawGroupId = params.groupId?.trim() ?? "";
@@ -26,9 +25,15 @@ export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): b
     name: groupChannel || undefined,
   }).config;
   if (resolved) {
-    if (resolved.autoReply === true) return false;
-    if (resolved.autoReply === false) return true;
-    if (typeof resolved.requireMention === "boolean") return resolved.requireMention;
+    if (resolved.autoReply === true) {
+      return false;
+    }
+    if (resolved.autoReply === false) {
+      return true;
+    }
+    if (typeof resolved.requireMention === "boolean") {
+      return resolved.requireMention;
+    }
   }
   return true;
 }

package/src/matrix/accounts.test.ts

@@ -1,5 +1,4 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
 import type { CoreConfig } from "../types.js";
 import { resolveMatrixAccount } from "./accounts.js";
 

package/src/matrix/accounts.ts

@@ -19,7 +19,9 @@ export function listMatrixAccountIds(_cfg: CoreConfig): string[] {
 
 export function resolveDefaultMatrixAccountId(cfg: CoreConfig): string {
   const ids = listMatrixAccountIds(cfg);
-  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
   return ids[0] ?? DEFAULT_ACCOUNT_ID;
 }
 
@@ -28,7 +30,7 @@ export function resolveMatrixAccount(params: {
   accountId?: string | null;
 }): ResolvedMatrixAccount {
   const accountId = normalizeAccountId(params.accountId);
-  const base = (params.cfg.channels?.matrix ?? {}) as MatrixConfig;
+  const base = params.cfg.channels?.matrix ?? {};
   const enabled = base.enabled !== false;
   const resolved = resolveMatrixConfig(params.cfg, process.env);
   const hasHomeserver = Boolean(resolved.homeserver);

package/src/matrix/actions/client.ts

@@ -1,5 +1,6 @@
-import { getMatrixRuntime } from "../../runtime.js";
 import type { CoreConfig } from "../types.js";
+import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
+import { getMatrixRuntime } from "../../runtime.js";
 import { getActiveMatrixClient } from "../active-client.js";
 import {
   createMatrixClient,
@@ -7,7 +8,6 @@ import {
   resolveMatrixAuth,
   resolveSharedMatrixClient,
 } from "../client.js";
-import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
 
 export function ensureNodeRuntime() {
   if (isBunRuntime()) {
@@ -19,9 +19,13 @@ export async function resolveActionClient(
   opts: MatrixActionClientOpts = {},
 ): Promise<MatrixActionClient> {
   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({