OpenClaw Matrix accounts and homeservers

A Matrix deployment is defined by two things: which accounts the Gateway logs in as, and how it reaches their homeservers. OpenClaw’s docs collect the account-level operations, profile, direct-room repair, multi-account layout, private homeservers and proxies, together with the target forms every other Matrix feature relies on. Here they are, with the rules that decide which account a command means and which room a target names.

Profiles and direct rooms

• A profile command sets the display name and avatar in one call; Matrix accepts content-repository avatar URLs directly, and an HTTP URL is uploaded first with the resolved content URL stored in the avatar setting, globally or per account.
• If direct-message state drifts, the account can end up with stale direct mappings pointing at old solo rooms; a direct inspect command shows the mapping for a peer and a repair command fixes it, both taking an account flag.
• The repair prefers a strict one-to-one DM already mapped, falls back to any currently joined strict DM with that user, and creates a fresh direct room and rewrites the mapping when no healthy DM exists; it never deletes old rooms, it picks the healthy one so future sends, verification notices and other direct flows target the right room.
• In a multi-account layout the top-level Matrix values act as defaults for named accounts unless an account overrides them, an inherited room entry can be scoped to one account with an account field, and entries without one are shared.

Matrix room IDs are case-sensitive.

Which account a command means

A default-account setting picks the named account that implicit routing, probing and CLI commands prefer; an account literally named default is used implicitly even without the setting; with several named accounts and no default the CLI refuses to guess and asks for the setting or an account flag; and the top-level block is treated as the implicit default only when its auth is complete, a homeserver plus access token or a homeserver plus user id and password, while named accounts stay discoverable from a homeserver and user id once cached credentials cover auth. When repair or setup promotes a single-account config to multi-account, an existing named account is preserved, only the auth and bootstrap keys move into the promoted account, and shared delivery-policy keys stay at the top level.

Reachability and targets

• Private and internal homeservers are blocked by default for SSRF protection; a per-account private-network opt-in allows localhost, LAN or Tailscale addresses and internal hostnames, also settable from the account-add command, while public cleartext homeservers stay blocked and HTTPS is preferred whenever possible.
• An explicit outbound proxy setting routes Matrix traffic through an HTTP or HTTPS proxy, overridable per named account, and the same proxy serves runtime traffic and account status probes.
• Targets take three forms wherever OpenClaw asks for a room or user: users as a Matrix id with optional user or matrix-user prefixes, rooms as a room id with optional room prefixes, where newer room versions have no server suffix, and aliases with optional channel prefixes. Room ids must keep their exact casing, since internal session keys are canonical lowercase and not a source for delivery ids; user lookups query the homeserver’s user directory, room lookups accept ids and aliases directly, joined-room name lookup is best-effort and applies to runtime allowlists only under the dangerous name-matching flag, and an unresolvable room name is ignored.

OpenClaw on Matrix is the channel post this deepens, and OpenClaw Matrix encryption and verification the companion page whose commands all take the same account flag.

On Diali

Matrix is on Diali’s connectable list, alongside WhatsApp, Telegram, Discord, Slack, Mattermost, SMS and voice: the homeserver account and the room allowlist are yours, the Gateway is ours. Connect your first channel in five minutes explains how those are linked, and Diali security the boundary that applies to each.

Why the refusal to guess

Refusing to pick an account when several exist is the same instinct as the case-sensitivity rule: a Matrix command that lands on the wrong account or room is worse than one that stops and asks. Hosted OpenClaw on Diali is the assistant and OpenClaw channel routing the general routing that these targets feed.

• Top-level values are defaults; accounts override.
• Private homeservers need an opt-in; cleartext stays blocked.
• Exact room id casing; the CLI never guesses an account.