docs/plugins/sdk-subpaths.md
The plugin SDK is exposed as a set of narrow public subpaths under
openclaw/plugin-sdk/. This page catalogs the commonly used subpaths grouped by
purpose. Three files define the surface:
scripts/lib/plugin-sdk-entrypoints.json: the maintained entrypoint inventory
the build compiles.scripts/lib/plugin-sdk-private-local-only-subpaths.json: repo-local
test/internal subpaths. Package exports are the inventory minus this list.src/plugin-sdk/entrypoints.ts: classification metadata for deprecated
subpaths, reserved bundled helpers, supported bundled facades, and
plugin-owned public surfaces.Maintainers audit the public export count with pnpm plugin-sdk:surface and
active reserved helper subpaths with pnpm plugins:boundary-report:summary;
unused reserved helper exports fail the CI report instead of staying in the
public SDK as dormant compatibility debt.
For the plugin authoring guide, see Plugin SDK overview.
| Subpath | Key exports |
|---|---|
plugin-sdk/plugin-entry | definePluginEntry |
plugin-sdk/core | defineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema, buildJsonChannelConfigSchema |
plugin-sdk/provider-entry | defineSingleProviderPluginEntry |
plugin-sdk/migration | Migration provider item helpers such as createMigrationItem, reason constants, item status markers, redaction helpers, and summarizeMigrationItems |
plugin-sdk/migration-runtime | 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/config-schema | Deprecated. Root openclaw.json Zod schema (OpenClawSchema); define plugin-local schemas instead and validate with plugin-sdk/json-schema-runtime |
Deprecated subpaths stay exported for older plugins, but new code should use the
focused SDK subpaths below. The maintained list is
scripts/lib/plugin-sdk-deprecated-public-subpaths.json; CI rejects bundled
production imports from it. Broad barrels such as plugin-sdk/compat,
plugin-sdk/config-types, plugin-sdk/infra-runtime, and
plugin-sdk/text-runtime are compatibility only, and plugin-sdk/zod is a
compatibility re-export: import zod directly from zod. The broad domain
barrels plugin-sdk/agent-runtime, plugin-sdk/channel-lifecycle,
plugin-sdk/channel-runtime, plugin-sdk/cli-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.
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-node-mocks, and testing. The private bundled helper surfaces
ssrf-runtime-internal and codex-native-task-runtime are also repo-local
only.
plugin-sdk/codex-mcp-projection is the only reserved subpath: a plugin-owned
compatibility surface for the bundled Codex plugin, not a general SDK API.
Cross-owner plugin imports are blocked by package contract guardrails, and
CI fails when a reserved subpath stops being imported.
plugin-sdk/codex-native-task-runtime is repo-local only and is not a package
export.
src/plugin-sdk/entrypoints.ts also tracks supported bundled facades, SDK
entrypoints backed by their bundled plugin until generic contracts replace
them: plugin-sdk/discord, plugin-sdk/lmstudio, plugin-sdk/lmstudio-runtime,
plugin-sdk/matrix, plugin-sdk/mattermost,
plugin-sdk/memory-core-engine-runtime, plugin-sdk/provider-zai-endpoint,
plugin-sdk/qa-runner-runtime, plugin-sdk/telegram-account,
plugin-sdk/tts-runtime, and plugin-sdk/zalouser. Several of these are also
deprecated for new code; see the per-row notes below.
Deprecated channel helper families stay available only for published-plugin
compatibility. The removal plan is: keep them through the external plugin
migration window, keep repo/bundled plugins on channel-inbound and
channel-outbound, then remove the compatibility subpaths in the next major
SDK cleanup. This applies to the old channel message/runtime, channel
streaming, direct-DM access, inbound helper splinter, reply-options,
and pairing-path families.
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.
| Subpath | Owner and purpose |
| --- | --- |
| `plugin-sdk/codex-mcp-projection` | Bundled Codex plugin helper for projecting user MCP server config into Codex app-server thread config (reserved package export) |
| `plugin-sdk/codex-native-task-runtime` | Bundled Codex plugin helper for mirroring Codex app-server native subagents into OpenClaw task state (repo-local only, not a package export) |