OpenClaw Matrix setup

Matrix is the one channel where OpenClaw is just another client on a homeserver you choose, so setup is mostly about credentials and invitations: how the bot logs in, which invites it accepts, and how allowlist entries have to be written. Here are the install, the auth options and the wizard, the auto-join rule that surprises people, the target formats, and the environment and cache details.

Install and auth

• The plugin installs with the plugins install command for the Matrix package, from npm first with a fallback to its declared ClawHub package only when the npm target is unavailable, with npm or clawhub prefixes to force a source and a local checkout path for development; the install registers and enables the plugin, and the channel does nothing until configured.
• Setup is four steps: create a Matrix account on the homeserver, configure the channel block with the homeserver and an access token or with the homeserver, a user ID and a password, where the token is created in a client or the admin UI and password auth mints and caches one on first login, check the status probe and start the gateway if it is offline, then start a DM or invite the bot to a room, remembering that fresh invites only land when auto-join allows them.
• The interactive path is the channels add command or the configure command's channels section: the wizard asks for the homeserver URL, the auth method, the user ID for password auth, an optional device name, whether to enable E2EE, and room access and auto-join, offers an env-var shortcut when matching Matrix variables exist and the account has no saved auth, resolves room names through the channels resolve command before saving an allowlist, and enabling E2EE runs the same bootstrap as the encryption setup command.
• The minimal token config enables the channel with the homeserver, the token and a pairing DM policy, the password config adds the user ID, the password and a device name with the token cached after first login, and token and password SecretRefs follow the shared provider-alias rules, including for named accounts, where an explicit env provider still enforces its allowlist and an empty allowlist denies every variable.

OpenClaw cannot tell at invite time whether an invite is a DM or a group, so every invite goes through autoJoin first; dm.policy only applies later, after the bot has joined and the room is classified.

Auto-join and introductions

Auto-join defaults to off, so the bot will not appear in new rooms or DMs from fresh invites until you join manually; because OpenClaw cannot tell at invite time whether an invite is a DM or a group, every invite passes auto-join first and the DM policy applies only after the bot has joined and the room is classified. The allowlist mode with an invite allowlist restricts accepted invites and the always mode accepts every invite; the invite allowlist accepts only a literal room ID, in the full form or the suffixless form of room version 12 and later, an alias with its server, or the wildcard, and plain room names are rejected because aliases resolve against the homeserver rather than against state the invited room claims. The docs' example allows an ops room by ID and a support room by alias with a mention requirement on the ops room. When the bot joins an allowed group room it posts one introduction grounded in the room name, topic and up to a hundred readable recent messages, using only the metadata when reading history fails and never inventing activity; introductions are on by default, disabled with the join-intro key or per account, never sent to direct rooms, and triggered only by an actual join transition rather than an unaccepted invite, a startup snapshot or a profile update.

Targets, accounts, credentials, environment

• Matrix user IDs are case-sensitive, so every allowlist, approver and approval-target field must carry the exact user-at-server value Matrix reports, and a config with different casing has to be fixed by hand because case-distinct IDs can be different users; DM and room sender fields take the user form with display names ignored unless the dangerous name-matching switch is on, approval forwarding targets take the user prefix with exact casing, room allowlist keys take a room ID or an alias with plain names ignored unless the switch is on, and invite allowlists take a room ID, an alias or the wildcard with plain names always rejected.
• The wizard normalises a friendly account name into an account ID, with punctuation hex-escaped in scoped environment variable names so accounts cannot collide, a hyphen becoming an escaped code so an ops-prod account maps to its own prefix; credentials are cached in the shared plugin SQLite state, so cached credentials make Matrix count as configured even without a token in the config file for setup, the doctor and status probes, and upgrades import the retired credential files through the doctor fix, verify the rows and archive the files.
• Config-backed environment variables cover the homeserver, access token, user ID, password, device ID and device name, unprefixed for the default account and with the account token inserted for named accounts, the homeserver variable cannot come from a workspace env file, and the recovery key is never read from the environment by OpenClaw itself, the CLI only suggesting a shell variable to pipe it through; the practical baseline enables the channel with a token and E2EE, a pairing DM policy with per-room session scope and thread replies off, an allowlist group policy with an admin sender and a mention-required room, an invite allowlist, inbound thread replies, reply mode off and partial streaming.

OpenClaw on Matrix is the channel post this setup belongs to, and OpenClaw Matrix encryption the E2EE bootstrap the wizard can run.

Invites before policy

The auto-join rule is the one to remember: a DM policy of pairing does nothing for a bot that never joined, because the invite was refused at the door. OpenClaw Matrix access control covers the room and DM policies that apply once it is inside, and Connect your first channel in five minutes the walkthrough for a channel with no homeserver to choose.

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. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• Token or password; the password mints and caches a token.
• Auto-join is off; invites pass it before any DM policy.
• User IDs are case-sensitive in every allowlist.