Migratie van de Plugin SDK

​

Wat is er gewijzigd

• openclaw/plugin-sdk en openclaw/plugin-sdk/compat - exporteerden tientallen helpers opnieuw terwijl de gerichte SDK werd gebouwd. Beide hoofdpaden zijn nu verwijderd; importeer in plaats daarvan een gedocumenteerd subpad.
• openclaw/plugin-sdk/infra-runtime - een brede barrel die systeem- gebeurtenissen, Heartbeat-status, afleveringswachtrijen, fetch-/proxyhelpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma’s combineerde.
• openclaw/plugin-sdk/config-runtime - een brede configuratiebarrel die alleen behouden bleef voor het latere compatibiliteitsvenster; directe runtimehelpers voor laden/schrijven zijn verwijderd.
• openclaw/extension-api - een verwijderde brug die Plugins directe toegang gaf tot helpers aan de hostzijde, zoals de ingebedde agentrunner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde hook die uitsluitend voor de ingebedde runner was bedoeld en gebeurtenissen daarvan observeerde, zoals tool_result. Gebruik in plaats daarvan middleware voor agenttoolresultaten (zie Ingebedde extensies voor toolresultaten migreren naar middleware).

​

Waarom

• Langzaam opstarten - door één helper te importeren, werden tientallen niet-gerelateerde modules geladen.
• Circulaire afhankelijkheden - brede herexports maakten het eenvoudig om importcycli te creëren.
• Onduidelijk API-oppervlak - er was geen manier om stabiele exports van interne exports te onderscheiden.

• Anthropic bewaart Claude-specifieke streamhelpers in zijn eigen api.ts / contract-api.ts-interface.
• OpenAI bewaart providerbouwers, helpers voor standaardmodellen en realtime providerbouwers in zijn eigen api.ts.
• OpenRouter bewaart de providerbouwer en helpers voor onboarding/configuratie in zijn eigen api.ts.

​

Compatibiliteitsbeleid

1. Voeg het nieuwe contract toe.
2. Behoud het oude gedrag via een compatibiliteitsadapter.
3. Geef een diagnostisch bericht of waarschuwing weer waarin het oude pad en de vervanging worden genoemd.
4. Dek beide paden af met tests.
5. Documenteer de uitfasering en het migratiepad.
6. Verwijder pas na het aangekondigde migratievenster, meestal in een hoofd- release.

​

Compatibiliteit voor installatie van gepubliceerde kanalen

​

Compatibiliteit van invoervelden voor kanaalinstallatie

​

Lezers verifiëren

1. Doorloop https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 pagina voor pagina met elke nextCursor en behoud pakketten waarvan de categories channels bevatten.
2. Voeg npm-kandidaten uit npm search --json --searchlimit=1000 "openclaw channel plugin" toe. Voeg kandidaten toe die alleen als bron beschikbaar zijn via GitHub-codezoekopdrachten naar openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup en openclaw/plugin-sdk/core.
3. Bepaal voor elke kandidaat de laatst gepubliceerde versie. Voer npm pack <package>@<version> --json --pack-destination <temp-dir> uit, pak het pakket uit en inspecteer de meegeleverde dist-JavaScript en declaraties op directe of gedestructureerde leesbewerkingen van velden. Download het ClawHub-artefact wanneer een pakket geen npm-release heeft.
4. Leg pakket, versie, veld of promotiesleutel en overeenkomend bestand vast. Een veld of sleutel kan alleen worden verwijderd wanneer geen gepubliceerd Pluginartefact het leest. Houd de namen van lezers in de codeopmerkingen naast de lijsten met behouden velden en sleutels gesynchroniseerd met de sweep.

​

Verouderde mediaprojectie

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

​

Migreren

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

// OpenClaw-runtimetools en dynamische tools van de Codex-runtime (resultaat kan worden
// getransformeerd). Codex-native toolresultaten worden ook doorgestuurd voor observatie,
// maar hun getransformeerde uitvoer bereikt het model nooit: het contract van de Codex-
// PostToolUse-hook kan een native toolantwoord niet vervangen.
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

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

// Nu
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Stel dit alleen in voor vertrouwde compatibiliteitsaanroepers die bewust
  // een door de shell bemiddelde fallback accepteren.
  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/

// Voorheen (verouderde laag voor achterwaartse compatibiliteit)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Nu (moderne gerichte 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";

// Voorheen (verouderde extension-api-brug)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// Nu (geïnjecteerde runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

Naslag voor importpaden

​

Verwijderde compatibiliteitsinterfaces

​

Procesglobale publicatie van API-providers

​

Privétestbarrel

​

Migratienaslag

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

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

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

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

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

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

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

// Voor
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Na
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

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

​

Migratie van Talk en realtime-spraak

// Door Gateway beheerde Talk-sessie-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 });

// Providersessie-API die door de client wordt beheerd.
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" });

​

Tijdlijn voor verwijdering

​

De waarschuwingen tijdelijk onderdrukken

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

​

Gerelateerd

• Aan de slag - bouw je eerste plugin
• SDK-overzicht - volledige referentie voor imports van subpaden
• Kanaalplugins - kanaalplugins bouwen
• Providerplugins - providerplugins bouwen
• Interne werking van plugins - diepgaande architectuurbeschrijving
• Pluginmanifest - referentie voor het manifestschema