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 vóór de nieuwe architectuur is gebouwd, helpt deze gids je bij de migratie.

# Wat verandert er

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

• 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 Plugin-architectuur werd gebouwd.
• openclaw/plugin-sdk/infra-runtime - een brede barrel met runtime-helpers die systeemgebeurtenissen, Heartbeat-status, afleverwachtrijen, fetch/proxy-helpers, 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 load/write-helpers bevat.
• openclaw/extension-api - een bridge die Plugins directe toegang gaf tot host-side helpers zoals de ingesloten agent-runner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde, alleen voor Pi bedoelde gebundelde extension-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 registratie-API voor embedded extension factories die alleen voor Pi 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. Breaking contractwijzigingen moeten eerst via een compatibiliteitsadapter, diagnostiek, documentatie en een deprecation-periode gaan. Dat geldt voor SDK-imports, manifestvelden, setup-API's, hooks en runtime-registratiegedrag.

# Waarom dit is veranderd

De oude aanpak veroorzaakte problemen:

• Trage opstart - het importeren van één helper laadde tientallen niet-gerelateerde modules
• Circulaire afhankelijkheden - brede re-exports maakten het gemakkelijk 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 gedocumenteerd contract.

Legacy provider-convenience-seams voor gebundelde kanalen zijn ook verdwenen. Channel-branded helper-seams waren private mono-repo-snelkoppelingen, geen stabiele Plugin-contracten. Gebruik in plaats daarvan smalle generieke SDK-subpaths. Houd binnen de gebundelde Plugin-workspace 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-seam
• OpenAI houdt provider builders, default-model-helpers en realtime provider builders in zijn eigen api.ts
• OpenRouter houdt provider builder- en onboarding/config-helpers in zijn eigen api.ts

# Migratieplan voor Talk en realtime voice

Realtime voice-, telefonie-, meeting- en browser-Talk-code wordt verplaatst van surface-local turn-boekhouding naar een gedeelde Talk-sessiecontroller die wordt geëxporteerd door openclaw/plugin-sdk/realtime-voice. De nieuwe controller beheert de algemene Talk-eventenvelope, actieve turn-status, capture-status, output-audiostatus, recente eventgeschiedenis en afwijzing van verouderde turns. 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 breaking-clean:

1. Houd de gedeelde controller/runtime-primitieven in plugin-sdk/realtime-voice.
2. Zet gebundelde oppervlakken over op 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 uiteindelijke talk.session.*- en talk.client.*-API.
4. Adverteer één live Talk-eventkanaal in Gateway hello-ok.features.events: talk.event.
5. Verwijder het oude realtime HTTP-endpoint en elk request-time pad voor instruction override.

Nieuwe code mag createTalkEventSequencer(...) niet direct aanroepen, tenzij deze een low-level adapter of test fixture implementeert. Geef de voorkeur aan de gedeelde controller zodat turn-scoped events niet zonder turn id kunnen worden verzonden, verouderde turnEnd / turnCancel-aanroepen geen nieuwere actieve turn kunnen wissen, en output-audio lifecycle-events 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 });
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 de provider-onderhandeling en het mediatransport beheert terwijl de Gateway credentials, instructies en toolbeleid beheert. talk.session.* is het algemene door Gateway beheerde oppervlak voor gateway-relay realtime, gateway-relay transcriptie en managed-room native STT/TTS-sessies.

Legacy configs 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 methodemapping:

Het uniforme control-vocabulaire is ook bewust smal:

Introduceer geen provider- of platformspecial cases in core om dit te laten werken. Core beheert Talk-sessiesemantiek. Provider-Plugins beheren vendor session setup. Voice-call en Google Meet beheren telefonie-/meetingadapters. Browser- en native apps beheren device capture/playback UX.

# 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 diagnostic of warning die het oude pad en de vervanging noemt
4. dek beide paden af in tests
5. documenteer de deprecation en het migratiepad
6. verwijder pas na de aangekondigde migratieperiode, meestal in een major release

Onderhouders 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 tussen eigenaren, of ongebruikte gereserveerde SDK- subpaden. Het rapport groepeert verouderde compatibiliteitsrecords op verwijderdatum, telt lokale code-/docs-verwijzingen, toont gereserveerde SDK-imports tussen eigenaren, en vat de private memory-host SDK-bridge samen zodat compatibiliteitsopschoning expliciet blijft in plaats van te vertrouwen op ad-hoczoekacties. Gereserveerde SDK-subpaden moeten bijgehouden eigenaargebruik hebben; ongebruikte gereserveerde helper-exports moeten uit de openbare SDK worden verwijderd.

Als een manifestveld nog wordt geaccepteerd, kunnen Plugin-auteurs het blijven gebruiken totdat de documentatie en diagnostiek iets anders zeggen. 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 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/

# Referentie voor importpaden

Deze tabel is bewust de gemeenschappelijke migratiesubset, niet het volledige SDK-oppervlak. De volledige lijst met meer dan 200 entrypoints staat in scripts/lib/plugin-sdk-entrypoints.json.

Gereserveerde helper-koppelvlakken voor gebundelde Plugins zijn uit de publieke SDK-exportmap 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 eigenaar-Pluginpakket; gedeeld hostgedrag moet verlopen via generieke SDK-contracten 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 regel onder elk item koppelt de oude API aan de canonieke vervanging.

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

# Verwijderingstijdlijn

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

# De waarschuwingen tijdelijk onderdrukken

Stel deze omgevingsvariabelen in terwijl je aan de migratie werkt:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_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
• Kanaal-Plugins - kanaal-Plugins bouwen
• Provider-Plugins - provider-Plugins bouwen
• Plugin Internals - diepgaande architectuuruitleg
• Plugin Manifest - manifest-schemareferentie