OpenClaw on Matrix

Matrix is a downloadable channel plugin built on the official Matrix SDK, and it covers more of the protocol than most bots: DMs, rooms, threads, media, reactions, polls, location, and end-to-end encryption. Node is the recommended runtime and encryption needs the SDK’s native crypto bindings for your platform. Here is the install and the two ways to authenticate, the auto-join rule that surprises people first, the encryption and verification pages, and the account rules the docs are strict about.

Setup

• Install the plugin; it comes from npm first and falls back to its ClawHub package, and the install registers and enables it, though the channel does nothing until configured.
• Configure a homeserver plus an access token, or a homeserver plus a user id and password, in which case the first login mints and caches a token; then probe the channel status and start the Gateway if it is offline.
• Or take the wizard: homeserver URL, auth method, user id for password auth, an optional device name, whether to enable encryption, and room access; existing Matrix environment variables can be adopted, and room names should be resolved to ids before an allowlist is saved.

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 allowlists

Auto-join defaults to off, so the bot appears in no new room or DM from a fresh invite until you join manually. An allowlist accepts only literal room ids, aliases or a wildcard, never plain room names, and always accepts every invite. When the bot joins an allowed group room it posts one introduction grounded in the room’s name, topic and recent messages, never in a direct room, and that can be turned off. User ids are case-sensitive and copied exactly; display names are ignored unless you set the flag whose name starts with dangerously.

Encryption

• The encryption page covers enabling E2EE, verifying the Gateway device with a recovery key, bootstrapping or repairing cross-signing, room-key backup and the crypto store layout, with per-account notes.
• Enabling encryption in the wizard runs the same bootstrap as the encryption setup command.
• The migration page covers the limits of encrypted-state recovery and the upgrade flow, which is the reading before any move of the Gateway to another machine.

OpenClaw security best practices is the wider checklist, and OpenClaw not responding the ladder for a bot that joined and says nothing.

Accounts and homeservers

Several accounts sit under named entries that inherit the top-level values; a private or LAN homeserver needs the private-network flag, a proxy can be set per account, and the token and password accept secret references under the shared provider-alias rules. The OpenClaw config file explains where those references resolve.

On Diali

Matrix is on Diali’s connectable list: the plugin, the runtime and the crypto bindings are ours to run, and the homeserver account and the room allowlist are yours. Hosted OpenClaw on Diali is the assistant and Security on Diali describes the boundary.

• Token or password; the password path caches a token.
• Auto-join is off; invites wait for you or for an allowlist of room ids.
• E2EE needs the native bindings and a verified device.