Plugin-SDK-Migration

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Was sich ändert

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

​

Warum sich das geändert hat

• 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

• 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

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.

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

​

Kompatibilitätsrichtlinie

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

​

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/

​

Importpfad-Referenz

​

Aktive Veraltungen

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

​

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