diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md
index 93bcaada56..04205d9497 100644
--- a/docs/channels/matrix.md
+++ b/docs/channels/matrix.md
@@ -190,6 +190,7 @@ Notes:
   - `openclaw pairing approve matrix <CODE>`
 - Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
 - `channels.matrix.dm.allowFrom` accepts full Matrix user IDs (example: `@user:server`). The wizard resolves display names to user IDs when directory search finds a single exact match.
+- Do not use display names or bare localparts (example: `"Alice"` or `"alice"`). They are ambiguous and are ignored for allowlist matching. Use full `@user:server` IDs.
 
 ## Rooms (groups)