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 sehr offene Oberflächen bereit, über die Plugins alles, was sie benötigten, aus einem einzigen Einstiegspunkt importieren konnten:

• openclaw/plugin-sdk/compat - ein einzelner Import, der Dutzende von Hilfsfunktionen erneut exportierte. Er wurde eingeführt, um ältere hook-basierte Plugins funktionsfähig zu halten, während die neue Plugin-Architektur entwickelt wurde.
• openclaw/plugin-sdk/infra-runtime - ein breites Barrel für Runtime-Hilfsfunktionen, das Systemereignisse, Heartbeat-Status, Zustellungswarteschlangen, Fetch-/Proxy-Hilfsfunktionen, Datei-Hilfsfunktionen, Genehmigungstypen und nicht zusammenhängende Dienstprogramme vermischte.
• openclaw/plugin-sdk/config-runtime - ein breites Config-Kompatibilitäts-Barrel, das während des Migrationsfensters weiterhin veraltete direkte Load-/Write-Hilfsfunktionen enthält.
• openclaw/extension-api - eine Brücke, die Plugins direkten Zugriff auf hostseitige Hilfsfunktionen wie den eingebetteten Agent Runner gab.
• api.registerEmbeddedExtensionFactory(...) - ein entfernter, nur für Pi vorgesehener Hook für gebündelte Erweiterungen, 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 migrieren, bevor sie im nächsten Major Release entfernt werden. Die nur für Pi vorgesehene API zur Registrierung eingebetteter Erweiterungs-Factorys wurde entfernt; verwenden Sie stattdessen Tool-Ergebnis-Middleware.

OpenClaw entfernt oder interpretiert dokumentiertes Plugin-Verhalten nicht in derselben Änderung neu, die einen Ersatz einführt. Breaking Changes an Verträgen 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 Runtime-Registrierungsverhalten.

# Warum sich das geändert hat

Der alte Ansatz verursachte Probleme:

• Langsamer Start - das Importieren einer Hilfsfunktion lud Dutzende nicht zusammenhängender Module
• Zirkuläre Abhängigkeiten - breite Re-Exports machten es leicht, Importzyklen zu erzeugen
• Unklare API-Oberfläche - es gab keine Möglichkeit zu erkennen, welche Exports stabil und welche intern waren

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

Veraltete Provider-Komfortseams für gebündelte Channels sind ebenfalls entfernt. Channel-gebrandete Hilfsseams waren private Monorepo-Abkürzungen, keine stabilen Plugin-Verträge. Verwenden Sie stattdessen schmale generische SDK-Unterpfade. Innerhalb des gebündelten Plugin-Workspace sollten Provider-eigene Hilfsfunktionen in der jeweiligen api.ts oder runtime-api.ts dieses Plugins bleiben.

Aktuelle Beispiele gebündelter Provider:

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

# Migrationsplan für Talk und Realtime-Voice

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 besitzt den gemeinsamen Talk-Ereignisumschlag, den aktiven Turn-Status, den Capture-Status, den Ausgabee-Audio-Status, den aktuellen Ereignisverlauf und die Ablehnung veralteter Turns. Provider-Plugins sollten weiterhin anbieterspezifische Realtime-Sitzungen besitzen; Surface-Plugins sollten weiterhin Capture, Wiedergabe, Telefonie und Meeting-Eigenheiten besitzen.

Diese Talk-Migration ist absichtlich klar brechend:

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 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 anfragezeitliche 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 Ausgabee-Audio-Lifecycle-Ereignisse über Telefonie, Meetings, Browser-Relay, Managed-Room-Handoff und native Talk-Clients hinweg konsistent bleiben.

Die angestrebte Form der öffentlichen API 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 });
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-Sitzungen verwenden talk.client.create, weil der Browser die Provider-Aushandlung und den Medientransport besitzt, während das Gateway Credentials, Instructions und Tool-Policy besitzt. talk.session.* ist die gemeinsame Gateway-verwaltete Oberfläche für Gateway-Relay-Realtime, Gateway-Relay-Transcription und Managed-Room-native STT-/TTS-Sitzungen.

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 neu.

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

Entfernte Methodenzuordnung:

Das vereinheitlichte Steuerungsvokabular ist ebenfalls bewusst schmal:

Führen Sie keine Provider- oder Plattform-Sonderfälle in Core ein, damit dies funktioniert. Core besitzt Talk-Sitzungssemantik. Provider-Plugins besitzen das Setup von Vendor-Sitzungen. Voice-Call und Google Meet besitzen Telefonie-/Meeting-Adapter. Browser- und native Apps besitzen UX für Geräte-Capture/-Wiedergabe.

# Kompatibilitätsrichtlinie

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

1. neuen Vertrag hinzufügen
2. altes Verhalten über einen Kompatibilitätsadapter 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, normalerweise 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äts-Owner und pnpm plugins:boundary-report:ci, wenn ein CI-Gate bei fälligen Kompatibilitätsdatensätzen, ownerübergreifenden reservierten SDK-Importen oder ungenutzten reservierten SDK- Unterpfaden fehlschlagen soll. Der Bericht gruppiert veraltete Kompatibilitätsdatensätze nach Entfernungsdatum, zählt lokale Code-/Doku-Referenzen, zeigt ownerübergreifende reservierte SDK-Importe und fasst die private Memory-Host-SDK-Bridge zusammen, damit Kompatibilitätsbereinigung explizit bleibt, anstatt sich auf Ad-hoc-Suchen zu stützen. Reservierte SDK-Unterpfade müssen nachverfolgte Owner-Nutzung haben; ungenutzte reservierte Helper-Exporte sollten aus dem öffentlichen SDK entfernt werden.

Wenn ein Manifestfeld weiterhin akzeptiert wird, können Plugin-Autoren es weiter verwenden, bis Dokumentation und Diagnose etwas anderes angeben. Neuer Code sollte die dokumentierte Alternative bevorzugen, aber bestehende Plugins sollten bei gewöhnlichen Minor- Releases nicht brechen.

# Migration

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/

# Referenz der Importpfade

Diese Tabelle ist bewusst die gemeinsame Teilmenge für die Migration, nicht die vollständige SDK-Oberfläche. Die vollständige Liste mit über 200 Einstiegspunkten befindet sich in scripts/lib/plugin-sdk-entrypoints.json.

Reservierte Hilfs-Seams für gebündelte Plugins wurden aus der Export-Map des öffentlichen SDK entfernt, mit Ausnahme ausdrücklich dokumentierter Kompatibilitäts-Fassaden wie dem veralteten plugin-sdk/discord-Shim, der für das veröffentlichte Paket @openclaw/[email protected] beibehalten wird. Owner-spezifische Hilfsfunktionen befinden sich im jeweils verantwortlichen Plugin-Paket; gemeinsam genutztes 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 über das Plugin-SDK, den Provider-Vertrag, die Laufzeitoberfläche und das Manifest hinweg gelten. Jede davon funktioniert heute noch, wird aber in einer zukünftigen Hauptversion entfernt. Der Eintrag unter jedem Punkt ordnet die alte API ihrem kanonischen Ersatz zu.

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

# Zeitplan für die Entfernung

Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten Hauptversion 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 run
OPENCLAW_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-Überblick – vollständige Referenz für Unterpfad-Importe
• Kanal-Plugins – Kanal-Plugins erstellen
• Provider-Plugins – Provider-Plugins erstellen
• Plugin-Interna – detaillierter Architekturüberblick
• Plugin-Manifest – Referenz zum Manifest-Schema