diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 0c6864ccea2..82dbc0fe010 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -31,6 +31,8 @@ openclaw plugins inspect --all openclaw plugins info openclaw plugins enable openclaw plugins disable +openclaw plugins registry +openclaw plugins registry --refresh openclaw plugins uninstall openclaw plugins doctor openclaw plugins update @@ -195,18 +197,20 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -Use `--enabled` to show only loaded plugins. Use `--verbose` to switch from the +Use `--enabled` to show only enabled plugins. Use `--verbose` to switch from the table view to per-plugin detail lines with source/origin/version/activation metadata. Use `--json` for machine-readable inventory plus registry diagnostics. -`plugins list` runs discovery from the current CLI environment and config. It is -useful for checking whether a plugin is enabled/loadable, but it is not a live -runtime probe of an already-running Gateway process. After changing plugin code, -enablement, hook policy, or `plugins.load.paths`, restart the Gateway that -serves the channel before expecting new `register(api)` code or hooks to run. -For remote/container deployments, verify you are restarting the actual -`openclaw gateway run` child, not only a wrapper process. +`plugins list` reads the persisted local plugin registry first, with a +manifest-only derived fallback when the registry is missing or invalid. It is +useful for checking whether a plugin is installed, enabled, and visible to cold +startup planning, but it is not a live runtime probe of an already-running +Gateway process. After changing plugin code, enablement, hook policy, or +`plugins.load.paths`, restart the Gateway that serves the channel before +expecting new `register(api)` code or hooks to run. For remote/container +deployments, verify you are restarting the actual `openclaw gateway run` child, +not only a wrapper process. For runtime hook debugging: @@ -333,6 +337,24 @@ For module-shape failures such as missing `register`/`activate` exports, rerun with `OPENCLAW_PLUGIN_LOAD_DEBUG=1` to include a compact export-shape summary in the diagnostic output. +### Registry + +```bash +openclaw plugins registry +openclaw plugins registry --refresh +openclaw plugins registry --json +``` + +The local plugin registry is OpenClaw's persisted cold read model for installed +plugin identity, enablement, source metadata, and contribution ownership. +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 +a runtime activation path. + ### Marketplace ```bash diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md index 3f67df8a56d..8813368d06e 100644 --- a/docs/gateway/doctor.md +++ b/docs/gateway/doctor.md @@ -457,7 +457,7 @@ Doctor prints a summary of the workspace state for the default agent: - **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills. - **Legacy workspace dirs**: warns when `~/openclaw` or other legacy workspace directories exist alongside the current workspace. -- **Plugin status**: counts loaded/disabled/errored plugins; lists plugin IDs for any +- **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any errors; reports bundle plugin capabilities. - **Plugin compatibility warnings**: flags plugins that have compatibility issues with the current runtime. diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 05fab1728f6..1d4175e5d11 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -159,12 +159,12 @@ hooks; restart the Gateway process that is serving the live channel before expecting updated `register(api)` code, `api.on(...)` hooks, tools, services, or provider/runtime hooks to run. -`openclaw plugins list` is a local CLI/config snapshot. A `loaded` plugin there -means the plugin is discoverable and loadable from the config/files seen by that -CLI invocation. It does not prove that an already-running remote Gateway child -has restarted into the same plugin code. On VPS/container setups with wrapper -processes, send restarts to the actual `openclaw gateway run` process, or use -`openclaw gateway restart` against the running Gateway. +`openclaw plugins list` is a local plugin registry/config snapshot. An +`enabled` plugin there means the persisted registry and current config allow the +plugin to participate. It does not prove that an already-running remote Gateway +child has restarted into the same plugin code. On VPS/container setups with +wrapper processes, send restarts to the actual `openclaw gateway run` process, +or use `openclaw gateway restart` against the running Gateway. - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved. @@ -256,7 +256,7 @@ Some categories are exclusive (only one active at a time): ```bash openclaw plugins list # compact inventory -openclaw plugins list --enabled # only loaded plugins +openclaw plugins list --enabled # only enabled plugins openclaw plugins list --verbose # per-plugin detail lines openclaw plugins list --json # machine-readable inventory openclaw plugins inspect # deep detail @@ -264,6 +264,8 @@ openclaw plugins inspect --json # machine-readable openclaw plugins inspect --all # fleet-wide table openclaw plugins info # inspect alias openclaw plugins doctor # diagnostics +openclaw plugins registry # inspect persisted registry state +openclaw plugins registry --refresh # rebuild persisted registry openclaw plugins install # install (ClawHub first, then npm) openclaw plugins install clawhub: # install from ClawHub only @@ -299,6 +301,13 @@ When `plugins.allow` is already set, `openclaw plugins install` adds the installed plugin id to that allowlist before enabling it, so installs are 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 +manifest/package metadata without loading plugin runtime modules. + `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.