vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-03 17:53:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 31
openclaw/docs/plugins/architecture-internals.md
Vincent Koc aa95b1a008
docs(plugins): split the plugin architecture internals by reader job (#142730) 
The page was 75,451 characters across 16 H2 sections and mixed
explanation, reference tables, and how-to steps. Split it along
conceptual seams into eight child pages under
docs/plugins/architecture-internals/, keeping the parent as a short
index:

- load-pipeline: discovery, safety gates, manifest-first metadata, the
  plugin cache boundary, and the registry model
- provider-hooks: the provider hook order table, worked example,
  bundled hook shapes, and provider catalogs
- runtime-helpers: speech, media understanding, subagent, web search,
  and image generation through api.runtime
- gateway-routes: plugin HTTP endpoints and their auth, scope,
  replacement, and admission rules
- channel-surfaces: conversation binding callbacks, message tool
  schemas, target resolution, config-backed directories, and read-only
  inspection
- packaging: SDK import subpaths, package packs, and channel catalog
  and install metadata
- context-engines: the contextEngine slot
- new-capability: sequence, file checklist, and contract-test pattern

Registry model stays with the load pipeline because it is the end of
that story, and Provider catalogs moves next to the hook table so the
table's "(deprecated, see below)" note for augmentModelCatalog and the
"the hooks above" reference in Built-in examples both keep a same-page
target.

Anchor strategy: every id the single-page version published is kept
alive on the parent index as an authored <a id="..."> stub pointing at
its new home. Ids were computed with parseDocsDocument, not a slug
approximation, so the punctuated `api.runtime.imageGeneration` heading
keeps both its encoded (`api.runtime.imagegeneration`) and cleaned
(`api-runtime-imagegeneration`) forms, and the five Accordion titles
under Built-in examples keep theirs. 30 stubs plus `related`, which the
index still publishes itself, cover all 31 original ids; parseDocsDocument
reports 0 collisions on the index and on every child.

Losslessness: all 16 original H2 blocks are byte-identical after the
move (15 on children, Related on the index). Fences 34 markers before
and after, identical fence-by-fence on info string and body as a
multiset; table rows 60 before and after; the 4 links inside moved
sections are unchanged. The single intra-page `](#hook-order-and-usage)`
link and its target both land on provider-hooks. No prose was rewritten.

Closes audit findings: r3-0544, r3-0548, r3-1925
2026-09-09 08:58:45 +08:00

7.9 KiB
Raw Blame History

summary read_when title
Plugin architecture internals: load pipeline, registry, runtime hooks, HTTP routes, and reference tables
Implementing provider runtime hooks, channel lifecycle, or package packs
Debugging plugin load order or registry state
Adding a new plugin capability or context engine plugin
Plugin architecture internals

For the public capability model, plugin shapes, and ownership/execution contracts, see Plugin architecture. This page covers the internal mechanics: load pipeline, registry, runtime hooks, Gateway HTTP routes, import paths, and schema tables.

What each page covers

  • Load pipeline and registry — discovery, safety gates, manifest-first metadata, the plugin cache boundary, and the registry model.
  • Provider hooks and catalogs — the provider hook order table, a worked example, bundled hook shapes, and catalog merge order.
  • Core runtime helpers — speech, media understanding, subagent, web search, and image generation through api.runtime.
  • Gateway routes — plugin HTTP endpoints and their auth, scope, replacement, and admission rules.
  • Channel surfaces — conversation binding callbacks, message tool schemas, target resolution, directories, and inspection.
  • Packs and import paths — SDK import subpaths, package packs, and channel catalog and install metadata.
  • Context engines — replacing session ingest, assembly, and compaction through the contextEngine slot.
  • New capability — the sequence, file checklist, and contract-test pattern for a capability core does not have yet.

Where each section moved

Every section of the single-page version now lives on this page or on one of the eight child pages below. The anchors from the single-page version still resolve here.

Load pipeline and registry

Load pipeline and registry — Discovery, safety gates, manifest-first metadata, the plugin cache boundary, and the registry core reads from.

Provider hooks and catalogs

Provider hooks and catalogs — The provider hook order table, a worked provider example, bundled hook shapes, and model catalog registration.

Core runtime helpers

Core runtime helpers — Speech, media understanding, subagent, web search, and image generation helpers exposed through api.runtime.

Gateway routes

Gateway routes — Registering plugin HTTP endpoints on the Gateway, and their auth, scope, replacement, and admission rules.

Channel surfaces

Channel surfaces — Conversation binding callbacks, message tool schemas, target resolution, config-backed directories, and read-only inspection.

Packs and import paths

Packs and import paths — Plugin SDK import subpaths, multi-extension package packs, and channel catalog and install metadata.

Context engines

Context engines — Taking over session ingest, assembly, and compaction through the contextEngine slot.

New capability

New capability — The sequence, file checklist, and contract-test pattern for adding a capability the plugin API does not have yet.

Related