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.
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 usesplugin-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.
Capability catalog entry
A manifest’scapabilityCatalogEntry default export satisfies
PluginCapabilityCatalogEntry from openclaw/plugin-sdk/plugin-entry:
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
PluginCapabilityCatalogContext. 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.
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 isscripts/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/channel-lifecycle,
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.
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,
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.
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.Channel subpaths
Channel subpaths
removal-pending records until
their recorded blockers are resolved; a registry date does not automatically
remove an export. See the removal timeline.
July aliases such as direct-DM access, reply-options, pairing paths, and channel
runtime splinters have been removed; bundled-only helpers are private-local.Provider subpaths
Provider subpaths
createBoundedProviderBinaryStream requires a request cleanup callback.
Stream cancellation and release() start source cancellation, unlock the reader,
and run cleanup once, then wait for both operations. Cancellation propagates
source failures; release() ignores them. Cleanup failures take precedence in
both cases. Overflow preserves its fitting prefix and error without waiting for
cleanup; later release() reports cleanup failure. After EOF or a read error,
the caller must still invoke and await release().Provider usage snapshots normally report one or more quota windows, each with
a label, percent used, and optional reset time. Providers that expose balance or
account-state text instead of resettable quota windows should return
summary with an empty windows array rather than fabricating percentages.
OpenClaw displays that summary text in status output; use error only when the
usage endpoint failed or returned no usable usage data.Auth and security subpaths
Auth and security subpaths
resolveReadOnlyEnvSecretRef returns blocked when the ref cannot be used, including an allowed env ref whose value is missing or empty. Callers may apply their existing fallback only for missing; a blocked ref must not borrow ambient or auth-profile credentials. Its provider check follows source-specific default aliases and explicit env allowlists.Use isLoopbackHost(host) when a plugin must accept only the local machine. It accepts localhost, IPv4 loopback literals across 127.0.0.0/8, ::1, bracketed IPv6, and IPv4-mapped IPv6 loopback literals. It parses IP literals rather than matching text prefixes, so a DNS name such as 127.0.0.1.evil.com is not loopback. Use isPrivateOrLoopbackHost(host) only when private-network hosts such as RFC 1918 addresses are also valid.Runtime and storage subpaths
Runtime and storage subpaths
Private process callers declare
using prepared = prepareSecretInputStdio(stdio, secretInput)
before spawning, then call await prepared?.deliverTo(child) once. Delivery closes the writer
and zeroes the transient credential buffer; disposal closes any untransferred descriptors,
including when spawning throws. POSIX uses anonymous pipes that support descriptor-path readers
without credential files; Windows retains its overlapped child pipe. Callers own child cleanup
when delivery fails.Capability and testing subpaths
Capability and testing subpaths
Memory subpaths
Memory subpaths
Reserved bundled-helper subpaths
Reserved bundled-helper subpaths
Reserved bundled-helper SDK subpaths are narrow owner-specific surfaces for
bundled plugin code. They are tracked in the SDK inventory so package
builds and aliasing stay deterministic, but they are not general plugin
authoring APIs. New reusable host contracts should use generic SDK subpaths
such as
plugin-sdk/gateway-runtime and plugin-sdk/ssrf-runtime.