mirror of
https://github.com/openclaw/openclaw.git
synced 2026-10-03 17:53:39 +00:00
f8b194a5be
* fix(plugins): normalize network runtimes * build(plugins): align network runtime dependencies * test(runtime): stabilize network compatibility checks * fix(codex): route managed transports through runtime owners
67 KiB
67 KiB
| summary | doc-schema-version | read_when | title | ||
|---|---|---|---|---|---|
| Plugin SDK subpath catalog: which imports live where, grouped by area | 1 |
|
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.
| Subpath | Key exports |
|---|---|
plugin-sdk/plugin-entry |
definePluginEntry, PluginCapabilityCatalog, PluginCapabilityCatalogEntry, PluginCapabilityCatalogContext |
plugin-sdk/core |
defineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema, buildJsonChannelConfigSchema, resolveTailscalePublishedHost |
plugin-sdk/provider-entry |
Private-local after July 2026; defineSingleProviderPluginEntry |
plugin-sdk/migration |
Private-local after July 2026; Migration provider item helpers such as createMigrationItem, reason constants, item status markers, redaction helpers, and summarizeMigrationItems |
plugin-sdk/migration-runtime |
Private-local after July 2026; Runtime migration helpers such as copyMigrationFileItem, resolvePlannedMigrationTargets, withCachedMigrationConfigRuntime, and writeMigrationReport |
plugin-sdk/health |
Doctor health-check registration, detection, repair, selection, severity, and finding types for bundled health consumers |
plugin-sdk/channel-entry-contract |
Bundled channel entry and setup-entry contracts, feature declarations, and lazy module-loading helpers |
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
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.
| Subpath | Key exports | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `createChannelConfigUiHints` | | `plugin-sdk/json-schema-runtime` | Private-local after July 2026; Cached JSON Schema validation helper for plugin-owned schemas | | `plugin-sdk/channel-setup` | `defineChannelSetupContract`, channel-owned setup field/input types, `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-dm-policy` | `createChannelDmPolicy` for account-aware setup policy descriptors | | `plugin-sdk/setup` | Shared setup wizard helpers, setup translator, allowlist prompts, setup status builders | | `plugin-sdk/setup-runtime` | `defineChannelSetupContract`, `createSetupTranslator`, `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | | `plugin-sdk/archive` | `extractArchive`, `readArchiveEntry`, archive limits and entry kinds | | `plugin-sdk/root-walk` | `walkRootDirectory`, root-walk options and entries | | `plugin-sdk/secret-file` | `createSecretFileAtomic`, synchronous and asynchronous secret reads | | `plugin-sdk/account-core` | Multi-account config/action-gate helpers, default-account fallback helpers | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, account-id normalization helpers | | `plugin-sdk/account-resolution` | Account lookup + default-fallback helpers | | `plugin-sdk/account-helpers` | Narrow account-list/account-action helpers | | `plugin-sdk/access-groups` | Private-local after July 2026; Access-group allowlist parsing and redacted group diagnostics helpers | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | Retained compatibility facade. `channel-outbound` exports `createChannelMessageReplyPipeline` and `resolveChannelMessageSourceReplyDeliveryMode`; other function names are unchanged, but named types do not all move. See [retained channel mappings](/plugins/sdk-migration#retained-channel-facade-mappings). | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter`, `resolveChannelDmAccess`, `resolveChannelDmAllowFrom`, `resolveChannelDmPolicy`, `normalizeChannelDmPolicy`, `normalizeLegacyDmAliases` | | `plugin-sdk/channel-config-schema` | Shared channel config schema primitives plus Zod and direct JSON/TypeBox builders | | `plugin-sdk/bundled-channel-config-schema` | Private-local after July 2026; Bundled OpenClaw channel config schemas for maintained bundled plugins only | | `plugin-sdk/chat-channel-ids` | Private-local after July 2026; `BUNDLED_CHAT_CHANNEL_IDS`, `BUNDLED_CHAT_CHANNEL_ENVELOPE_PREFIXES`, `ChatChannelId`. Canonical bundled/official chat channel ids plus formatter labels/aliases for plugins that need to recognize envelope-prefixed text without hardcoding their own table. | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-ingress-runtime` | Experimental high-level channel ingress runtime resolver, implicit-mention policy resolver, and route fact builders for migrated channel receive paths. Prefer this over assembling effective allowlists, command allowlists, and legacy projections in each plugin. See [Channel ingress API](/plugins/sdk-channel-ingress). | | `plugin-sdk/channel-lifecycle` | Retained compatibility facade. Selected functions move unchanged to `channel-outbound`; other helpers require behavioral migration or an owner-approved public replacement. Named types do not all move. See [retained channel mappings](/plugins/sdk-migration#retained-channel-facade-mappings). | | `plugin-sdk/channel-outbound` | Message lifecycle contracts plus reply pipeline options, receipts, live preview/streaming, lifecycle helpers, outbound identity, payload planning, durable sends, and message-send context helpers. See [Channel outbound API](/plugins/sdk-channel-outbound). | | `plugin-sdk/channel-message` | Retained compatibility facade. Move outbound exports to `channel-outbound` and its three dispatch aliases to their renamed exports in `channel-inbound`. See [retained channel mappings](/plugins/sdk-migration#retained-channel-facade-mappings). | | `plugin-sdk/inbound-envelope` | Shared inbound route + envelope builder helpers | | `plugin-sdk/inbound-event-delivery` | Process-local correlation between active inbound events and successful channel sends | | `plugin-sdk/inbound-reply-dispatch` | Deprecated compatibility shim for `dispatchInboundReplyWithBase`; its compatibility-ledger gate is the next Plugin SDK major, not a calendar date. Use `plugin-sdk/channel-inbound` for inbound runners and `plugin-sdk/channel-outbound` for message delivery helpers. | | `plugin-sdk/outbound-media` | Private-local after July 2026; Shared outbound media loading and hosted-media state helpers | | `plugin-sdk/poll-runtime` | Private-local after July 2026; Narrow poll normalization helpers | | `plugin-sdk/thread-bindings-runtime` | Private-local after July 2026; Thread-binding lifecycle and adapter helpers | | `plugin-sdk/agent-media-payload` | Deprecated compatibility facade for legacy `Media*` payload projection. Pass ordered facts through `MsgContext.media` / `toInboundMediaFacts(...)`; import local-root policy from `plugin-sdk/media-local-roots`. | | `plugin-sdk/conversation-runtime` | Deprecated broad barrel for conversation/thread binding, pairing, and configured-binding helpers; prefer focused binding subpaths such as `plugin-sdk/thread-bindings-runtime` and `plugin-sdk/session-binding-runtime` | | `plugin-sdk/runtime-group-policy` | Runtime group-policy resolution helpers | | `plugin-sdk/channel-status` | Shared channel status snapshot/summary helpers | | `plugin-sdk/channel-config-primitives` | Narrow channel config-schema primitives | | `plugin-sdk/channel-config-writes` | Private-local after July 2026; Channel config-write authorization helpers | | `plugin-sdk/channel-plugin-common` | Shared channel plugin prelude exports | | `plugin-sdk/allowlist-config-edit` | Allowlist config edit/read helpers | | `plugin-sdk/direct-dm-guard-policy` | Private-local after July 2026; Narrow direct-DM pre-crypto guard policy helpers | | `plugin-sdk/discord` | Deprecated Discord compatibility facade for published `@openclaw/discord@2026.3.13` and tracked owner compatibility; new plugins should use generic channel SDK subpaths | | `plugin-sdk/telegram-account` | Deprecated Telegram account-resolution compatibility facade for tracked owner compatibility; new plugins should use injected runtime helpers or generic channel SDK subpaths | | `plugin-sdk/interactive-runtime` | Semantic message presentation, delivery, and legacy interactive reply helpers. See [Message Presentation](/plugins/message-presentation) | | `plugin-sdk/question-gateway-runtime` | Resolve runtime-authored `ask_user` choices through the Gateway from channel interaction handlers | | `plugin-sdk/channel-inbound` | Shared inbound helpers for event classification, context building, formatting, roots, debounce, mention matching, mention-policy, and inbound logging | | `plugin-sdk/channel-inbound-debounce` | Narrow inbound debounce helpers | | `plugin-sdk/channel-mention-gating` | Private-local after July 2026; Narrow mention-policy, mention marker, and mention text helpers without the broader inbound runtime surface | | `plugin-sdk/channel-streaming-config` | Dependency-light channel streaming config readers (`getChannelStreamingConfigObject`, `resolveChannelStreamingNativeTransport`) for doctor contract closures and other control-plane paths that must not load the reply pipeline | | `plugin-sdk/channel-send-result` | Reply result types | | `plugin-sdk/channel-actions` | Channel message-action helpers, plus deprecated native schema helpers kept for plugin compatibility | | `plugin-sdk/channel-route` | Private-local after July 2026; Shared route normalization, parser-driven target resolution, thread-id stringification, dedupe/compact route keys, parsed-target types, and route/target comparison helpers | | `plugin-sdk/channel-targets` | Private-local after July 2026; Target parsing helpers; route comparison callers should use `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | Channel contract types | | `plugin-sdk/channel-feedback` | Feedback/reaction wiring | | `plugin-sdk/reply-payload` | Reply payload types, normalization, content/media inspection, native question option ordering, chunked send helpers, reasoning detection, and reply fan-out |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.
textis a string. Withoutoptions, the function uses logging configuration.modeaccepts"tools"(the default) or"off". Registered exact secrets are masked even when mode is"off".patternsis a readonly array of strings,RegExpobjects, 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 gaingwhen absent. Captures select the value to mask; without captures, the whole match is masked. sensitiveFieldPatternshas 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:
inputis the current string passed toexec, after registered-secret masking and earlier rules. Do not use offsets from the original user text.offsetis a UTF-16 code-unit index into that current string.matchis a nonempty exact substring beginning there. Emit records in ascending order without overlap.groupscontains capture strings in order, using""for unmatched groups. The last nonempty capture selects the secret's last occurrence withinmatch; 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.
| Subpath | Owner and purpose |
| --- | --- |
| `plugin-sdk/codex-mcp-projection` | Private-local after July 2026; Bundled Codex plugin helper for projecting user MCP server config into Codex app-server thread config (default-only package export) |
| `plugin-sdk/codex-session-transcript-runtime` | Private-local bundled Codex plugin helper for serializing transcript-mirror writes (default-only package export) |
| `plugin-sdk/ssrf-runtime-internal` | Private-local host helper for configured loopback requests owned by bundled Ollama/browser and the exact official `@openclaw/llama-cpp-provider` package (default-only package export) |