Plugin-SDK-Migration

​

Was sich ändert

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

​

Warum sich das geändert hat

• 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

• 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

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.

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

​

Kompatibilitätsrichtlinie

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

​

So migrieren Sie

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

// OpenClaw and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

​

Referenz für Importpfade

​

Aktive Veraltungen

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

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

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

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

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

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

{
  "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

​

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