diff --git a/extensions/matrix/src/onboarding.ts b/extensions/matrix/src/onboarding.ts
index c85f3a25ac..1a9ed014c8 100644
--- a/extensions/matrix/src/onboarding.ts
+++ b/extensions/matrix/src/onboarding.ts
@@ -8,9 +8,9 @@ import {
 } from "openclaw/plugin-sdk";
 import type { CoreConfig, DmPolicy } from "./types.js";
 import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
-import { listMatrixDirectoryPeersLive } from "./directory-live.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";
+import { resolveMatrixTargets } from "./resolve-targets.js";
 
 const channel = "matrix" as const;
 
@@ -65,14 +65,16 @@ async function promptMatrixAllowFrom(params: {
 
   while (true) {
     const entry = await prompter.text({
-      message: "Matrix allowFrom (username or user id)",
+      message: "Matrix allowFrom (full @user:server; display name only if unique)",
       placeholder: "@user:server",
       initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
       validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
     });
     const parts = parseInput(String(entry));
     const resolvedIds: string[] = [];
-    let unresolved: string[] = [];
+    const pending: string[] = [];
+    const unresolved: string[] = [];
+    const unresolvedNotes: string[] = [];
 
     for (const part of parts) {
       if (isFullUserId(part)) {
@@ -83,28 +85,33 @@ async function promptMatrixAllowFrom(params: {
         unresolved.push(part);
         continue;
       }
-      const results = await listMatrixDirectoryPeersLive({
+      pending.push(part);
+    }
+
+    if (pending.length > 0) {
+      const results = await resolveMatrixTargets({
         cfg,
-        query: part,
-        limit: 5,
+        inputs: pending,
+        kind: "user",
       }).catch(() => []);
-      const match = results.find((result) => result.id);
-      if (match?.id) {
-        resolvedIds.push(match.id);
-        if (results.length > 1) {
-          await prompter.note(
-            `Multiple matches for "${part}", using ${match.id}.`,
-            "Matrix allowlist",
-          );
+      for (const result of results) {
+        if (result?.resolved && result.id) {
+          resolvedIds.push(result.id);
+          continue;
+        }
+        if (result?.input) {
+          unresolved.push(result.input);
+          if (result.note) {
+            unresolvedNotes.push(`${result.input}: ${result.note}`);
+          }
         }
-      } else {
-        unresolved.push(part);
       }
     }
 
     if (unresolved.length > 0) {
+      const details = unresolvedNotes.length > 0 ? unresolvedNotes : unresolved;
       await prompter.note(
-        `Could not resolve: ${unresolved.join(", ")}. Use full @user:server IDs.`,
+        `Could not resolve:\n${details.join("\n")}\nUse full @user:server IDs.`,
         "Matrix allowlist",
       );
       continue;