vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 04:50:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify bundled plugin recovery refs

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-04 13:24:04 +01:00
parent 56960e33e6
commit c89d4857e4
4 changed files with 31 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/cli/plugins.md
View File

@@ -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.

9
docs/plugins/manifest.md
View File

@@ -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.

20
docs/plugins/sdk-setup.md
View File

@@ -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:

5
docs/tools/plugin.md
View File

@@ -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: