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:

​

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

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

​

Docked link readers

See docked link readers for passive documents beside chat.

​

Related