Plugin प्रवेश बिंदु

हर plugin एक डिफ़ॉल्ट एंट्री ऑब्जेक्ट निर्यात करता है। SDK प्रत्येक एंट्री आकार के लिए एक सहायक प्रदान करता है: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry।

पैकेज एंट्रियाँ

इंस्टॉल किए गए plugins स्रोत और बिल्ट एंट्रियों, दोनों पर package.json openclaw फ़ील्ड इंगित करते हैं:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

• extensions और setupEntry स्रोत एंट्रियाँ हैं, जिनका उपयोग वर्कस्पेस और git चेकआउट डेवलपमेंट के लिए किया जाता है।
• इंस्टॉल किए गए पैकेजों के लिए runtimeExtensions और runtimeSetupEntry को प्राथमिकता दी जाती है: इनसे npm पैकेज रनटाइम TypeScript कंपाइलेशन छोड़ सकते हैं।
• मौजूद होने पर runtimeExtensions की ऐरे लंबाई extensions से मेल खानी चाहिए (एंट्रियाँ स्थान के अनुसार जोड़ी जाती हैं)। runtimeSetupEntry के लिए setupEntry आवश्यक है।
• यदि कोई runtimeExtensions/runtimeSetupEntry आर्टिफ़ैक्ट घोषित है, लेकिन मौजूद नहीं है, तो इंस्टॉल/डिस्कवरी पैकेजिंग त्रुटि के साथ विफल हो जाती है; OpenClaw चुपचाप स्रोत पर फ़ॉलबैक नहीं करता। स्रोत फ़ॉलबैक (नीचे) केवल तभी लागू होता है, जब कोई रनटाइम एंट्री बिल्कुल घोषित न हो।
• यदि कोई इंस्टॉल किया गया पैकेज केवल TypeScript स्रोत एंट्री घोषित करता है, तो OpenClaw मेल खाने वाले बिल्ट dist/*.js (या .mjs/.cjs) पीयर को खोजकर उसका उपयोग करता है; अन्यथा वह TypeScript स्रोत पर फ़ॉलबैक करता है।
• सभी एंट्री पथ plugin पैकेज डायरेक्टरी के अंदर ही रहने चाहिए। रनटाइम एंट्रियाँ और अनुमानित बिल्ट-JS पीयर बाहर निकलने वाले extensions या setupEntry स्रोत पथ को मान्य नहीं बनाते।

defineToolPlugin

इंपोर्ट: openclaw/plugin-sdk/tool-plugin

उन plugins के लिए जो केवल एजेंट टूल जोड़ते हैं। यह स्रोत को छोटा रखता है, TypeBox स्कीमा से कॉन्फ़िगरेशन और टूल-पैरामीटर प्रकारों का अनुमान लगाता है, सामान्य रिटर्न मानों को OpenClaw टूल-रिज़ल्ट प्रारूप में रैप करता है, और वह स्थिर मेटाडेटा उजागर करता है जिसे openclaw plugins build plugin मेनिफ़ेस्ट (contracts.tools, configSchema) में लिखता है।

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      outputSchema: Type.Object(        {          symbol: Type.String(),          hasKey: Type.Boolean(),        },        { additionalProperties: false },      ),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema वैकल्पिक है; इसे छोड़ने पर सख़्त खाली ऑब्जेक्ट स्कीमा का उपयोग होता है (जेनरेट किए गए मेनिफ़ेस्ट में फिर भी configSchema शामिल होता है)।
• execute सामान्य स्ट्रिंग या JSON-सीरियलाइज़ करने योग्य मान लौटाता है; सहायक इसे टेक्स्ट टूल रिज़ल्ट के रूप में रैप करता है, जिसमें details मूल (स्ट्रिंग में अपरिवर्तित) रिटर्न मान पर सेट होता है।
• outputSchema वैकल्पिक रूप से Code Mode और Tool Search के लिए उस मूल details मान का वर्णन करता है। कैटलॉग कॉल निष्पादन से पहले अमान्य स्कीमा अस्वीकार करते हैं और अंतिम मान लौटाने से पहले उसे सत्यापित करते हैं।
• कस्टम टूल रिज़ल्ट के लिए, openclaw/plugin-sdk/tool-results textResult और jsonResult निर्यात करता है।
• टूल नाम स्थिर होते हैं, इसलिए openclaw plugins build घोषित टूलों से contracts.tools व्युत्पन्न करता है और नामों को हाथ से दोहराने की आवश्यकता नहीं होती।
• रनटाइम लोडिंग सख़्त रहती है: इंस्टॉल किए गए plugins को फिर भी openclaw.plugin.json और package.json openclaw.extensions की आवश्यकता होती है। OpenClaw अनुपस्थित मेनिफ़ेस्ट डेटा का अनुमान लगाने के लिए कभी भी plugin कोड निष्पादित नहीं करता।

definePluginEntry

इंपोर्ट: openclaw/plugin-sdk/plugin-entry

प्रोवाइडर plugins, उन्नत टूल plugins, हुक plugins और ऐसी हर चीज़ के लिए जो मैसेजिंग चैनल नहीं है।

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({/* ... */});    api.registerTool({/* ... */});  },});

• id आपके openclaw.plugin.json मेनिफ़ेस्ट से मेल खाना चाहिए।
• बाहरी सेशन कैटलॉग openclaw/plugin-sdk/session-catalog और api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }) का उपयोग करते हैं। कोर sessions.catalog.* Gateway विधियों का स्वामी है; प्रोवाइडर RPC पंजीकृत किए बिना होस्ट, सेशन और सामान्यीकृत ट्रांसक्रिप्ट प्रोजेक्शन लौटाते हैं। सूची प्रोवाइडर को प्रत्येक होस्ट के पूर्ण होते ही वैकल्पिक onHost(host) कॉलबैक कॉल करना चाहिए; लौटी हुई होस्ट ऐरे अंतिम संगतता स्नैपशॉट के रूप में आवश्यक रहती है।
• kind अप्रचलित है: इसके बजाय openclaw.plugin.json मेनिफ़ेस्ट के kind फ़ील्ड में एक एक्सक्लूसिव स्लॉट ("memory" या "context-engine") घोषित करें। रनटाइम-एंट्री kind केवल पुराने plugins के लिए संगतता फ़ॉलबैक के रूप में बनी हुई है।
• लेज़ी मूल्यांकन के लिए configSchema एक फ़ंक्शन हो सकता है। OpenClaw पहली बार एक्सेस करने पर स्कीमा को रिज़ॉल्व करके मेमोइज़ करता है, इसलिए महँगे स्कीमा बिल्डर केवल एक बार चलते हैं।
• एक nodeHostCommands डिस्क्रिप्टर isAvailable({ config, env }) परिभाषित कर सकता है। false लौटाने से वह कमांड और उसकी क्षमता हेडलेस Node की Gateway घोषणा से छूट जाती है। OpenClaw इसका मूल्यांकन Node-लोकल स्टार्टअप कॉन्फ़िगरेशन के संदर्भ में करता है; कमांड हैंडलर को इनवोक किए जाने पर फिर भी उपलब्धता सत्यापित करनी चाहिए।

defineChannelPluginEntry

इंपोर्ट: openclaw/plugin-sdk/channel-core

definePluginEntry को चैनल-विशिष्ट वायरिंग के साथ रैप करता है: यह स्वचालित रूप से api.registerChannel({ plugin }) कॉल करता है, वैकल्पिक रूट-सहायता CLI मेटाडेटा सीम उजागर करता है, और पंजीकरण मोड के आधार पर registerFull को गेट करता है।

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

कॉलबैक प्रत्येक पंजीकरण मोड के अनुसार चलते हैं (पूरी तालिका पंजीकरण मोड के अंतर्गत है):

• setRuntime, "cli-metadata" और "tool-discovery" को छोड़कर हर मोड में चलता है। रनटाइम संदर्भ यहाँ संग्रहीत करें, आम तौर पर createPluginRuntimeStore के माध्यम से।
• registerCliMetadata, "cli-metadata", "discovery" और "full" के लिए चलता है। इसे चैनल-स्वामित्व वाले CLI डिस्क्रिप्टरों के प्रामाणिक स्थान के रूप में उपयोग करें, ताकि रूट सहायता सक्रिय न हो, डिस्कवरी स्नैपशॉट में स्थिर कमांड मेटाडेटा शामिल हो और सामान्य CLI पंजीकरण पूर्ण plugin लोड के साथ संगत बना रहे।
• registerFull केवल "full" और "tool-discovery" के लिए चलता है। "tool-discovery" के लिए यह चैनल पंजीकरण के बजाय चलता है: OpenClaw registerChannel/setRuntime को पूरी तरह छोड़ देता है और केवल registerFull कॉल करता है, इसलिए स्वतंत्र टूल डिस्कवरी या निष्पादन के लिए आपके चैनल को आवश्यक कोई भी प्रोवाइडर/टूल पंजीकरण वहाँ होना चाहिए, सामान्य चैनल सेटअप के पीछे नहीं।
• डिस्कवरी पंजीकरण निष्क्रिय होता है, इंपोर्ट-मुक्त नहीं: स्नैपशॉट बनाने के लिए OpenClaw विश्वसनीय plugin एंट्री और चैनल plugin मॉड्यूल का मूल्यांकन कर सकता है। शीर्ष-स्तरीय इंपोर्ट को दुष्प्रभाव-मुक्त रखें और सॉकेट, क्लाइंट, वर्कर और सेवाओं को केवल "full" वाले पथों के पीछे रखें।
• definePluginEntry की तरह, configSchema भी एक लेज़ी फ़ैक्टरी हो सकता है; OpenClaw पहली बार एक्सेस करने पर रिज़ॉल्व किए गए स्कीमा को मेमोइज़ करता है।

CLI पंजीकरण:

• Plugin-स्वामित्व वाले रूट CLI कमांड के लिए api.registerCli(..., { descriptors: [...] }) का उपयोग करें, जिन्हें आप रूट CLI पार्स ट्री से गायब किए बिना लेज़ी-लोड करना चाहते हैं। डिस्क्रिप्टर नामों का मिलान अक्षरों, संख्याओं, हाइफ़न और अंडरस्कोर से होना चाहिए और शुरुआत किसी अक्षर या संख्या से होनी चाहिए; OpenClaw अन्य प्रारूपों को अस्वीकार करता है और सहायता रेंडर करने से पहले विवरणों से टर्मिनल नियंत्रण अनुक्रम हटा देता है। रजिस्ट्रार द्वारा प्रदर्शित प्रत्येक शीर्ष-स्तरीय कमांड रूट को कवर करें। अकेला commands तत्पर संगतता पथ पर रहता है।
• युग्मित-Node सुविधा कमांड के लिए api.registerNodeCliFeature(...) का उपयोग करें, ताकि वे openclaw nodes के अंतर्गत आएँ (registerCli(registrar, { parentPath: ["nodes"], ... }) के समतुल्य)।
• अन्य नेस्टेड Plugin कमांड के लिए, parentPath जोड़ें और रजिस्ट्रार को दिए गए program ऑब्जेक्ट पर कमांड पंजीकृत करें; Plugin को कॉल करने से पहले OpenClaw इसे पैरेंट कमांड में रिज़ॉल्व करता है।
• चैनल Plugin के लिए, CLI डिस्क्रिप्टर registerCliMetadata से पंजीकृत करें और registerFull को केवल रनटाइम कार्य पर केंद्रित रखें।
• यदि registerFull Gateway RPC विधियाँ भी पंजीकृत करता है, तो उन्हें Plugin-विशिष्ट प्रीफ़िक्स पर रखें। आरक्षित कोर एडमिन नेमस्पेस (config.*, exec.approvals.*, wizard.*, update.*) को हमेशा operator.admin में परिवर्तित किया जाता है।

defineSetupPluginEntry

इम्पोर्ट: openclaw/plugin-sdk/channel-core

हल्की setup-entry.ts फ़ाइल के लिए। बिना किसी रनटाइम या CLI वायरिंग के केवल { plugin } लौटाता है।

 export default defineSetupPluginEntry(myChannelPlugin);

जब कोई चैनल अक्षम हो, कॉन्फ़िगर न किया गया हो, या स्थगित लोडिंग सक्षम हो, तब OpenClaw पूर्ण एंट्री के बजाय इसे लोड करता है। यह कब महत्वपूर्ण होता है, इसके लिए सेटअप और कॉन्फ़िगरेशन देखें।

defineSetupPluginEntry(...) को सीमित सेटअप सहायक फ़ैमिली के साथ युग्मित करें:

भारी SDK, CLI पंजीकरण और दीर्घकालिक रनटाइम सेवाओं को पूर्ण एंट्री में रखें।

सेटअप और रनटाइम सतहों को विभाजित करने वाले बंडल किए गए वर्कस्पेस चैनल इसके बजाय openclaw/plugin-sdk/channel-entry-contract से defineBundledChannelSetupEntry(...) का उपयोग कर सकते हैं। यह सेटअप एंट्री को सेटअप-सुरक्षित Plugin/सीक्रेट एक्सपोर्ट बनाए रखते हुए भी रनटाइम सेटर प्रदर्शित करने देता है:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* सेटअप-सुरक्षित रूट */      },    });  },});

इसका उपयोग केवल तब करें, जब किसी सेटअप प्रवाह को पूर्ण चैनल एंट्री लोड होने से पहले वास्तव में हल्के रनटाइम सेटर या सेटअप-सुरक्षित Gateway सतह की आवश्यकता हो। registerSetupRuntime केवल "setup-runtime" लोड के लिए चलता है; इसे केवल-कॉन्फ़िगरेशन रूट या उन विधियों तक सीमित रखें, जिनका स्थगित पूर्ण सक्रियण से पहले मौजूद होना आवश्यक है।

पंजीकरण मोड

api.registrationMode आपके Plugin को बताता है कि उसे कैसे लोड किया गया था:

defineChannelPluginEntry इस विभाजन को स्वचालित रूप से संभालता है। यदि आप किसी चैनल के लिए सीधे definePluginEntry का उपयोग करते हैं, तो मोड स्वयं जाँचें और याद रखें कि "tool-discovery" चैनल पंजीकरण छोड़ देता है:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // केवल-क्षमता सतहें (प्रदाता/टूल) पंजीकृत करें, चैनल नहीं।    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // भारी केवल-रनटाइम पंजीकरण  api.registerService(/* ... */);}

दीर्घकालिक सेवाएँ अपने सेवा कॉन्टेक्स्ट के माध्यम से छोटे अमान्यकरण या लाइफ़साइकल इवेंट उत्सर्जित कर सकती हैं:

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw इसे plugin.<plugin-id>.changed के रूप में नेमस्पेस करता है। इवेंट नाम एक लोअरकेस सेगमेंट होते हैं, पेलोड सीमाबद्ध JSON होने चाहिए और स्कोप operator.read, operator.write या operator.admin होना चाहिए। एमिटर केवल सेवा के जीवनकाल के लिए मौजूद रहता है और सेवा रुकने या उसका प्रारंभ विफल होने के बाद निरस्त कर दिया जाता है। पूर्ण रिकॉर्ड के बजाय संस्करण या अमान्यकरण पेलोड को प्राथमिकता दें, ताकि अधिकृत क्लाइंट Plugin की स्कोप्ड Gateway विधियों के माध्यम से कैनोनिकल स्थिति दोबारा पढ़ें।

खोज मोड एक गैर-सक्रियकारी रजिस्ट्री स्नैपशॉट बनाता है। यह फिर भी Plugin एंट्री और चैनल Plugin ऑब्जेक्ट का मूल्यांकन कर सकता है, ताकि OpenClaw चैनल क्षमताएँ और स्थिर CLI डिस्क्रिप्टर पंजीकृत कर सके। खोज में मॉड्यूल मूल्यांकन को विश्वसनीय लेकिन हल्का मानें: शीर्ष स्तर पर कोई नेटवर्क क्लाइंट, सबप्रोसेस, लिसनर, डेटाबेस कनेक्शन, बैकग्राउंड वर्कर, क्रेडेंशियल पठन या अन्य लाइव रनटाइम साइड इफ़ेक्ट नहीं।

"setup-runtime" को वह अवधि मानें, जिसमें सेटअप-केवल स्टार्टअप सतहों को पूर्ण बंडल किए गए चैनल रनटाइम में दोबारा प्रवेश किए बिना मौजूद होना चाहिए। चैनल पंजीकरण, सेटअप-सुरक्षित HTTP रूट, सेटअप-सुरक्षित Gateway विधियाँ और प्रत्यायोजित सेटअप सहायक इसके उपयुक्त उपयोग हैं। भारी बैकग्राउंड सेवाएँ, CLI रजिस्ट्रार और प्रदाता/क्लाइंट SDK बूटस्ट्रैप अब भी "full" में ही होने चाहिए।

Plugin प्रारूप

OpenClaw लोड किए गए Plugin को उनके पंजीकरण व्यवहार के आधार पर वर्गीकृत करता है:

किसी Plugin का प्रारूप देखने के लिए openclaw plugins inspect <id> का उपयोग करें।

संबंधित

• SDK अवलोकन - पंजीकरण API और उपपथ संदर्भ
• रनटाइम सहायक - api.runtime और createPluginRuntimeStore
• सेटअप और कॉन्फ़िगरेशन - मैनिफ़ेस्ट, सेटअप एंट्री, स्थगित लोडिंग
• चैनल Plugin - ChannelPlugin ऑब्जेक्ट बनाना
• प्रदाता Plugin - प्रदाता पंजीकरण और हुक