Plugin SDK reference
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.
API stability
All OpenClaw plugin APIs are experimental. This includes every
openclaw/plugin-sdk/* subpath, registration and runtime APIs, channel and
provider contracts, hooks, and native Control UI APIs. These contracts can
change between OpenClaw releases.
Pin the OpenClaw version used to develop and deploy your plugin, and test each host version you declare compatible. Set package compatibility ranges from those tested versions; do not assume a working build supports future releases. Existing compatibility windows and upgrade migrations still apply. Experimental status does not remove a documented migration path.
Native UI from user-installed plugins also requires the default-off Custom plugin UI lab. Backend plugin APIs and ordinary plugin loading do not require that setting.
What each page covers
- Imports and module layout — which subpath to import from, the subpath catalog, and the internal barrel convention.
- Capability registration — provider registrars plus the worker-provider and embedding runtime contracts.
- Tools and commands — agent tools, custom commands, node-host commands, and widget presenters.
- Infrastructure registration — hooks, HTTP routes, Gateway methods, services, and the webhook and SQLite helpers.
- Host hooks — session extensions, trusted tool policies, Control UI descriptors, and runtime lifecycle.
- CLI and discovery — Gateway discovery advertisers, plugin CLI registration, and CLI backends.
- Memory and context slots — the exclusive context-engine and memory-capability slots and their adapters.
- Events and hook semantics — typed lifecycle hooks and the decision rules each hook applies.
Registration API
The register(api) callback receives an OpenClawPluginApi object with these
methods:
Each group of registration methods has its own page:
| Group | What it registers |
|---|---|
| Capability registration | Inference, media, search, transcript, worker, and embedding providers |
| Tools and commands | Agent tools, custom commands, node-host commands, widget presenters |
| Infrastructure | Hooks, HTTP routes, Gateway methods, CLI, services, migrations |
| Host hooks | Session extensions, trusted tool policies, Control UI descriptors |
| CLI and discovery | Gateway discovery advertisers, CLI registrars, CLI backends |
| Exclusive slots | Context engine and memory capability, one active at a time |
| Events and lifecycle | Typed lifecycle hooks and conversation binding callbacks |
Session discussion provider
Plugins that provide an external team-chat surface for a session can register
the single process-wide provider exported by
openclaw/plugin-sdk/session-discussion. Its info({ sessionKey }) method
reports whether a discussion is unavailable, ready to open, or already open;
open({ sessionKey }) creates or resolves the discussion and returns its embed
and external URLs. Registering another provider replaces the current provider.
API object fields
| Field | Type | Description |
|---|---|---|
api.id |
string |
Plugin id |
api.name |
string |
Display name |
api.version |
string? |
Plugin version (optional) |
api.description |
string? |
Plugin description (optional) |
api.source |
string |
Plugin source path |
api.runtimeSource |
string? |
Selected runtime entrypoint path, when the loader has selected a runtime artifact |
api.rootDir |
string? |
Plugin root directory (optional) |
api.config |
OpenClawConfig |
Current config snapshot (active in-memory runtime snapshot when available) |
api.pluginConfig |
Record<string, unknown> |
Plugin-specific config from plugins.entries.<id>.config |
api.runtime |
PluginRuntime |
Runtime helpers |
api.logger |
PluginLogger |
Scoped logger (debug, info, warn, error) |
api.registrationMode |
PluginRegistrationMode |
Current load mode; "setup-runtime" is the lightweight setup flow with runtime available |
api.resolvePath(input) |
(string) => string |
Resolve path relative to plugin root |
Use api.runtimeSource to locate private modules beside the selected runtime
entrypoint. It records the loader's source, standalone package, or bundled
artifact choice and always identifies the main runtime entry, even during
setup registration. api.source and api.rootDir retain discovery identity;
they can differ from the selected artifact. runtimeSource is absent when no
runtime artifact has been selected, including metadata-only APIs. This path is
a location fact, not authorization to invoke a retired plugin.
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.
- Import convention
- Subpath reference
- Capability registration
- Tools and commands
- Infrastructure
- File-watch capacity errors
- SQLite write admission
- Webhook body rejection
- Post-ack webhook work
- Requester-scoped MCP connections
- Host hooks for workflow plugins
- When to use tool-result middleware
- Gateway discovery registration
- CLI registration metadata
- CLI backend registration
- Exclusive slots
- Memory embedding adapters
- Events and lifecycle
- Hook decision semantics
- Internal module convention
Related
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.
