From 0bd5764cfaf9e801bf63841ecece6f299736ce2a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Fri, 24 Apr 2026 04:07:47 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@d717dbba514ad211863fbad33bd97a1fce4b521f --- .openclaw-sync/source.json | 4 ++-- docs/plugins/architecture.md | 39 ++++++++++++------------------- docs/plugins/manifest.md | 43 ++++++++++++++++------------------- docs/plugins/sdk-migration.md | 24 ++++++++----------- 4 files changed, 46 insertions(+), 64 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index ff59974f7..3f69509ee 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "b1d0c14d387be6d07b8ede2bbef83b82dd4db93c", - "syncedAt": "2026-04-24T04:00:47.624Z" + "sha": "d717dbba514ad211863fbad33bd97a1fce4b521f", + "syncedAt": "2026-04-24T04:06:14.353Z" } diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index 9d886a973..4de8c088e 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -119,31 +119,22 @@ signals also appear in `openclaw status --all` and `openclaw plugins doctor`. ## Architecture overview -OpenClaw's plugin system is split into four planes: +OpenClaw's plugin system has four layers: -1. **Source plane** - OpenClaw decides where a plugin comes from and how it can be installed. This - includes bundled catalogs, official external catalogs, ClawHub/npm specs, - local source paths, minimum host version, expected npm integrity, and install - policy checks. -2. **Control plane** - OpenClaw reads package and manifest metadata before runtime code executes. - This includes discovery, config schemas, provider/channel ownership, - setup/onboarding hints, contracts, auth choices, and enablement policy. -3. **Load plane** - OpenClaw builds deterministic plans for concrete needs such as a provider, - channel, command, hook stage, or contract. Legacy `activation.*` fields are - compatibility hints in this plane, not the preferred public contract. -4. **Runtime plane** - OpenClaw imports plugin code only for actual execution. Native plugins - register capabilities into scoped or compatibility registries; compatible - bundles can still normalize into registry records without importing runtime - code. - -The important compatibility rule: documented external plugins and existing -bundled plugins must keep working while contracts migrate. Breaking changes need -a replacement contract, compatibility adapter, diagnostics, tests, docs, and an -approved deprecation window before removal. +1. **Manifest + discovery** + OpenClaw finds candidate plugins from configured paths, workspace roots, + global plugin roots, and bundled plugins. Discovery reads native + `openclaw.plugin.json` manifests plus supported bundle manifests first. +2. **Enablement + validation** + Core decides whether a discovered plugin is enabled, disabled, blocked, or + selected for an exclusive slot such as memory. +3. **Runtime loading** + Native OpenClaw plugins are loaded in-process via jiti and register + capabilities into a central registry. Compatible bundles are normalized into + registry records without importing runtime code. +4. **Surface consumption** + The rest of OpenClaw reads the registry to expose tools, channels, provider + setup, hooks, HTTP routes, CLI commands, and services. For plugin CLI specifically, root command discovery is split in two phases: diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index fecdeaa36..7788b0d2b 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -239,15 +239,11 @@ runtime still owns actual CLI registration through a lightweight | `commandName` | Yes | `string` | Subcommand mounted beneath `openclaw qa`, for example `matrix`. | | `description` | No | `string` | Fallback help text used when the shared host needs a stub command. | -This block is legacy hint metadata. It does not register runtime behavior, and -it does not replace `register(...)`, `setupEntry`, or other runtime/plugin -entrypoints. Existing plugins may keep these fields, but new manifests should -prefer explicit ownership fields such as `providers`, `channels`, `contracts`, -`commandAliases`, and `setup`. - -Current consumers still parse `activation` through the compatibility layer so -existing bundled and external plugins keep working. New code should treat these -fields as fallback hints for load planning, not as the primary plugin contract. +This block is metadata only. It does not register runtime behavior, and it does +not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints. +Current consumers use it as a narrowing hint before broader plugin loading, so +missing activation metadata usually only costs performance; it should not +change correctness while legacy manifest ownership fallbacks still exist. ```json { @@ -261,24 +257,23 @@ fields as fallback hints for load planning, not as the primary plugin contract. } ``` -| Field | Required | Type | What it means | -| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | -| `onProviders` | No | `string[]` | Legacy provider load hint. Prefer top-level `providers`. | -| `onCommands` | No | `string[]` | Legacy command load hint. Prefer command aliases or CLI descriptors. | -| `onChannels` | No | `string[]` | Legacy channel load hint. Prefer top-level `channels`. | -| `onRoutes` | No | `string[]` | Legacy route load hint. Keep only when no narrower route metadata exists yet. | -| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Legacy broad capability hint. Do not add new uses. | +| Field | Required | Type | What it means | +| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | No | `string[]` | Provider ids that should activate this plugin when requested. | +| `onCommands` | No | `string[]` | Command ids that should activate this plugin. | +| `onChannels` | No | `string[]` | Channel ids that should activate this plugin. | +| `onRoutes` | No | `string[]` | Route kinds that should activate this plugin. | +| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. | Current live consumers: -- command-triggered CLI planning prefers `commandAliases[].cliCommand` or - `commandAliases[].name` before legacy `activation.onCommands` -- channel-triggered setup/channel planning prefers `channels[]` before legacy - `activation.onChannels` -- provider-triggered setup/runtime planning prefers `providers[]` and - `setup.providers[]` before legacy `activation.onProviders` -- broad capability planning prefers explicit ownership metadata before legacy - `activation.onCapabilities` +- command-triggered CLI planning falls back to legacy + `commandAliases[].cliCommand` or `commandAliases[].name` +- channel-triggered setup/channel planning falls back to legacy `channels[]` + ownership when explicit channel activation metadata is missing +- provider-triggered setup/runtime planning falls back to legacy + `providers[]` and top-level `cliBackends[]` ownership when explicit provider + activation metadata is missing ## setup reference diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index fd726846b..f6d18fc44 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -25,14 +25,12 @@ anything they needed from a single entry point: host-side helpers like the embedded agent runner. Both surfaces are now **deprecated**. They still work at runtime, but new -plugins must not use them, and existing plugins should migrate before an -approved breaking release removes them. +plugins must not use them, and existing plugins should migrate before the next +major release removes them. - The backwards-compatibility layer remains supported during the migration - window. Any removal must go through a documented deprecation path first: - replacement contract, compatibility adapter, diagnostics, tests, docs, and an - explicitly approved breaking release. + The backwards-compatibility layer will be removed in a future major release. + Plugins that still import from these surfaces will break when that happens. ## Why this changed @@ -376,15 +374,13 @@ check the source at `src/plugin-sdk/` or ask in Discord. ## Removal timeline -| When | What happens | -| ---------------------------------- | ---------------------------------------------------------------------------- | -| **Now** | Deprecated surfaces emit runtime warnings and keep working through adapters. | -| **Migration window** | Replacement contracts, diagnostics, tests, and docs stay available together. | -| **Approved breaking release only** | Deprecated surfaces may be removed after the migration window. | +| When | What happens | +| ---------------------- | ----------------------------------------------------------------------- | +| **Now** | Deprecated surfaces emit runtime warnings | +| **Next major release** | Deprecated surfaces will be removed; plugins still using them will fail | -All core plugins have already been migrated. External plugins should migrate, -but documented external plugins should not break without the compatibility path -above. +All core plugins have already been migrated. External plugins should migrate +before the next major release. ## Suppressing the warnings temporarily