Plugin SDK Subpaths Guide

The plugin SDK exposes a narrow set of public subpaths, alongside bundled helpers that exist only inside the repository. Everything under openclaw/plugin-sdk/ falls into one of these two categories. This page documents both, and flags anything that is private to the local environment. Three files mark the dividing line:

scripts/lib/plugin-sdk-entrypoints.json: the maintained inventory of entrypoints that the build compiles.
scripts/lib/plugin-sdk-private-local-only-subpaths.json: internal subpaths that are kept out of the typed, documented SDK. Production entries stay available as JavaScript-only host runtime exports for separately published official plugins; test-only entries are not exported at all.
scripts/lib/plugin-sdk-entries.mts: derived metadata for public and private exports, supported bundled facades, and public surfaces owned by plugins.

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

For guidance on writing plugins, refer to Plugin SDK overview.

Plugin entry

Subpath	Key exports
`plugin-sdk/plugin-entry`	`definePluginEntry`
`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

Compatibility and private-local helpers

Only subpaths deprecated in a later window remain exported. The July 2026 aliases and unused subpaths were removed, and bundled-only helpers were dropped from the public package, now marked private-local below. 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 also deprecated, with focused subpaths recommended instead.

OpenClaw's Vitest-backed test-helper subpaths are repo-local only and 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 became private-local following the July 2026 cleanup. The package contract guardrails identify which bundled facades stay publicly supported until generic contracts take over. These facades are marked deprecated for fresh code; check the notes in each row below.

Channel subpaths

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`	Deprecated compatibility facade. Use `plugin-sdk/channel-outbound`.
`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 and 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.
`plugin-sdk/channel-lifecycle`	Deprecated compatibility facade. Use `plugin-sdk/channel-outbound`.
`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.
`plugin-sdk/channel-message`	Deprecated compatibility alias for `plugin-sdk/channel-outbound`.
`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/messaging-targets`	Deprecated target parsing alias; use `plugin-sdk/channel-targets`
`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
`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`	Config readers for dependency-light channel streaming (`getChannelStreamingConfigObject`, `resolveChannelStreamingNativeTransport`), used by doctor contract closures and other control-plane paths that must avoid loading the reply pipeline
`plugin-sdk/channel-send-result`	Types for reply results
`plugin-sdk/channel-actions`	Helpers for channel message actions, plus deprecated native schema helpers retained 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; callers comparing routes should use `plugin-sdk/channel-route`
`plugin-sdk/channel-contract`	Types for channel contracts
`plugin-sdk/channel-feedback`	Wiring for feedback and reactions

Channel compatibility subpaths in later windows stay public only until their registry dates. July aliases, including direct-DM access, reply-options, pairing paths, and channel runtime splinters, have been dropped; bundled-only helpers are now private-local.

Provider subpaths

Subpath	Key exports
`plugin-sdk/provider-entry`	Restricted to private use after July 2026; `defineSingleProviderPluginEntry`
`plugin-sdk/provider-setup`	Restricted to private use after July 2026; Curated setup utilities for local and self-hosted providers
`plugin-sdk/cli-backend`	Restricted to private use after July 2026; CLI backend defaults plus watchdog constants
`plugin-sdk/provider-auth-runtime`	Restricted to private use after July 2026; Provider auth runtime utilities: OAuth loopback flow, token exchange, auth persistence, and API-key resolution
`plugin-sdk/provider-oauth-runtime`	Restricted to private use after July 2026; Generic provider OAuth callback types, callback-page rendering, PKCE/state helpers, authorization-input parsing, token-expiry helpers, and abort helpers
`plugin-sdk/provider-auth-api-key`	Restricted to private use after July 2026; API-key onboarding/profile-write helpers like `upsertApiKeyProfile`
`plugin-sdk/provider-auth-result`	Restricted to private use after July 2026; Standard OAuth auth-result builder
`plugin-sdk/provider-env-vars`	Restricted to private use after July 2026; Provider auth env-var lookup helpers
`plugin-sdk/provider-auth`	`createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials`, OpenAI Codex auth-import helpers, deprecated `resolveOpenClawAgentDir` compatibility export
`plugin-sdk/provider-model-shared`	Restricted to private use after July 2026; `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `resolveFamilyForwardCompatModel`, `selectPreferredLocalModelId`, `normalizeModelCompat`, `parseModelRef`, shared replay-policy builders, provider-endpoint helpers, and shared model-id normalization helpers
`plugin-sdk/provider-catalog-live-runtime`	Restricted to private use after July 2026; Live provider model catalog helpers for guarded `/models`-style discovery: `buildLiveModelProviderConfig`, provider-owned `projectRows`, `fetchLiveProviderModelRows`, `getCachedLiveProviderModelRows`, `fetchLiveProviderModelIds`, `LiveModelCatalogHttpError`, `clearLiveCatalogCacheForTests`, TTL cache, and static fallback
`plugin-sdk/provider-catalog-runtime`	Provider catalog augmentation runtime hook and plugin-provider registry seams for contract tests
`plugin-sdk/provider-catalog-shared`	Restricted to private use after July 2026; `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat`
`plugin-sdk/provider-http`	Restricted to private use after July 2026; Generic provider HTTP/endpoint capability helpers, provider HTTP errors, and audio transcription multipart form helpers
`plugin-sdk/provider-web-fetch-contract`	Restricted to private use after July 2026; Narrow web-fetch config/selection contract helpers such as `enablePluginInConfig` and `WebFetchProviderPlugin`
`plugin-sdk/provider-web-fetch`	Restricted to private use after July 2026; Web-fetch provider registration/cache helpers
`plugin-sdk/provider-web-search-config-contract`	Restricted to private use after July 2026; Narrow web-search config/credential helpers for providers that do not need plugin-enable wiring
`plugin-sdk/provider-web-search-contract`	Restricted to private use after July 2026; Narrow web-search config/credential contract helpers such as `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, and scoped credential setters/getters
`plugin-sdk/provider-web-search`	Restricted to private use after July 2026; Web-search provider registration/cache/runtime helpers
`plugin-sdk/embedding-providers`	Restricted to private use after July 2026; General embedding provider types and read helpers, including `EmbeddingProviderAdapter`, `getEmbeddingProvider(...)`, and `listEmbeddingProviders(...)`; plugins register providers through `api.registerEmbeddingProvider(...)` so manifest ownership is enforced
`plugin-sdk/provider-tools`	Restricted to private use after July 2026; `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, and DeepSeek/Gemini/OpenAI schema cleanup + diagnostics
`plugin-sdk/provider-usage`	Private-local after July 2026; Provider usage snapshot types, shared usage fetch helpers, and provider fetchers such as `fetchClaudeUsage`
`plugin-sdk/provider-stream`	Private-local after July 2026; `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper types, plain-text tool-call compat, and shared Anthropic/Google/Kilocode/MiniMax/Moonshot/OpenAI/OpenRouter/Z.AI wrapper helpers
`plugin-sdk/provider-stream-shared`	Private-local after July 2026; Public shared provider stream wrapper helpers including `composeProviderStreamWrappers`, `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPlainTextToolCallCompatWrapper`, `createPayloadPatchStreamWrapper`, `createToolStreamWrapper`, `normalizeOpenAICompatibleReasoningPayload`, `setQwenChatTemplateThinking`, and Anthropic/DeepSeek/OpenAI-compatible stream utilities
`plugin-sdk/provider-transport-runtime`	Private-local after July 2026; Native provider transport helpers such as guarded fetch, tool-result text extraction, transport message transforms, and writable transport event streams
`plugin-sdk/provider-onboard`	Private-local after July 2026; Onboarding config patch helpers
`plugin-sdk/global-singleton`	Private-local after July 2026; Process-local singleton/map/cache helpers
`plugin-sdk/group-activation`	Private-local after July 2026; Narrow group activation mode and command parsing helpers

Provider usage snapshots typically report one or more quota windows, each carrying a label, percent used, and an optional reset time. When a provider exposes balance or account-state text instead of resettable quota windows, it should return summary with an empty windows array rather than inventing percentages. OpenClaw shows that summary text in status output; reserve error for cases where the usage endpoint failed or provided no usable usage data.

Auth and security subpaths

Subpath	Key exports
`plugin-sdk/command-auth`	Deprecated broad command authorization surface (`resolveControlCommandGate`, command registry helpers including dynamic argument menu formatting, sender-authorization helpers); use channel ingress/runtime authorization or command-status helpers
`plugin-sdk/command-status`	Command/help message builders such as `buildCommandsMessagePaginated` and `buildHelpMessage`
`plugin-sdk/approval-auth-runtime`	Approver resolution and same-chat action-auth helpers
`plugin-sdk/approval-client-runtime`	Native exec approval profile/filter helpers
`plugin-sdk/approval-delivery-runtime`	Native approval capability/delivery adapters
`plugin-sdk/approval-gateway-runtime`	Shared approval gateway resolver
`plugin-sdk/approval-reference-runtime`	Private-local after July 2026; Deterministic durable-locator helper for transport-limited approval callbacks
`plugin-sdk/approval-handler-adapter-runtime`	Lightweight native approval adapter loading helpers for hot channel entrypoints
`plugin-sdk/approval-handler-runtime`	Broader approval handler runtime helpers; prefer the narrower adapter/gateway seams when they are enough
`plugin-sdk/approval-native-runtime`	Native approval target, account-binding, route-gate, forwarding fallback, and local native exec prompt suppression helpers
`plugin-sdk/approval-reaction-runtime`	Private-local after July 2026; Hardcoded approval reaction bindings, reaction prompt payloads, reaction target stores, reaction hint text helpers, and compatibility export for local native exec prompt suppression
`plugin-sdk/approval-reply-runtime`	Exec/plugin approval reply payload helpers
`plugin-sdk/approval-runtime`	Exec/plugin approval payload helpers, approval-capability builders, approval auth/profile helpers, native approval routing/runtime helpers, and structured approval display helpers such as `formatApprovalDisplayPath`
`plugin-sdk/command-auth-native`	Native command auth, dynamic argument menu formatting, and native session-target helpers
`plugin-sdk/command-detection`	Shared command detection helpers
`plugin-sdk/command-primitives-runtime`	Lightweight command text predicates for hot channel paths
`plugin-sdk/command-surface`	Private-local after July 2026; Command-body normalization and command-surface helpers
`plugin-sdk/allow-from`	Allow-from parsing, normalization, resolution, and matching helpers
`plugin-sdk/provider-auth-login-flow-runtime`	Private-local after July 2026; Lazy provider auth login flow helpers for private channel and Web UI device-code pairing
`plugin-sdk/channel-secret-basic-runtime`	Narrow secret-contract exports and target-registry builders for non-TTS channel/plugin secret surfaces
`plugin-sdk/channel-secret-tts-runtime`	Private-local after July 2026; Narrow nested channel TTS secret assignment helpers
`plugin-sdk/secret-ref-runtime`	Narrow SecretRef typing, resolution, setup-plan construction, and setup CLI scaffolding for plugin-owned secret providers
`plugin-sdk/security-runtime`	Deprecated broad barrel for trust, DM gating, root-bounded file/path helpers including create-only writes, sync/async atomic file replacement, sibling temp writes, cross-device move fallback, private file-store helpers, symlink-parent guards, external-content, sensitive text redaction, constant-time secret comparison, and secret-collection helpers; prefer focused security/SSRF/secret subpaths
`plugin-sdk/ssrf-policy`	Host allowlist and private-network SSRF policy helpers
`plugin-sdk/ssrf-dispatcher`	Private-local after July 2026; Narrow pinned-dispatcher helpers without the broad infra runtime surface
`plugin-sdk/ssrf-runtime`	Pinned-dispatcher, SSRF-guarded fetch, SSRF error, SSRF policy helpers, and loopback/private host classification
`plugin-sdk/secret-input`	Secret input parsing helpers
`plugin-sdk/webhook-ingress`	Webhook request/target helpers and raw websocket/body coercion
`plugin-sdk/webhook-request-guards`	Request body size/timeout helpers, canonical Gateway browser-origin acceptance via `resolveAcceptedBrowserOrigin`, and `runDetachedWebhookWork` for tracked post-ack processing

Use isLoopbackHost(host) when a plugin needs to allow connections solely from the local host. This option recognizes localhost, IPv4 loopback literals spanning 127.0.0.0/8, ::1, bracketed IPv6, and IPv4-mapped IPv6 loopback literals. Instead of checking text prefixes, it parses the IP literals themselves, meaning a DNS name like 127.0.0.1.evil.com won't be treated as loopback. Reserve isPrivateOrLoopbackHost(host) for cases where private-network hosts, including RFC 1918 addresses, are acceptable as well.

Runtime and storage subpaths

Subpath	Key exports
`plugin-sdk/runtime`	Runtime, logging, and backup utilities, plus plugin install-path warnings and process helpers
`plugin-sdk/runtime-env`	Compact runtime environment, logger, timeout, retry, and backoff utilities
`plugin-sdk/browser-config`	Private-local after July 2026; Supported browser config facade for normalized profiles and defaults, CDP URL parsing, and browser-control auth utilities
`plugin-sdk/agent-harness-task-runtime`	Private-local after July 2026; Generic task lifecycle and completion delivery utilities for harness-backed agents using a host-issued task scope
`plugin-sdk/agent-harness-runtime`	Agent-harness runtime utilities. `acquireSessionWriteLock`, `resolveSessionWriteLockAcquireTimeoutMs`, `resolveSessionWriteLockOptions`, and `SessionWriteLockAcquireTimeoutConfig` are deprecated no-op compatibility exports slated for removal in the 2026.10 release train. They no longer block or create lock sidecars; harnesses should rely on OpenClaw's per-session lane plus the durable writer claim and in-transaction fence.
`plugin-sdk/codex-mcp-projection`	Private-local after July 2026; Bundled Codex helper for mapping user MCP server config into Codex thread config; not for third-party plugins
`plugin-sdk/native-hook-relay-runtime`	Private-local bundled runtime helper for retained native direct-child hook policy; not for third-party plugins
`plugin-sdk/codex-session-transcript-runtime`	Private-local bundled Codex helper for serializing transcript-mirror writes; not for third-party plugins
`plugin-sdk/channel-runtime-context`	Generic channel runtime-context registration and lookup utilities
`plugin-sdk/runtime-store`	`createPluginRuntimeStore`
`plugin-sdk/plugin-command-runtime`	Registry-generation-bound native plugin command candidates, terminal catalog decisions, and exact selected dispatch execution
`plugin-sdk/plugin-runtime`	Deprecated broad barrel for plugin command, hook, HTTP, and interactive helpers; prefer focused plugin runtime subpaths
`plugin-sdk/hook-runtime`	Deprecated broad barrel for webhook and internal hook pipeline helpers; prefer focused hook and plugin runtime subpaths
`plugin-sdk/lazy-runtime`	Lazy runtime import and binding utilities such as `createLazyRuntimeModule`, `createLazyRuntimeMethod`, and `createLazyRuntimeSurface`
`plugin-sdk/process-runtime`	Private-local after July 2026; Process exec utilities
`plugin-sdk/node-host`	Private-local after July 2026; Node-host executable resolution and PTY resume utilities
`plugin-sdk/cli-argv`	Dependency-light root-option parsing for CLI metadata, including `getRootOptionAwareCommandPath` and `consumeRootOptionToken`
`plugin-sdk/cli-runtime`	Private-local after July 2026; Deprecated broad barrel for CLI formatting, wait, version, argument-invocation, and lazy command-group helpers; prefer focused CLI and runtime subpaths
`plugin-sdk/qa-runner-runtime`	Private-local after July 2026; Supported facade exposing plugin QA scenarios through the CLI command surface
`plugin-sdk/tts-runtime`	Private-local after July 2026; Supported facade for text-to-speech config schemas and runtime utilities
`plugin-sdk/gateway-method-runtime`	Reserved Gateway method dispatch helper for plugin HTTP routes that declare `contracts.gatewayMethodDispatch: ["authenticated-request"]`
`plugin-sdk/gateway-runtime`	Gateway client, event-loop-ready client start helper, gateway CLI RPC, gateway protocol errors, advertised LAN host resolution, and channel-status patch utilities
`plugin-sdk/config-contracts`	Focused config surface for plugin config shapes such as `OpenClawConfig` and channel and provider config types, plus the dependency-light runtime helper `resolveGatewayPublicOrigin(cfg)` which returns the normalized `gateway.publicOrigin` (bare http(s) origin, optional reverse-proxy path, no query or hash) or `undefined` when unset, for building links back to the Gateway
`plugin-sdk/plugin-config-runtime`	Deprecated compatibility facade for runtime plugin-config helpers; new plugins use `api.pluginConfig` plus focused config contracts, snapshots, and mutation utilities
`plugin-sdk/config-mutation`	Transactional config mutation utilities such as `mutateConfigFile`, `replaceConfigFile`, and `logConfigUpdated`
`plugin-sdk/message-tool-delivery-hints`	Private-local after July 2026; Shared message-tool delivery metadata hint strings
`plugin-sdk/runtime-config-snapshot`	Current process config snapshot utilities such as `getRuntimeConfig`, `getRuntimeConfigSnapshot`, and test snapshot setters
`plugin-sdk/text-autolink-runtime`	Private-local after July 2026; File-reference autolink detection without the broad text barrel
`plugin-sdk/reply-runtime`	Shared inbound and reply runtime utilities, chunking, dispatch, heartbeat, reply planner
`plugin-sdk/reply-dispatch-runtime`	Narrow reply dispatch and finalize and conversation-label utilities
`plugin-sdk/reply-history`	Shared short-window reply-history utilities. New message-turn code should use `createChannelHistoryWindow`; lower-level map utilities remain deprecated compatibility exports only
`plugin-sdk/reply-reference`	Private-local after July 2026; `createReplyReferencePlanner`
`plugin-sdk/reply-chunking`	Narrow text and markdown chunking utilities
`plugin-sdk/agent-scope-runtime`	Focused agent ID, directory, default-agent, and session-agent scope resolution utilities for dependency-light control-plane and migration paths
`plugin-sdk/session-store-runtime`	Session workflow utilities (`getSessionEntry`, `listSessionEntries`, `patchSessionEntry`, `upsertSessionEntry`), repair and lifecycle helpers (`deleteSessionEntry`, `cleanupSessionLifecycleArtifacts`, `resolveSessionStoreBackupPaths`), marker helpers for transitional `sessionFile` values, bounded recent user/assistant transcript text reads keyed by session identity, session store path and session-key helpers, and updated-at reads, with no broad config writes or maintenance imports
`plugin-sdk/session-catalog`	External session catalog contracts, projections, adoption helpers, and history import
`plugin-sdk/session-discussion`	External session discussion provider contracts, registration, and canonical Control UI session path building
`plugin-sdk/session-transcript-runtime`	Private-local after July 2026; Transcript identity, bounded raw and visible cursors, scoped target/read/write helpers, visible message-entry projection, update publishing, write locks, and transcript memory hit keys
`plugin-sdk/sqlite-runtime`	Private-local after July 2026; Focused SQLite agent-schema, path, and transaction helpers for first-party runtime, without database lifecycle controls
`plugin-sdk/cron-store-runtime`	Private-local after July 2026; Cron store path/load/save helpers
`plugin-sdk/state-paths`	State/OAuth dir path helpers
`plugin-sdk/plugin-state-runtime`	Private-local after July 2026; Plugin-scoped keyed-state and BLOB contracts plus connection pragma, verified WAL maintenance, and atomic STRICT-schema migration helpers. Plugin-state leases were removed; use SQLite transactions and keyed stores instead
`plugin-sdk/routing`	Route/session-key/account binding helpers such as `resolveAgentRoute`, `buildAgentSessionKey`, and `resolveDefaultAgentBoundAccountId`
`plugin-sdk/status-helpers`	Shared channel/account status summary helpers, runtime-state defaults, and issue metadata helpers
`plugin-sdk/target-resolver-runtime`	Private-local after July 2026; Shared target resolver helpers
`plugin-sdk/string-normalization-runtime`	Private-local after July 2026; Slug/string normalization helpers
`plugin-sdk/request-url`	Private-local after July 2026; Extract string URLs from fetch/request-like inputs
`plugin-sdk/run-command`	Timed command runner with normalized stdout/stderr results
`plugin-sdk/param-readers`	Common tool/CLI param readers
`plugin-sdk/tool-plugin`	Define a simple typed agent-tool plugin and expose static metadata for manifest generation
`plugin-sdk/tool-payload`	Private-local after July 2026; Extract normalized payloads from tool result objects
`plugin-sdk/tool-results`	Typed text and JSON agent tool result builders
`plugin-sdk/tool-send`	Extract canonical send target fields from tool args
`plugin-sdk/sandbox`	Private-local after July 2026; Sandbox backend types and SSH/OpenShell command helpers, including fail-fast exec command preflight
`plugin-sdk/temp-path`	Shared temp-download path helpers and private secure temp workspaces
`plugin-sdk/logging-core`	Subsystem logger and redaction helpers
`plugin-sdk/markdown-table-runtime`	Private-local after July 2026; Markdown table mode and conversion helpers
`plugin-sdk/model-session-runtime`	Model/session override helpers such as `applyModelOverrideToSessionEntry` and `resolveAgentMaxConcurrent`
`plugin-sdk/talk-config-runtime`	Private-local after July 2026; Talk provider config resolution helpers
`plugin-sdk/json-store`	Small JSON state read/write helpers
`plugin-sdk/json-unsafe-integers`	Private-local after July 2026; JSON parsing helpers that preserve unsafe integer literals as strings
`plugin-sdk/file-lock`	Private-local after July 2026; Owner-scoped re-entrant file-lock helpers plus Doctor-safe reclaim of definitely stale, unchanged retired lock sidecars. Nested acquisitions share a refcount only when callers pass the same logical-operation `reentrantOwner`; ownerless or different-owner calls contend normally
`plugin-sdk/persistent-dedupe`	Disk-backed dedupe cache helpers
`plugin-sdk/ingress-effect-once`	Durable claim/commit guard for non-idempotent ingress side effects
`plugin-sdk/acp-runtime`	Private-local after July 2026; ACP runtime/session and reply-dispatch helpers
`plugin-sdk/acp-runtime-backend`	Private-local after July 2026; Lightweight ACP backend registration and reply-dispatch helpers for startup-loaded plugins
`plugin-sdk/acp-binding-resolve-runtime`	Private-local after July 2026; Read-only ACP binding resolution without lifecycle startup imports
`plugin-sdk/boolean-param`	Loose boolean param reader
`plugin-sdk/dangerous-name-runtime`	Private-local after July 2026; Dangerous-name matching resolution helpers
`plugin-sdk/device-bootstrap`	Device bootstrap and pairing token helpers, including `BOOTSTRAP_HANDOFF_OPERATOR_SCOPES`
`plugin-sdk/extension-shared`	Shared passive-channel, status, and ambient proxy helper primitives
`plugin-sdk/models-provider-runtime`	`/models` command/provider reply helpers
`plugin-sdk/skill-commands-runtime`	Skill command listing helpers
`plugin-sdk/native-command-registry`	Native command registry/build/serialize helpers
`plugin-sdk/agent-harness`	Experimental trusted-plugin surface for low-level agent harnesses: harness types, active-run steer/abort helpers, OpenClaw tool bridge helpers, runtime-plan tool policy helpers, terminal outcome classification, tool progress formatting/detail helpers, and attempt result utilities
`plugin-sdk/async-lock-runtime`	Private-local after July 2026; Process-local async lock helper for small runtime state files
`plugin-sdk/channel-activity-runtime`	Private-local after July 2026; Channel activity telemetry helper
`plugin-sdk/concurrency-runtime`	Private-local after July 2026; Bounded async task concurrency helper
`plugin-sdk/dedupe-runtime`	Helpers for dedupe caches that live in memory or persist to disk
`plugin-sdk/delivery-queue-runtime`	Restricted to private use after July 2026; utility for draining outbound messages awaiting delivery
`plugin-sdk/file-access-runtime`	Restricted to private use after July 2026; safe handling of local files, temp roots, media source paths, and directory durability
`plugin-sdk/heartbeat-runtime`	Restricted to private use after July 2026; helpers for heartbeat wake-ups, events, and visibility
`plugin-sdk/expect-runtime`	Restricted to private use after July 2026; assertion utility for required values to enforce provable runtime invariants
`plugin-sdk/number-runtime`	Restricted to private use after July 2026; utility for coercing numbers
`plugin-sdk/secure-random-runtime`	Restricted to private use after July 2026; helpers for secure tokens and UUIDs
`plugin-sdk/system-event-runtime`	Restricted to private use after July 2026; narrow helpers for enqueueing and peeking system events
`plugin-sdk/transport-ready-runtime`	Restricted to private use after July 2026; helper that waits for transport readiness
`plugin-sdk/exec-approvals-runtime`	Restricted to private use after July 2026; exec approval policy file helpers that avoid the broad infra-runtime barrel
`plugin-sdk/infra-runtime`	Compatibility shim marked deprecated; rely on injected runtime APIs or documented typed-public subpaths instead
`plugin-sdk/collection-runtime`	Helpers for small bounded caches
`plugin-sdk/diagnostic-runtime`	Helpers for diagnostic flags, events, trace contexts, and normalizing low-cardinality dimensions
`plugin-sdk/error-runtime`	Helpers for error graphs, formatting, coercing unknown values, and shared error classification, along with `PlatformMessageNotDispatchedError` and `isApprovalNotFoundError`
`plugin-sdk/fetch-runtime`	Restricted to private use after July 2026; helpers for wrapped fetch, proxy handling, EnvHttpProxyAgent options, and pinned lookups
`plugin-sdk/runtime-fetch`	Restricted to private use after July 2026; runtime fetch that respects dispatchers without importing proxy or guarded-fetch modules
`plugin-sdk/inline-image-data-url-runtime`	Restricted to private use after July 2026; sanitizer for inline image data URLs and signature sniffing helpers that skip the broad media runtime surface
`plugin-sdk/response-limit-runtime`	Restricted to private use after July 2026; response-body readers bounded by bytes, idle time, and deadlines, without pulling in the broad media runtime surface
`plugin-sdk/session-binding-runtime`	Restricted to private use after July 2026; current conversation binding state without configured binding routing or pairing stores
`plugin-sdk/context-visibility-runtime`	Restricted to private use after July 2026; context visibility resolution and supplemental context filtering that avoid broad config or security imports
`plugin-sdk/string-coerce-runtime`	Narrow coercion and normalization helpers for primitive records and strings, without markdown or logging imports
`plugin-sdk/html-entity-runtime`	Restricted to private use after July 2026; single-pass decoding of semicolon-terminated HTML5 entities without broad text utilities
`plugin-sdk/text-utility-runtime`	Restricted to private use after July 2026; low-level text and path helpers, including HTML escaping for five entities
`plugin-sdk/widget-html`	Detection of complete documents, size validation, and tool input errors for self-contained HTML widgets
`plugin-sdk/host-runtime`	Restricted to private use after July 2026; helpers for normalizing hostnames and SCP hosts
`plugin-sdk/retry-runtime`	Restricted to private use after July 2026; helpers for retry configuration and the retry runner
`plugin-sdk/agent-runtime`	Deprecated broad barrel for agent directory, identity, and workspace helpers, including `resolveAgentDir`, `resolveDefaultAgentDir`, and the deprecated `resolveOpenClawAgentDir` compatibility export; choose focused agent or runtime subpaths instead
`plugin-sdk/directory-runtime`	Directory queries and dedup backed by configuration
`plugin-sdk/keyed-async-queue`	Restricted to private use after July 2026; `KeyedAsyncQueue`

Capability and testing subpaths

Subpath	Key exports
`plugin-sdk/media-runtime`	A deprecated broad media barrel that aggregates `saveRemoteMedia`, `saveResponseMedia`, `readRemoteMediaBuffer`, and the deprecated `fetchRemoteMedia`; switch to `plugin-sdk/media-store`, `plugin-sdk/media-mime`, `plugin-sdk/outbound-media`, and capability runtime subpaths, and when a URL needs to become OpenClaw media, rely on store helpers rather than buffer reads
`plugin-sdk/media-local-roots`	Purpose-built `getAgentScopedMediaLocalRoots(...)` and policy-aware `getAgentScopedMediaLocalRootsForSources(...)` utilities for reading plugin-owned local media
`plugin-sdk/media-mime`	Tight MIME normalization, file-extension mapping, MIME detection, and media-kind utilities
`plugin-sdk/media-store`	Tight media store utilities, for instance `saveMediaBuffer` and `saveMediaStream`
`plugin-sdk/media-generation-runtime`	Private-local after July 2026; shared media-generation failover utilities, candidate selection, and missing-model messaging
`plugin-sdk/media-understanding`	Deprecated compatibility facade for media-understanding provider types and utilities; new providers register via the injected plugin API and keep request helpers plugin-owned
`plugin-sdk/text-chunking`	Outbound text and offset-preserving range chunking, markdown chunking/render utilities, quote-aware HTML tag tokenization, markdown table conversion, directive-tag stripping, and safe-text utilities
`plugin-sdk/speech`	Private-local after July 2026; speech provider types plus provider-facing directive, registry, validation, OpenAI-compatible TTS builder, and speech helper exports
`plugin-sdk/speech-core`	Private-local after July 2026; shared speech provider types, registry, directive, normalization, and speech helper exports
`plugin-sdk/speech-settings`	Lightweight TTS config resolution and normalization primitives without provider registries or synthesis runtime
`plugin-sdk/realtime-transcription`	Private-local after July 2026; realtime transcription provider types, registry helpers, and shared WebSocket session helper
`plugin-sdk/realtime-bootstrap-context`	Private-local after July 2026; realtime profile bootstrap helper for bounded `IDENTITY.md`, `USER.md`, and `SOUL.md` context injection
`plugin-sdk/realtime-voice-audio-queue`	Private-local JavaScript-only host runtime for bundled or separately published official plugins; narrow bounded audio queue seam for lazy realtime voice provider facades without importing the broader realtime voice runtime; not for third-party plugins
`plugin-sdk/realtime-voice-activation`	Private-local; dependency-light realtime-voice activation-name helpers (normalize, match, word-count, sort) for doctor contract closures and other control-plane paths that must not load the realtime voice runtime
`plugin-sdk/realtime-voice`	Private-local after July 2026; realtime voice provider types, registry helpers, shared audio-energy/speech-onset gates, and realtime voice behavior helpers, including the transport-independent session harness and output activity tracking. For official runtime consumers, sender-auth contract revision 1 forwards ingress-authenticated `senderId` and `senderIsOwner` unchanged; ingress owns authentication, and consumers requiring the handoff must fail closed on other revisions.
`plugin-sdk/meeting-runtime`	Browser-meeting session runtime, realtime audio engines/transports, `MeetingPlatformAdapter`, browser/node control, agent-consult, voice-call delegation, setup checks, and SoX command helpers
`plugin-sdk/image-generation`	Private-local after July 2026; image generation provider types plus image asset/data URL helpers and the OpenAI-compatible image provider builder
`plugin-sdk/image-generation-core`	Private-local after July 2026; shared image-generation types, failover, auth, and registry helpers
`plugin-sdk/music-generation`	Private-local after July 2026; music generation provider/request/result types
`plugin-sdk/video-generation`	Private-local after July 2026; video generation provider/request/result types
`plugin-sdk/video-generation-core`	Private-local after July 2026; shared video-generation types, failover helpers, provider lookup, and model-ref parsing
`plugin-sdk/transcripts`	Private-local after July 2026; shared transcript source provider types, registry helpers, meeting-provider bridge factory, session descriptors, and utterance metadata
`plugin-sdk/webhook-targets`	Private-local after July 2026; webhook target registry and route-install helpers
`plugin-sdk/web-media`	Shared remote/local media loading helpers
`plugin-sdk/plugin-test-api`	Repo-local minimal `createTestPluginApi` helper for direct plugin registration unit tests without importing repo test helper bridges
`plugin-sdk/agent-runtime-test-contracts`	Repo-local native agent-runtime adapter contract fixtures for auth, delivery, fallback, tool-hook, prompt-overlay, schema, and transcript projection tests
`plugin-sdk/channel-test-helpers`	Repo-local channel-oriented test helpers for generic actions/setup/status contracts, directory assertions, account startup lifecycle, send-config threading, runtime mocks, status issues, outbound delivery, and hook registration
`plugin-sdk/channel-target-testing`	Repo-local shared target-resolution error-case suite for channel tests
`plugin-sdk/channel-contract-testing`	Repo-local narrow channel contract test helpers without the broad testing barrel
`plugin-sdk/plugin-test-contracts`	Repo-local plugin package, registration, public artifact, runtime API, and import side-effect contract helpers
`plugin-sdk/plugin-state-test-runtime`	Repo-local plugin state store, ingress queue, and state DB test helpers
`plugin-sdk/provider-test-contracts`	Repo-local provider runtime, auth, discovery, onboard, catalog, wizard, media capability, replay policy, realtime STT live-audio, web-search/fetch, and stream contract helpers
`plugin-sdk/provider-http-test-mocks`	Private-local after July 2026; repo-local opt-in Vitest HTTP/auth mocks for provider tests that exercise `plugin-sdk/provider-http`
`plugin-sdk/reply-payload-testing`	Repo-local helpers for attaching metadata to reply payload fixtures
`plugin-sdk/sqlite-runtime-testing`	Repo-local SQLite lifecycle helpers for first-party tests
`plugin-sdk/test-state`	Repo-local isolated OpenClaw state, config, workspace, environment, and auth-profile fixtures for plugin tests
`plugin-sdk/test-fixtures`	Repo-local generic CLI runtime capture, direct-import smoke, sandbox context, skill writer, agent-message, system-event, module reload, bundled plugin path, terminal-text, chunking, auth-token, and typed-case fixtures
`plugin-sdk/test-node-mocks`	Repo-local focused Node builtin mock helpers for use inside Vitest `vi.mock("node:*")` factories

Memory subpaths

Subpath	Key exports
`plugin-sdk/memory-core-host-embedding-registry`	Restricted to private use after July 2026; helper registry for lightweight memory embedding providers
`plugin-sdk/memory-core-host-engine-curated`	Restricted to private use, focused on curated-memory annotation parsing for doctor and promotion paths
`plugin-sdk/memory-core-host-engine-foundation`	Core exports for the memory host foundation engine
`plugin-sdk/memory-core-host-engine-fs`	Restricted to private use, focused on filesystem and user-path helpers for doctor migrations
`plugin-sdk/memory-core-host-engine-embeddings`	Restricted to private use after July 2026; memory host embedding contracts, registry access, and generic batch/remote helpers. `registerMemoryEmbeddingProvider` on this surface is deprecated; use the generic embedding provider API for new providers.
`plugin-sdk/memory-core-host-engine-sessions`	Restricted to private use after July 2026; memory session transcript and query helpers
`plugin-sdk/memory-core-host-engine-schema`	Restricted to private use, focused on memory index schema and sqlite-vec helpers for doctor migrations
`plugin-sdk/memory-core-host-engine-storage`	Restricted to private use after July 2026; memory host storage engine exports
`plugin-sdk/memory-core-host-secret`	Restricted to private use after July 2026; memory host secret helpers
`plugin-sdk/memory-core-host-status`	Restricted to private use after July 2026; memory host status helpers
`plugin-sdk/memory-core-host-runtime-cli`	Restricted to private use after July 2026; memory host CLI runtime helpers
`plugin-sdk/memory-core-host-runtime-core`	Restricted to private use after July 2026; memory host core runtime helpers
`plugin-sdk/memory-core-host-runtime-files`	Restricted to private use after July 2026; memory host file/runtime helpers
`plugin-sdk/memory-host-core`	Deprecated compatibility facade for vendor-neutral memory host helpers. New memory plugins use injected memory capabilities and host-prepared prompts; companion plugins still use the retained facade for public-artifact discovery until a focused read seam exists.
`plugin-sdk/memory-host-events`	Restricted to private use after July 2026; vendor-neutral alias for memory host event journal helpers
`plugin-sdk/memory-host-markdown`	Restricted to private use after July 2026; shared managed-markdown helpers for memory-adjacent plugins
`plugin-sdk/memory-host-search`	Restricted to private use after July 2026; active memory runtime facade for search-manager access

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.

Subpath	Owner and purpose
`plugin-sdk/codex-mcp-projection`	Restricted to private use 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`	Restricted to private use; bundled Codex plugin helper for serializing transcript-mirror writes (default-only package export)
`plugin-sdk/ssrf-runtime-internal`	Restricted to private use; host helper for configured loopback requests owned by bundled Ollama/browser and the exact official `@openclaw/llama-cpp-provider` package (default-only package export)