OpenClaw has moved from a broad backwards-compatibility layer to a modern plugin
\narchitecture with focused, documented imports. If your plugin was built before
\nthe new architecture, this guide helps you migrate.<\/p>\n
The old plugin system provided two wide-open surfaces that let plugins import
\nanything they needed from a single entry point:<\/p>\n
openclaw\/plugin-sdk\/compat<\/code><\/strong> \u2014 a single import that re-exported dozens of
\n helpers. It was introduced to keep older hook-based plugins working while the
\n new plugin architecture was being built.<\/li>\nopenclaw\/extension-api<\/code><\/strong> \u2014 a bridge that gave plugins direct access to
\n host-side helpers like the embedded agent runner.<\/li>\n<\/ul>\nBoth surfaces are now deprecated<\/strong>. They still work at runtime, but new
\nplugins must not use them, and existing plugins should migrate before the next
\nmajor release removes them.<\/p>\n\n The backwards-compatibility layer will be removed in a future major release.
\n Plugins that still import from these surfaces will break when that happens.\n<\/p>\n
Why this changed<\/h2>\n
The old approach caused problems:<\/p>\n
\n- Slow startup<\/strong> \u2014 importing one helper loaded dozens of unrelated modules<\/li>\n
- Circular dependencies<\/strong> \u2014 broad re-exports made it easy to create import cycles<\/li>\n
- Unclear API surface<\/strong> \u2014 no way to tell which exports were stable vs internal<\/li>\n<\/ul>\n
The modern plugin SDK fixes this: each import path (openclaw\/plugin-sdk\/<subpath><\/code>)
\nis a small, self-contained module with a clear purpose and documented contract.<\/p>\nHow to migrate<\/h2>\n
Search your plugin for imports from either deprecated surface:<\/p>\n
```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\ngrep -r \"plugin-sdk\/compat\" my-plugin\/\ngrep -r \"openclaw\/extension-api\" my-plugin\/\n```\n<\/code><\/pre>\n<\/p>\n\n Each export from the old surface maps to a specific modern import path:<\/p>\n
```typescript theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n\/\/ Before (deprecated backwards-compatibility layer)\nimport {\n createChannelReplyPipeline,\n createPluginRuntimeStore,\n resolveControlCommandGate,\n} from \"openclaw\/plugin-sdk\/compat\";\n\n\/\/ After (modern focused imports)\nimport { createChannelReplyPipeline } from \"openclaw\/plugin-sdk\/channel-reply-pipeline\";\nimport { createPluginRuntimeStore } from \"openclaw\/plugin-sdk\/runtime-store\";\nimport { resolveControlCommandGate } from \"openclaw\/plugin-sdk\/command-auth\";\n```\n\nFor host-side helpers, use the injected plugin runtime instead of importing\ndirectly:\n\n```typescript theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n\/\/ Before (deprecated extension-api bridge)\nimport { runEmbeddedPiAgent } from \"openclaw\/extension-api\";\nconst result = await runEmbeddedPiAgent({ sessionId, prompt });\n\n\/\/ After (injected runtime)\nconst result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });\n```\n\nThe same pattern applies to other legacy bridge helpers:\n\n| Old import | Modern equivalent |\n| -------------------------- | -------------------------------------------- |\n| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |\n| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |\n| `resolveAgentIdentity` | `api.runtime.agent.resolveAgentIdentity` |\n| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |\n| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |\n| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |\n| session store helpers | `api.runtime.agent.session.*` |\n<\/code><\/pre>\n<\/p>\n\n bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n pnpm build
\n pnpm test -- my-plugin\/<\/code><\/p>\nImport path reference<\/h2>\n
\n | Import path | Purpose | Key exports |
\n | ———————————– | ———————————— | ———————————————– |
\n | plugin-sdk\/core<\/code> | Plugin entry definitions, base types | defineChannelPluginEntry<\/code>, definePluginEntry<\/code> |
\n | plugin-sdk\/channel-setup<\/code> | Setup wizard adapters | createOptionalChannelSetupSurface<\/code> |
\n | plugin-sdk\/channel-pairing<\/code> | DM pairing primitives | createChannelPairingController<\/code> |
\n | plugin-sdk\/channel-reply-pipeline<\/code> | Reply prefix + typing wiring | createChannelReplyPipeline<\/code> |
\n | plugin-sdk\/channel-config-helpers<\/code> | Config adapter factories | createHybridChannelConfigAdapter<\/code> |
\n | plugin-sdk\/channel-config-schema<\/code> | Config schema builders | Channel config schema types |
\n | plugin-sdk\/channel-policy<\/code> | Group\/DM policy resolution | resolveChannelGroupRequireMention<\/code> |
\n | plugin-sdk\/channel-lifecycle<\/code> | Account status tracking | createAccountStatusSink<\/code> |
\n | plugin-sdk\/channel-runtime<\/code> | Runtime wiring helpers | Channel runtime utilities |
\n | plugin-sdk\/channel-send-result<\/code> | Send result types | Reply result types |
\n | plugin-sdk\/runtime-store<\/code> | Persistent plugin storage | createPluginRuntimeStore<\/code> |
\n | plugin-sdk\/allow-from<\/code> | Allowlist formatting | formatAllowFromLowercase<\/code> |
\n | plugin-sdk\/allowlist-resolution<\/code> | Allowlist input mapping | mapAllowlistResolutionInputs<\/code> |
\n | plugin-sdk\/command-auth<\/code> | Command gating | resolveControlCommandGate<\/code> |
\n | plugin-sdk\/secret-input<\/code> | Secret input parsing | Secret input helpers |
\n | plugin-sdk\/webhook-ingress<\/code> | Webhook request helpers | Webhook target utilities |
\n | plugin-sdk\/reply-payload<\/code> | Message reply types | Reply payload types |
\n | plugin-sdk\/provider-onboard<\/code> | Provider onboarding patches | Onboarding config helpers |
\n | plugin-sdk\/keyed-async-queue<\/code> | Ordered async queue | KeyedAsyncQueue<\/code> |
\n | plugin-sdk\/testing<\/code> | Test utilities | Test helpers and mocks |\n<\/p>\nUse the narrowest import that matches the job. If you cannot find an export,
\ncheck the source at src\/plugin-sdk\/<\/code> or ask in Discord.<\/p>\nRemoval timeline<\/h2>\n