Use this file to discover all available pages before exploring further.

Plugin SDK migration

OpenClaw has moved from a broad backwards-compatibility layer to a modern plugin architecture with focused, documented imports. If your plugin was built before the new architecture, this guide helps you migrate.

What is changing

The old plugin system provided two wide-open surfaces that let plugins import anything they needed from a single entry point:

text
openclaw/plugin-sdk/compat
— a single import that re-exported dozens of helpers. It was introduced to keep older hook-based plugins working while the new plugin architecture was being built.
text
openclaw/plugin-sdk/infra-runtime
— a broad runtime helper barrel that mixed system events, heartbeat state, delivery queues, fetch/proxy helpers, file helpers, approval types, and unrelated utilities.
text
openclaw/plugin-sdk/config-runtime
— a broad config compatibility barrel that still carries deprecated direct load/write helpers during the migration window.
text
openclaw/extension-api
— a bridge that gave plugins direct access to host-side helpers like the embedded agent runner.
text
api.registerEmbeddedExtensionFactory(...)
— a removed Pi-only bundled extension hook that could observe embedded-runner events such as
text
tool_result
.

The broad import surfaces are now deprecated. They still work at runtime, but new plugins must not use them, and existing plugins should migrate before the next major release removes them. The Pi-only embedded extension factory registration API has been removed; use tool-result middleware instead.

OpenClaw does not remove or reinterpret documented plugin behavior in the same change that introduces a replacement. Breaking contract changes must first go through a compatibility adapter, diagnostics, docs, and a deprecation window. That applies to SDK imports, manifest fields, setup APIs, hooks, and runtime registration behavior.

warning

The backwards-compatibility layer will be removed in a future major release. Plugins that still import from these surfaces will break when that happens. Pi-only embedded extension factory registrations already no longer load.

Why this changed

The old approach caused problems:

Slow startup — importing one helper loaded dozens of unrelated modules
Circular dependencies — broad re-exports made it easy to create import cycles
Unclear API surface — no way to tell which exports were stable vs internal

The modern plugin SDK fixes this: each import path (

text

openclaw/plugin-sdk/\<subpath\>

) is a small, self-contained module with a clear purpose and documented contract.

Legacy provider convenience seams for bundled channels are also gone. Channel-branded helper seams were private mono-repo shortcuts, not stable plugin contracts. Use narrow generic SDK subpaths instead. Inside the bundled plugin workspace, keep provider-owned helpers in that plugin's own

text

api.ts

text

runtime-api.ts

Current bundled provider examples:

Anthropic keeps Claude-specific stream helpers in its own
text
api.ts
/
text
contract-api.ts
seam
OpenAI keeps provider builders, default-model helpers, and realtime provider builders in its own
text
api.ts
OpenRouter keeps provider builder and onboarding/config helpers in its own
text
api.ts

Compatibility policy

For external plugins, compatibility work follows this order:

add the new contract
keep the old behavior wired through a compatibility adapter
emit a diagnostic or warning that names the old path and replacement
cover both paths in tests
document the deprecation and migration path
remove only after the announced migration window, usually in a major release

Maintainers can audit the current migration queue with

text

pnpm plugins:boundary-report

. Use

text

pnpm plugins:boundary-report:summary

for compact counts,

text

--owner <id>

for one plugin or compatibility owner, and

text

pnpm plugins:boundary-report:ci

when a CI gate should fail on due compatibility records, cross-owner reserved SDK imports, or unused reserved SDK subpaths. The report groups deprecated compatibility records by removal date, counts local code/docs references, surfaces cross-owner reserved SDK imports, and summarizes the private memory-host SDK bridge so compatibility cleanup stays explicit instead of relying on ad hoc searches. Reserved SDK subpaths must have tracked owner usage; unused reserved helper exports should be removed from the public SDK.

If a manifest field is still accepted, plugin authors can keep using it until the docs and diagnostics say otherwise. New code should prefer the documented replacement, but existing plugins should not break during ordinary minor releases.

How to migrate

Migrate runtime config load/write helpers

Bundled plugins should stop calling `api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` directly. Prefer config that was already passed into the active call path. Long-lived handlers that need the current process snapshot can use `api.runtime.config.current()`. Long-lived agent tools should use the tool context's `ctx.getRuntimeConfig()` inside `execute` so a tool created before a config write still sees the refreshed runtime config.


text
Config writes must go through the transactional helpers and choose an
after-write policy:

```typescript}
await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});
```

Use `afterWrite: { mode: "restart", reason: "..." }` when the caller knows
the change requires a clean gateway restart, and
`afterWrite: { mode: "none", reason: "..." }` only when the caller owns the
follow-up and deliberately wants to suppress the reload planner.
Mutation results include a typed `followUp` summary for tests and logging;
the gateway remains responsible for applying or scheduling the restart.
`loadConfig` and `writeConfigFile` remain as deprecated compatibility
helpers for external plugins during the migration window and warn once with
the `runtime-config-load-write` compatibility code. Bundled plugins and repo
runtime code are protected by scanner guardrails in
`pnpm check:deprecated-internal-config-api` and
`pnpm check:no-runtime-action-load-config`: new production plugin usage
fails outright, direct config writes fail, gateway server methods must use
the request runtime snapshot, runtime channel send/action/client helpers
must receive config from their boundary, and long-lived runtime modules have
zero allowed ambient `loadConfig()` calls.

New plugin code should also avoid importing the broad
`openclaw/plugin-sdk/config-runtime` compatibility barrel. Use the narrow
SDK subpath that matches the job:

| Need                                                            | Import                                        |
| --------------------------------------------------------------- | --------------------------------------------- |
| Config types such as `OpenClawConfig`                           | `openclaw/plugin-sdk/config-types`            |
| Already-loaded config assertions and plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime`   |
| Current runtime snapshot reads                                  | `openclaw/plugin-sdk/runtime-config-snapshot` |
| Config writes                                                   | `openclaw/plugin-sdk/config-mutation`         |
| Session store helpers                                           | `openclaw/plugin-sdk/session-store-runtime`   |
| Markdown table config                                           | `openclaw/plugin-sdk/markdown-table-runtime`  |
| Group policy runtime helpers                                    | `openclaw/plugin-sdk/runtime-group-policy`    |
| Secret input resolution                                         | `openclaw/plugin-sdk/secret-input-runtime`    |
| Model/session overrides                                         | `openclaw/plugin-sdk/model-session-runtime`   |

Bundled plugins and their tests are scanner-guarded against the broad
barrel so imports and mocks stay local to the behavior they need. The broad
barrel still exists for external compatibility, but new code should not
depend on it.

Migrate Pi tool-result extensions to middleware

Bundled plugins must replace Pi-only `api.registerEmbeddedExtensionFactory(...)` tool-result handlers with runtime-neutral middleware.


text
```typescript}
// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});
```

Update the plugin manifest at the same time:

```json}
{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"]
  }
}
```

External plugins cannot register tool-result middleware because it can
rewrite high-trust tool output before the model sees it.

Migrate approval-native handlers to capability facts

Approval-capable channel plugins now expose native approval behavior through `approvalCapability.nativeRuntime` plus the shared runtime-context registry.


text
Key changes:

* Replace `approvalCapability.handler.loadRuntime(...)` with
  `approvalCapability.nativeRuntime`
* Move approval-specific auth/delivery off legacy `plugin.auth` /
  `plugin.approvals` wiring and onto `approvalCapability`
* `ChannelPlugin.approvals` has been removed from the public channel-plugin
  contract; move delivery/native/render fields onto `approvalCapability`
* `plugin.auth` remains for channel login/logout flows only; approval auth
  hooks there are no longer read by core
* Register channel-owned runtime objects such as clients, tokens, or Bolt
  apps through `openclaw/plugin-sdk/channel-runtime-context`
* Do not send plugin-owned reroute notices from native approval handlers;
  core now owns routed-elsewhere notices from actual delivery results
* When passing `channelRuntime` into `createChannelManager(...)`, provide a
  real `createPluginRuntime().channel` surface. Partial stubs are rejected.

See `/plugins/sdk-channel-plugins` for the current approval capability
layout.

Audit Windows wrapper fallback behavior

If your plugin uses `openclaw/plugin-sdk/windows-spawn`, unresolved Windows `.cmd`/`.bat` wrappers now fail closed unless you explicitly pass `allowShellFallback: true`.


text
```typescript}
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  allowShellFallback: true,
});
```

If your caller does not intentionally rely on shell fallback, do not set
`allowShellFallback` and handle the thrown error instead.

Find deprecated imports

Search your plugin for imports from either deprecated surface:


text
```bash}
grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
```

Replace with focused imports

Each export from the old surface maps to a specific modern import path:


text
```typescript}
// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```

For host-side helpers, use the injected plugin runtime instead of importing
directly:

```typescript}
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```

The same pattern applies to other legacy bridge helpers:

| Old import                 | Modern equivalent                            |
| -------------------------- | -------------------------------------------- |
| `resolveAgentDir`          | `api.runtime.agent.resolveAgentDir`          |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
| `resolveAgentIdentity`     | `api.runtime.agent.resolveAgentIdentity`     |
| `resolveThinkingDefault`   | `api.runtime.agent.resolveThinkingDefault`   |
| `resolveAgentTimeoutMs`    | `api.runtime.agent.resolveAgentTimeoutMs`    |
| `ensureAgentWorkspace`     | `api.runtime.agent.ensureAgentWorkspace`     |
| session store helpers      | `api.runtime.agent.session.*`                |

Replace broad infra-runtime imports

`openclaw/plugin-sdk/infra-runtime` still exists for external compatibility, but new code should import the focused helper surface it actually needs:


text
| Need                                       | Import                                         |
| ------------------------------------------ | ---------------------------------------------- |
| System event queue helpers                 | `openclaw/plugin-sdk/system-event-runtime`     |
| Heartbeat event and visibility helpers     | `openclaw/plugin-sdk/heartbeat-runtime`        |
| Pending delivery queue drain               | `openclaw/plugin-sdk/delivery-queue-runtime`   |
| Channel activity telemetry                 | `openclaw/plugin-sdk/channel-activity-runtime` |
| In-memory dedupe caches                    | `openclaw/plugin-sdk/dedupe-runtime`           |
| Safe local-file/media path helpers         | `openclaw/plugin-sdk/file-access-runtime`      |
| Dispatcher-aware fetch                     | `openclaw/plugin-sdk/runtime-fetch`            |
| Proxy and guarded fetch helpers            | `openclaw/plugin-sdk/fetch-runtime`            |
| SSRF dispatcher policy types               | `openclaw/plugin-sdk/ssrf-dispatcher`          |
| Approval request/resolution types          | `openclaw/plugin-sdk/approval-runtime`         |
| Approval reply payload and command helpers | `openclaw/plugin-sdk/approval-reply-runtime`   |
| Error formatting helpers                   | `openclaw/plugin-sdk/error-runtime`            |
| Transport readiness waits                  | `openclaw/plugin-sdk/transport-ready-runtime`  |
| Secure token helpers                       | `openclaw/plugin-sdk/secure-random-runtime`    |
| Bounded async task concurrency             | `openclaw/plugin-sdk/concurrency-runtime`      |
| Numeric coercion                           | `openclaw/plugin-sdk/number-runtime`           |
| Process-local async lock                   | `openclaw/plugin-sdk/async-lock-runtime`       |
| File locks                                 | `openclaw/plugin-sdk/file-lock`                |

Bundled plugins are scanner-guarded against `infra-runtime`, so repo code
cannot regress to the broad barrel.

Migrate channel route helpers

New channel route code should use `openclaw/plugin-sdk/channel-route`. The older route-key and comparable-target names remain as compatibility aliases during the migration window, but new plugins should use the route names that describe the behavior directly:


text
| Old helper                                     | Modern helper                               |
| ---------------------------------------------- | ------------------------------------------- |
| `channelRouteIdentityKey(...)`                 | `channelRouteDedupeKey(...)`                |
| `channelRouteKey(...)`                         | `channelRouteCompactKey(...)`               |
| `ComparableChannelTarget`                      | `ChannelRouteParsedTarget`                  |
| `resolveComparableTargetForChannel(...)`       | `resolveRouteTargetForChannel(...)`         |
| `resolveComparableTargetForLoadedChannel(...)` | `resolveRouteTargetForLoadedChannel(...)`   |
| `comparableChannelTargetsMatch(...)`           | `channelRouteTargetsMatchExact(...)`        |
| `comparableChannelTargetsShareRoute(...)`      | `channelRouteTargetsShareConversation(...)` |

The modern route helpers normalize `{ channel, to, accountId, threadId }`
consistently across native approvals, reply suppression, inbound dedupe,
cron delivery, and session routing. If your plugin owns custom target
grammar, use `resolveChannelRouteTargetWithParser(...)` to adapt that
parser into the same route target contract.

Build and test

```bash} pnpm build pnpm test -- my-plugin/ ```

Import path reference

This table is intentionally the common migration subset, not the full SDK surface. The full list of 200+ entrypoints lives in

text

scripts/lib/plugin-sdk-entrypoints.json

Reserved bundled-plugin helper seams have been retired from the public SDK export map except for explicitly documented compatibility facades such as the deprecated

text

plugin-sdk/discord

shim retained for the published

text

@openclaw/discord@2026.3.13

package. Owner-specific helpers live inside the owning plugin package; shared host behavior should move through generic SDK contracts such as

text

plugin-sdk/gateway-runtime

text

plugin-sdk/security-runtime

, and

text

plugin-sdk/plugin-config-runtime

Use the narrowest import that matches the job. If you cannot find an export, check the source at

text

src/plugin-sdk/

or ask maintainers which generic contract should own it.

Active deprecations

Narrower deprecations that apply across the plugin SDK, provider contract, runtime surface, and manifest. Each one still works today but will be removed in a future major release. The entry below every item maps the old API to its canonical replacement.

note

Extension-level deprecations (inside bundled channel/provider plugins under `extensions/`) are tracked inside their own `api.ts` and `runtime-api.ts` barrels. They do not affect third-party plugin contracts and are not listed here. If you consume a bundled plugin's local barrel directly, read the deprecation comments in that barrel before upgrading.

Removal timeline

When	What happens
Now	Deprecated surfaces emit runtime warnings
Next major release	Deprecated surfaces will be removed; plugins still using them will fail

All core plugins have already been migrated. External plugins should migrate before the next major release.

Suppressing the warnings temporarily

Set these environment variables while you work on migrating:


bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

This is a temporary escape hatch, not a permanent solution.

Getting Started — build your first plugin
SDK Overview — full subpath import reference
Channel Plugins — building channel plugins
Provider Plugins — building provider plugins
Plugin Internals — architecture deep dive
Plugin Manifest — manifest schema reference

OpenClaw Docs

Plugin SDK migration

What is changing

warning

Why this changed

Compatibility policy

How to migrate

Migrate runtime config load/write helpers

Migrate Pi tool-result extensions to middleware

Migrate approval-native handlers to capability facts

Audit Windows wrapper fallback behavior

Find deprecated imports

Replace with focused imports

Replace broad infra-runtime imports

Migrate channel route helpers

Build and test

Import path reference

Active deprecations

note

Removal timeline

Suppressing the warnings temporarily

Related