mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 07:50:43 +00:00
docs: describe plugin install index store
This commit is contained in:
Shakker
@@ -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 <id> --dry-run
|
||||
openclaw plugins uninstall <id> --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
|
||||
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -266,7 +266,7 @@ openclaw plugins info <id> # 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 <package> # install (ClawHub first, then npm)
|
||||
openclaw plugins install clawhub:<pkg> # install from ClawHub only
|
||||
@@ -280,7 +280,7 @@ openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # update one plugin
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update --all # update all
|
||||
openclaw plugins uninstall <id> # remove config and install ledger records
|
||||
openclaw plugins uninstall <id> # remove config and plugin index records
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --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 <id-or-npm-spec>` 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.
|
||||
|
||||
Reference in New Issue
Block a user