Plugin-SDK-Migration

​

Was sich geändert hat

• openclaw/plugin-sdk und openclaw/plugin-sdk/compat – exportierten Dutzende Hilfsfunktionen erneut, während das fokussierte SDK entwickelt wurde. Beide Wurzeln wurden inzwischen entfernt; importieren Sie stattdessen einen dokumentierten Unterpfad.
• openclaw/plugin-sdk/infra-runtime – ein umfassendes Barrel, das System- ereignisse, Heartbeat-Zustand, Zustellwarteschlangen, Fetch-/Proxy-Hilfsfunktionen, Dateihilfen, Genehmigungstypen und nicht zusammengehörige Dienstprogramme vermischte.
• openclaw/plugin-sdk/config-runtime – ein umfassendes Konfigurations-Barrel, das nur für sein späteres Kompatibilitätsfenster beibehalten wurde; direkte Hilfsfunktionen zum Laden und Schreiben zur Laufzeit wurden entfernt.
• openclaw/extension-api – eine entfernte 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 bestimmter Hook, der Ereignisse des eingebetteten Runners wie tool_result beobachtete. Verwenden Sie stattdessen Middleware für Agent- Werkzeugergebnisse (siehe Erweiterungen für eingebettete Werkzeugergebnisse zu Middleware migrieren).

​

Warum

• Langsamer Start – der Import 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.

• 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 seinem eigenen api.ts.
• OpenRouter behält den Provider-Builder und Hilfsfunktionen für Onboarding und Konfiguration in seinem eigenen api.ts.

​

Kompatibilitätsrichtlinie

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

​

Kompatibilität der Einrichtung veröffentlichter Kanäle

​

Kompatibilität der Eingabefelder für die Kanaleinrichtung

​

Leser überprüfen

1. Blättern Sie mit jedem nextCursor durch https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 und behalten Sie Pakete bei, deren categories channels enthalten.
2. Fügen Sie npm-Kandidaten aus npm search --json --searchlimit=1000 "openclaw channel plugin" hinzu. Fügen Sie reine Quellcode-Kandidaten aus GitHub-Codesuchen nach openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup und openclaw/plugin-sdk/core hinzu.
3. Ermitteln Sie für jeden Kandidaten die neueste veröffentlichte Version. Führen Sie npm pack <package>@<version> --json --pack-destination <temp-dir> aus, entpacken Sie sie und untersuchen Sie den ausgelieferten dist-JavaScript-Code und die Deklarationen auf direkte oder destrukturierte Feldzugriffe. Laden Sie das ClawHub-Artefakt herunter, wenn ein Paket keine npm-Veröffentlichung besitzt.
4. Erfassen Sie Paket, Version, Feld oder Hochstufungsschlüssel und die übereinstimmende Datei. Ein Feld oder Schlüssel darf nur gelöscht werden, wenn kein veröffentlichtes Plugin-Artefakt darauf zugreift. Halten Sie die Lesernamen in den Codekommentaren neben den Listen der beibehaltenen Felder und Schlüssel mit der Prüfung synchron.

​

Veraltete Medienprojektion

import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";

const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = finalizeInboundContext({ Body: caption, media });

​

Migration

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

// OpenClaw-Laufzeitwerkzeuge und dynamische Werkzeuge der Codex-Laufzeit (das Ergebnis kann
// transformiert werden). Ergebnisse nativer Codex-Werkzeuge werden zur Beobachtung ebenfalls weitergeleitet,
// ihre transformierte Ausgabe erreicht das Modell jedoch nie: Der Vertrag des Codex-
// PostToolUse-Hooks kann die Antwort eines nativen Werkzeugs nicht ersetzen.
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

// Vorher
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Nachher
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Legen Sie dies nur für vertrauenswürdige Kompatibilitätsaufrufer fest, die einen
  // über die Shell vermittelten Fallback bewusst 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 Laufzeit)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

Referenz für Importpfade

​

Entfernte Kompatibilitätsoberflächen

​

Prozessglobale Veröffentlichung von API-Providern

​

Privates Testing-Barrel

​

Migrationsreferenz

// Vorher
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// Nachher
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Vorher
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Nachher
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Vorher
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// Nachher
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

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

// Vorher
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Nachher
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Vorher
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Nachher
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

​

Migration von Talk und Echtzeit-Sprachkommunikation

// Vom Gateway verwaltete 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 });

// Vom Client verwaltete 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" });

​

Zeitplan für die Entfernung

​

Warnungen vorübergehend unterdrücken

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

Verwandte Themen

• Erste Schritte - Erstellen Sie Ihr erstes Plugin
• SDK-Übersicht - vollständige Importreferenz für Unterpfade
• Kanal-Plugins - Kanal-Plugins erstellen
• Provider-Plugins - Provider-Plugins erstellen
• Plugin-Interna - ausführlicher Einblick in die Architektur
• Plugin-Manifest - Referenz zum Manifest-Schema