OpenClaw Matrix encryption and verification

Encrypted Matrix rooms only work when the Gateway’s device is trusted by the account that owns it, and trust on Matrix is a chain: secret storage, cross-signing keys, a verified device and a room-key backup. OpenClaw wraps that chain in a small set of commands and is explicit about what each trust signal proves. Here is how encryption is enabled, how status and verification work, how cross-signing is bootstrapped or repaired, how backups are restored or reset, the SAS commands, and the operational notes.

Enabling and status

• In encrypted rooms outbound image events use an encrypted thumbnail file so previews are encrypted alongside the attachment, with no configuration since the plugin detects the room’s encryption state; every Matrix command accepts verbose, JSON and account flags, and output is concise by default.
• The encryption setup command bootstraps secret storage and cross-signing and creates a room-key backup if needed, with the recovery key read from stdin so it never appears in process arguments and a deliberate flag to discard the current cross-signing identity; a new account can enable encryption at creation, and both paths finish their client operations before saving the config so a running Gateway can reload afterwards, while a failed bootstrap still saves the setting and reports next steps.
• Verify status reports three independent signals: locally trusted, trusted by this client only; cross-signing verified, reported by the SDK; and signed by owner, a diagnostic that the device carries your self-signing key. An include-recovery-key flag only confirms a raw key is available in text output and directs you to JSON, which must then be kept private.
• Verifying the device with a recovery key over stdin reports three states, key accepted, backup usable and device verified by owner, and exits non-zero when full identity trust is incomplete even if the key unlocked backup material; finishing then means self-verification from another client, which the self-verify command waits for until cross-signing reports verified.

Verified by owner is yes only when Cross-signing verified is yes; local trust or an owner signature alone is not enough.

Repair and backup

The bootstrap command is the repair and setup path for encrypted accounts: it bootstraps secret storage reusing an existing recovery key when possible, bootstraps cross-signing and uploads missing public keys, marks and cross-signs the current device, and creates a server-side room-key backup if none exists; when the homeserver requires interactive auth to upload keys, OpenClaw tries no auth, then the dummy login stage, then password login, which needs the account password in config. Backup status shows whether a server-side backup exists and whether this device can decrypt it, restore imports backed-up room keys into the local crypto store, and an edit whose history is not fully decrypted is fixed by restoring the missing keys and retrying, or by sending a new message when the keys are gone. A backup reset replaces a broken backup with a fresh baseline, accepting the loss of unrecoverable history and optionally recreating secret storage, and a rotate flag is added only when the previous recovery key should stop unlocking the new baseline.

SAS, accounts, startup

• The verify list command shows pending requests, and verify request sends one, either self-verification with the own-user flag to be accepted in another client of the same user, or a specific user, device or room; the lower-level lifecycle commands accept a request, start the SAS flow, print the emoji or decimals, confirm or reject the match, and cancel with a reason and code, all taking DM follow-up hints when anchored to a direct room.
• Without an account flag the commands use the implicit default account, with several named accounts and no default they refuse to guess, and a named account without encryption reports its own config key. With encryption on, startup verification defaults to if-unverified: an unverified device requests self-verification in another client, skipping duplicates under a twenty-four-hour cooldown that can be tuned or switched off, and startup also runs a conservative bootstrap pass that attempts a guarded repair without a password and stays non-fatal when password auth is required.
• Verification lifecycle notices, request, ready with emoji guidance, start, completion and SAS details, post into the strict DM verification room as notices and never reach the agent pipeline; inbound requests from another client are tracked and auto-accepted, self-verification starts the SAS flow automatically and confirms its own side while you still compare in your client. A device no longer listed on the homeserver is replaced by adding the account again with a password login or a fresh access token, stale devices are listed and pruned with the devices commands, and crypto state lives under the state directory in per-account roots keyed by homeserver, user and token hash, where a lone older root is normal rotation continuity but several populated roots should be inspected and archived rather than deleted.

OpenClaw on Matrix is the channel post this deepens, and OpenClaw Matrix accounts and homeservers the companion page on multi-account layouts, private homeservers and target forms.

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.

What the trust rule buys

Insisting on cross-signing verification rather than local trust means a stolen or replayed device cannot be waved through by the Gateway itself; only the account owner, from another client, can complete the chain. Hosted OpenClaw on Diali is the assistant and OpenClaw doctor the command that surfaces crypto-state problems alongside the rest of the config.

• Setup, verify, bootstrap, backup: four commands.
• Recovery keys over stdin, never on the command line.
• Only cross-signing counts; finish from another client.