Plugin-SDK-migratie

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

Wat verandert er

Het oude pluginsysteem bood twee zeer ruime oppervlakken waarmee plugins alles wat ze nodig hadden vanuit één entrypoint konden importeren:

• openclaw/plugin-sdk/compat - één import die tientallen helpers opnieuw exporteerde. Deze werd geïntroduceerd om oudere, op hooks gebaseerde plugins werkend te houden terwijl de nieuwe pluginarchitectuur werd gebouwd.
• openclaw/plugin-sdk/infra-runtime - een brede barrel voor runtimehelpers die systeemgebeurtenissen, Heartbeat-status, afleverwachtrijen, fetch-/proxyhelpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma's mengde.
• openclaw/plugin-sdk/config-runtime - een brede barrel voor configuratiecompatibiliteit die tijdens de migratieperiode nog verouderde directe laad-/schrijfhelpers bevat.
• openclaw/extension-api - een bridge die plugins directe toegang gaf tot host-side helpers zoals de ingebedde agentrunner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde, alleen voor Pi bedoelde gebundelde extensiehook 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 alleen voor Pi bedoelde registratie-API voor embedded extension factories is verwijderd; gebruik in plaats daarvan tool-result middleware.

OpenClaw verwijdert of herinterpreteert gedocumenteerd plugingedrag niet in dezelfde wijziging die een vervanging introduceert. Brekende contractwijzigingen moeten eerst via een compatibiliteitsadapter, diagnostiek, docs en een deprecation window lopen. Dat geldt voor SDK-imports, manifestvelden, setup-API's, hooks en runtime-registratiegedrag.

Waarom dit is gewijzigd

De oude aanpak veroorzaakte problemen:

• Trage opstart - 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 - er was geen manier om te zien welke exports stabiel waren en welke 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.

Legacy provider-convenience seams voor gebundelde kanalen zijn ook verdwenen. Kanaalgebrande helperseams waren private mono-repo-snelkoppelingen, geen stabiele plugincontracten. Gebruik in plaats daarvan smalle generieke SDK-subpaden. Houd binnen de werkruimte van gebundelde plugins 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 de eigen api.ts / contract-api.ts seam
• OpenAI houdt providerbuilders, default-model-helpers en realtime providerbuilders in de eigen api.ts
• OpenRouter houdt providerbuilder en onboarding-/configuratiehelpers in de eigen api.ts

Migratieplan voor Talk en realtime spraak

Realtime spraak, telefonie, meetings en browser-Talk-code verhuizen van oppervlak-lokale beurtadministratie 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, capturestatus, output-audiostatus, recente gebeurtenisgeschiedenis en afwijzing van verouderde beurten. Providerplugins moeten eigenaar blijven van leveranciersspecifieke realtime sessies; surface-plugins moeten eigenaar blijven van capture, playback, telefonie en meeting-eigenaardigheden.

Deze Talk-migratie is bewust clean breaking:

1. Houd de gedeelde controller-/runtimeprimitieven in plugin-sdk/realtime-voice.
2. Verplaats gebundelde surfaces naar de gedeelde controller: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, 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 pad voor request-time instruction overrides.

Nieuwe code moet createTalkEventSequencer(...) niet direct aanroepen, tenzij die een low-level adapter of testfixture implementeert. Geef de voorkeur aan de gedeelde controller, zodat turn-scoped gebeurtenissen niet zonder turn id kunnen worden uitgezonden, verouderde turnEnd- / turnCancel-aanroepen geen nieuwere actieve beurt kunnen wissen, en lifecycle-gebeurtenissen voor output-audio consistent blijven in telefonie, meetings, browser relay, managed-room handoff en native Talk-clients.

De beoogde publieke API-vorm 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 });

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

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

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

Verwijderde methodemap:

De uniforme controlevocabulaire is ook bewust smal:

Voer geen provider- of platformspecifieke uitzonderingen in de kern in om dit te laten werken. De kern beheert de semantiek van Talk-sessies. Providerplugins beheren de sessie-instelling van leveranciers. Spraakoproepen en Google Meet beheren telefonie-/vergaderadapters. Browsers en native apps beheren de UX voor apparaatopname/-weergave.

Compatibiliteitsbeleid

Voor externe plugins volgt compatibiliteitswerk deze volgorde:

1. voeg het nieuwe contract toe
2. houd het oude gedrag verbonden 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 afschaffing en het migratiepad
6. verwijder pas na de aangekondigde migratieperiode, 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 vervallen compatibiliteitsrecords, gereserveerde SDK-imports over eigenaren heen, of ongebruikte gereserveerde SDK- subpaden. Het rapport groepeert verouderde compatibiliteitsrecords op verwijderdatum, telt lokale code-/docsverwijzingen, toont gereserveerde SDK-imports over eigenaren heen, en vat de private SDK-brug voor geheugenhosts samen zodat compatibiliteitsopschoning expliciet blijft in plaats van te vertrouwen op ad-hoczoekopdrachten. Gereserveerde SDK-subpaden moeten bijgehouden eigenaarsgebruik hebben; ongebruikte gereserveerde helperexports 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 ??= {};  },});

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ 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 exportmap van de publieke SDK verwijderd, behalve expliciet gedocumenteerde compatibiliteitsfacades zoals de verouderde plugin-sdk/discord-shim die behouden blijft voor het gepubliceerde @openclaw/[email protected]-pakket. Eigenaarsspecifieke helpers staan binnen het pakket van de beherende Plugin; gedeeld hostgedrag moet via generieke SDK-contracten verlopen, 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 ervoor verantwoordelijk moet zijn.

Actieve deprecations

Smallere deprecations die gelden voor de Plugin-SDK, het providercontract, het runtime-oppervlak en het 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";

{  "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 referentie voor subpad-imports
• Kanaal-Plugins - kanaal-Plugins bouwen
• Provider-Plugins - provider-Plugins bouwen
• Plugin-internals - diepgaande architectuuruitleg
• Plugin-manifest - referentie voor manifestschema