openclaw
diff --git a/‎docs/channels/matrix.md‎
Lines changed: 28 additions & 1 deletion b/‎docs/channels/matrix.md‎
Lines changed: 28 additions & 1 deletion
diff --git a/‎extensions/matrix/index.test.ts‎
Lines changed: 1 addition & 0 deletions b/‎extensions/matrix/index.test.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎extensions/matrix/index.ts‎
Lines changed: 0 additions & 13 deletions b/‎extensions/matrix/index.ts‎
Lines changed: 0 additions & 13 deletions
diff --git a/‎extensions/matrix/src/channel.setup.test.ts‎
Lines changed: 40 additions & 0 deletions b/‎extensions/matrix/src/channel.setup.test.ts‎
Lines changed: 40 additions & 0 deletions
@@ -68,6 +68,8 @@ Key wizard behaviors:
 - 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`.
@@ -292,7 +294,32 @@ Use strict room allowlists and mention requirements when enabling bot-to-bot tra
 
 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
 {
 
@@ -116,6 +116,7 @@ describe("matrix plugin", () => {
 
     registerMatrixFullRuntime(api);
 
+    expect(runtimeMocks.ensureMatrixCryptoRuntime).not.toHaveBeenCalled();
     expect(on.mock.calls.map(([hookName]) => hookName)).toEqual([
       "subagent_spawning",
       "subagent_ended",
 
@@ -2,7 +2,6 @@ import {
   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";
 
@@ -16,18 +15,6 @@ function loadMatrixHandlersRuntimeModule() {
 }
 
 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);
 
@@ -138,6 +138,7 @@ describe("matrix setup post-write bootstrap", () => {
 
     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');
@@ -177,6 +178,44 @@ describe("matrix setup post-write bootstrap", () => {
     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({
@@ -207,6 +246,7 @@ describe("matrix setup post-write bootstrap", () => {
 
         expect(verificationMocks.bootstrapMatrixVerification).toHaveBeenCalledWith({
           accountId: "default",
+          cfg: nextCfg,
         });
         expect(log).toHaveBeenCalledWith('Matrix verification bootstrap: complete for "default".');
       },