From 37ce39b5c5ce4e06afc2244b07187454c5cae927 Mon Sep 17 00:00:00 2001 From: Shakker Date: Sat, 25 Apr 2026 23:07:05 +0100 Subject: [PATCH] docs: describe plugin install index store --- docs/cli/plugins.md | 21 ++++++++------------- docs/gateway/configuration-reference.md | 11 +---------- docs/gateway/security/audit-checks.md | 6 +++--- docs/plugins/architecture-internals.md | 12 ++++-------- docs/tools/plugin.md | 10 +++------- 5 files changed, 19 insertions(+), 41 deletions(-) diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 3f4e763f4d9..e324cf9c4d7 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -232,20 +232,15 @@ openclaw plugins install -l ./my-plugin source path instead of copying over a managed install target. Use `--pin` on npm installs to save the resolved exact spec (`name@version`) in -the managed install ledger while keeping the default behavior unpinned. +the managed plugin index while keeping the default behavior unpinned. -### Install Ledger +### Plugin Index -Plugin install metadata is machine-managed state, not user config. New installs +Plugin install metadata is machine-managed state, not user config. Installs and updates write it to `plugins/installs.json` under the active OpenClaw state directory. The file includes a do-not-edit warning and is used by `openclaw plugins update`, uninstall, diagnostics, and the cold plugin registry. -Legacy `plugins.installs` entries in `openclaw.json` remain readable as a -deprecated compatibility fallback. When install/update/uninstall paths rewrite -plugin install state, OpenClaw writes the ledger file and removes -`plugins.installs` from the persisted config payload. - ### Uninstall ```bash @@ -254,8 +249,8 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` removes plugin records from `plugins.entries`, the managed install -ledger, the plugin allowlist, and linked `plugins.load.paths` entries when +`uninstall` removes plugin records from `plugins.entries`, the persisted plugin +index, the plugin allowlist, and linked `plugins.load.paths` entries when applicable. For active memory plugins, the memory slot resets to `memory-core`. @@ -275,7 +270,7 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Updates apply to tracked plugin installs in the managed install ledger and +Updates apply to tracked plugin installs in the managed plugin index and tracked hook-pack installs in `hooks.internal.installs`. When you pass a plugin id, OpenClaw reuses the recorded install spec for that @@ -365,8 +360,8 @@ Normal startup, provider owner lookup, channel setup classification, and plugin inventory can read it without importing plugin runtime modules. Use `plugins registry` to inspect whether the persisted registry is present, -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 +current, or stale. Use `--refresh` to rebuild it from the persisted plugin +index, 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 diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 52b98097267..6d60f337140 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -187,16 +187,7 @@ See [MCP](/cli/mcp#openclaw-as-an-mcp-client-registry) and - Enabled Claude bundle plugins can also contribute embedded Pi defaults from `settings.json`; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches. - `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins. - `plugins.slots.contextEngine`: pick the active context engine plugin id; defaults to `"legacy"` unless you install and select another engine. -- `plugins.installs`: deprecated compatibility fallback for legacy - CLI-managed install metadata. New plugin installs write the managed - `plugins/installs.json` state ledger instead. - - Legacy records include `source`, `spec`, `sourcePath`, `installPath`, - `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, - `shasum`, `resolvedAt`, `installedAt`. - - Treat `plugins.installs.*` as managed state; prefer CLI commands over - manual edits. - -See [Plugins](/tools/plugin). + See [Plugins](/tools/plugin). --- diff --git a/docs/gateway/security/audit-checks.md b/docs/gateway/security/audit-checks.md index c0c95f3acfb..d862c997c93 100644 --- a/docs/gateway/security/audit-checks.md +++ b/docs/gateway/security/audit-checks.md @@ -97,9 +97,9 @@ exhaustive): | `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` includes mutable or risky directories | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | no | | `skills.workspace.symlink_escape` | warn | Workspace `skills/**/SKILL.md` resolves outside workspace root (symlink-chain drift) | workspace `skills/**` filesystem state | no | | `plugins.extensions_no_allowlist` | warn | Plugins are installed without an explicit plugin allowlist | `plugins.allowlist` | no | -| `plugins.installs_unpinned_npm_specs` | warn | Plugin install records are not pinned to immutable npm specs | plugin install metadata | no | -| `plugins.installs_missing_integrity` | warn | Plugin install records lack integrity metadata | plugin install metadata | no | -| `plugins.installs_version_drift` | warn | Plugin install records drift from installed packages | plugin install metadata | no | +| `plugins.index_unpinned_npm_specs` | warn | Plugin install records are not pinned to immutable npm specs | plugin install metadata | no | +| `plugins.index_missing_integrity` | warn | Plugin install records lack integrity metadata | plugin install metadata | no | +| `plugins.index_version_drift` | warn | Plugin install records drift from installed packages | plugin install metadata | no | | `plugins.code_safety` | warn/critical | Plugin code scan found suspicious or dangerous patterns | plugin code / install source | no | | `plugins.code_safety.entry_path` | warn | Plugin entry path points into hidden or `node_modules` locations | plugin manifest `entry` | no | | `plugins.code_safety.entry_escape` | critical | Plugin entry escapes the plugin directory | plugin manifest `entry` | no | diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index 1d5bdf25515..e3a13a76e8d 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -905,7 +905,7 @@ normalized facts warn if the parsed npm package name drifts from that identity. They also warn when `defaultChoice` is invalid or points at a source that is not available, and when npm integrity metadata is present without a valid npm source. Consumers should treat `installSource` as an additive optional field so -older hand-built entries and compatibility shims do not have to synthesize it. +hand-built entries and catalog shims do not have to synthesize it. This lets onboarding and diagnostics explain source-plane state without importing plugin runtime. @@ -914,17 +914,13 @@ Official external npm entries should prefer an exact `npmSpec` plus compatibility, but they surface source-plane warnings so the catalog can move toward pinned, integrity-checked installs without breaking existing plugins. When onboarding installs from a local catalog path, it records a managed plugin -install ledger entry with `source: "path"` and a workspace-relative +plugin index entry with `source: "path"` and a workspace-relative `sourcePath` when possible. The absolute operational load path stays in `plugins.load.paths`; the install record avoids duplicating local workstation paths into long-lived config. This keeps local development installs visible to source-plane diagnostics without adding a second raw filesystem-path disclosure -surface. Legacy `plugins.installs` config entries are still read as a -compatibility fallback while the state-managed `plugins/installs.json` ledger -becomes the install source of truth. -`openclaw doctor --fix` migrates those legacy config entries into the managed -ledger and refreshes the cold registry index without loading plugin runtime -modules. +surface. The persisted `plugins/installs.json` plugin index is the install +source of truth and can be refreshed without loading plugin runtime modules. ## Context engine plugins diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index ca336e630da..aba665f97cf 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -266,7 +266,7 @@ openclaw plugins info # inspect alias openclaw plugins doctor # diagnostics openclaw plugins registry # inspect persisted registry state openclaw plugins registry --refresh # rebuild persisted registry -openclaw doctor --fix # repair registry/ledger migration state +openclaw doctor --fix # repair plugin registry state openclaw plugins install # install (ClawHub first, then npm) openclaw plugins install clawhub: # install from ClawHub only @@ -280,7 +280,7 @@ openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # update one plugin openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # update all -openclaw plugins uninstall # remove config and install ledger records +openclaw plugins uninstall # remove config and plugin index records openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -306,12 +306,8 @@ OpenClaw keeps a persisted local plugin registry as the cold read model for plugin inventory, contribution ownership, and startup planning. Install, update, uninstall, enable, and disable flows refresh that registry after changing plugin state. If the registry is missing, stale, or invalid, `openclaw plugins registry ---refresh` rebuilds it from the durable install ledger, config policy, and +--refresh` rebuilds it from the durable plugin index, config policy, and manifest/package metadata without loading plugin runtime modules. -If a machine still has legacy `plugins.installs` records in config, run -`openclaw doctor --fix` to move them into the managed -`plugins/installs.json` ledger and remove the config copy. - `openclaw plugins update ` applies to tracked installs. Passing an npm package spec with a dist-tag or exact version resolves the package name back to the tracked plugin record and records the new spec for future updates.