Plugin SDK माइग्रेशन

OpenClaw एक व्यापक पिछड़ी-संगतता लेयर से हटकर केंद्रित, दस्तावेजीकृत imports वाली आधुनिक Plugin architecture पर आ गया है। यदि आपका Plugin नई architecture से पहले बनाया गया था, तो यह guide आपको migrate करने में मदद करती है।

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

पुराना Plugin system दो बहुत खुले surfaces देता था, जिनसे Plugins एक ही entry point से अपनी जरूरत की कोई भी चीज import कर सकते थे:

• 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 कर सकता था।

व्यापक import surfaces अब deprecated हैं। वे runtime पर अब भी काम करते हैं, लेकिन नए Plugins को उनका उपयोग नहीं करना चाहिए, और existing Plugins को अगले major release में इन्हें हटाए जाने से पहले migrate कर लेना चाहिए। embedded-runner-only extension factory registration API हटा दी गई है; इसके बजाय tool-result middleware का उपयोग करें।

OpenClaw replacement पेश करने वाले उसी change में documented Plugin behavior को remove या reinterpret नहीं करता। Breaking contract changes को पहले compatibility adapter, diagnostics, docs, और deprecation window से गुजरना होगा। यह SDK imports, manifest fields, setup APIs, hooks, और runtime registration behavior पर लागू होता है।

यह क्यों बदला

पुराने approach ने समस्याएं पैदा कीं:

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

आधुनिक Plugin SDK इसे ठीक करता है: हर import path (openclaw/plugin-sdk/\<subpath\>) एक छोटा, self-contained module है, जिसका उद्देश्य साफ और contract documented है।

bundled channels के लिए legacy provider convenience seams भी हट गए हैं। Channel-branded helper seams private mono-repo shortcuts थे, stable Plugin contracts नहीं। इसके बजाय narrow generic SDK subpaths का उपयोग करें। bundled Plugin workspace के अंदर, provider-owned helpers को उसी Plugin के अपने api.ts या runtime-api.ts में रखें।

Current bundled provider examples:

• 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

Realtime voice, telephony, meeting, और browser Talk code surface-local turn bookkeeping से हटकर openclaw/plugin-sdk/realtime-voice द्वारा export किए गए shared Talk session controller पर जा रहा है। नया controller common Talk event envelope, active turn state, capture state, output-audio state, recent event history, और stale-turn rejection का owner है। Provider Plugins को vendor-specific realtime sessions का ownership रखना चाहिए; surface Plugins को capture, playback, telephony, और meeting quirks का ownership रखना चाहिए।

यह Talk migration जानबूझकर breaking-clean है:

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 करें।

नए code को createTalkEventSequencer(...) सीधे call नहीं करना चाहिए, जब तक कि वह कोई low-level adapter या test fixture implement न कर रहा हो। shared controller को prefer करें ताकि turn-scoped events बिना turn id के emit न हो सकें, stale turnEnd / turnCancel calls किसी नए active turn को clear न कर सकें, और output-audio lifecycle events telephony, meetings, browser relay, managed-room handoff, और native Talk clients में consistent रहें।

Target public API shape यह है:

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

Browser-owned WebRTC/provider-websocket sessions talk.client.create का उपयोग करते हैं, क्योंकि browser provider negotiation और media transport own करता है, जबकि Gateway credentials, instructions, और tool policy own करता है। talk.session.* gateway-relay realtime, gateway-relay transcription, और managed-room native STT/TTS sessions के लिए common Gateway-managed surface है।

Legacy configs जिन्होंने realtime selectors को talk.provider / talk.providers के पास रखा था, उन्हें openclaw doctor --fix से repair किया जाना चाहिए; runtime Talk speech/TTS provider config को realtime provider config के रूप में reinterpret नहीं करता।

Supported talk.session.create combinations जानबूझकर छोटे रखे गए हैं:

Removed method map:

Unified control vocabulary भी जानबूझकर narrow है:

इसे काम कराने के लिए core में प्रदाता या प्लेटफॉर्म विशेष मामले न जोड़ें। core Talk सेशन semantics का स्वामी है। प्रदाता plugins vendor सेशन सेटअप के स्वामी हैं। voice-call और Google Meet telephony/meeting adapters के स्वामी हैं। browser और native apps device capture/playback UX के स्वामी हैं।

संगतता नीति

external plugins के लिए, संगतता कार्य इस क्रम का पालन करता है:

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

Maintainers वर्तमान migration queue का audit pnpm plugins:boundary-report से कर सकते हैं। compact counts के लिए pnpm plugins:boundary-report:summary, एक Plugin या compatibility owner के लिए --owner <id>, और जब CI gate को due compatibility records, cross-owner reserved SDK imports, या unused reserved SDK subpaths पर fail होना चाहिए तब pnpm plugins:boundary-report:ci का उपयोग करें। report deprecated compatibility records को removal date के अनुसार group करती है, local code/docs references गिनती है, cross-owner reserved SDK imports surface करती है, और private memory-host SDK bridge को summarize करती है ताकि compatibility cleanup ad hoc searches पर निर्भर रहने के बजाय explicit रहे। Reserved SDK subpaths में tracked owner usage होना चाहिए; unused reserved helper exports को public SDK से हटा देना चाहिए।

यदि कोई manifest field अभी भी स्वीकार किया जाता है, तो plugin authors उसे तब तक use कर सकते हैं जब तक docs और diagnostics अन्यथा न कहें। नए code को documented replacement को prefer करना चाहिए, लेकिन मौजूदा plugins ordinary minor releases के दौरान break नहीं होने चाहिए।

migrate कैसे करें

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

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst 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 buildpnpm test -- my-plugin/

इम्पोर्ट path reference

यह तालिका जानबूझकर सामान्य माइग्रेशन उपसमुच्चय है, पूर्ण SDK सतह नहीं। कंपाइलर एंट्रीपॉइंट इन्वेंटरी scripts/lib/plugin-sdk-entrypoints.json में रहती है; package exports सार्वजनिक उपसमुच्चय से जनरेट किए जाते हैं।

आरक्षित bundled-plugin helper seams को सार्वजनिक SDK export map से हटा दिया गया है, सिवाय स्पष्ट रूप से प्रलेखित compatibility facades जैसे deprecated plugin-sdk/discord shim, जिसे प्रकाशित @openclaw/discord@2026.3.13 package के लिए बनाए रखा गया है। Owner-specific helpers स्वामित्व रखने वाले Plugin package के अंदर रहते हैं; साझा host behavior को generic SDK contracts जैसे plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, और plugin-sdk/plugin-config-runtime के माध्यम से जाना चाहिए।

काम से मेल खाने वाला सबसे संकीर्ण import उपयोग करें। अगर आपको कोई export नहीं मिलता, तो src/plugin-sdk/ पर source देखें या maintainers से पूछें कि कौन सा generic contract उसका स्वामी होना चाहिए।

सक्रिय deprecations

Plugin SDK, provider contract, runtime surface, और manifest पर लागू होने वाली संकरी deprecations। इनमें से हर एक आज भी काम करता है, लेकिन भविष्य की major release में हटाया जाएगा। हर item के नीचे दी गई entry पुराने API को उसके canonical replacement से map करती है।

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

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

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

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

सभी core Plugin पहले ही माइग्रेट किए जा चुके हैं। बाहरी Plugin को अगले प्रमुख रिलीज़ से पहले माइग्रेट कर लेना चाहिए।

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

माइग्रेशन पर काम करते समय ये environment variables सेट करें:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_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 संदर्भ