vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 12:10:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: describe plugin metadata snapshot

Browse Source
This commit is contained in:
Shakker
2026-04-27 16:21:56 +01:00
parent d62cc59388
commit 5240422f03
2 changed files with 17 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/plugins/architecture-internals.md
View File

@@ -93,13 +93,15 @@ OpenClaw keeps short in-process caches for:
These caches reduce bursty startup and repeated command overhead. They are safe
to think of as short-lived performance caches, not persistence.
Gateway hot paths should prefer the current `PluginLookUpTable` or an explicit
manifest registry passed through the call chain. For callers that still rebuild
manifest metadata from the persisted installed plugin index, OpenClaw also keeps
a small bounded fallback cache keyed by the installed index, request shape,
config policy, runtime roots, and manifest/package file signatures. That cache is
only a fallback for repeated installed-index reconstruction; it is not a mutable
runtime plugin registry.
Gateway startup hot paths should prefer the current `PluginMetadataSnapshot`,
the derived `PluginLookUpTable`, or an explicit manifest registry passed through
the call chain. Config validation, startup auto-enable, and plugin bootstrap use
the same snapshot when available. For callers that still rebuild manifest
metadata from the persisted installed plugin index, OpenClaw also keeps a small
bounded fallback cache keyed by the installed index, request shape, config
policy, runtime roots, and manifest/package file signatures. That cache is only a
fallback for repeated installed-index reconstruction; it is not a mutable runtime
plugin registry.
Performance note:

12
docs/plugins/architecture.md
View File

@@ -145,19 +145,23 @@ The important design boundary:
That split lets OpenClaw validate config, explain missing/disabled plugins, and build UI/schema hints before the full runtime is active.
### Plugin lookup table
### Plugin metadata snapshot and lookup table
Gateway startup builds a `PluginLookUpTable` from the installed plugin index and manifest registry for the current config snapshot. The table is metadata-only: it stores plugin ids, manifest records, diagnostics, owner maps, a plugin id normalizer, and the startup plugin plan. It does not hold loaded plugin modules, provider SDKs, package contents, or runtime exports.
Gateway startup builds one `PluginMetadataSnapshot` for the current config snapshot. The snapshot is metadata-only: it stores the installed plugin index, manifest registry, manifest diagnostics, owner maps, a plugin id normalizer, and manifest records. It does not hold loaded plugin modules, provider SDKs, package contents, or runtime exports.
The lookup table keeps repeated startup decisions on the fast path:
Plugin-aware config validation, startup auto-enable, and Gateway plugin bootstrap consume that snapshot instead of rebuilding manifest/index metadata independently. `PluginLookUpTable` is derived from the same snapshot and adds the startup plugin plan for the current runtime config.
The snapshot and lookup table keep repeated startup decisions on the fast path:
- channel ownership
- deferred channel startup
- startup plugin ids
- provider and CLI backend ownership
- setup provider, command alias, model catalog provider, and manifest contract ownership
- plugin config schema and channel config schema validation
- startup auto-enable decisions
The safety boundary is snapshot replacement, not mutation. Rebuild the table when config, plugin inventory, install records, or persisted index policy changes. Do not treat it as a broad mutable global registry, and do not keep unbounded historical tables. Runtime plugin loading remains separate from lookup-table metadata so stale runtime state cannot be hidden behind a metadata cache.
The safety boundary is snapshot replacement, not mutation. Rebuild the snapshot when config, plugin inventory, install records, or persisted index policy changes. Do not treat it as a broad mutable global registry, and do not keep unbounded historical snapshots. Runtime plugin loading remains separate from metadata snapshots so stale runtime state cannot be hidden behind a metadata cache.
Some cold-path callers still reconstruct manifest registries directly from the persisted installed plugin index instead of receiving a Gateway `PluginLookUpTable`. That fallback path keeps a small bounded in-memory cache keyed by the installed index, request shape, config policy, runtime roots, and manifest/package file signatures. It is a fallback safety net for repeated index reconstruction, not the preferred Gateway hot path. Prefer passing the current lookup table or an explicit manifest registry through runtime flows when a caller already has one.