Plugin-SDK-Migration

OpenClaw hat eine umfassende Abwärtskompatibilitätsschicht durch eine moderne Plugin- Architektur ersetzt, die aus kleinen, gezielten Importen aufgebaut ist. Wenn Ihr Plugin vor dieser Änderung erstellt wurde, führt dieser Leitfaden es auf die aktuellen Verträge über.

Was sich geändert hat

Zwei weit offene Importoberflächen ermöglichten Plugins früher, über einen einzigen Einstiegspunkt auf nahezu alles zuzugreifen:

• openclaw/plugin-sdk/compat – exportierte Dutzende Hilfsfunktionen erneut, damit ältere Hook-basierte Plugins weiterhin funktionierten, während die neue Architektur entwickelt wurde.
• openclaw/plugin-sdk/infra-runtime – ein umfassendes Barrel, das Systemereignisse, Heartbeat-Status, Zustellungswarteschlangen, Fetch-/Proxy-Hilfsfunktionen, Dateihilfen, Genehmigungstypen und nicht zusammengehörige Hilfsfunktionen vermischte.
• openclaw/plugin-sdk/config-runtime – ein umfassendes Konfigurations-Barrel, das während des Migrationszeitraums weiterhin veraltete direkte Hilfsfunktionen zum Laden/Schreiben enthielt.
• openclaw/extension-api – eine Brücke, die Plugins direkten Zugriff auf hostseitige Hilfsfunktionen wie den eingebetteten Agent-Runner gewährte.
• api.registerEmbeddedExtensionFactory(...) – ein entfernter, ausschließlich für den eingebetteten Runner vorgesehener Hook, der Ereignisse des eingebetteten Runners wie tool_result beobachtete. Verwenden Sie stattdessen Agent-Middleware für Tool-Ergebnisse (siehe Eingebettete Erweiterungen für Tool-Ergebnisse zu Middleware migrieren).

Diese Oberflächen sind veraltet: Sie funktionieren weiterhin, neue Plugins dürfen sie jedoch nicht verwenden, und bestehende Plugins sollten vor dem nächsten Major-Release migriert werden, in dem sie entfernt werden. registerEmbeddedExtensionFactory wurde bereits entfernt; veraltete Registrierungen werden nicht mehr geladen.

OpenClaw entfernt oder interpretiert dokumentiertes Plugin-Verhalten nicht in derselben Änderung neu, in der ein Ersatz eingeführt wird. Nicht abwärtskompatible Vertragsänderungen durchlaufen zunächst einen Kompatibilitätsadapter, Diagnosen, Dokumentation und einen Übergangszeitraum. Dies gilt für SDK-Importe, Manifestfelder, Einrichtungs-APIs, Hooks und das Registrierungsverhalten zur Laufzeit.

Warum

• Langsamer Start – das Importieren einer Hilfsfunktion lud Dutzende nicht zusammengehöriger Module.
• Zirkuläre Abhängigkeiten – umfassende Re-Exporte erleichterten das Erzeugen von Importzyklen.
• Unklare API-Oberfläche – stabile Exporte ließen sich nicht von internen unterscheiden.

Jedes openclaw/plugin-sdk/<subpath> ist jetzt ein kleines, eigenständiges Modul mit einem dokumentierten Vertrag.

Auch die bisherigen Provider-Komfortschnittstellen für gebündelte Kanäle wurden entfernt – kanalspezifische Hilfsabkürzungen waren private Annehmlichkeiten des Monorepos und keine stabilen Plugin-Verträge. Verwenden Sie stattdessen gezielte generische SDK-Unterpfade. Behalten Sie im Arbeitsbereich des gebündelten Plugins Provider-eigene Hilfsfunktionen in der plugin-eigenen api.ts oder runtime-api.ts:

• Anthropic behält Claude-spezifische Stream-Hilfsfunktionen in seiner eigenen api.ts- / contract-api.ts-Schnittstelle.
• OpenAI behält Provider-Builder, Hilfsfunktionen für Standardmodelle und Builder für Echtzeit-Provider in seiner eigenen api.ts.
• OpenRouter behält Provider-Builder und Hilfsfunktionen für Onboarding/Konfiguration in seiner eigenen api.ts.

Kompatibilitätsrichtlinie

Kompatibilitätsarbeiten für externe Plugins erfolgen in dieser Reihenfolge:

1. Fügen Sie den neuen Vertrag hinzu.
2. Binden Sie das bisherige Verhalten weiterhin über einen Kompatibilitätsadapter ein.
3. Geben Sie eine Diagnose oder Warnung aus, die den bisherigen Pfad und dessen Ersatz nennt.
4. Decken Sie beide Pfade durch Tests ab.
5. Dokumentieren Sie die Veraltung und den Migrationspfad.
6. Entfernen Sie das bisherige Verhalten erst nach dem angekündigten Migrationszeitraum, üblicherweise in einem Major- Release.

Wenn ein Manifestfeld weiterhin akzeptiert wird, verwenden Sie es weiter, bis Dokumentation und Diagnosen etwas anderes angeben. Neuer Code sollte den dokumentierten Ersatz bevorzugen; bestehende Plugins dürfen bei gewöhnlichen Minor-Releases nicht funktionsunfähig werden.

Prüfen Sie die aktuelle Migrationswarteschlange mit pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci wird mit allen drei Fehler-Flags ausgeführt. Jeder Kompatibilitätseintrag besitzt ein ausdrückliches removeAfter-Datum (nicht ein vages „nächstes Major-Release“) – der Bericht gruppiert veraltete Einträge nach diesem Datum, zählt lokale Code-/Dokumentationsreferenzen, zeigt reservierte SDK-Importe über Verantwortlichkeitsgrenzen hinweg an und fasst die private SDK-Brücke zum Memory-Host zusammen. Reservierte SDK-Unterpfade müssen nachverfolgte Nutzung durch den Verantwortlichen aufweisen; ungenutzte reservierte Exporte sollten aus dem öffentlichen SDK entfernt werden.

Migration

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

// Dynamische Tools der OpenClaw- und Codex-Laufzeitapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Vorherconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Nachherconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Legen Sie dies nur für vertrauenswürdige Kompatibilitätsaufrufer fest, die absichtlich  // einen über die Shell vermittelten Fallback akzeptieren.  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/

// Vorher (veraltete Abwärtskompatibilitätsschicht)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Nachher (moderne, gezielte Importe)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";

// Vorher (veraltete extension-api-Brücke)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Nachher (injizierte Runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Referenz der Importpfade

Diese Tabelle bildet die gemeinsame Teilmenge für Migrationen ab, nicht die vollständige SDK-Oberfläche. Das Inventar der Compiler-Einstiegspunkte befindet sich in scripts/lib/plugin-sdk-entrypoints.json; Paketexporte werden aus der öffentlichen Teilmenge generiert.

Reservierte Hilfsschnittstellen für gebündelte Plugins wurden aus der öffentlichen SDK- Exportzuordnung entfernt, mit Ausnahme ausdrücklich dokumentierter Kompatibilitätsfassaden wie dem veralteten plugin-sdk/discord-Shim, der für externe Plugins beibehalten wird, die weiterhin das veröffentlichte Paket @openclaw/discord direkt importieren. Eigentümerspezifische Hilfsfunktionen befinden sich im Paket des jeweiligen Plugins; gemeinsam genutztes Host-Verhalten wird über generische SDK-Verträge wie plugin-sdk/gateway-runtime, plugin-sdk/security-runtime und plugin-sdk/plugin-config-runtime bereitgestellt.

Verwenden Sie den spezifischsten Import, der zur Aufgabe passt. Wenn Sie keinen Export finden, prüfen Sie den Quellcode unter src/plugin-sdk/ oder fragen Sie die Maintainer, welchem generischen Vertrag er zugeordnet werden sollte.

Aktive Veraltungen

Spezifischere Veraltungen innerhalb des Plugin-SDK, des Provider-Vertrags, der Runtime- Oberfläche und des Manifests. Alle funktionieren derzeit noch, werden jedoch in einer zukünftigen Hauptversion entfernt. Jeder Eintrag ordnet die alte API ihrem kanonischen Ersatz zu.

// Vorherimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Nachherimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

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

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

// Vorherconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Nachherconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Vorherimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Nachherimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Migration von Talk und Echtzeitsprachfunktionen

Echtzeitsprach-, Telefonie-, Besprechungs- und Browser-Talk-Code verwendet gemeinsam einen Talk- Sitzungscontroller, der von openclaw/plugin-sdk/realtime-voice exportiert wird. Der Controller verwaltet die gemeinsame Talk-Ereignishülle, den Zustand des aktiven Gesprächsabschnitts, den Aufnahme- zustand, den Ausgabeaudiozustand, den Verlauf der jüngsten Ereignisse und die Zurückweisung veralteter Gesprächsabschnitte. Provider-Plugins verwalten anbieterspezifische Echtzeitsitzungen; Oberflächen-Plugins verwalten Besonderheiten bei Aufnahme, Wiedergabe, Telefonie und Besprechungen.

Alle gebündelten Oberflächen verwenden den gemeinsamen Controller: Browser-Relay, Übergabe an verwaltete Räume, Echtzeit-Sprachanrufe, Streaming-STT für Sprachanrufe, Google Meet in Echtzeit und natives Push-to-Talk. Gateway kündigt in hello-ok.features.events einen Live-Talk-Ereigniskanal an: talk.event.

Neuer Code sollte createTalkEventSequencer(...) nicht direkt aufrufen, es sei denn, er implementiert einen Low-Level-Adapter oder eine Test-Fixture. Verwenden Sie den gemeinsamen Controller, damit auf Gesprächsabschnitte beschränkte Ereignisse nicht ohne Gesprächsabschnitts-ID ausgegeben werden können, veraltete Aufrufe von turnEnd / turnCancel keinen neueren aktiven Gesprächsabschnitt löschen können und Ereignisse des Ausgabeaudio-Lebenszyklus über Telefonie, Besprechungen, Browser-Relay, Übergabe an verwaltete Räume und native Talk-Clients hinweg konsistent bleiben.

Die öffentliche API-Struktur:

// Gateway-eigene Talk-Sitzungs-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-eigene Provider-Sitzungs-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" });

Browsereigene WebRTC-/Provider-WebSocket-Sitzungen verwenden talk.client.create, da der Browser die Provider-Aushandlung und den Medientransport verwaltet, während das Gateway Anmeldedaten, Anweisungen und Werkzeugrichtlinien verwaltet. talk.session.* ist die gemeinsame, vom Gateway verwaltete Oberfläche für Echtzeit über Gateway-Relay, Transkription über Gateway-Relay und native STT-/TTS-Sitzungen in verwalteten Räumen.

Alte Konfigurationen, die Echtzeitselektoren neben talk.provider / talk.providers platzieren, sollten mit openclaw doctor --fix repariert werden; die Talk-Laufzeit interpretiert Sprach-/TTS-Provider-Konfigurationen nicht als Echtzeit-Provider-Konfigurationen um.

Die unterstützten Kombinationen für talk.session.create sind bewusst begrenzt:

Methodenzuordnung für Leser, die von den älteren Familien talk.realtime.* / talk.transcription.* / talk.handoff.* migrieren (alle entfernt):

Das vereinheitlichte Steuerungsvokabular ist ebenfalls bewusst begrenzt:

Führen Sie keine Provider- oder Plattformsonderfälle im Kern ein, damit dies funktioniert. Der Kern ist für die Semantik der Talk-Sitzungen zuständig. Provider-Plugins sind für die Einrichtung der Anbietersitzungen zuständig. Voice-call und Google Meet sind für Telefonie-/Meeting-Adapter zuständig. Browser und native Apps sind für die UX der Geräteerfassung und -wiedergabe zuständig.

Zeitplan für die Entfernung

Alle Kern-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten Hauptversion migriert werden. Führen Sie pnpm plugins:boundary-report aus, um zu sehen, welche Kompatibilitätseinträge für die von Ihrem Plugin verwendeten Oberflächen als Nächstes fällig sind.

Warnungen vorübergehend unterdrücken

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Dies ist ein vorübergehender Notausgang, keine dauerhafte Lösung.

Verwandte Themen

• Erste Schritte - Erstellen Sie Ihr erstes Plugin
• SDK-Übersicht - vollständige Referenz für Subpath-Importe
• Kanal-Plugins - Kanal-Plugins erstellen
• Provider-Plugins - Provider-Plugins erstellen
• Plugin-Interna - ausführliche Erläuterung der Architektur
• Plugin-Manifest - Referenz des Manifest-Schemas