Plugin-SDK-migratie

Documentation Index

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

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

​

Wat verandert er

• openclaw/plugin-sdk/compat - één import die tientallen helpers opnieuw exporteerde. Deze werd geïntroduceerd om oudere, op hooks gebaseerde plugins werkend te houden terwijl de nieuwe pluginarchitectuur werd gebouwd.
• openclaw/plugin-sdk/infra-runtime - een brede barrel voor runtimehelpers die systeemgebeurtenissen, Heartbeat-status, afleverwachtrijen, fetch-/proxyhelpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma’s mengde.
• openclaw/plugin-sdk/config-runtime - een brede barrel voor configuratiecompatibiliteit die tijdens de migratieperiode nog verouderde directe laad-/schrijfhelpers bevat.
• openclaw/extension-api - een bridge die plugins directe toegang gaf tot host-side helpers zoals de ingebedde agentrunner.
• api.registerEmbeddedExtensionFactory(...) - een verwijderde, alleen voor Pi bedoelde gebundelde extensiehook die embedded-runner-gebeurtenissen zoals tool_result kon observeren.

​

Waarom dit is gewijzigd

• Trage opstart - het importeren van één helper laadde tientallen niet-gerelateerde modules
• Circulaire afhankelijkheden - brede herexports maakten het makkelijk om importcycli te creëren
• Onduidelijk API-oppervlak - er was geen manier om te zien welke exports stabiel waren en welke intern

• Anthropic houdt Claude-specifieke streamhelpers in de eigen api.ts / contract-api.ts seam
• OpenAI houdt providerbuilders, default-model-helpers en realtime providerbuilders in de eigen api.ts
• OpenRouter houdt providerbuilder en onboarding-/configuratiehelpers in de eigen api.ts

​

Migratieplan voor Talk en realtime spraak

1. Houd de gedeelde controller-/runtimeprimitieven in plugin-sdk/realtime-voice.
2. Verplaats gebundelde surfaces naar de gedeelde controller: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime en native push-to-talk.
3. Vervang oude Talk RPC-families door de definitieve talk.session.*- en talk.client.*-API.
4. Adverteer één live Talk-gebeurteniskanaal in Gateway hello-ok.features.events: talk.event.
5. Verwijder het oude realtime HTTP-endpoint en elk pad voor 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 });

​

Compatibiliteitsbeleid

1. voeg het nieuwe contract toe
2. houd het oude gedrag verbonden via een compatibiliteitsadapter
3. geef een diagnose of waarschuwing uit die het oude pad en de vervanging noemt
4. dek beide paden af in tests
5. documenteer de afschaffing en het migratiepad
6. verwijder pas na de aangekondigde migratieperiode, meestal in een major release

​

Migreren

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/

​

Referentie voor importpaden

​

Actieve deprecations

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

​

Verwijderingstijdlijn

​

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 subpad-imports
• Kanaal-Plugins - kanaal-Plugins bouwen
• Provider-Plugins - provider-Plugins bouwen
• Plugin-internals - diepgaande architectuuruitleg
• Plugin-manifest - referentie voor manifestschema