Plugin SDK-migratie

​

Wat verandert er

• openclaw/plugin-sdk/compat - één import die tientallen helpers opnieuw exporteerde. Deze werd geïntroduceerd om oudere hook-gebaseerde Plugins te laten werken terwijl de nieuwe Plugin-architectuur werd gebouwd.
• openclaw/plugin-sdk/infra-runtime - een brede runtime-helperbarrel die systeemgebeurtenissen, Heartbeat-status, afleverwachtrijen, fetch/proxy-helpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma’s combineerde.
• openclaw/plugin-sdk/config-runtime - een brede configuratiecompatibiliteitsbarrel die tijdens het migratievenster nog verouderde directe laad-/schrijfhelpers bevat.
• openclaw/extension-api - een brug die Plugins directe toegang gaf tot host-side helpers zoals de ingebouwde agent-runner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde, alleen voor de embedded runner bestemde gebundelde extensie-hook die embedded-runner-gebeurtenissen zoals tool_result kon observeren.

​

Waarom dit is gewijzigd

• Trage start - het importeren van één helper laadde tientallen niet-gerelateerde modules
• Circulaire afhankelijkheden - brede herexports maakten het makkelijk om importcycli te creëren
• Onduidelijk API-oppervlak - geen manier om te zien welke exports stabiel waren versus intern

• Anthropic houdt Claude-specifieke streamhelpers in zijn eigen api.ts / contract-api.ts-overgang
• OpenAI houdt provider-builders, default-model-helpers en realtime-provider- builders in zijn eigen api.ts
• OpenRouter houdt provider-builder- en onboarding-/configuratiehelpers in zijn eigen api.ts

​

Migratieplan voor Talk en realtime spraak

1. Houd de gedeelde controller-/runtime-primitieven in plugin-sdk/realtime-voice.
2. Zet gebundelde oppervlakken over naar de gedeelde controller: browserrelay, managed-room-handoff, realtime voice-call, streaming STT voor voice-call, Google Meet realtime en native push-to-talk.
3. Vervang oude Talk-RPC-families door de definitieve talk.session.*- en talk.client.*-API.
4. Adverteer één live Talk-gebeurteniskanaal in Gateway hello-ok.features.events: talk.event.
5. Verwijder het oude realtime HTTP-endpoint en elk request-time pad voor instructie-override.

// 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: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
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 });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

​

Compatibiliteitsbeleid

1. voeg het nieuwe contract toe
2. houd het oude gedrag aangesloten via een compatibiliteitsadapter
3. geef een diagnose of waarschuwing uit die het oude pad en de vervanging noemt
4. dek beide paden af in tests
5. documenteer de veroudering en het migratiepad
6. verwijder pas na het aangekondigde migratievenster, meestal in een major release

​

Migreren

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

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

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

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

pnpm build
pnpm test -- my-plugin/

​

Referentie voor importpaden

​

Actieve deprecaties

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

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

// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

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

​

Verwijderingstijdlijn

​

De waarschuwingen tijdelijk onderdrukken

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

​

Gerelateerd

• Aan de slag - bouw je eerste plugin
• SDK-overzicht - volledige importreferentie voor subpaden
• Kanaalplugins - kanaalplugins bouwen
• Provider-plugins - provider-plugins bouwen
• Plugin-internals - diepgaande architectuurverkenning
• Pluginmanifest - referentie voor manifestschema