diff --git a/CHANGELOG.md b/CHANGELOG.md
index af0e0005976..fc99a0401f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ Docs: https://docs.openclaw.ai
 - Plugins/startup: normalize startup and provider plugin enablement through registry aliases so boot paths do not need the legacy manifest alias scan. Thanks @vincentkoc.
 - Providers/plugins: resolve provider ownership, provider discovery scopes, and catalog-hook provider ids from the cold plugin registry instead of rescanning manifests on those paths. Thanks @vincentkoc.
 - Plugins/chat commands: refresh the persisted plugin registry after `/plugins enable` and `/plugins disable`, matching the CLI mutation path. Thanks @vincentkoc.
+- Plugins/compat: mark `OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY` as a deprecated break-glass switch and point operators at registry repair instead. Thanks @vincentkoc.
 - Diagnostics/OTEL: add bounded outbound message delivery lifecycle diagnostics and export them as low-cardinality delivery spans/metrics without message body, recipient, room, or media-path data. (#71471) Thanks @vincentkoc and @jlapenna.
 - Diagnostics/OTEL: emit bounded exec-process diagnostics and export them as `openclaw.exec` spans without exposing command text, working directories, or container identifiers. (#71451) Thanks @vincentkoc and @jlapenna.
 - Diagnostics/OTEL: support `OPENCLAW_OTEL_PRELOADED=1` so the plugin can reuse an already-registered OpenTelemetry SDK while keeping OpenClaw diagnostic listeners wired. (#71450) Thanks @vincentkoc and @jlapenna.
diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
index 82dbc0fe010..9e4406bf334 100644
--- a/docs/cli/plugins.md
+++ b/docs/cli/plugins.md
@@ -355,6 +355,11 @@ current, or stale. Use `--refresh` to rebuild it from the durable install
 ledger, config policy, and manifest/package metadata. This is a repair path, not
 a runtime activation path.
 
+`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` is a deprecated break-glass
+compatibility switch for registry read failures. Prefer `plugins registry
+--refresh` or `openclaw doctor --fix`; the env fallback is only for emergency
+startup recovery while the migration rolls out.
+
 ### Marketplace
 
 ```bash
diff --git a/docs/plugins/compatibility.md b/docs/plugins/compatibility.md
index 819fbe1b568..ebfe08fd56a 100644
--- a/docs/plugins/compatibility.md
+++ b/docs/plugins/compatibility.md
@@ -86,6 +86,8 @@ Current compatibility records include:
   toward `agentRuntime`
 - generated bundled channel config metadata fallback while registry-first
   `channelConfigs` metadata lands
+- the persisted plugin registry disable env while repair flows migrate operators
+  to `openclaw plugins registry --refresh` and `openclaw doctor --fix`
 
 New plugin code should prefer the replacement listed in the registry and in the
 specific migration guide. Existing plugins can keep using a compatibility path
diff --git a/src/plugins/compat/registry.ts b/src/plugins/compat/registry.ts
index d7473508ad2..282da5406fc 100644
--- a/src/plugins/compat/registry.ts
+++ b/src/plugins/compat/registry.ts
@@ -210,6 +210,19 @@ export const PLUGIN_COMPAT_RECORDS = [
     diagnostics: ["channel config metadata fallback"],
     tests: ["src/plugins/contracts/config-footprint-guardrails.test.ts"],
   },
+  {
+    code: "disable-persisted-plugin-registry-env",
+    status: "deprecated",
+    owner: "config",
+    introduced: "2026-04-25",
+    deprecated: "2026-04-25",
+    warningStarts: "2026-04-25",
+    replacement: "`openclaw plugins registry --refresh` and `openclaw doctor --fix`",
+    docsPath: "/cli/plugins#registry",
+    surfaces: ["OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY", "plugin registry reads"],
+    diagnostics: ["persisted-registry-disabled"],
+    tests: ["src/plugins/plugin-registry.test.ts"],
+  },
 ] as const satisfies readonly PluginCompatRecord[];
 
 export type PluginCompatCode = (typeof PLUGIN_COMPAT_RECORDS)[number]["code"];
diff --git a/src/plugins/plugin-registry.test.ts b/src/plugins/plugin-registry.test.ts
index 884ec38fda4..4e3fb663fa9 100644
--- a/src/plugins/plugin-registry.test.ts
+++ b/src/plugins/plugin-registry.test.ts
@@ -290,7 +290,10 @@ describe("plugin registry facade", () => {
 
     expect(result.source).toBe("derived");
     expect(result.diagnostics).toEqual([
-      expect.objectContaining({ code: "persisted-registry-disabled" }),
+      expect.objectContaining({
+        code: "persisted-registry-disabled",
+        message: expect.stringContaining("deprecated break-glass compatibility switch"),
+      }),
     ]);
     expect(listPluginRecords({ index: result.snapshot }).map((plugin) => plugin.pluginId)).toEqual([
       "demo",
diff --git a/src/plugins/plugin-registry.ts b/src/plugins/plugin-registry.ts
index 7f30d778df3..9377ac02330 100644
--- a/src/plugins/plugin-registry.ts
+++ b/src/plugins/plugin-registry.ts
@@ -45,6 +45,10 @@ export type PluginRegistrySnapshotResult = {
 
 export const DISABLE_PERSISTED_PLUGIN_REGISTRY_ENV = "OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY";
 
+function formatDeprecatedPersistedRegistryDisableWarning(): string {
+  return `${DISABLE_PERSISTED_PLUGIN_REGISTRY_ENV} is a deprecated break-glass compatibility switch; use \`openclaw plugins registry --refresh\` or \`openclaw doctor --fix\` to repair registry state.`;
+}
+
 export type LoadPluginRegistryParams = LoadInstalledPluginIndexParams &
   InstalledPluginIndexStoreOptions & {
     index?: PluginRegistrySnapshot;
@@ -175,7 +179,7 @@ export function loadPluginRegistrySnapshotWithMetadata(
       level: "warn",
       code: "persisted-registry-disabled",
       message: disabledByEnv
-        ? `${DISABLE_PERSISTED_PLUGIN_REGISTRY_ENV} is set; using legacy derived plugin index.`
+        ? `${formatDeprecatedPersistedRegistryDisableWarning()} Using legacy derived plugin index.`
         : "Persisted plugin registry reads are disabled by the caller; using derived plugin index.",
     });
   }