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

docs(plugins): sdk-overview — sentence-case title, tighten intro into Warning, Related as CardGroup, progressive-disclose embedded-factory note

Browse Source
This commit is contained in:
Vincent Koc
2026-04-23 10:15:43 -07:00
parent e0f5961e28
commit 27d6b8db5b
1 changed files with 66 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/plugins/sdk-overview.md
View File

@@ -1,6 +1,6 @@
--- ---
title: "Plugin SDK Overview" title: "Plugin SDK overview"
sidebarTitle: "SDK Overview" sidebarTitle: "SDK overview"
summary: "Import map, registration API reference, and SDK architecture" summary: "Import map, registration API reference, and SDK architecture"
read_when: read_when:
- You need to know which SDK subpath to import from - You need to know which SDK subpath to import from
@@ -8,17 +8,16 @@ read_when:
- You are looking up a specific SDK export - 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 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**. reference for **what to import** and **what you can register**.
<Tip> <Tip>
**Looking for a how-to guide?** Looking for a how-to guide instead?
- First plugin? Start with [Getting Started](/plugins/building-plugins)
- Channel plugin? See [Channel Plugins](/plugins/sdk-channel-plugins) - First plugin? Start with [Building plugins](/plugins/building-plugins).
- Provider plugin? See [Provider Plugins](/plugins/sdk-provider-plugins) - Channel plugin? See [Channel plugins](/plugins/sdk-channel-plugins).
</Tip> - Provider plugin? See [Provider plugins](/plugins/sdk-provider-plugins).
</Tip>
## Import convention ## 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 the broader umbrella surface and shared helpers such as
`buildChannelConfigSchema`. `buildChannelConfigSchema`.
Do not add or depend on provider-named convenience seams such as <Warning>
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, Do not import provider- or channel-branded convenience seams (for example
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, or `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
channel-branded helper seams. Bundled plugins should compose generic Bundled plugins compose generic SDK subpaths inside their own `api.ts` /
SDK subpaths inside their own `api.ts` or `runtime-api.ts` barrels, and core `runtime-api.ts` barrels; core consumers should either use those plugin-local
should either use those plugin-local barrels or add a narrow generic SDK barrels or add a narrow generic SDK contract when a need is truly
contract when the need is truly cross-channel. cross-channel.
The generated export map still contains a small set of bundled-plugin helper A small set of bundled-plugin helper seams (`plugin-sdk/feishu`,
seams such as `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/matrix*`, and similar) still appear in the
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, and `plugin-sdk/matrix*`. Those generated export map. They exist for bundled-plugin maintenance only and are
subpaths exist for bundled-plugin maintenance and compatibility only; they are not recommended import paths for new third-party plugins.
intentionally omitted from the common table below and are not the recommended </Warning>
import path for new third-party plugins.
## Subpath reference ## Subpath reference
The most commonly used subpaths, grouped by purpose. The generated full list of The most commonly used subpaths, grouped by purpose. The generated full list of
200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`. 200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`; reserved
bundled-plugin helper subpaths appear there but are implementation detail
Reserved bundled-plugin helper subpaths still appear in that generated list. unless a doc page explicitly promotes them.
Treat those as implementation detail/compatibility surfaces unless a doc page
explicitly promotes one as public.
### Plugin entry ### Plugin entry
@@ -355,18 +351,23 @@ methods:
| `api.registerMemoryPromptSupplement(builder)` | Additive memory-adjacent prompt section | | `api.registerMemoryPromptSupplement(builder)` | Additive memory-adjacent prompt section |
| `api.registerMemoryCorpusSupplement(adapter)` | Additive memory search/read corpus | | `api.registerMemoryCorpusSupplement(adapter)` | Additive memory search/read corpus |
Reserved core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, <Note>
`update.*`) always stay `operator.admin`, even if a plugin tries to assign a Reserved core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`,
narrower gateway method scope. Prefer plugin-specific prefixes for `update.*`) always stay `operator.admin`, even if a plugin tries to assign a
plugin-owned methods. narrower gateway method scope. Prefer plugin-specific prefixes for
plugin-owned methods.
</Note>
Use `api.registerEmbeddedExtensionFactory(...)` when a plugin needs Pi-native <Accordion title="When to use registerEmbeddedExtensionFactory">
event timing during OpenClaw embedded runs, for example async `tool_result` Use `api.registerEmbeddedExtensionFactory(...)` when a plugin needs Pi-native
rewrites that must happen before the final tool-result message is emitted. event timing during OpenClaw embedded runs — for example async `tool_result`
This is a bundled-plugin seam today: only bundled plugins may register one, and rewrites that must happen before the final tool-result message is emitted.
they must declare `contracts.embeddedExtensionFactories: ["pi"]` in
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 `openclaw.plugin.json`. Keep normal OpenClaw plugin hooks for everything that
does not require that lower-level seam. does not require that lower-level seam.
</Accordion>
### CLI registration metadata ### CLI registration metadata
@@ -500,23 +501,20 @@ my-plugin/
</Warning> </Warning>
Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`, 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 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. 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 helper is intentionally provider-specific and does not belong in a generic SDK
subpath yet. Current bundled example: the Anthropic provider keeps its Claude subpath yet. Bundled examples:
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.
Other current bundled examples: - **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, - **`@openclaw/openai-provider`**: `api.ts` exports provider builders,
default-model helpers, and realtime provider builders default-model helpers, and realtime provider builders.
- `@openclaw/openrouter-provider`: `api.ts` exports the provider builder plus - **`@openclaw/openrouter-provider`**: `api.ts` exports the provider builder
onboarding/config helpers plus onboarding/config helpers.
<Warning> <Warning>
Extension production code should also avoid `openclaw/plugin-sdk/<other-plugin>` Extension production code should also avoid `openclaw/plugin-sdk/<other-plugin>`
@@ -527,9 +525,23 @@ Other current bundled examples:
## Related ## Related
- [Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry` options <CardGroup cols={2}>
- [Runtime Helpers](/plugins/sdk-runtime) — full `api.runtime` namespace reference <Card title="Entry points" icon="door-open" href="/plugins/sdk-entrypoints">
- [Setup and Config](/plugins/sdk-setup) — packaging, manifests, config schemas `definePluginEntry` and `defineChannelPluginEntry` options.
- [Testing](/plugins/sdk-testing) — test utilities and lint rules </Card>
- [SDK Migration](/plugins/sdk-migration) — migrating from deprecated surfaces <Card title="Runtime helpers" icon="gears" href="/plugins/sdk-runtime">
- [Plugin Internals](/plugins/architecture) — deep architecture and capability model Full `api.runtime` namespace reference.
</Card>
<Card title="Setup and config" icon="sliders" href="/plugins/sdk-setup">
Packaging, manifests, and config schemas.
</Card>
<Card title="Testing" icon="vial" href="/plugins/sdk-testing">
Test utilities and lint rules.
</Card>
<Card title="SDK migration" icon="arrows-turn-right" href="/plugins/sdk-migration">
Migrating from deprecated surfaces.
</Card>
<Card title="Plugin internals" icon="diagram-project" href="/plugins/architecture">
Deep architecture and capability model.
</Card>
</CardGroup>