diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index be4a7bccd..5b011d08d 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "f1edd601bc28e6aba2a49b17db1bbee4d7fe30b6",
-  "syncedAt": "2026-04-27T23:06:37.193Z"
+  "sha": "2fbbc6e2faa038ddc38c3cd53329b2a2c567c6ed",
+  "syncedAt": "2026-04-27T23:08:00.522Z"
 }
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
index a1d6d037d..3a7c78939 100644
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -86,6 +86,7 @@ cat ~/.openclaw/openclaw.json
     - Legacy plugin manifest contract key migration (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
     - Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
     - Legacy agent runtime-policy migration to `agents.defaults.agentRuntime` and `agents.list[].agentRuntime`.
+    - Stale plugin config cleanup when plugins are enabled; when `plugins.enabled=false`, stale plugin references are treated as inert containment config and are preserved.
   </Accordion>
   <Accordion title="State and integrity">
     - Session lock file inspection and stale lock cleanup.
diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index e33143a44..52a0df329 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -72,6 +72,10 @@ logs warnings and skips that channel instead of blocking every other channel.
 Run `openclaw doctor --fix` to remove the stale channel/plugin entries; unknown
 channel keys without stale-plugin evidence still fail validation so typos stay
 visible.
+If `plugins.enabled: false` is set, stale plugin references are treated as inert:
+Gateway startup skips plugin discovery/load work and `openclaw doctor` preserves
+the disabled plugin config instead of auto-removing it. Re-enable plugins before
+running doctor cleanup if you want stale plugin ids removed.
 
 Packaged OpenClaw installs do not eagerly install every bundled plugin's
 runtime dependency tree. When a bundled OpenClaw-owned plugin is active from
@@ -248,7 +252,7 @@ even when source overlay mounts are present.
 
 ### Enablement rules
 
-- `plugins.enabled: false` disables all plugins
+- `plugins.enabled: false` disables all plugins and skips plugin discovery/load work
 - `plugins.deny` always wins over allow
 - `plugins.entries.\<id\>.enabled: false` disables that plugin
 - Workspace-origin plugins are **disabled by default** (must be explicitly enabled)
@@ -257,6 +261,8 @@ even when source overlay mounts are present.
 - Some bundled opt-in plugins are enabled automatically when config names a
   plugin-owned surface, such as a provider model ref, channel config, or harness
   runtime
+- Stale plugin config is preserved while `plugins.enabled: false` is active;
+  re-enable plugins before running doctor cleanup if you want stale ids removed
 - OpenAI-family Codex routes keep separate plugin boundaries:
   `openai-codex/*` belongs to the OpenAI plugin, while the bundled Codex
   app-server plugin is selected by `agentRuntime.id: "codex"` or legacy