Plugin SDK subpaths

The plugin SDK contains narrow public subpaths and repository-only bundled helpers under openclaw/plugin-sdk/. This page catalogs every typed public subpath and labels selected private-local entries explicitly; it is not an inventory of every internal runtime helper. Four files define the boundary:

• scripts/lib/plugin-sdk-entrypoints.json: the maintained entrypoint inventory the build compiles.
• scripts/lib/plugin-sdk-private-local-only-subpaths.json: internal subpaths excluded from the typed, documented SDK. Production entries remain available as JavaScript-only host runtime exports for separately published official plugins; test-only entries stay unexported.
• scripts/lib/plugin-sdk-deprecated-public-subpaths.json: public compatibility subpaths retained only through their documented removal windows.
• scripts/lib/plugin-sdk-entries.mts: derived public/private export metadata, supported bundled facades, and plugin-owned public surfaces.

After changing the entrypoint inventories, run pnpm plugin-sdk:sync-exports, then pnpm plugin-sdk:check-exports. The same registration command maintains package exports, private artifact exclusions in package.json's files, and private workspace declaration aliases in extensions/tsconfig.package-boundary.paths.json and extensions/xai/tsconfig.json. It owns literal flat !dist/plugin-sdk/<name>.js and .d.ts exclusions, including names with underscores, uppercase letters, dots, or Unicode, and removes obsolete exclusions when entries become public or are removed. Nested paths, glob or escape syntax, non-entrypoint metadata, and other file rules retain their order; unrelated mappings and XAI's intentional private-alias omissions are preserved. These local declaration aliases do not add types to JavaScript-only published SDK exports; test-only entries remain unexported.

Maintainers audit the public export count with pnpm plugin-sdk:surface and the compatibility queue with pnpm plugins:boundary-report:summary.

For the plugin authoring guide, see Plugin SDK overview.

Plugin entry

Native feature authoring uses plugin-sdk/feature-contract (defineFeatureContract, createFeatureClient), plugin-sdk/feature-plugin (defineFeaturePlugin), and plugin-sdk/control-ui (defineControlUiPlugin, host and view types). The contract and Control UI subpaths are browser safe; feature-plugin is backend only. See Feature plugins.

Navigation items registered with host.ui.registerNavigation can set parent to another navigation ID in the same plugin; host.ui.pinNavigation(id) pins an already registered item once using the user's existing sidebar preferences.

Control UI conversation dock

ControlUiHost from openclaw/plugin-sdk/control-ui has this optional member:

dock?: {  /** Dock a conversation beside the current page; replaces a conversation dock already open. */  openSession: (params: {    sessionKey: string;    agentId: string;    label: string;    context?: { page: string; detail?: Readonly<Record<string, string>> };  }) => void;  close: () => void;  readonly openSessionKey: string | null;};

Check host.dock before presenting a dock action. Supply both sessionKey and agentId for the intended conversation; label is its dock tab title. openSession reuses the Home chat pane, drafts, attachments, placement and size persistence, and close and placement controls. It replaces Home, Ask OpenClaw, or a previously docked conversation. close() leaves no dock open and does not restore the previous conversation.

Navigation keeps the dock open, except that it hides while the same session and agent are open as the Chat or Dashboard page. Leaving that page reveals the dock again. openSessionKey is the visible plugin-opened session key, or null when there is none, including while hidden or showing Home or Ask OpenClaw. host.subscribe(...) listeners fire when that value changes.

The plugin activation owns the opened dock. Disposing a mounted view retires its host handles but keeps the dock open during navigation. Disposing the activation closes the dock only if it still belongs to that activation; it does not close a replacement opened by another activation. Retained dock operations reject after their view or activation ends.

The normal chat pane enforces the viewer's access. Read-only viewers can open the dock and receive the existing read-only composer behavior. A session the viewer cannot open displays the pane's normal error state. Docking grants no additional session access.

The optional context supplies an untrusted ambient hint. page can name a plugin page; detail is a flat record of string fields. The host retains up to four detail fields in sorted key order, omits empty or oversized keys, and bounds each escaped key to 32 characters and each JSON-encoded value to 128 characters. These limits include escaping; the value limit includes its JSON quotes. The page uses the existing 64-character work-context limit. When context is omitted, the host builds the current page's reference as it does for Home.

The operator can remove the reference before sending. At send time the host captures a snapshot and formats it as quoted reference data, never instructions or permission to access another session. Sent messages retain the Context attached presentation; Technical details includes the plugin fields. Queues and retries keep the captured snapshot.

Capability catalog entry

A manifest's capabilityCatalogEntry default export satisfies PluginCapabilityCatalogEntry from openclaw/plugin-sdk/plugin-entry:

import type { PluginCapabilityCatalogEntry } from "openclaw/plugin-sdk/plugin-entry";import { buildSpeechProvider } from "./speech-provider.js"; export default {  speechProviders: [buildSpeechProvider()],} satisfies PluginCapabilityCatalogEntry;

The optional collections are speechProviders, realtimeTranscriptionProviders, and realtimeVoiceProviders. Use the same provider factories as full registration; retain their configuration, aliases, readiness functions, execution methods, and non-enumerable internal methods. The host registers descriptors through the normal registrar, preserving its ownership and registration lifecycle.

The export may instead be a synchronous factory receiving PluginCapabilityCatalogHostContext. It supplies native host operations for readiness, auth resolution, provider headers, bounded HTTP responses, WebSocket transcription, and capture/logging. Pass the operations used by a provider into its shared factory; keep synchronous constructors and invoke the operations only when needed. This avoids transforming host runtime modules through the plugin source loader during catalog construction or connection setup. Construction must not query auth stores, start sessions, or import broad host or plugin runtime modules. Cold discovery does not receive a live broker; active registrations retain their broker-bound behavior.

PluginCapabilityCatalogHostContext requires captureWsEventAsync; use PluginCapabilityCatalogHostEntry for factories that consume it. The shipped PluginCapabilityCatalogContext and PluginCapabilityCatalogEntry types remain available, including the deprecated synchronous captureWsEvent member. Callbacks accepting the legacy context remain assignable to host registration callbacks: the host supplies all legacy fields plus the async capability. Host composition owns these operations; catalog validation does not load capture runtime to add them.

See manifest capability catalogs for family coverage, compatibility, artifact selection, and failure behavior.

Compatibility and private-local helpers

Deprecated compatibility subpaths remain exported under their recorded windows and retention blockers. July 2026 aliases and unused subpaths were deleted, while bundled-only helpers were excluded from the typed public SDK and are labeled private-local below. Production-private JavaScript exports remain available for official plugin runtimes. The maintained list is scripts/lib/plugin-sdk-deprecated-public-subpaths.json; CI rejects bundled imports of these compatibility-only subpaths. The broad domain barrels plugin-sdk/agent-runtime, plugin-sdk/conversation-runtime, plugin-sdk/hook-runtime, plugin-sdk/media-runtime, plugin-sdk/plugin-runtime, and plugin-sdk/security-runtime are likewise deprecated in favor of focused subpaths.

The channel-lifecycle, channel-message, channel-reply-pipeline, config-runtime, and infra-runtime compatibility subpaths were removed with SDK-owner approval on September 30, 2026. Use the migration guide for the focused replacements and per-export differences.

OpenClaw's Vitest-backed test-helper subpaths are repo-local only and are no longer package exports: agent-runtime-test-contracts, channel-contract-testing, channel-target-testing, channel-test-helpers, compiled-subprocess-testing, plugin-state-test-runtime, plugin-test-api, plugin-test-contracts, plugin-test-runtime, provider-http-test-mocks, provider-test-contracts, reply-payload-testing, sqlite-runtime-testing, test-env, test-fixtures, test-live, test-live-auth, test-media-generation, test-media-understanding, test-node-mocks, and testing. ssrf-runtime-internal is a JavaScript-only host runtime reserved for exact trusted local-service plugins; it is not a public plugin authoring API.

The private-local session-key-runtime provides pure cron/dreaming session-key classification and usage-counted transcript filename parsing. Bundled memory readers use it without loading session storage, artifact cleanup, or archive compression. Filename parsing shares a pure grammar with the artifact helpers. Existing memory session facades retain these exports for installed plugin compatibility.

The private official-plugin runtime node-crypto-runtime exposes sha256Hex for hashing strings or bytes without loading memory indexing helpers. It is a JavaScript-only host runtime export, not a typed public Plugin SDK entrypoint.

Bundled plugin helper subpaths

Bundled-only helper modules are private-local after the July 2026 sweep. Package contract guardrails classify the supported bundled facades that remain public until generic contracts replace them. Those facades are deprecated for new code; see the per-row notes below.

Asynchronous proxy capture

Use initializeDebugProxyCaptureAsync, captureHttpExchangeAsync, captureWsEventAsync, and finalizeDebugProxyCaptureAsync from openclaw/plugin-sdk/proxy-capture for runtime capture. Await initialization, direct store operations, and capture calls wherever the owning flow permits. HTTP capture reads a cloned response body: waiting for that read must not delay handing the original response to its caller. WebSocket event callbacks likewise leave capture completion to their lifecycle owner.

The published 2026.9.6 host does not expose these async capture operations. Plugins supporting that host must read optional diagnostic operations from the SDK module namespace and check availability before calling them. Ordinary channel or provider operations continue without those diagnostics; configured proxy routing still applies. Do not fall back to synchronous capture writes. Features that require capture storage or readback must report an unavailable capability instead of claiming successful capture. Remove these availability checks when the plugin's minimum supported host includes the async operations.

For long-lived streams, observe capture completion separately and let the runtime finalizer settle it during cleanup. If a maintenance callback returns or awaits the capture Promise, maintenance waits for that body capture too. Use the capture signal when the owning request must end its read before EOF.

The capture owner immediately observes callback-only writes, reports and retains failures, and rethrows them during async finalization. Plugin invocation wrappers can return a derived Promise, so an ignored callback call must also observe the final returned Promise, for example void captureWsEventAsync(event, settings).catch(() => {});. This observer does not change the capture API's original rejecting Promise or replace awaited finalizeDebugProxyCaptureAsync(settings) at shutdown.

Acquire an async store with await acquireDebugProxyCaptureStoreAsync({ env }) and always await lease.release() in finally. Finalize the runtime capture owner and release owned leases before closing its database. Closing the underlying database directly for maintenance invalidates capture admission; it does not substitute for capture finalization and draining. Doctor and migration maintenance owners drain their own capture work before releasing their execution claims. A shared session ends only when its last claim closes; the surrounding runtime retains its own claim. Async capture finalization targets the whole selected session. For inspection, use createDebugProxyCaptureReaderAsync({ env }): construction does not open a database, and its async getSessionEvents and readBlob methods read existing state without creating a missing database, returning [] or null when absent.

Synchronous capture writers, initialization/finalization, and store constructors/accessors remain deprecated compatibility APIs for shipped plugins. Migrate their callers and lifecycle cleanup together; removal requires a breaking Plugin SDK release. Mixing legacy synchronous writes with async commands does not establish one global order: synchronous writes may interleave between async commands. finalizeDebugProxyCapture synchronously settles the session's legacy capture readers and writes and releases their stores. If the host also uses async capture, its claims and fetch capture remain active until their async lifecycle cleanup completes. Later legacy capture calls stay inactive until explicit initialization. Use await finalizeDebugProxyCaptureAsync(settings) when the caller owns shutdown of the whole mixed session.

Related

• Plugin SDK overview
• Plugin SDK setup
• Building plugins
• Plugin architecture internals
• Tool plugins