Plugin-SDK-Migration

OpenClaw ist von einer breiten Rückwärtskompatibilitätsschicht zu einer modernen Plugin- Architektur mit fokussierten, dokumentierten Imports gewechselt. Wenn Ihr Plugin vor der neuen Architektur gebaut wurde, hilft Ihnen dieser Leitfaden bei der Migration.

Was sich ändert

Das alte Plugin-System stellte zwei weit offene Oberflächen bereit, über die Plugins alles, was sie benötigten, von einem einzigen Einstiegspunkt importieren konnten:

• openclaw/plugin-sdk/compat - ein einzelner Import, der Dutzende Hilfsfunktionen erneut exportierte. Er wurde eingeführt, damit ältere Hook-basierte Plugins weiter funktionieren konnten, während die neue Plugin-Architektur aufgebaut wurde.
• openclaw/plugin-sdk/infra-runtime - ein breites Runtime-Hilfs-Barrel, das Systemereignisse, Heartbeat-Zustand, Zustellungswarteschlangen, Fetch-/Proxy-Hilfen, Dateihilfen, Freigabetypen und nicht verwandte Hilfsfunktionen mischte.
• openclaw/plugin-sdk/config-runtime - ein breites Konfigurations-Kompatibilitäts-Barrel, das während des Migrationsfensters weiterhin veraltete direkte Lade-/Schreibhilfen enthält.
• openclaw/extension-api - eine Brücke, die Plugins direkten Zugriff auf hostseitige Hilfen wie den eingebetteten Agent-Runner gab.
• api.registerEmbeddedExtensionFactory(...) - ein entfernter, nur für den Embedded Runner bestimmter Hook für gebündelte Extensions, der Embedded-Runner-Ereignisse wie tool_result beobachten konnte.

Die breiten Import-Oberflächen sind jetzt veraltet. Sie funktionieren zur Laufzeit weiterhin, aber neue Plugins dürfen sie nicht verwenden, und bestehende Plugins sollten vor der nächsten Hauptversion migrieren, in der sie entfernt werden. Die nur für den Embedded Runner bestimmte Extension-Factory-Registrierungs-API wurde entfernt; verwenden Sie stattdessen Tool-Result-Middleware.

OpenClaw entfernt oder interpretiert dokumentiertes Plugin-Verhalten nicht in derselben Änderung neu, die einen Ersatz einführt. Vertragsbrechende Änderungen müssen zuerst über einen Kompatibilitätsadapter, Diagnosen, Dokumentation und ein Deprecation-Fenster laufen. Das gilt für SDK-Imports, Manifest-Felder, Setup-APIs, Hooks und das Registrierungsverhalten zur Laufzeit.

Warum sich das geändert hat

Der alte Ansatz verursachte Probleme:

• Langsamer Start - das Importieren einer Hilfsfunktion lud Dutzende nicht verwandter Module
• Zirkuläre Abhängigkeiten - breite Re-Exports machten es leicht, Importzyklen zu erzeugen
• Unklare API-Oberfläche - es war nicht erkennbar, welche Exporte stabil und welche intern waren

Das moderne Plugin-SDK behebt dies: Jeder Importpfad (openclaw/plugin-sdk/\<subpath\>) ist ein kleines, eigenständiges Modul mit klarem Zweck und dokumentiertem Vertrag.

Legacy-Komfort-Schnittstellen für Provider in gebündelten Channels sind ebenfalls entfernt. Channel-gebrandete Hilfsschnittstellen waren private Mono-Repo-Abkürzungen, keine stabilen Plugin-Verträge. Verwenden Sie stattdessen enge generische SDK-Unterpfade. Innerhalb des gebündelten Plugin-Workspace sollten Provider-eigene Hilfen in der eigenen api.ts oder runtime-api.ts dieses Plugins bleiben.

Aktuelle Beispiele für gebündelte Provider:

• Anthropic hält Claude-spezifische Stream-Hilfen in seiner eigenen api.ts- / contract-api.ts-Schnittstelle
• OpenAI hält Provider-Builder, Default-Model-Hilfen und Realtime-Provider- Builder in seiner eigenen api.ts
• OpenRouter hält Provider-Builder und Onboarding-/Konfigurationshilfen in seiner eigenen api.ts

Migrationsplan für Talk und Echtzeit-Sprache

Realtime-Voice-, Telefonie-, Meeting- und Browser-Talk-Code wird von oberflächenlokaler Turn-Buchhaltung zu einem gemeinsamen Talk-Sitzungscontroller verschoben, der von openclaw/plugin-sdk/realtime-voice exportiert wird. Der neue Controller verwaltet den gemeinsamen Talk-Ereignisumschlag, den aktiven Turn-Zustand, den Capture-Zustand, den Ausgabe-Audio-Zustand, den Verlauf der letzten Ereignisse und die Zurückweisung veralteter Turns. Provider-Plugins sollten weiterhin anbieterspezifische Realtime-Sitzungen verwalten; Oberflächen-Plugins sollten weiterhin Capture, Wiedergabe, Telefonie und Meeting-Besonderheiten verwalten.

Diese Talk-Migration ist bewusst als sauberer Bruch angelegt:

1. Behalten Sie die gemeinsamen Controller-/Runtime-Primitiven in plugin-sdk/realtime-voice.
2. Verschieben Sie gebündelte Oberflächen auf den gemeinsamen Controller: Browser-Relay, Managed-Room-Handoff, Voice-Call-Realtime, Voice-Call-Streaming-STT, Google Meet-Realtime und natives Push-to-Talk.
3. Ersetzen Sie alte Talk-RPC-Familien durch die finale talk.session.*- und talk.client.*-API.
4. Veröffentlichen Sie einen Live-Talk-Ereigniskanal in Gateway hello-ok.features.events: talk.event.
5. Löschen Sie den alten Realtime-HTTP-Endpunkt und jeden Pfad für anfragezeitige Instruction-Overrides.

Neuer Code sollte createTalkEventSequencer(...) nicht direkt aufrufen, außer er implementiert einen Low-Level-Adapter oder eine Test-Fixture. Bevorzugen Sie den gemeinsamen Controller, damit turn-bezogene Ereignisse nicht ohne Turn-ID ausgegeben werden können, veraltete turnEnd- / turnCancel-Aufrufe keinen neueren aktiven Turn löschen können und Ausgabe-Audio-Lebenszyklusereignisse über Telefonie, Meetings, Browser-Relay, Managed-Room-Handoff und native Talk-Clients hinweg konsistent bleiben.

Die angestrebte öffentliche API-Form ist:

// 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-eigene WebRTC-/Provider-WebSocket-Sitzungen verwenden talk.client.create, weil der Browser die Provider-Aushandlung und den Medientransport besitzt, während das Gateway Zugangsdaten, Instructions und Tool-Policy besitzt. talk.session.* ist die gemeinsame vom Gateway verwaltete Oberfläche für Gateway-Relay-Realtime, Gateway-Relay-Transkription und Managed-Room-native STT/TTS-Sitzungen.

Legacy-Konfigurationen, die Realtime-Selektoren neben talk.provider / talk.providers platziert haben, sollten mit openclaw doctor --fix repariert werden; Runtime Talk interpretiert Speech-/TTS-Provider-Konfiguration nicht als Realtime-Provider-Konfiguration neu.

Die unterstützten talk.session.create-Kombinationen sind bewusst klein:

Entfernte Methodenzuordnung:

Das vereinheitlichte Kontrollvokabular ist ebenfalls bewusst eng gefasst:

Führen Sie keine Provider- oder Plattform-Sonderfälle im Core ein, damit dies funktioniert. Core besitzt die Semantik von Talk-Sitzungen. Provider-Plugins besitzen die Einrichtung von Vendor-Sitzungen. Sprachanruf und Google Meet besitzen Telefonie-/Meeting-Adapter. Browser und native Apps besitzen die UX für Geräteaufnahme und Wiedergabe.

Kompatibilitätsrichtlinie

Für externe Plugins folgt Kompatibilitätsarbeit dieser Reihenfolge:

1. den neuen Vertrag hinzufügen
2. das alte Verhalten über einen Kompatibilitätsadapter verdrahtet lassen
3. eine Diagnose oder Warnung ausgeben, die den alten Pfad und den Ersatz benennt
4. beide Pfade in Tests abdecken
5. die Deprecation und den Migrationspfad dokumentieren
6. erst nach dem angekündigten Migrationsfenster entfernen, üblicherweise in einem Major Release

Maintainer können die aktuelle Migrationswarteschlange mit pnpm plugins:boundary-report prüfen. Verwenden Sie pnpm plugins:boundary-report:summary für kompakte Zählungen, --owner <id> für ein einzelnes Plugin oder einen Kompatibilitäts-Owner und pnpm plugins:boundary-report:ci, wenn ein CI-Gate bei fälligen Kompatibilitätseinträgen, ownerübergreifenden reservierten SDK-Importen oder ungenutzten reservierten SDK- Unterpfaden fehlschlagen soll. Der Bericht gruppiert veraltete Kompatibilitätseinträge nach Entfernungsdatum, zählt lokale Code-/Docs-Referenzen, zeigt ownerübergreifende reservierte SDK-Importe an und fasst die private Memory-Host-SDK-Bridge zusammen, damit Kompatibilitätsbereinigung explizit bleibt, statt sich auf Ad-hoc-Suchen zu verlassen. Reservierte SDK-Unterpfade müssen nachverfolgte Owner-Nutzung haben; ungenutzte reservierte Helper-Exports sollten aus dem öffentlichen SDK entfernt werden.

Wenn ein Manifest-Feld weiterhin akzeptiert wird, können Plugin-Autoren es weiter verwenden, bis Docs und Diagnosen etwas anderes sagen. Neuer Code sollte den dokumentierten Ersatz bevorzugen, aber bestehende Plugins sollten bei gewöhnlichen Minor Releases nicht brechen.

So migrieren Sie

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/

Referenz für Importpfade

Diese Tabelle ist absichtlich die gemeinsame Migrations-Teilmenge, nicht die vollständige SDK- Oberfläche. Das Inventar der Compiler-Einstiegspunkte liegt in scripts/lib/plugin-sdk-entrypoints.json; Paket-Exports werden aus der öffentlichen Teilmenge generiert.

Reservierte Helper-Seams für gebündelte Plugins wurden aus der öffentlichen SDK- Export-Map entfernt, außer ausdrücklich dokumentierten Kompatibilitäts-Fassaden wie dem veralteten plugin-sdk/discord-Shim, der für das veröffentlichte Paket @openclaw/discord@2026.3.13 beibehalten wird. Owner-spezifische Helper befinden sich im jeweiligen Plugin-Paket; gemeinsames Host-Verhalten sollte über generische SDK- Verträge wie plugin-sdk/gateway-runtime, plugin-sdk/security-runtime und plugin-sdk/plugin-config-runtime laufen.

Verwenden Sie den engsten Import, der zur Aufgabe passt. Wenn Sie keinen Export finden, prüfen Sie die Quelle unter src/plugin-sdk/ oder fragen Sie Maintainer, welcher generische Vertrag dafür zuständig sein sollte.

Aktive Veraltungen

Engere Veraltungen, die für das gesamte Plugin-SDK, den Provider-Vertrag, die Runtime-Oberfläche und das Manifest gelten. Jede davon funktioniert heute noch, wird aber in einem zukünftigen Major-Release entfernt. Der Eintrag unter jedem Element ordnet die alte API ihrem kanonischen Ersatz zu.

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

Zeitplan für die Entfernung

Alle Kern-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten Major-Version migrieren.

Warnungen vorübergehend unterdrücken

Setzen Sie diese Umgebungsvariablen, während Sie an der Migration arbeiten:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Dies ist ein temporärer Ausweg, keine dauerhafte Lösung.

Verwandte Themen

• Erste Schritte - erstellen Sie Ihr erstes Plugin
• SDK-Übersicht - vollständige Referenz für Subpath-Importe
• Channel-Plugins - Channel-Plugins erstellen
• Provider-Plugins - Provider-Plugins erstellen
• Plugin-Interna - ausführlicher Architekturüberblick
• Plugin-Manifest - Referenz zum Manifest-Schema