From 2f90831b6885d84a15a6845be550ede493d3743e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 25 Apr 2026 18:40:18 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@888448facc1b9d1b65d8da83d734190dcbd7d1ba --- .openclaw-sync/source.json | 4 ++-- docs/.generated/config-baseline.sha256 | 4 ++-- docs/cli/plugins.md | 23 ++++++++++++++++++----- docs/gateway/configuration-reference.md | 11 ++++++++--- docs/plugins/architecture-internals.md | 8 +++++--- 5 files changed, 35 insertions(+), 15 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 333e9c90b..18e58204c 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f204f0c9994fe5cc39cee5f165d597eb5b18ff2a", - "syncedAt": "2026-04-25T18:36:49.920Z" + "sha": "888448facc1b9d1b65d8da83d734190dcbd7d1ba", + "syncedAt": "2026-04-25T18:38:46.902Z" } diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 5ea41f550..0aafcd4e1 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -439ff58a4a54f0f4bda959239f382cc3b2f94a282680dcd89bd3f8c93e0f07d0 config-baseline.json -6ef86147534d12aa5ac7a9cf208b4627177090c92479a71dfd1791096d20353b config-baseline.core.json +c8d24c55df89a76f44cd6ab5fdb7c28b0b3a8adadcd2c94a1d81263512075c0f config-baseline.json +97c37380e03c167ee710adb0ee297573146e78434635780226b744841628370b config-baseline.core.json 7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3 config-baseline.channel.json 7825b56a5b3fcdbe2e09ef8fe5d9f12ac3598435afebe20413051e45b0d1968e config-baseline.plugin.json diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 9e4406bf3..c9637730c 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -231,7 +231,19 @@ 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 -`plugins.installs` while keeping the default behavior unpinned. +the managed install ledger while keeping the default behavior unpinned. + +### Install Ledger + +Plugin install metadata is machine-managed state, not user config. New 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 @@ -241,8 +253,9 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`, -the plugin allowlist, and linked `plugins.load.paths` entries when applicable. +`uninstall` removes plugin records from `plugins.entries`, the managed install +ledger, the plugin allowlist, and linked `plugins.load.paths` entries when +applicable. For active memory plugins, the memory slot resets to `memory-core`. By default, uninstall also removes the plugin install directory under the active @@ -261,8 +274,8 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Updates apply to tracked installs in `plugins.installs` and tracked hook-pack -installs in `hooks.internal.installs`. +Updates apply to tracked plugin installs in the managed install ledger and +tracked hook-pack installs in `hooks.internal.installs`. When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. That means previously stored dist-tags such as `@beta` and exact pinned diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index ec916e481..614ea8ae3 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -186,9 +186,14 @@ 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`: CLI-managed install metadata used by `openclaw plugins update`. - - Includes `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Treat `plugins.installs.*` as managed state; prefer CLI commands over manual edits. +- `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/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index 5d2895ba6..203e8a9d9 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -911,13 +911,15 @@ Official external npm entries should prefer an exact `npmSpec` plus `expectedIntegrity`. Bare package names and dist-tags still work for 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 -`plugins.installs` entry with `source: "path"` and a workspace-relative +When onboarding installs from a local catalog path, it records a managed plugin +install ledger 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. +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. ## Context engine plugins