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:

• 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.
• 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.
• openclaw/plugin-sdk/config-runtime - a broad config compatibility barrel that still carries deprecated direct load/write helpers during the migration window.
• openclaw/extension-api - a bridge that gave plugins direct access to host-side helpers like the embedded agent runner.
• api.registerEmbeddedExtensionFactory(...) - a removed Pi-only bundled extension hook that could observe embedded-runner events such as 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.

# 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 (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 api.ts or runtime-api.ts.

Current bundled provider examples:

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

# Talk and realtime voice migration plan

Realtime voice, telephony, meeting, and browser Talk code is moving from surface-local turn bookkeeping to a shared Talk session controller exported by openclaw/plugin-sdk/realtime-voice. The new controller owns the common Talk event envelope, active turn state, capture state, output-audio state, recent event history, and stale-turn rejection. Provider plugins should keep owning vendor-specific realtime sessions; surface plugins should keep owning capture, playback, telephony, and meeting quirks.

This Talk migration is intentionally breaking-clean:

1. Keep the shared controller/runtime primitives in plugin-sdk/realtime-voice.
2. Move bundled surfaces onto the shared controller: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime, and native push-to-talk.
3. Replace old Talk RPC families with the final talk.session.* and talk.client.* API.
4. Advertise one live Talk event channel in Gateway hello-ok.features.events: talk.event.
5. Delete the old realtime HTTP endpoint and any request-time instruction override path.

New code should not call createTalkEventSequencer(...) directly unless it is implementing a low-level adapter or test fixture. Prefer the shared controller so turn-scoped events cannot be emitted without a turn id, stale turnEnd / turnCancel calls cannot clear a newer active turn, and output-audio lifecycle events stay consistent across telephony, meetings, browser relay, managed-room handoff, and native Talk clients.

The target public API shape is:

// Gateway-owned Talk session API.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// Client-owned provider session API.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });

Browser-owned WebRTC/provider-websocket sessions use talk.client.create, because the browser owns the provider negotiation and media transport while the Gateway owns credentials, instructions, and tool policy. talk.session.* is the common Gateway-managed surface for gateway-relay realtime, gateway-relay transcription, and managed-room native STT/TTS sessions.

Legacy configs that placed realtime selectors beside talk.provider / talk.providers should be repaired with openclaw doctor --fix; runtime Talk does not reinterpret speech/TTS provider config as realtime provider config.

The supported talk.session.create combinations are intentionally small:

Removed method map:

The unified control vocabulary is also deliberately narrow:

Do not introduce provider or platform special cases in core to make this work. Core owns Talk session semantics. Provider plugins own vendor session setup. Voice-call and Google Meet own telephony/meeting adapters. Browser and native apps own device capture/playback UX.

# Compatibility policy

For external plugins, compatibility work follows this order:

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

Maintainers can audit the current migration queue with pnpm plugins:boundary-report. Use pnpm plugins:boundary-report:summary for compact counts, --owner <id> for one plugin or compatibility owner, and 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

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

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

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

// 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,
});

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/

// 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";

// 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 });

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 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 plugin-sdk/discord shim retained for the published @openclaw/[email protected] package. Owner-specific helpers live inside the owning plugin package; shared host behavior should move through generic SDK contracts such as plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, and plugin-sdk/plugin-config-runtime.

Use the narrowest import that matches the job. If you cannot find an export, check the source at 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.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# Removal timeline

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:

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.

# Related

• 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