Plugin-SDK-migratie

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.

​

Wat verandert er

• openclaw/plugin-sdk/compat — een enkele import die tientallen helpers opnieuw exporteerde. Deze werd geïntroduceerd om oudere hook-gebaseerde plugins werkend te houden terwijl de nieuwe pluginarchitectuur werd gebouwd.
• openclaw/plugin-sdk/infra-runtime — een brede runtime-helperbarrel die systeemgebeurtenissen, Heartbeat-status, afleveringswachtrijen, fetch-/proxyhelpers, bestandshelpers, goedkeuringstypen en niet-gerelateerde hulpprogramma’s mengde.
• openclaw/plugin-sdk/config-runtime — een brede config-compatibiliteitsbarrel 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 agent-runner.
• api.registerEmbeddedExtensionFactory(...) — een verwijderde alleen-voor-Pi gebundelde extension-hook die embedded-runner-gebeurtenissen zoals tool_result kon observeren.

​

Waarom dit is veranderd

• Trage startup — het importeren van één helper laadde tientallen niet-gerelateerde modules
• Circulaire afhankelijkheden — brede re-exports maakten het gemakkelijk om importcycli te creëren
• Onduidelijk API-oppervlak — geen manier om te zien welke exports stabiel waren versus intern

• Anthropic bewaart Claude-specifieke streamhelpers in zijn eigen api.ts / contract-api.ts seam
• OpenAI bewaart provider-builders, default-model helpers en realtime provider builders in zijn eigen api.ts
• OpenRouter bewaart provider builder en onboarding-/confighelpers in zijn eigen api.ts

​

Compatibiliteitsbeleid

1. voeg het nieuwe contract toe
2. houd het oude gedrag aangesloten via een compatibiliteitsadapter
3. geef een diagnostische melding of waarschuwing die het oude pad en de vervanging noemt
4. dek beide paden af in tests
5. documenteer de deprecatie en het migratiepad
6. verwijder pas na het aangekondigde migratievenster, 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 subpath-importreferentie
• Kanaalplugins — kanaalplugins bouwen
• Providerplugins — providerplugins bouwen
• Plugin Internals — diepgaande architectuuruitleg
• Pluginmanifest — referentie voor het manifestschema