diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
index d1347d96daa..0ed8425cd3a 100644
--- a/docs/cli/plugins.md
+++ b/docs/cli/plugins.md
@@ -68,6 +68,11 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
 Bare package names are checked against ClawHub first, then npm. Security note:
 treat plugin installs like running code. Prefer pinned versions.
 
+If config is invalid, `plugins install` normally fails closed and tells you to
+run `openclaw doctor --fix` first. The only documented exception is a narrow
+bundled-plugin recovery path for plugins that explicitly opt into
+`openclaw.install.allowInvalidConfigRecovery`.
+
 `--force` reuses the existing install target and overwrites an already-installed
 plugin or hook pack in place. Use it when you are intentionally reinstalling
 the same id from a new local path, archive, ClawHub package, or npm artifact.
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index a2b5ee8a729..630fa383f3c 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -339,13 +339,20 @@ Important examples:
 | `openclaw.install.npmSpec` / `openclaw.install.localPath`         | Install/update hints for bundled and externally published plugins.                     |
 | `openclaw.install.defaultChoice`                                  | Preferred install path when multiple install sources are available.                    |
 | `openclaw.install.minHostVersion`                                 | Minimum supported OpenClaw host version, using a semver floor like `>=2026.3.22`.      |
-| `openclaw.install.allowInvalidConfigRecovery`                     | Allows setup/install flows to offer guarded recovery when config is invalid.           |
+| `openclaw.install.allowInvalidConfigRecovery`                     | Allows a narrow bundled-plugin reinstall recovery path when config is invalid.         |
 | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Lets setup-only channel surfaces load before the full channel plugin during startup.   |
 
 `openclaw.install.minHostVersion` is enforced during install and manifest
 registry loading. Invalid values are rejected; newer-but-valid values skip the
 plugin on older hosts.
 
+`openclaw.install.allowInvalidConfigRecovery` is intentionally narrow. It does
+not make arbitrary broken configs installable. Today it only allows install
+flows to recover from specific stale bundled-plugin upgrade failures, such as a
+missing bundled plugin path or a stale `channels.<id>` entry for that same
+bundled plugin. Unrelated config errors still block install and send operators
+to `openclaw doctor --fix`.
+
 ## JSON Schema requirements
 
 - **Every plugin must ship a JSON Schema**, even if it accepts no config.
diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md
index 56ec4ffdb7f..c130d49a5c0 100644
--- a/docs/plugins/sdk-setup.md
+++ b/docs/plugins/sdk-setup.md
@@ -135,17 +135,23 @@ Example:
 
 `openclaw.install` is package metadata, not manifest metadata.
 
-| Field                        | Type                 | What it means                                                                  |
-| ---------------------------- | -------------------- | ------------------------------------------------------------------------------ |
-| `npmSpec`                    | `string`             | Canonical npm spec for install/update flows.                                   |
-| `localPath`                  | `string`             | Local development or bundled install path.                                     |
-| `defaultChoice`              | `"npm"` \| `"local"` | Preferred install source when both are available.                              |
-| `minHostVersion`             | `string`             | Minimum supported OpenClaw version in the form `>=x.y.z`.                      |
-| `allowInvalidConfigRecovery` | `boolean`            | Lets setup/install flows offer guarded recovery when plugin config is invalid. |
+| Field                        | Type                 | What it means                                                                    |
+| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
+| `npmSpec`                    | `string`             | Canonical npm spec for install/update flows.                                     |
+| `localPath`                  | `string`             | Local development or bundled install path.                                       |
+| `defaultChoice`              | `"npm"` \| `"local"` | Preferred install source when both are available.                                |
+| `minHostVersion`             | `string`             | Minimum supported OpenClaw version in the form `>=x.y.z`.                        |
+| `allowInvalidConfigRecovery` | `boolean`            | Lets bundled-plugin reinstall flows recover from specific stale-config failures. |
 
 If `minHostVersion` is set, install and manifest-registry loading both enforce
 it. Older hosts skip the plugin; invalid version strings are rejected.
 
+`allowInvalidConfigRecovery` is not a general bypass for broken configs. It is
+for narrow bundled-plugin recovery only, so reinstall/setup can repair known
+upgrade leftovers like a missing bundled plugin path or stale `channels.<id>`
+entry for that same plugin. If config is broken for unrelated reasons, install
+still fails closed and tells the operator to run `openclaw doctor --fix`.
+
 ### Deferred full load
 
 Channel plugins can opt into deferred loading with:
diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index d4ec23c1d88..c3dc2d92d85 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -56,6 +56,11 @@ If you prefer chat-native control, enable `commands.plugins: true` and use:
 The install path uses the same resolver as the CLI: local path/archive, explicit
 `clawhub:<pkg>`, or bare package spec (ClawHub first, then npm fallback).
 
+If config is invalid, install normally fails closed and points you at
+`openclaw doctor --fix`. The only recovery exception is a narrow bundled-plugin
+reinstall path for plugins that opt into
+`openclaw.install.allowInvalidConfigRecovery`.
+
 ## Plugin types
 
 OpenClaw recognizes two plugin formats: