OpenClaw Plugin SDK migration: replace legacy imports and metadata
An OpenClaw Plugin SDK migration is a maintenance job, not a rewrite. Start by finding broad SDK imports, old hook registrations, and legacy environment-variable metadata. Then move each use to the documented focused contract, keep compatibility fields only for the host versions you still support, and validate the packaged artifact before publishing.
The current migration reference is clear about the reason for this work: broad SDK barrels made it easy to pull unrelated runtime code into a plugin, create circular dependencies, and blur the line between public API and host internals. Focused subpaths make a plugin’s dependency surface easier to inspect and test.
OpenClaw v2026.6.34 put the migration back on the release checklist. Its release notes call out before_agent_start, root openclaw/plugin-sdk imports, providerAuthEnvVars, and channelEnvVars as legacy surfaces. That does not mean every plugin should delete them blindly. The compatibility registry and package validation output tell you which replacement applies and whether your supported host range still needs an adapter.
What changed in the Plugin SDK
The old root SDK and openclaw/plugin-sdk/compat exposed a wide collection of helpers. The migration guide says new code should use a documented openclaw/plugin-sdk/<subpath> import instead. It also lists other broad or retired surfaces, including infra-runtime, config-runtime, and the old openclaw/extension-api bridge.
That is a practical boundary, not a style preference. A plugin that needs one reply-pipeline helper should not import event, queue, filesystem, approval, and proxy utilities just to obtain it. Narrow imports make the dependency visible in review and reduce the chance that a harmless update changes unrelated runtime behavior.
This is separate from building a tool plugin. The earlier guide to typed OpenClaw tool plugins covers defineToolPlugin and package generation. Migration work is about bringing an existing plugin onto supported SDK, hook, and manifest contracts.
OpenClaw Plugin SDK migration checklist
Treat the migration as a series of small checks. Do not combine it with unrelated feature work.
- Inventory imports and manifest fields. Search for root SDK imports,
compat,before_agent_start,providerAuthEnvVars, andchannelEnvVars. Record the OpenClaw versions your package claims to support before changing anything. - Replace broad imports with a documented focused subpath. Use the Plugin SDK migration reference and the SDK subpath catalog to select the public contract for the capability you use. Do not replace a broad import with an undocumented host-internal import just to make TypeScript compile.
- Move old hook behavior to the current hook stage. The migration guide maps retired embedded extension behavior to agent tool-result middleware and documents the modern hook contracts. Pick the replacement that matches the plugin’s actual lifecycle job.
- Make setup metadata declarative. Provider environment variables belong in
setup.providers[].envVars. Channel setup should be represented in current setup, channel-config, or package metadata rather than forcing the host to boot runtime code merely to discover configuration needs. - Keep adapters only when they have a reason. Some compatibility fields remain valid for an announced window or for older supported hosts. Keep the old field only when your support policy requires it, document that policy, and plan its removal.
- Validate the package, not just the source tree. Run
clawhub package validate <path-to-plugin>against the artifact you intend to publish. It catches legacy root imports, missing entrypoints, manifest drift, unsupported fields, and incomplete install metadata.
A recent community discussion put the operational point well: a tool call can succeed while the real outcome is still wrong. Plugin migration deserves the same discipline. A clean compile is one signal. A validated package loaded by a target host is the signal that matters.
Legacy surfaces and the safer replacement path
| Legacy surface | Move toward | Verify before publishing |
|---|---|---|
openclaw/plugin-sdk or /compat | A documented focused SDK subpath | No legacy-root-import finding in package validation |
before_agent_start | The current documented hook stage for the lifecycle job | The hook runs in an integration test with a supported host |
providerAuthEnvVars | setup.providers[].envVars | Setup status is available without starting provider runtime code |
channelEnvVars | Current setup, channel config, or channel package metadata | Channel setup is visible and package validation is clean |
| Embedded tool-result extension factory | Agent tool-result middleware | Tool-result behavior is covered by an end-to-end test |
The table is deliberately conservative. There is no universal search-and-replace for a plugin SDK. A channel package, a provider package, and a small tool plugin have different registration and setup needs. Use the migration page to map the specific surface, then read the focused reference it points to.
How to avoid the two common migration mistakes
The first mistake is treating a compatibility warning as a production outage. OpenClaw’s compatibility policy adds a new contract, routes old behavior through an adapter, emits a diagnostic, documents the change, and only then schedules removal. If your package supports an older host, an adapter may still be appropriate. The decision should come from your version policy, not from the urge to make a warning disappear.
The second mistake is assuming a source-level build proves the package works. Published plugins fail at a different boundary: missing dist entrypoints, mismatched package and manifest versions, incomplete install metadata, or a plugin API range that does not match the host it was tested against. ClawHub’s plugin validation fixes page is useful here because it describes the author-facing finding and the package-level remedy.
For broader architecture, how OpenClaw works explains why this boundary matters. Plugins extend a self-hosted control plane that already owns sessions, policies, channels, tools, and delivery. Keeping plugin setup inspectable makes upgrades less surprising for the operator.
A low-risk rollout sequence
Use a branch that changes one compatibility surface at a time. First update imports and test the plugin’s normal startup. Next migrate one metadata family and run package validation. Finally test the built package against the oldest and newest OpenClaw versions you officially support.
Write down the result for each surface:
- Which legacy path was found?
- Which focused replacement did the docs specify?
- Does an older host still need the compatibility adapter?
- Which package-validation finding disappeared?
- Which integration test proves the behavior still works?
That record pays for itself during the next release. It also prevents a maintenance patch from quietly becoming an unsupported-host break.
If you are still deciding whether a capability should live in a plugin at all, start with what OpenClaw is and the tool plugin guide. Tool plugins, channel plugins, and provider plugins should use the smallest contract that matches their job. Smaller contracts are easier to migrate later.
FAQ
Is openclaw/plugin-sdk still safe to import?
New plugins should use documented focused SDK subpaths. Existing plugins should follow the migration diagnostics and their declared host-version support policy. Do not swap a root import for an internal host import.
Should I remove providerAuthEnvVars immediately?
Move provider environment-variable metadata to setup.providers[].envVars. Keep a compatibility field only if the OpenClaw versions you explicitly support still require it, then remove it when that support window closes.
How do I know whether the migration is complete?
Build the package, run clawhub package validate <path-to-plugin>, and test the published artifact on the supported host versions. A clean source build alone is not enough.
Does this replace the OpenClaw plugin documentation?
No. This guide is a workflow for planning and verifying a migration. The Plugin SDK migration reference, manifest reference, and package-validation documentation are the source of truth for exact contracts and current deprecation windows.
Keep the migration narrow
A Plugin SDK migration is successful when the plugin uses a documented public contract, setup remains inspectable without loading unnecessary runtime code, and the package validates against the host versions it promises to support. Keep the change small, test the actual artifact, and let the compatibility registry decide the timing of any final cleanup.
Sources: OpenClaw Plugin SDK migration reference, OpenClaw plugin validation fixes, OpenClaw v2026.6.34 release notes, OpenClaw Plugin SDK overview, OpenClaw compatibility issue #56402.