Migratie van de Plugin SDK

OpenClaw heeft een brede laag voor achterwaartse compatibiliteit vervangen door een moderne Plugin- architectuur die is opgebouwd uit kleine, gerichte imports. Als jouw Plugin van vóór die wijziging dateert, helpt deze handleiding je om over te stappen op de huidige contracten.

Wat is er gewijzigd

Verschillende zeer ruime importoppervlakken gaven Plugins voorheen vanuit één toegangspunt toegang tot vrijwel alles:

• openclaw/plugin-sdk en openclaw/plugin-sdk/compat - exporteerden tientallen helpers opnieuw terwijl de gerichte SDK werd gebouwd. Beide hoofdpaden zijn nu verwijderd; importeer in plaats daarvan een gedocumenteerd subpad.
• openclaw/plugin-sdk/infra-runtime - een brede barrel die systeem- gebeurtenissen, Heartbeat-status, afleveringswachtrijen, fetch-/proxyhelpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma's combineerde.
• openclaw/plugin-sdk/config-runtime - een brede configuratiebarrel die alleen behouden bleef voor het latere compatibiliteitsvenster; directe runtimehelpers voor laden/schrijven zijn verwijderd.
• openclaw/extension-api - een verwijderde brug die Plugins directe toegang gaf tot helpers aan de hostzijde, zoals de ingebedde agentrunner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde hook die uitsluitend voor de ingebedde runner was bedoeld en gebeurtenissen daarvan observeerde, zoals tool_result. Gebruik in plaats daarvan middleware voor agenttoolresultaten (zie Ingebedde extensies voor toolresultaten migreren naar middleware).

De hoofd-SDK, compatibiliteitsbarrel, extensiebrug en fabriek voor ingebedde extensies zijn verwijderd. infra-runtime en config-runtime blijven alleen bestaan voor hun afzonderlijk vastgelegde latere vensters; nieuwe Plugins moeten gerichte subpaden gebruiken.

OpenClaw verwijdert of herinterpreteert gedocumenteerd Plugingedrag niet in dezelfde wijziging waarin een vervanging wordt geïntroduceerd. Incompatibele contractwijzigingen doorlopen eerst een compatibiliteitsadapter, diagnostiek, documentatie en een uitfaseringsvenster. Dat geldt voor SDK-imports, manifestvelden, installatie-API's, hooks en runtimegedrag voor registratie.

Waarom

• Langzaam opstarten - door één helper te importeren, werden tientallen niet-gerelateerde modules geladen.
• Circulaire afhankelijkheden - brede herexports maakten het eenvoudig om importcycli te creëren.
• Onduidelijk API-oppervlak - er was geen manier om stabiele exports van interne exports te onderscheiden.

Elke openclaw/plugin-sdk/<subpath> is nu een kleine, zelfstandige module met een gedocumenteerd contract.

Verouderde gemaksinterfaces voor providers van gebundelde kanalen zijn ook verdwenen - helpersnelkoppelingen met kanaalnamen waren private gemakken voor de monorepo, geen stabiele Plugincontracten. Gebruik in plaats daarvan smalle, algemene SDK-subpaden. Houd binnen de werkruimte van de gebundelde Plugin helpers die eigendom zijn van de provider in de eigen api.ts of runtime-api.ts van die Plugin:

• Anthropic bewaart Claude-specifieke streamhelpers in zijn eigen api.ts / contract-api.ts-interface.
• OpenAI bewaart providerbouwers, helpers voor standaardmodellen en realtime providerbouwers in zijn eigen api.ts.
• OpenRouter bewaart de providerbouwer en helpers voor onboarding/configuratie in zijn eigen api.ts.

Compatibiliteitsbeleid

Compatibiliteitswerk voor externe Plugins volgt deze volgorde:

1. Voeg het nieuwe contract toe.
2. Behoud het oude gedrag via een compatibiliteitsadapter.
3. Geef een diagnostisch bericht of waarschuwing weer waarin het oude pad en de vervanging worden genoemd.
4. Dek beide paden af met tests.
5. Documenteer de uitfasering en het migratiepad.
6. Verwijder pas na het aangekondigde migratievenster, meestal in een hoofd- release.

Als een manifestveld nog wordt geaccepteerd, blijf het dan gebruiken totdat de documentatie en diagnostiek anders aangeven. Nieuwe code moet de gedocumenteerde vervanging gebruiken; bestaande Plugins mogen niet defect raken tijdens normale kleinere releases.

Compatibiliteit voor installatie van gepubliceerde kanalen

Slack-, Discord-, Signal- en Microsoft Teams-pakketten die via 2026.7.1 worden gepubliceerd, importeren kanaalspecifieke configuratieschema's uit openclaw/plugin-sdk/bundled-channel-config-schema. De gepubliceerde Slack- en Discord-pakketten importeren ook createLegacyCompatChannelDmPolicy en promptLegacyChannelAllowFromForAccount uit openclaw/plugin-sdk/setup-runtime.

Die exports blijven beschikbaar als verouderde runtimecompatibiliteitsadapters. Nieuwe en opnieuw gepubliceerde Plugins moeten hun configuratieschema's en installatiebeleid lokaal beheren, met algemene primitieve onderdelen uit channel-config-schema en setup-runtime. De compatibiliteitsexports kunnen pas worden verwijderd wanneer de minimaal ondersteunde versies van gepubliceerde pakketten ze niet meer importeren.

Compatibiliteit van invoervelden voor kanaalinstallatie

ChannelSetupInput houdt nu alleen de kanaaloverstijgende installatie-envelop permanent getypeerd. Kanaalspecifieke velden blijven getypeerd in een verouderde compatibiliteits- laag, zodat bestaande externe Plugins blijven compileren terwijl Pluginauteurs die velden verplaatsen naar lokale invoertypen voor de installatie van hun Plugin.

OpenClaw brengt geen hoofdreleases uit. Bij een registersweep op 2026-07-22 werden 426 gepubliceerde externe kanaal-Plugins geïnspecteerd en 21 velden zonder lezers verwijderd. De 22 behouden velden hebben elk een bekende gepubliceerde lezer. Elk volgend veld wordt verwijderd zodra geen gepubliceerde Plugin het meer leest; de behouden verzameling krimpt naarmate Pluginauteurs migreren naar lokale invoertypen voor Plugininstallatie.

Dezelfde sweep verwijderde 23 verouderde promotiesleutels voor niet-gedeclareerde adapters zonder gepubliceerde afhankelijken. Zes algemene sleutels en de uitsluitend voor installatie bedoelde sleutel rooms blijven bestaan. Ook die verzameling krimpt naarmate gepubliceerde Plugins singleAccountKeysToMove declareren.

Het gedeelde type heeft geen indexsignatuur. Sleutels die eigendom zijn van Plugins kunnen nog steeds aanwezig zijn in runtime-invoerobjecten; declareer ze in een lokale intersectie voor de Plugin of beperk ze via het installatieschema van de eigenaar-Plugin.

De verouderde promotielaag voor niet-gedeclareerde adapters volgt hetzelfde beleid op basis van lezers. Declareer singleAccountKeysToMove, inclusief een lege array wanneer de Plugin geen extra promotiesleutels nodig heeft, zodat de gedeelde fallback sleutel voor sleutel kan worden uitgefaseerd.

Lezers verifiëren

1. Doorloop https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 pagina voor pagina met elke nextCursor en behoud pakketten waarvan de categories channels bevatten.
2. Voeg npm-kandidaten uit npm search --json --searchlimit=1000 "openclaw channel plugin" toe. Voeg kandidaten toe die alleen als bron beschikbaar zijn via GitHub-codezoekopdrachten naar openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup en openclaw/plugin-sdk/core.
3. Bepaal voor elke kandidaat de laatst gepubliceerde versie. Voer npm pack <package>@<version> --json --pack-destination <temp-dir> uit, pak het pakket uit en inspecteer de meegeleverde dist-JavaScript en declaraties op directe of gedestructureerde leesbewerkingen van velden. Download het ClawHub-artefact wanneer een pakket geen npm-release heeft.
4. Leg pakket, versie, veld of promotiesleutel en overeenkomend bestand vast. Een veld of sleutel kan alleen worden verwijderd wanneer geen gepubliceerd Pluginartefact het leest. Houd de namen van lezers in de codeopmerkingen naast de lijsten met behouden velden en sleutels gesynchroniseerd met de sweep.

Dit is uitsluitend een compatibiliteitsregistratie voor broncode/typen. Er is geen runtimeadapter of vermelding in het compatibiliteitsregister, omdat runtime-invoerobjecten voor installatie en het installatiegedrag ongewijzigd zijn.

Controleer de huidige migratiewachtrij met pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci wordt uitgevoerd met alle drie foutvlaggen. Verouderde registraties hebben normaal gesproken een expliciete datum removeAfter in plaats van een vage 'volgende hoofdrelease'. Bij een registratie waarvan de eigenaar geen datum heeft goedgekeurd, ontbreekt removeAfter, wordt no-date weergegeven en is verwijdering nooit toegestaan. Het rapport groepeert verouderde registraties op datum, telt lokale verwijzingen in code/documentatie, toont gereserveerde SDK-imports tussen eigenaren en vat de private SDK-brug voor de geheugenhost samen. Gereserveerde SDK-subpaden moeten bijgehouden gebruik door eigenaren hebben; ongebruikte gereserveerde exports moeten uit de openbare SDK worden verwijderd.

Verouderde mediaprojectie

De compatibiliteitsregistratie media-legacy-projection omvat de oude parallelle mediavelden, payloadbouwers, aliassen voor hookmetadata en namen van mediasjablonen. De goedgekeurde datum removeAfter is 2026-10-01 (twee releasetreinen nadat de op feiten gebaseerde vervangingen zijn uitgebracht). Voor verwijdering is daarnaast op dat moment een schone sweep van gepubliceerde Pluginartefacten vereist; migreer vóór die datum.

Vervang voor binnenkomende kanaalgegevens de enkelvoudige/meervoudige MediaPath, MediaUrl, MediaType, MediaPaths, MediaUrls, MediaTypes, MediaTranscribedIndexes, MediaWorkspaceDir en MediaStaged door geordende feiten:

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

Gebruik event.media in de hooks inbound_claim en message_received. Als externe media niet lokaal zijn klaargezet, gebruik dan event.originalMedia voor identiteit/diagnostiek en wacht op event.media; event.mediaStagingPending onderscheidt die status. Lees de verouderde enkelvoudige/meervoudige eigenschappen niet uit event.metadata.

Vervang voor CLI-mediamodellen {{MediaPath}}, {{MediaUrl}}, {{MediaType}} en {{MediaDir}} door {{AttachmentPath}}, {{AttachmentUrl}}, {{AttachmentContentType}} en {{AttachmentDir}}. Gebruik {{AttachmentIndex}} wanneer de positie van de bijlage van belang is.

Importeer voor lokaal beleid voor het lezen van media getAgentScopedMediaLocalRoots(...) of getAgentScopedMediaLocalRootsForSources(...) uit openclaw/plugin-sdk/media-local-roots. De openclaw/plugin-sdk/agent-media-payload-facade en de bijbehorende buildAgentMediaPayload(...)-projectie zijn verouderd.

Migreren

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

// OpenClaw-runtimetools en dynamische tools van de Codex-runtime (resultaat kan worden// getransformeerd). Codex-native toolresultaten worden ook doorgestuurd voor observatie,// maar hun getransformeerde uitvoer bereikt het model nooit: het contract van de Codex-// PostToolUse-hook kan een native toolantwoord niet vervangen.api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Voorheenconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Nuconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Stel dit alleen in voor vertrouwde compatibiliteitsaanroepers die bewust  // een door de shell bemiddelde fallback accepteren.  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/

// Voorheen (verouderde laag voor achterwaartse compatibiliteit)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Nu (moderne gerichte 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";

// Voorheen (verouderde extension-api-brug)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Nu (geïnjecteerde runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Naslag voor importpaden

De exportmap van het openbare pakket is de gezaghebbende bron voor importeerbare SDK- subpaden. Gebruik de thematische SDK-handleidingen waarnaar wordt verwezen vanuit het SDK-overzicht en geef de voorkeur aan het specifiekste gedocumenteerde openbare subpad. De compilerinventaris in scripts/lib/plugin-sdk-entrypoints.json bevat ook privé-lokale vermeldingen die worden gebruikt om gebundelde plugins te bouwen; hun aanwezigheid daarin maakt ze niet tot openbare pakketexports.

Deze tabel is de gebruikelijke migratiesubset, niet de volledige SDK-interface. De inventaris met compilerinvoerpunten staat in scripts/lib/plugin-sdk-entrypoints.json; pakketexports worden gegenereerd uit de openbare subset.

Gereserveerde helperinterfaces voor gebundelde plugins zijn uit de openbare SDK- exportmap verwijderd, met uitzondering van expliciet gedocumenteerde compatibiliteitsfacades zoals de verouderde plugin-sdk/discord-shim die behouden blijft voor externe plugins die nog steeds rechtstreeks het gepubliceerde pakket @openclaw/discord importeren. Eigenaarsspecifieke helpers bevinden zich in het pakket van de eigenaar; gedeeld hostgedrag verloopt via generieke SDK-contracten zoals plugin-sdk/gateway-runtime, plugin-sdk/security-runtime en de geïnjecteerde Plugin-API.

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

Verwijderde compatibiliteitsinterfaces

Tijdens de opschoningsronde van juli 2026 zijn de root-SDK- en compat-barrels, de extension API- brug, de verlopen aliassen voor SDK-subpaden, ongebruikte SDK-subpaden en de openbare exports voor uitsluitend gebundelde SDK-modules verwijderd. Uitsluitend gebundelde modules blijven voor hun repository-eigenaren beschikbaar via privé-lokale bouwtoewijzingen; ze zijn niet importeerbaar vanuit het gepubliceerde pakket.

Procesglobale publicatie van API-providers

registerApiProvider(...) en unregisterApiProviders(...) zijn verwijderd uit openclaw/plugin-sdk/llm. Ze publiceerden API-transporten in procesglobale status, die modelruntimes met een eigen levenscyclus vervolgens naar elk voorbereid register moesten kopiëren.

Providerplugins moeten providers voor tekstinferentie registreren via api.registerProvider(...). Code en tests die eigendom zijn van de host en een ApiRegistry aanmaken, moeten rechtstreeks in dat register registreren, zodat providereigendom en afbouw beperkt blijven tot de voorbereide runtime.

Privétestbarrel

openclaw/plugin-sdk/testing was repository-lokaal en uitgesloten van uitgebrachte pakket- artefacten, en is daarom vóór de removeAfter-datum van 2026-07-28 verwijderd. Repository- tests gebruiken gerichte subpaden zoals plugin-sdk/plugin-test-runtime, plugin-sdk/channel-test-helpers, plugin-sdk/channel-target-testing, plugin-sdk/test-env en plugin-sdk/test-fixtures.

Migratienaslag

Deze toewijzingen omvatten zowel in juli 2026 verwijderde oppervlakken als actieve afschrijvingen met een latere termijn. Een toewijzing is migratierichtlijn, geen bewijs dat het oude oppervlak beschikbaar blijft; raadpleeg het compatibiliteitsregister en de verwijderingstijdlijn voor de huidige status.

// Voorheenimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Nuimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

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

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

// Voorconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Naconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Voorimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Naimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

Migratie van Talk en realtime-spraak

Code voor realtime-spraak, telefonie, vergaderingen en browser-Talk gebruikt één Talk- sessiecontroller die wordt geëxporteerd door openclaw/plugin-sdk/realtime-voice. De controller beheert de algemene Talk-eventenvelop, de status van de actieve beurt, de opname- status, de status van uitgaande audio, de recente eventgeschiedenis en het weigeren van verouderde beurten. Providerplugins beheren leveranciersspecifieke realtime-sessies. Plugins voor browservergaderingen gebruiken openclaw/plugin-sdk/meeting-runtime voor sessie-, browser-, audio-, nodehost-, agentconsultatie- en spraakoproepmechanismen en implementeren vervolgens MeetingPlatformAdapter voor URL-regels, DOM-scripts, het koppelen van handmatige acties, ondertiteling, het aanmaken en inbel- plannen. REST-API's van platforms, OAuth, artefacten, selectors en namen voor overdracht blijven in de plugin. Browsermachtigingsplannen ontvangen de aangevraagde vergader-URL, zodat elk platform alleen zijn exact ondersteunde origins kan toestaan. Sessieruntimes moeten ook platformspecifieke live-status normaliseren nadat het verlaten van de browser is bevestigd; historische transcriptvelden mogen behouden blijven, maar de gereedheid van ondertiteling en audio mag na het verlaten niet actief blijven.

Alle gebundelde oppervlakken draaien op de gedeelde controller: browserrelay, overdracht van beheerde ruimtes, realtime-spraakoproepen, streaming-STT voor spraakoproepen, realtime van Google Meet en native push-to-talk. Gateway maakt één live Talk-eventkanaal bekend in hello-ok.features.events: talk.event.

Nieuwe code hoort createTalkEventSequencer(...) niet rechtstreeks aan te roepen, tenzij een adapter op laag niveau of testfixture wordt geïmplementeerd. Gebruik de gedeelde controller, zodat events die aan een beurt zijn gekoppeld niet zonder beurt-id kunnen worden uitgezonden, verouderde aanroepen van turnEnd / turnCancel een nieuwere actieve beurt niet kunnen wissen en lifecycle-events voor uitgaande audio consistent blijven voor telefonie, vergaderingen, browserrelay, overdracht van beheerde ruimtes en native Talk-clients.

De vorm van de openbare API:

// Door Gateway beheerde Talk-sessie-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 }); // Providersessie-API die door de client wordt beheerd.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" });

WebRTC-/provider-websocketsessies die door de browser worden beheerd, gebruiken talk.client.create, omdat de browser de provideronderhandeling en het mediatransport beheert, terwijl de Gateway de inloggegevens, instructies en het toolbeleid beheert. talk.session.* is het algemene, door Gateway beheerde oppervlak voor realtime via gatewayrelay, transcriptie via gatewayrelay en native STT/TTS-sessies in beheerde ruimtes.

Verouderde configuraties die realtime-selectors naast talk.provider / talk.providers plaatsen, moeten worden gerepareerd met openclaw doctor --fix; Talk in de runtime interpreteert providerconfiguratie voor spraak/TTS niet opnieuw als providerconfiguratie voor realtime.

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

Methodetoewijzing voor lezers die migreren van de oudere families talk.realtime.* / talk.transcription.* / talk.handoff.* (allemaal verwijderd):

Het uniforme besturingsvocabulaire is eveneens bewust beperkt:

Voer geen speciale gevallen voor providers of platforms in de kern in om dit te laten werken. De kern beheert de semantiek van Talk-sessies. Providerplugins beheren het opzetten van leverancierssessies. Spraakoproepen en Google Meet beheren telefonie-/vergaderadapters. Browser- en native apps beheren de UX voor opname/afspelen op het apparaat.

Tijdlijn voor verwijdering

De resterende openbare SDK-subpaden hieronder hebben registergestuurde verwijderingsvensters. De rijen van 30 juli zijn verwijderd na hun vroege, door onderhouders goedgekeurde opschoningsronde: ongebruikte subpaden zijn verwijderd, eerdere compatibiliteitsaliassen zijn verwijderd en uitsluitend gebundelde modules zijn gedegradeerd tot privé-lokale buildtoewijzingen.

Alle coreplugins zijn al gemigreerd. Externe plugins moeten migreren vóór de volgende hoofdrelease. Voer pnpm plugins:boundary-report uit om te zien welke compatibiliteitsrecords het eerst verlopen voor de oppervlakken die jouw plugin gebruikt.

De waarschuwingen tijdelijk onderdrukken

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 imports van subpaden
• Kanaalplugins - kanaalplugins bouwen
• Providerplugins - providerplugins bouwen
• Interne werking van plugins - diepgaande architectuurbeschrijving
• Pluginmanifest - referentie voor het manifestschema