Plugin SDK माइग्रेशन

​

क्या बदल रहा है

• openclaw/plugin-sdk/compat - एक single import जो दर्जनों helpers को re-export करता था। इसे पुराने hook-based Plugins को काम करते रहने के लिए पेश किया गया था, जबकि नई Plugin architecture बनाई जा रही थी।
• openclaw/plugin-sdk/infra-runtime - एक व्यापक runtime helper barrel, जिसमें system events, heartbeat state, delivery queues, fetch/proxy helpers, file helpers, approval types, और असंबंधित utilities मिले हुए थे।
• openclaw/plugin-sdk/config-runtime - एक व्यापक config compatibility barrel, जो migration window के दौरान अब भी deprecated direct load/write helpers रखता है।
• openclaw/extension-api - एक bridge जिसने Plugins को embedded agent runner जैसे host-side helpers तक direct access दिया।
• api.registerEmbeddedExtensionFactory(...) - एक हटाया गया embedded-runner-only bundled extension hook, जो tool_result जैसे embedded-runner events को observe कर सकता था।

​

यह क्यों बदला

• Slow startup - एक helper import करने से दर्जनों असंबंधित modules load हो जाते थे
• Circular dependencies - व्यापक re-exports से import cycles बनाना आसान हो गया था
• Unclear API surface - यह बताने का कोई तरीका नहीं था कि कौन से exports stable हैं और कौन से internal

• Anthropic अपने Claude-specific stream helpers को अपने api.ts / contract-api.ts seam में रखता है
• OpenAI provider builders, default-model helpers, और realtime provider builders को अपने api.ts में रखता है
• OpenRouter provider builder और onboarding/config helpers को अपने api.ts में रखता है

​

Talk और realtime voice migration plan

1. shared controller/runtime primitives को plugin-sdk/realtime-voice में रखें।
2. bundled surfaces को shared controller पर move करें: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime, और native push-to-talk।
3. पुराने Talk RPC families को final talk.session.* और talk.client.* API से replace करें।
4. Gateway hello-ok.features.events में एक live Talk event channel advertise करें: talk.event।
5. पुराने realtime HTTP endpoint और किसी भी request-time instruction override path को delete करें।

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

​

संगतता नीति

1. नया अनुबंध जोड़ें
2. पुराने व्यवहार को compatibility adapter के माध्यम से wired रखें
3. ऐसा diagnostic या warning उत्सर्जित करें जो पुराने पथ और प्रतिस्थापन का नाम बताए
4. दोनों पथों को tests में cover करें
5. deprecation और migration path को document करें
6. announced migration window के बाद ही हटाएं, आम तौर पर major release में

​

migrate कैसे करें

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/

​

इम्पोर्ट path reference

​

सक्रिय deprecations

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

​

हटाने की समयरेखा

​

चेतावनियों को अस्थायी रूप से दबाना

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

​

संबंधित

• शुरू करें - अपना पहला Plugin बनाएँ
• SDK अवलोकन - पूरा subpath import संदर्भ
• Channel Plugins - channel Plugin बनाना
• Provider Plugins - provider Plugin बनाना
• Plugin Internals - आर्किटेक्चर की गहरी जानकारी
• Plugin Manifest - manifest schema संदर्भ