Plugin SDK-migratie

OpenClaw is overgestapt van een brede laag voor achterwaartse compatibiliteit naar een moderne Plugin- architectuur met gerichte, gedocumenteerde imports. Als je Plugin is gebouwd vóór de nieuwe architectuur, helpt deze gids je met migreren.

Wat verandert er

Het oude Plugin-systeem bood twee volledig open oppervlakken waarmee Plugins alles wat ze nodig hadden vanuit één enkel ingangspunt konden importeren:

• 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.

De brede importoppervlakken zijn nu verouderd. Ze werken nog steeds tijdens runtime, maar nieuwe Plugins mogen ze niet gebruiken, en bestaande Plugins moeten migreren voordat de volgende major release ze verwijdert. De API voor registratie van extensiefactory's die alleen voor de embedded runner was bedoeld, is verwijderd; gebruik in plaats daarvan tool-result-middleware.

OpenClaw verwijdert of herinterpreteert gedocumenteerd Plugin-gedrag niet in dezelfde wijziging die een vervanging introduceert. Brekende contractwijzigingen moeten eerst via een compatibiliteitsadapter, diagnostiek, documentatie en een deprecatievenster verlopen. Dat geldt voor SDK-imports, manifestvelden, setup-API's, hooks en runtime- registratiegedrag.

Waarom dit is gewijzigd

De oude aanpak veroorzaakte problemen:

• 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

De moderne Plugin-SDK lost dit op: elk importpad (openclaw/plugin-sdk/\<subpath\>) is een kleine, zelfstandige module met een duidelijk doel en een gedocumenteerd contract.

Verouderde gemaksovergangen voor providers voor gebundelde kanalen zijn ook verdwenen. Kanaalbranded helperovergangen waren private mono-repo-snelkoppelingen, geen stabiele Plugin-contracten. Gebruik in plaats daarvan smalle generieke SDK-subpaden. Houd binnen de gebundelde Plugin-werkruimte provider-owned helpers in de eigen api.ts of runtime-api.ts van die Plugin.

Huidige voorbeelden van gebundelde providers:

• 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

Realtime spraak-, telefonie-, meeting- en browser-Talk-code verhuist van oppervlaklokale beurtboekhouding naar een gedeelde Talk-sessiecontroller die wordt geëxporteerd door openclaw/plugin-sdk/realtime-voice. De nieuwe controller beheert de gemeenschappelijke Talk- gebeurtenisenvelop, actieve beurtstatus, capture-status, output-audio-status, recente gebeurtenisgeschiedenis en afwijzing van verouderde beurten. Provider-Plugins moeten vendor- specifieke realtime-sessies blijven beheren; surface-Plugins moeten capture, playback, telefonie- en meeting-eigenaardigheden blijven beheren.

Deze Talk-migratie is bewust brekend schoon:

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.

Nieuwe code mag createTalkEventSequencer(...) niet rechtstreeks aanroepen, tenzij deze een low-level adapter of testfixture implementeert. Geef de voorkeur aan de gedeelde controller zodat beurtgebonden gebeurtenissen niet zonder turn id kunnen worden uitgezonden, verouderde turnEnd- / turnCancel-aanroepen geen nieuwere actieve beurt kunnen wissen, en output-audio-lifecycle- gebeurtenissen consistent blijven tussen telefonie, meetings, browserrelay, managed-room- handoff en native Talk-clients.

De beoogde vorm van de publieke API 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: { 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" });

Browser-owned WebRTC/provider-websocket-sessies gebruiken talk.client.create, omdat de browser de provideronderhandeling en mediatransport beheert terwijl de Gateway referenties, instructies en toolbeleid beheert. talk.session.* is het gemeenschappelijke door Gateway beheerde oppervlak voor gateway-relay-realtime, gateway-relay- transcriptie en managed-room native STT/TTS-sessies.

Verouderde configuraties die realtime-selectors naast talk.provider / talk.providers plaatsten, moeten worden gerepareerd met openclaw doctor --fix; runtime Talk herinterpreteert spraak-/TTS-providerconfiguratie niet als realtime-providerconfiguratie.

De ondersteunde combinaties voor talk.session.create zijn bewust klein:

Kaart met verwijderde methoden:

De uniforme controlevocabulaire is ook bewust smal:

Introduceer geen provider- of platformspecifieke uitzonderingen in core om dit te laten werken. Core beheert de semantiek van Talk-sessies. Provider-plugins beheren het instellen van leverancierssessies. Spraakoproepen en Google Meet beheren telefonie- en vergaderadapters. Browser- en native apps beheren de UX voor apparaatopname en -weergave.

Compatibiliteitsbeleid

Voor externe plugins volgt compatibiliteitswerk deze volgorde:

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

Maintainers kunnen de huidige migratiewachtrij controleren met pnpm plugins:boundary-report. Gebruik pnpm plugins:boundary-report:summary voor compacte aantallen, --owner <id> voor één plugin of compatibiliteitseigenaar, en pnpm plugins:boundary-report:ci wanneer een CI-gate moet falen op verlopen compatibiliteitsrecords, cross-owner gereserveerde SDK-imports of ongebruikte gereserveerde SDK- subpaden. Het rapport groepeert verouderde compatibiliteitsrecords op verwijderdatum, telt lokale code-/docs-verwijzingen, brengt cross-owner gereserveerde SDK-imports naar boven en vat de private memory-host SDK-bridge samen, zodat compatibiliteitsopschoning expliciet blijft in plaats van te vertrouwen op ad-hoczoekopdrachten. Gereserveerde SDK-subpaden moeten bijgehouden eigenaarsgebruik hebben; ongebruikte gereserveerde helper-exports moeten uit de publieke SDK worden verwijderd.

Als een manifestveld nog steeds wordt geaccepteerd, kunnen pluginauteurs het blijven gebruiken totdat de docs en diagnoses anders aangeven. Nieuwe code moet de gedocumenteerde vervanging verkiezen, maar bestaande plugins mogen niet breken tijdens gewone minor releases.

Migreren

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

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

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

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst 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 buildpnpm test -- my-plugin/

Referentie voor importpaden

Deze tabel is bewust de gemeenschappelijke migratiesubset, niet het volledige SDK- oppervlak. De inventaris van compiler-entrypoints staat in scripts/lib/plugin-sdk-entrypoints.json; package-exports worden gegenereerd uit de publieke subset.

Gereserveerde helper-seams voor gebundelde Plugins zijn uit de publieke SDK- exportmap gehaald, behalve expliciet gedocumenteerde compatibiliteitsfacades zoals de verouderde plugin-sdk/discord-shim die behouden blijft voor het gepubliceerde pakket @openclaw/discord@2026.3.13. Eigenaarsspecifieke helpers staan binnen het eigenaarspakket van de Plugin; gedeeld hostgedrag moet via generieke SDK- contracten lopen, zoals plugin-sdk/gateway-runtime, plugin-sdk/security-runtime en plugin-sdk/plugin-config-runtime.

Gebruik de smalste import die bij de taak past. Als je geen export kunt vinden, controleer dan de bron in src/plugin-sdk/ of vraag maintainers welk generiek contract er eigenaar van moet zijn.

Actieve deprecaties

Smalere deprecaties die gelden voor de plugin-SDK, het providercontract, runtime-oppervlak en manifest. Ze werken vandaag nog allemaal, maar worden in een toekomstige major release verwijderd. De vermelding onder elk item koppelt de oude API aan de canonieke vervanging.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

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

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Verwijderingstijdlijn

Alle core-plugins zijn al gemigreerd. Externe plugins moeten migreren vóór de volgende major release.

De waarschuwingen tijdelijk onderdrukken

Stel deze omgevingsvariabelen in terwijl je aan de migratie werkt:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Dit is een tijdelijke uitweg, geen permanente oplossing.

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