- Room allowlist entries accept room IDs and aliases directly. Prefer `!room:server` or `#alias:server`; unresolved names are ignored at runtime by allowlist resolution.

- In invite auto-join allowlist mode, use only stable invite targets: `!roomId:server`, `#alias:server`, or `*`. Plain room names are rejected.

- To resolve room names before saving, use `openclaw channels resolve --channel matrix "Project Room"`.

- When setup enables E2EE, OpenClaw writes the encryption config and runs the

same verification bootstrap used by `openclaw matrix encryption setup`.

<Warning>

`channels.matrix.autoJoin` defaults to `off`.

In encrypted (E2EE) rooms, outbound image events use `thumbnail_file` so image previews are encrypted alongside the full attachment. Unencrypted rooms still use plain `thumbnail_url`. No configuration is needed — the plugin detects E2EE state automatically.

Enable encryption:

Recommended setup flow:

```bash

openclaw matrix encryption setup

```

This enables `channels.matrix.encryption`, bootstraps Matrix secret storage and

cross-signing, creates room-key backup state when needed, then prints the

current verification and backup status with next steps.

For a new account, enable E2EE during account creation:

```bash

openclaw matrix account add \

--homeserver https://matrix.example.org \

--access-token syt_xxx \

--enable-e2ee

```

Multi-account setups can target a specific account:

```bash

openclaw matrix encryption setup --account assistant

```

Manual config equivalent:

```json5

{

registerMatrixFullRuntime(api);

expect(runtimeMocks.ensureMatrixCryptoRuntime).not.toHaveBeenCalled();

expect(on.mock.calls.map(([hookName]) => hookName)).toEqual([

"subagent_spawning",

"subagent_ended",

defineBundledChannelEntry,

type OpenClawPluginApi,

} from "openclaw/plugin-sdk/channel-entry-contract";

import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";

import { registerMatrixCliMetadata } from "./cli-metadata.js";

import { registerMatrixSubagentHooks } from "./subagent-hooks-api.js";

}

export function registerMatrixFullRuntime(api: OpenClawPluginApi): void {

void loadMatrixHandlersRuntimeModule()

.then(({ ensureMatrixCryptoRuntime }) =>

ensureMatrixCryptoRuntime({ log: api.logger.info }).catch((err: unknown) => {

const message = formatErrorMessage(err);

api.logger.warn?.(`matrix: crypto runtime bootstrap failed: ${message}`);

}),

)

.catch((err: unknown) => {

const message = formatErrorMessage(err);

api.logger.warn?.(`matrix: failed loading crypto bootstrap runtime: ${message}`);

});

api.registerGatewayMethod("matrix.verify.recoveryKey", async (ctx) => {

const { handleVerifyRecoveryKey } = await loadMatrixHandlersRuntimeModule();

await handleVerifyRecoveryKey(ctx);

expect(verificationMocks.bootstrapMatrixVerification).toHaveBeenCalledWith({

accountId: "default",

cfg: nextCfg,

});

expect(log).toHaveBeenCalledWith('Matrix verification bootstrap: complete for "default".');

expect(log).toHaveBeenCalledWith('Matrix backup version for "default": 7');

expect(error).not.toHaveBeenCalled();

});

it("bootstraps verification when setup enables encryption for an existing account", async () => {

const previousCfg = {

channels: {

matrix: {

homeserver: "https://matrix.example.org",

userId: "@flurry:example.org",

accessToken: "token",

encryption: false,

},

},

} as CoreConfig;

const nextCfg = {

channels: {

matrix: {

homeserver: "https://matrix.example.org",

userId: "@flurry:example.org",

accessToken: "token",

encryption: true,

},

},

} as CoreConfig;

mockBootstrapResult({ success: true, backupVersion: "8" });

await runAfterAccountConfigWritten({

previousCfg,

nextCfg,

accountId: "default",

input: {},

});

expect(verificationMocks.bootstrapMatrixVerification).toHaveBeenCalledWith({

accountId: "default",

cfg: nextCfg,

});

expect(log).toHaveBeenCalledWith('Matrix verification bootstrap: complete for "default".');

expect(log).toHaveBeenCalledWith('Matrix backup version for "default": 8');

});

it("logs a warning when verification bootstrap fails", async () => {

const { previousCfg, nextCfg, accountId, input } = applyDefaultAccountConfig();

mockBootstrapResult({

expect(verificationMocks.bootstrapMatrixVerification).toHaveBeenCalledWith({

accountId: "default",

cfg: nextCfg,

});

expect(log).toHaveBeenCalledWith('Matrix verification bootstrap: complete for "default".');

},