diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 083acb7e0..03a97ea8a 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "8e12c24d17218dc50023aaf5543df1b7c36520aa", - "syncedAt": "2026-04-25T23:59:57.116Z" + "sha": "6ed642a86ddbea83e0f84186de47613a1a146d35", + "syncedAt": "2026-04-26T00:06:36.229Z" } diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 5f09ae36e..29f1ed94d 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -3b9a8841973205560a5396e7a18d301852941a95a561900984ad618e69a99d05 config-baseline.json -089ab9493c8482687f19da89d37e069fc402543696c92e6e3be86072c1e48c68 config-baseline.core.json +f5236ba3f34837485d1e319262d4d73ecd46ea8890d3f4c26a069834f376b796 config-baseline.json +484b36513ecb4a13cc945c3916fbe5ac712b5e0ab2c4ffa2dc811758da4ec7a6 config-baseline.core.json 7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3 config-baseline.channel.json 17eb3f8887193579ff32e35f9bd520ba2bd6049e52ab18855c5d41fcbf195d83 config-baseline.plugin.json diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 3f4e763f4..8e72120c2 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -232,19 +232,17 @@ 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. +directory. Its top-level `installRecords` map is the durable source of install +metadata, including records for broken or missing plugin manifests. The +`plugins` array is the manifest-derived cold registry cache. The file includes a +do-not-edit warning and is used by `openclaw plugins update`, uninstall, +diagnostics, and the cold plugin registry. ### Uninstall @@ -254,8 +252,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 +273,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 +363,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 52b980972..b4551df67 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -187,14 +187,6 @@ 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). diff --git a/docs/gateway/security/audit-checks.md b/docs/gateway/security/audit-checks.md index c0c95f3ac..b97df3930 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.installs_unpinned_npm_specs` | warn | Plugin index records are not pinned to immutable npm specs | plugin install metadata | no | +| `plugins.installs_missing_integrity` | warn | Plugin index records lack integrity metadata | plugin install metadata | no | +| `plugins.installs_version_drift` | warn | Plugin index 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 1d5bdf255..89b3fd945 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,15 @@ 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. +Its `installRecords` map is durable even when a plugin manifest is missing or +invalid; its `plugins` array is a rebuildable manifest/cache view. ## Context engine plugins diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index ca336e630..fb36bef75 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 @@ -305,13 +305,11 @@ immediately loadable after restart. 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 +state. The same `plugins/installs.json` file keeps durable install metadata in +top-level `installRecords` and rebuildable manifest metadata in `plugins`. If +the registry is missing, stale, or invalid, `openclaw plugins registry +--refresh` rebuilds its manifest view from install records, 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.