From 27d6b8db5bcbd3bcbc6faa18807635f9dd4dc7c5 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 23 Apr 2026 10:15:43 -0700 Subject: [PATCH] =?UTF-8?q?docs(plugins):=20sdk-overview=20=E2=80=94=20sen?= =?UTF-8?q?tence-case=20title,=20tighten=20intro=20into=20Warning,=20Relat?= =?UTF-8?q?ed=20as=20CardGroup,=20progressive-disclose=20embedded-factory?= =?UTF-8?q?=20note?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plugins/sdk-overview.md | 120 +++++++++++++++++++---------------- 1 file changed, 66 insertions(+), 54 deletions(-) diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index 479a3821380..981e73ecba9 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -1,6 +1,6 @@ --- -title: "Plugin SDK Overview" -sidebarTitle: "SDK Overview" +title: "Plugin SDK overview" +sidebarTitle: "SDK overview" summary: "Import map, registration API reference, and SDK architecture" read_when: - You need to know which SDK subpath to import from @@ -8,17 +8,16 @@ read_when: - You are looking up a specific SDK export --- -# Plugin SDK Overview - The plugin SDK is the typed contract between plugins and core. This page is the reference for **what to import** and **what you can register**. - **Looking for a how-to guide?** - - First plugin? Start with [Getting Started](/plugins/building-plugins) - - Channel plugin? See [Channel Plugins](/plugins/sdk-channel-plugins) - - Provider plugin? See [Provider Plugins](/plugins/sdk-provider-plugins) - + Looking for a how-to guide instead? + +- First plugin? Start with [Building plugins](/plugins/building-plugins). +- Channel plugin? See [Channel plugins](/plugins/sdk-channel-plugins). +- Provider plugin? See [Provider plugins](/plugins/sdk-provider-plugins). + ## Import convention @@ -35,29 +34,26 @@ prefer `openclaw/plugin-sdk/channel-core`; keep `openclaw/plugin-sdk/core` for the broader umbrella surface and shared helpers such as `buildChannelConfigSchema`. -Do not add or depend on provider-named convenience seams such as -`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, or -channel-branded helper seams. Bundled plugins should compose generic -SDK subpaths inside their own `api.ts` or `runtime-api.ts` barrels, and core -should either use those plugin-local barrels or add a narrow generic SDK -contract when the need is truly cross-channel. + + Do not import provider- or channel-branded convenience seams (for example + `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). + Bundled plugins compose generic SDK subpaths inside their own `api.ts` / + `runtime-api.ts` barrels; core consumers should either use those plugin-local + barrels or add a narrow generic SDK contract when a need is truly + cross-channel. -The generated export map still contains a small set of bundled-plugin helper -seams such as `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, and `plugin-sdk/matrix*`. Those -subpaths exist for bundled-plugin maintenance and compatibility only; they are -intentionally omitted from the common table below and are not the recommended -import path for new third-party plugins. +A small set of bundled-plugin helper seams (`plugin-sdk/feishu`, +`plugin-sdk/zalo`, `plugin-sdk/matrix*`, and similar) still appear in the +generated export map. They exist for bundled-plugin maintenance only and are +not recommended import paths for new third-party plugins. + ## Subpath reference The most commonly used subpaths, grouped by purpose. The generated full list of -200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`. - -Reserved bundled-plugin helper subpaths still appear in that generated list. -Treat those as implementation detail/compatibility surfaces unless a doc page -explicitly promotes one as public. +200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`; reserved +bundled-plugin helper subpaths appear there but are implementation detail +unless a doc page explicitly promotes them. ### Plugin entry @@ -355,18 +351,23 @@ methods: | `api.registerMemoryPromptSupplement(builder)` | Additive memory-adjacent prompt section | | `api.registerMemoryCorpusSupplement(adapter)` | Additive memory search/read corpus | -Reserved core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) always stay `operator.admin`, even if a plugin tries to assign a -narrower gateway method scope. Prefer plugin-specific prefixes for -plugin-owned methods. + + Reserved core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) always stay `operator.admin`, even if a plugin tries to assign a + narrower gateway method scope. Prefer plugin-specific prefixes for + plugin-owned methods. + -Use `api.registerEmbeddedExtensionFactory(...)` when a plugin needs Pi-native -event timing during OpenClaw embedded runs, for example async `tool_result` -rewrites that must happen before the final tool-result message is emitted. -This is a bundled-plugin seam today: only bundled plugins may register one, and -they must declare `contracts.embeddedExtensionFactories: ["pi"]` in + + Use `api.registerEmbeddedExtensionFactory(...)` when a plugin needs Pi-native + event timing during OpenClaw embedded runs — for example async `tool_result` + rewrites that must happen before the final tool-result message is emitted. + +This is a bundled-plugin seam today: only bundled plugins may register one, +and they must declare `contracts.embeddedExtensionFactories: ["pi"]` in `openclaw.plugin.json`. Keep normal OpenClaw plugin hooks for everything that does not require that lower-level seam. + ### CLI registration metadata @@ -500,23 +501,20 @@ my-plugin/ Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts`, and similar public entry files) now prefer the +`index.ts`, `setup-entry.ts`, and similar public entry files) prefer the active runtime config snapshot when OpenClaw is already running. If no runtime snapshot exists yet, they fall back to the resolved config file on disk. -Provider plugins can also expose a narrow plugin-local contract barrel when a +Provider plugins can expose a narrow plugin-local contract barrel when a helper is intentionally provider-specific and does not belong in a generic SDK -subpath yet. Current bundled example: the Anthropic provider keeps its Claude -stream helpers in its own public `api.ts` / `contract-api.ts` seam instead of -promoting Anthropic beta-header and `service_tier` logic into a generic -`plugin-sdk/*` contract. +subpath yet. Bundled examples: -Other current bundled examples: - -- `@openclaw/openai-provider`: `api.ts` exports provider builders, - default-model helpers, and realtime provider builders -- `@openclaw/openrouter-provider`: `api.ts` exports the provider builder plus - onboarding/config helpers +- **Anthropic**: public `api.ts` / `contract-api.ts` seam for Claude + beta-header and `service_tier` stream helpers. +- **`@openclaw/openai-provider`**: `api.ts` exports provider builders, + default-model helpers, and realtime provider builders. +- **`@openclaw/openrouter-provider`**: `api.ts` exports the provider builder + plus onboarding/config helpers. Extension production code should also avoid `openclaw/plugin-sdk/` @@ -527,9 +525,23 @@ Other current bundled examples: ## Related -- [Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry` options -- [Runtime Helpers](/plugins/sdk-runtime) — full `api.runtime` namespace reference -- [Setup and Config](/plugins/sdk-setup) — packaging, manifests, config schemas -- [Testing](/plugins/sdk-testing) — test utilities and lint rules -- [SDK Migration](/plugins/sdk-migration) — migrating from deprecated surfaces -- [Plugin Internals](/plugins/architecture) — deep architecture and capability model + + + `definePluginEntry` and `defineChannelPluginEntry` options. + + + Full `api.runtime` namespace reference. + + + Packaging, manifests, and config schemas. + + + Test utilities and lint rules. + + + Migrating from deprecated surfaces. + + + Deep architecture and capability model. + +