Plugin SDK माइग्रेशन

OpenClaw व्यापक पश्च-संगतता परत से केंद्रित, दस्तावेजीकृत imports वाली आधुनिक Plugin आर्किटेक्चर पर आ गया है। यदि आपका Plugin नई आर्किटेक्चर से पहले बनाया गया था, तो यह मार्गदर्शिका आपको माइग्रेट करने में मदद करती है।

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

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

• openclaw/plugin-sdk/compat - एक single import जो दर्जनों helpers को फिर से export करता था। इसे पुराने hook-आधारित plugins को चलते रखने के लिए पेश किया गया था, जबकि नई Plugin आर्किटेक्चर बनाई जा रही थी।
• 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 तक सीधी पहुंच दी।
• api.registerEmbeddedExtensionFactory(...) - हटाया गया embedded-runner-only bundled extension hook, जो tool_result जैसे embedded-runner events देख सकता था।

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

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

यह क्यों बदला

पुराने approach से समस्याएं हुईं:

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

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

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

वर्तमान bundled provider उदाहरण:

• 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 का मालिक है। Provider plugins को vendor-specific realtime sessions का मालिक बने रहना चाहिए; surface plugins को capture, playback, telephony, और meeting quirks का मालिक बने रहना चाहिए।

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

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

नए code को createTalkEventSequencer(...) सीधे call नहीं करना चाहिए, जब तक कि वह low-level adapter या test fixture implement नहीं कर रहा हो। shared controller को प्राथमिकता दें ताकि 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 रहें।

लक्षित 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 का मालिक है, जबकि Gateway credentials, instructions, और tool policy का मालिक है। 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 के रूप में फिर से व्याख्यायित नहीं करता।

समर्थित talk.session.create combinations जानबूझकर छोटे हैं:

हटाया गया method map:

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

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

संगतता नीति

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

1. नया अनुबंध जोड़ें
2. पुराने व्यवहार को compatibility adapter के माध्यम से wired रखें
3. पुराना path और replacement बताने वाला diagnostic या warning उत्सर्जित करें
4. tests में दोनों paths cover करें
5. deprecation और migration path का documentation करें
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 का summary देती है ताकि compatibility cleanup ad hoc searches पर निर्भर रहने के बजाय explicit रहे। Reserved SDK subpaths में tracked owner usage होना चाहिए; unused reserved helper exports को public SDK से हटा देना चाहिए।

यदि कोई manifest field अभी भी accepted है, तो Plugin authors इसे तब तक उपयोग कर सकते हैं जब तक docs और diagnostics अन्यथा न कहें। New code को documented replacement को प्राथमिकता देनी चाहिए, लेकिन existing plugins ordinary minor releases के दौरान टूटने नहीं चाहिए।

Migration कैसे करें

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/

इम्पोर्ट पथ संदर्भ

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

आरक्षित bundled-plugin helper seams को सार्वजनिक SDK export map से हटा दिया गया है, सिवाय स्पष्ट रूप से दस्तावेजीकृत compatibility facades के, जैसे प्रकाशित @openclaw/discord@2026.3.13 पैकेज के लिए रखी गई deprecated plugin-sdk/discord shim। Owner-specific helpers संबंधित plugin पैकेज के अंदर रहते हैं; shared 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 को इसका owner होना चाहिए।

सक्रिय 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";

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

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

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

माइग्रेशन पर काम करते समय ये एनवायरनमेंट वेरिएबल सेट करें:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

यह एक अस्थायी बचाव मार्ग है, स्थायी समाधान नहीं।

संबंधित

• आरंभ करना - अपना पहला Plugin बनाएं
• SDK अवलोकन - पूर्ण सबपाथ इंपोर्ट संदर्भ
• चैनल Plugin - चैनल Plugin बनाना
• प्रदाता Plugin - प्रदाता Plugin बनाना
• Plugin आंतरिक विवरण - आर्किटेक्चर की गहन जानकारी
• Plugin मैनिफेस्ट - मैनिफेस्ट स्कीमा संदर्भ