diff --git a/docs/channels/groups.md b/docs/channels/groups.md
index f7aa57633aa..66b8720a8c4 100644
--- a/docs/channels/groups.md
+++ b/docs/channels/groups.md
@@ -1,5 +1,5 @@
 ---
-summary: "Group chat behavior across surfaces (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams/Zalo)"
+summary: "Group chat behavior across surfaces (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)"
 read_when:
   - Changing group chat behavior or mention gating
 title: "Groups"
@@ -7,7 +7,7 @@ title: "Groups"
 
 # Groups
 
-OpenClaw treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.
+OpenClaw treats group chats consistently across surfaces: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
 
 ## Beginner intro (2 minutes)
 
@@ -187,7 +187,7 @@ Notes:
 - DM pairing approvals (`*-allowFrom` store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
 - Discord: allowlist uses `channels.discord.guilds.<id>.channels`.
 - Slack: allowlist uses `channels.slack.channels`.
-- Matrix: allowlist uses `channels.matrix.groups` (room IDs, aliases, or names). Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.
+- Matrix: allowlist uses `channels.matrix.groups`. Prefer room IDs or aliases; joined-room name lookup is best-effort, and unresolved names are ignored at runtime. Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.
 - Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`).
 - Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
 - Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.
diff --git a/docs/channels/location.md b/docs/channels/location.md
index 103f57663c4..ddfdfd5cd98 100644
--- a/docs/channels/location.md
+++ b/docs/channels/location.md
@@ -1,5 +1,5 @@
 ---
-summary: "Inbound channel location parsing (Telegram + WhatsApp) and context fields"
+summary: "Inbound channel location parsing (Telegram/WhatsApp/Matrix) and context fields"
 read_when:
   - Adding or modifying channel location parsing
   - Using location context fields in agent prompts or tools
diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md
index 06a03c5fc76..2adc79fd84b 100644
--- a/docs/channels/matrix.md
+++ b/docs/channels/matrix.md
@@ -187,9 +187,9 @@ done:
 - Media replies still send attachments normally. If a stale preview can no longer be reused safely, OpenClaw redacts it before sending the final media reply.
 - Preview edits cost extra Matrix API calls. Leave streaming off if you want the most conservative rate-limit behavior.
 
-## E2EE setup
+## Encryption and verification
 
-## Bot to bot rooms
+### Bot to bot rooms
 
 By default, Matrix messages from other configured OpenClaw Matrix accounts are ignored.
 
@@ -426,6 +426,19 @@ Planned improvement:
 
 - add SecretRef support for persistent Matrix key material so recovery keys and related store-encryption secrets can be sourced from OpenClaw secrets providers instead of only local files
 
+## Profile management
+
+Update the Matrix self-profile for the selected account with:
+
+```bash
+openclaw matrix profile set --name "OpenClaw Assistant"
+openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
+```
+
+Add `--account <id>` when you want to target a named Matrix account explicitly.
+
+Matrix accepts `mxc://` avatar URLs directly. When you pass an `http://` or `https://` avatar URL, OpenClaw uploads it to Matrix first and stores the resolved `mxc://` URL back into `channels.matrix.avatarUrl` (or the selected account override).
+
 ## Automatic verification notices
 
 Matrix now posts verification lifecycle notices directly into the strict DM verification room as `m.notice` messages.
@@ -709,7 +722,7 @@ Live directory lookup uses the logged-in Matrix account:
 - `ackReaction`: optional ack reaction override for this channel/account.
 - `ackReactionScope`: optional ack reaction scope override (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
 - `reactionNotifications`: inbound reaction notification mode (`own`, `off`).
-- `mediaMaxMb`: outbound media size cap in MB.
+- `mediaMaxMb`: media size cap in MB for Matrix media handling. It applies to outbound sends and inbound media processing.
 - `autoJoin`: invite auto-join policy (`always`, `allowlist`, `off`). Default: `off`.
 - `autoJoinAllowlist`: rooms/aliases allowed when `autoJoin` is `allowlist`. Alias entries are resolved to room IDs during invite handling; OpenClaw does not trust alias state claimed by the invited room.
 - `dm`: DM policy block (`enabled`, `policy`, `allowFrom`).