Plugin-SDK-Migration

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

Was sich ändert

Das alte Plugin-System stellte zwei weit geöffnete 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, um ältere Hook-basierte Plugins funktionsfähig zu halten, während die neue Plugin-Architektur aufgebaut wurde.
• openclaw/plugin-sdk/infra-runtime - ein breites Runtime-Hilfs- barrel, das Systemereignisse, Heartbeat-Status, Zustellungswarteschlangen, Fetch-/Proxy-Hilfen, Dateihilfen, Genehmigungstypen und nicht verwandte Dienstprogramme vermischte.
• openclaw/plugin-sdk/config-runtime - ein breites Config-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 Pi gebündelter Extension-Hook, der eingebettete 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 migriert werden, bevor sie im nächsten Major-Release entfernt werden. Die Pi-only-API zur Registrierung einer eingebetteten Extension-Factory wurde entfernt; verwenden Sie stattdessen Tool-Result-Middleware.

OpenClaw entfernt oder reinterpretieren dokumentiertes Plugin-Verhalten nicht in derselben Änderung, die einen Ersatz einführt. Breaking-Contract-Änderungen müssen zuerst durch einen Kompatibilitätsadapter, Diagnosen, Dokumentation und ein Deprecation-Fenster gehen. Das gilt für SDK-Imports, Manifest-Felder, Setup-APIs, Hooks und Runtime- Registrierungsverhalten.

Warum sich das geändert hat

Der alte Ansatz verursachte Probleme:

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

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

Legacy-Komfortseams für Provider gebündelter Channels sind ebenfalls entfernt. Channel-gebrandete Hilfsseams waren private Mono-Repo-Abkürzungen, keine stabilen Plugin-Verträge. Verwenden Sie stattdessen schmale generische SDK-Subpaths. Innerhalb des gebündelten Plugin-Workspace sollten Provider-eigene Hilfen im jeweiligen eigenen api.ts oder runtime-api.ts des Plugins bleiben.

Aktuelle Beispiele für gebündelte Provider:

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

Migrationsplan für Talk und Echtzeit-Sprache

Realtime-Voice-, Telefonie-, Meeting- und Browser-Talk-Code wird von oberflächenlokaler Turn-Buchführung zu einem gemeinsamen Talk-Session-Controller verschoben, der von openclaw/plugin-sdk/realtime-voice exportiert wird. Der neue Controller verwaltet die gemeinsame Talk-Event-Hülle, den aktiven Turn-Status, Capture-Status, Output-Audio-Status, die aktuelle Ereignishistorie und die Zurückweisung veralteter Turns. Provider-Plugins sollten weiterhin anbieterspezifische Realtime- Sessions besitzen; Surface-Plugins sollten weiterhin Capture, Wiedergabe, Telefonie und Meeting-Eigenheiten besitzen.

Diese Talk-Migration ist absichtlich sauber brechend:

1. Behalten Sie die gemeinsamen Controller-/Runtime-Primitiven in plugin-sdk/realtime-voice.
2. Verschieben Sie gebündelte Surfaces 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 endgültige talk.session.*- und talk.client.*-API.
4. Bewerben 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 Request-time- Instruction-Overrides.

Neuer Code sollte createTalkEventSequencer(...) nicht direkt aufrufen, es sei denn, 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 Output-Audio-Lifecycle-Ereignisse ü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 });

Browser-eigene WebRTC-/Provider-Websocket-Sessions verwenden talk.client.create, weil der Browser die Provider-Aushandlung und den Medientransport besitzt, während das Gateway Zugangsdaten, Instruktionen und Tool-Policy besitzt. talk.session.* ist die gemeinsame Gateway-verwaltete Oberfläche für Gateway-Relay-Realtime, Gateway-Relay- Transkription und native Managed-Room-STT-/TTS-Sessions.

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

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

Entfernte Methodenzuordnung:

Das vereinheitlichte Steuervokabular ist ebenfalls bewusst schmal:

Führen Sie keine Provider- oder Plattform-Sonderfälle im Core ein, damit dies funktioniert. Der Core besitzt die Talk-Sitzungssemantik. 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äteerfassung/-wiedergabe.

Kompatibilitätsrichtlinie

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

1. neuen Vertrag hinzufügen
2. altes Verhalten über einen Kompatibilitätsadapter weiter verdrahtet lassen
3. Diagnose oder Warnung ausgeben, die den alten Pfad und den Ersatz nennt
4. beide Pfade in Tests abdecken
5. Deprecation und 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 Plugin oder einen Kompatibilitätseigentümer 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- Subpfaden 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-Subpfade müssen nachverfolgte Owner-Nutzung haben; ungenutzte reservierte Helper-Exporte sollten aus dem öffentlichen SDK entfernt werden.

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

Migration

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/

Importpfad-Referenz

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

Reservierte Hilfs-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 Package @openclaw/[email protected] beibehalten wurde. Owner-spezifische Hilfsfunktionen leben im owning Plugin-Package; 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 die Maintainer, welcher generische Vertrag dafür zuständig sein sollte.

Aktive Veraltungen

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

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

Zeitplan für die Entfernung

Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor dem nächsten Major-Release 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 - Ihr erstes Plugin erstellen
• SDK-Übersicht - vollständige Referenz für Unterpfad-Importe
• Channel-Plugins - Channel-Plugins erstellen
• Provider-Plugins - Provider-Plugins erstellen
• Plugin-Interna - tiefgehender Einblick in die Architektur
• Plugin-Manifest - Referenz zum Manifest-Schema