Skip to main content
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.

​
Capability catalog entry

A manifest’s capabilityCatalogEntry default export satisfies PluginCapabilityCatalogEntry from openclaw/plugin-sdk/plugin-entry:
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 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 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/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.
The September channel facades remain public as 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.
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.

​
Sensitive text redaction

The retained openclaw/plugin-sdk/security-runtime export and its @openclaw/plugin-sdk/security-runtime package facade expose redactSensitiveText(text, options?). It returns the redacted string.
  • text is a string. Without options, the function uses logging configuration.
  • mode accepts "tools" (the default) or "off". Registered exact secrets are masked even when mode is "off".
  • patterns is a readonly array of strings, RegExp objects, or synchronous matcher objects. An omitted or empty array uses the default string rules. A nonempty array replaces that string list. Built-in form-body, structured-auth, and AWS bare-key protections always apply when mode is "tools". String rules run in order after form-body and structured-auth preprocessing.
  • String entries accept a regex source (default flags gi) or /source/flags. Strings pass the config regex safety validator. Regex entries gain g when absent. Captures select the value to mask; without captures, the whole match is masked.
  • sensitiveFieldPatterns has the same entry types but is used by structured redaction, not by this text function.
A matcher has source: string (a diagnostic label) and exec(input): Iterable<{ match: string; groups: string[]; input: string; offset: number }>. It must finish synchronously and return a fresh iterable for each call. Keep cursors and other scan state local to that call; the same object can be reused. Each record must satisfy these requirements:
  • input is the current string passed to exec, after registered-secret masking and earlier rules. Do not use offsets from the original user text.
  • offset is a UTF-16 code-unit index into that current string. match is a nonempty exact substring beginning there. Emit records in ascending order without overlap.
  • groups contains capture strings in order, using "" for unmatched groups. The last nonempty capture selects the secret’s last occurrence within match; an empty capture list selects the whole match. Include only the intended secret in that capture so surrounding text remains intact.
Matcher objects and RegExp objects are programmatic arguments. They are never serialized into logging.redactPatterns, which remains a string array. OpenClaw does not persist matcher state or migrate configuration for this argument kind. Existing string and regex callers remain supported. Older hosts need not support matcher objects; plugins using them must require a host version that supports them.For structured SecretRefs, 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.
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.
For bundled plugins, markdown-table-runtime exposes getMarkdownTableSource(table) for tables returned by markdownToIRWithMeta(text, { tableMode: "block" }). It returns source start/end offsets, a continuation prefix, and the original cell Markdown in headers/rows. Slice the same input string to preserve table bytes without reparsing Markdown containers. This metadata is non-enumerable; the getter returns undefined for tables without it.
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.