openclaw.plugin.json, को कवर करता है। संगत बंडल लेआउट (Codex, Claude, Cursor) के लिए, Plugin बंडल देखें।
संगत बंडल प्रारूप इसके बजाय अपनी स्वयं की मैनिफ़ेस्ट फ़ाइलों का उपयोग करते हैं:
- Codex बंडल:
.codex-plugin/plugin.json - Claude बंडल:
.claude-plugin/plugin.json, या बिना मैनिफ़ेस्ट वाला डिफ़ॉल्ट Claude कंपोनेंट लेआउट - Cursor बंडल:
.cursor-plugin/plugin.json
openclaw.plugin.json स्कीमा के अनुसार उन्हें सत्यापित नहीं करता। संगत बंडल के लिए, लेआउट के OpenClaw की रनटाइम अपेक्षाओं से मेल खाने पर OpenClaw बंडल मेटाडेटा, घोषित स्किल रूट, Claude कमांड रूट, Claude settings.json डिफ़ॉल्ट, Claude LSP डिफ़ॉल्ट और समर्थित हुक पैक पढ़ता है।
प्रत्येक मूल OpenClaw Plugin के Plugin रूट में openclaw.plugin.json होना अनिवार्य है। OpenClaw इसका उपयोग Plugin कोड निष्पादित किए बिना कॉन्फ़िगरेशन सत्यापित करने के लिए करता है। अनुपलब्ध या अमान्य मैनिफ़ेस्ट कॉन्फ़िगरेशन सत्यापन को रोक देता है और इसे Plugin त्रुटि माना जाता है।
संपूर्ण Plugin सिस्टम मार्गदर्शिका के लिए Plugin और मूल क्षमता मॉडल तथा मौजूदा बाहरी-संगतता मार्गदर्शन के लिए क्षमता मॉडल देखें।
यह फ़ाइल क्या करती है
openclaw.plugin.json वह मेटाडेटा है जिसे OpenClaw आपका Plugin कोड लोड करने से पहले पढ़ता है। इसमें मौजूद प्रत्येक चीज़ इतनी किफ़ायती होनी चाहिए कि Plugin रनटाइम बूट किए बिना उसका निरीक्षण किया जा सके।
इसका उपयोग इनके लिए करें:
- Plugin पहचान, कॉन्फ़िगरेशन सत्यापन और कॉन्फ़िगरेशन UI संकेत
- प्रमाणीकरण, ऑनबोर्डिंग और सेटअप मेटाडेटा (उपनाम, स्वतः-सक्षम करना, प्रदाता एनवायरनमेंट वेरिएबल, प्रमाणीकरण विकल्प)
- कंट्रोल-प्लेन सतहों के लिए सक्रियण संकेत
- संक्षिप्त मॉडल-फ़ैमिली स्वामित्व
- स्थिर क्षमता-स्वामित्व स्नैपशॉट (
contracts) - डैशबोर्ड विजेट डेटा बाइंडिंग और क्रिया शब्द
- स्थिर MCP सर्वर, जो Plugin सक्षम रहने के दौरान मौजूद होने चाहिए
- QA रनर मेटाडेटा, जिसका साझा
openclaw qaहोस्ट निरीक्षण कर सकता है - चैनल-विशिष्ट कॉन्फ़िगरेशन मेटाडेटा, जिसे कैटलॉग और सत्यापन सतहों में मर्ज किया जाता है
package.json में होने चाहिए।
न्यूनतम उदाहरण
विस्तृत उदाहरण
शीर्ष-स्तरीय फ़ील्ड संदर्भ
MCP सर्वर संदर्भ
mcpServers किसी नेटिव Plugin को MCP App सहित MCP सर्वर प्रदान करने देता है, जिसके लिए ऑपरेटरों को openclaw.json में उसकी स्थिर प्रक्रिया परिभाषा दोहराने की आवश्यकता नहीं होती:
command, args, cwd, और workingDirectory पथ Plugin रूट से रिज़ॉल्व होते हैं। उपयोगकर्ता कॉन्फ़िगरेशन प्रामाणिक रहता है: mcp.servers.<name> किसी Plugin डिफ़ॉल्ट को बदल सकता है या उसे छोड़ने के लिए enabled: false सेट कर सकता है। MCP App रेंडरिंग और सर्वर-टूल कॉल के लिए अब भी सामान्य MCP Apps सेटिंग और प्रभावी टूल नीति आवश्यक हैं; सर्वर घोषित करने से इनमें से कोई भी सीमा बायपास नहीं होती।
डैशबोर्ड संदर्भ
dashboard किसी सक्षम Plugin को कोर में Plugin नीति जोड़े बिना, अनुमति-प्राप्त डैशबोर्ड विजेट के लिए मौजूदा Gateway RPC उपलब्ध कराने देता है। डेटा बाइंडिंग में उसी Plugin द्वारा operator.read के साथ पंजीकृत विधि का नाम होना चाहिए; एक्शन वर्ब में उसके द्वारा operator.write के साथ पंजीकृत विधि का नाम होना चाहिए। असंगति होने पर पंजीकरण के दौरान Plugin अस्वीकार कर दिया जाता है।
<plugin-id>.<id> का उपयोग करती हैं, जैसे example.items.list और example.refresh। स्थायी अनुमति नेमस्पेस को असंदिग्ध रखने के लिए, OpenClaw Plugin-आईडी खंड में % और . को %25 और %2E के रूप में एस्केप करता है; सामान्य Plugin आईडी अपना स्वाभाविक रूप बनाए रखते हैं। paramShape एक वैकल्पिक JSON Schema है, जिसे OpenClaw द्वारा Plugin RPC लागू करने से पहले एक्शन पैरामीटर ऑब्जेक्ट पर लागू किया जाता है।
कैटलॉग संदर्भ
catalog Plugin ब्राउज़र के लिए वैकल्पिक प्रदर्शन संकेत प्रदान करता है। होस्ट इन संकेतों को अनदेखा कर सकते हैं। ये कभी भी Plugin को इंस्टॉल या सक्षम नहीं करते, और न ही उसके रनटाइम व्यवहार या विश्वास स्तर को बदलते हैं।
जनरेशन प्रदाता मेटाडेटा संदर्भ
जनरेशन प्रदाता मेटाडेटा फ़ील्ड संबद्धcontracts.*GenerationProviders सूची में घोषित प्रदाताओं के लिए स्थिर प्रमाणीकरण संकेतों का वर्णन करते हैं। OpenClaw इन फ़ील्ड को प्रदाता रनटाइम लोड होने से पहले पढ़ता है, ताकि कोर टूल प्रत्येक प्रदाता Plugin को आयात किए बिना यह तय कर सकें कि कोई जनरेशन प्रदाता उपलब्ध है या नहीं।
इन फ़ील्ड का उपयोग केवल कम लागत वाले, घोषणात्मक तथ्यों के लिए करें। ट्रांसपोर्ट, अनुरोध रूपांतरण, टोकन रीफ़्रेश, क्रेडेंशियल सत्यापन और वास्तविक जनरेशन व्यवहार Plugin रनटाइम में रहते हैं।
प्रत्येक
configSignals प्रविष्टि में ये समर्थित हैं:
प्रत्येक
mode गार्ड में ये समर्थित हैं:
प्रत्येक
authSignals प्रविष्टि में ये समर्थित हैं:
प्रत्येक
providerBaseUrl गार्ड में ये समर्थित हैं:
टूल मेटाडेटा संदर्भ
toolMetadata टूल नाम के अनुसार कुंजीबद्ध, जनरेशन प्रदाता मेटाडेटा के समान configSignals और authSignals आकारों का उपयोग करता है। contracts.tools स्वामित्व घोषित करता है। toolMetadata कम लागत वाला उपलब्धता प्रमाण घोषित करता है, ताकि केवल उसकी टूल फ़ैक्ट्री से null लौटवाने के लिए OpenClaw को Plugin रनटाइम आयात न करना पड़े।
toolMetadata प्रविष्टियाँ साझा किए गए उपरोक्त configSignals/authSignals फ़ील्ड के अतिरिक्त optional (टूल को Plugin सक्रियण के लिए अनिवार्य नहीं चिह्नित करता है) और replaySafe (अपूर्ण मॉडल टर्न के बाद टूल निष्पादन को दोहराने के लिए सुरक्षित चिह्नित करता है) भी स्वीकार करती हैं।
यदि किसी टूल में toolMetadata नहीं है, तो OpenClaw मौजूदा व्यवहार बनाए रखता है और टूल अनुबंध के नीति से मेल खाने पर स्वामी Plugin को लोड करता है। उन हॉट-पाथ टूल के लिए जिनकी फ़ैक्टरी प्रमाणीकरण/कॉन्फ़िगरेशन पर निर्भर है, Plugin लेखकों को पूछने के लिए कोर से रनटाइम आयात कराने के बजाय toolMetadata घोषित करना चाहिए।
providerAuthChoices संदर्भ
प्रत्येकproviderAuthChoices प्रविष्टि एक ऑनबोर्डिंग या प्रमाणीकरण विकल्प का वर्णन करती है। OpenClaw इसे प्रदाता रनटाइम लोड होने से पहले पढ़ता है। प्रदाता सेटअप सूचियाँ प्रदाता रनटाइम लोड किए बिना इन मैनिफ़ेस्ट विकल्पों, डिस्क्रिप्टर से प्राप्त सेटअप विकल्पों और इंस्टॉल-कैटलॉग मेटाडेटा का उपयोग करती हैं।
जब
appGuidedDiscovery सत्य हो, तो मेल खाने वाली प्रदाता प्रमाणीकरण विधि को
appGuidedSetup.detect और appGuidedSetup.prepare उपलब्ध कराने होंगे। पहचान
केवल-पढ़ने योग्य होनी चाहिए: कोई लॉगिन, मॉडल पुल, डाउनलोड या कॉन्फ़िगरेशन लेखन नहीं। तैयारी
चुने गए सटीक मॉडल की दोबारा जाँच करती है और एक कॉन्फ़िगरेशन प्रस्ताव लौटाती है; OpenClaw उस
प्रस्ताव का अलगाव में लाइव परीक्षण करता है और सफलता के बाद ही उसे कमिट करता है।
commandAliases संदर्भ
जब कोई Plugin ऐसे रनटाइम कमांड नाम का स्वामी हो जिसे उपयोगकर्ता गलती सेplugins.allow में रख सकते हैं या रूट CLI कमांड के रूप में चलाने का प्रयास कर सकते हैं, तब commandAliases का उपयोग करें। OpenClaw निदान के लिए Plugin रनटाइम कोड आयात किए बिना इस मेटाडेटा का उपयोग करता है।
activation संदर्भ
जब Plugin कम लागत में यह घोषित कर सकता हो कि किन नियंत्रण-प्लेन इवेंट में उसे सक्रियण/लोड योजना में शामिल करना चाहिए, तबactivation का उपयोग करें।
यह ब्लॉक प्लानर मेटाडेटा है, लाइफ़साइकल API नहीं। यह रनटाइम व्यवहार पंजीकृत नहीं करता, register(...) को प्रतिस्थापित नहीं करता और यह वादा नहीं करता कि Plugin कोड पहले ही निष्पादित हो चुका है। सक्रियण प्लानर मौजूदा मैनिफ़ेस्ट स्वामित्व मेटाडेटा, जैसे providers, channels, commandAliases, setup.providers, contracts.tools और हुक पर वापस जाने से पहले उम्मीदवार Plugin को सीमित करने के लिए इन फ़ील्ड का उपयोग करता है।
उस सबसे संकीर्ण मेटाडेटा को प्राथमिकता दें जो पहले से स्वामित्व का वर्णन करता है। जब providers, channels, commandAliases, सेटअप डिस्क्रिप्टर या contracts संबंध को व्यक्त करते हों, तब उनका उपयोग करें। उन अतिरिक्त प्लानर संकेतों के लिए activation का उपयोग करें जिन्हें उन स्वामित्व फ़ील्ड द्वारा दर्शाया नहीं जा सकता। claude-cli, my-cli या google-gemini-cli जैसे CLI रनटाइम उपनामों के लिए शीर्ष-स्तरीय cliBackends का उपयोग करें; activation.onAgentHarnesses केवल उन एम्बेडेड एजेंट हार्नेस आईडी के लिए है जिनके पास पहले से कोई स्वामित्व फ़ील्ड नहीं है।
प्रत्येक Plugin को activation.onStartup जानबूझकर सेट करना चाहिए। इसे केवल तभी true पर सेट करें जब Plugin को Gateway स्टार्टअप के दौरान चलना अनिवार्य हो। जब Plugin स्टार्टअप पर निष्क्रिय हो और केवल अधिक संकीर्ण ट्रिगर से लोड होना चाहिए, तब इसे false पर सेट करें। onStartup को छोड़ने पर अब Plugin स्टार्टअप पर निहित रूप से लोड नहीं होता; स्टार्टअप, चैनल, कॉन्फ़िगरेशन, एजेंट हार्नेस, मेमोरी या अन्य अधिक संकीर्ण सक्रियण ट्रिगर के लिए स्पष्ट सक्रियण मेटाडेटा का उपयोग करें।
वर्तमान सक्रिय उपभोक्ता:
- Gateway स्टार्टअप योजना स्पष्ट स्टार्टअप इंपोर्ट के लिए
activation.onStartupका उपयोग करती है। - कमांड-ट्रिगर की गई CLI योजना पुराने
commandAliases[].cliCommandयाcommandAliases[].nameपर फ़ॉलबैक करती है। - एजेंट-रनटाइम स्टार्टअप योजना एम्बेडेड हार्नेस के लिए
activation.onAgentHarnessesऔर CLI रनटाइम उपनामों के लिए शीर्ष-स्तरीयcliBackends[]का उपयोग करती है। - स्पष्ट चैनल सक्रियण मेटाडेटा अनुपलब्ध होने पर चैनल-ट्रिगर की गई सेटअप/चैनल योजना पुराने
channels[]स्वामित्व पर फ़ॉलबैक करती है। - स्टार्टअप Plugin योजना बंडल किए गए ब्राउज़र Plugin के
browserब्लॉक जैसे गैर-चैनल रूट कॉन्फ़िगरेशन सतहों के लिएactivation.onConfigPathsका उपयोग करती है। - स्पष्ट प्रोवाइडर सक्रियण मेटाडेटा अनुपलब्ध होने पर प्रोवाइडर-ट्रिगर की गई सेटअप/रनटाइम योजना पुराने
providers[]और शीर्ष-स्तरीयcliBackends[]स्वामित्व पर फ़ॉलबैक करती है।
activation-command-hint का अर्थ है कि activation.onCommands मेल खाता है, जबकि manifest-command-alias का अर्थ है कि प्लानर ने इसके बजाय commandAliases स्वामित्व का उपयोग किया। ये कारण लेबल होस्ट डायग्नोस्टिक्स और परीक्षणों के लिए हैं; Plugin लेखकों को उस मेटाडेटा की घोषणा जारी रखनी चाहिए जो स्वामित्व का सर्वोत्तम वर्णन करता है।
qaRunners संदर्भ
जब कोई Plugin साझाopenclaw qa रूट के अंतर्गत एक या अधिक ट्रांसपोर्ट रनर प्रदान करता है, तब qaRunners का उपयोग करें। इस मेटाडेटा को सस्ता और स्थिर रखें; Plugin
रनटाइम अब भी एक हल्की
runtime-api.ts सतह के माध्यम से वास्तविक CLI पंजीकरण का स्वामी होता है, जो मेल खाने वाले qaRunnerCliRegistrations निर्यात करती है। एक
वैकल्पिक adapterFactory पंजीकृत कमांड के रनर को बदले बिना
ट्रांसपोर्ट को साझा QA परिदृश्यों के लिए उपलब्ध कराता है।
adapterFactory आईडी का commandName से मेल खाना आवश्यक है। मैनिफ़ेस्ट में अनुपस्थित
कमांड के लिए पंजीकरण निर्यात न करें।
setup संदर्भ
जब सेटअप और ऑनबोर्डिंग सतहों को रनटाइम लोड होने से पहले सस्ते Plugin-स्वामित्व वाले मेटाडेटा की आवश्यकता हो, तबsetup का उपयोग करें।
cliBackends वैध रहता है और CLI अनुमान बैकएंड का वर्णन करना जारी रखता है। setup.cliBackends कंट्रोल-प्लेन/सेटअप प्रवाहों के लिए सेटअप-विशिष्ट डिस्क्रिप्टर सतह है, जिसे केवल-मेटाडेटा रहना चाहिए।
मौजूद होने पर, setup.providers और setup.cliBackends सेटअप खोज के लिए पसंदीदा डिस्क्रिप्टर-प्रथम लुकअप सतह हैं। यदि डिस्क्रिप्टर केवल उम्मीदवार Plugin को सीमित करता है और सेटअप को अब भी अधिक समृद्ध सेटअप-समय रनटाइम हुक की आवश्यकता है, तो requiresRuntime: true सेट करें और फ़ॉलबैक निष्पादन पथ के रूप में setup-api को बनाए रखें।
OpenClaw सामान्य प्रोवाइडर प्रमाणीकरण और एन्वायरनमेंट-वेरिएबल लुकअप में setup.providers[].envVars को शामिल करता है। सेटअप और स्थिति का एन्वायरनमेंट मेटाडेटा वहाँ रखें।
जब किसी बिलिंग या संगठन-स्तरीय क्रेडेंशियल को अनुमान क्रेडेंशियल बने बिना resolveUsageAuth सक्रिय करना हो, तब providerUsageAuthEnvVars का उपयोग करें। ये नाम वर्कस्पेस dotenv ब्लॉकिंग, ACP चाइल्ड-प्रोसेस स्ट्रिपिंग, सैंडबॉक्स सीक्रेट फ़िल्टरिंग और व्यापक सीक्रेट स्क्रबिंग में जुड़ते हैं। प्रोवाइडर रनटाइम अब भी resolveUsageAuth के भीतर मान को पढ़ता और वर्गीकृत करता है।
जब कोई सेटअप प्रविष्टि उपलब्ध न हो, या जब setup.requiresRuntime: false यह घोषित करे कि सेटअप रनटाइम अनावश्यक है, तब OpenClaw setup.providers[].authMethods से सरल सेटअप विकल्प भी प्राप्त कर सकता है। कस्टम लेबल, CLI फ़्लैग, ऑनबोर्डिंग दायरे और असिस्टेंट मेटाडेटा के लिए स्पष्ट providerAuthChoices प्रविष्टियों को प्राथमिकता मिलती है।
requiresRuntime: false केवल तभी सेट करें, जब वे डिस्क्रिप्टर सेटअप सतह के लिए पर्याप्त हों। OpenClaw स्पष्ट false को केवल-डिस्क्रिप्टर अनुबंध मानता है और सेटअप लुकअप के लिए setup-api या openclaw.setupEntry निष्पादित नहीं करेगा। यदि कोई केवल-डिस्क्रिप्टर Plugin फिर भी उन सेटअप रनटाइम प्रविष्टियों में से किसी एक को शिप करता है, तो OpenClaw एक योगात्मक डायग्नोस्टिक रिपोर्ट करता है और उसे अनदेखा करना जारी रखता है। requiresRuntime को छोड़ देने पर पुराना फ़ॉलबैक व्यवहार बना रहता है, ताकि फ़्लैग के बिना डिस्क्रिप्टर जोड़ने वाले मौजूदा Plugin न टूटें।
चूँकि सेटअप लुकअप Plugin-स्वामित्व वाला setup-api कोड निष्पादित कर सकता है, सामान्यीकृत setup.providers[].id और setup.cliBackends[] मानों को खोजे गए सभी Plugin में अद्वितीय रहना आवश्यक है। अस्पष्ट स्वामित्व खोज क्रम से विजेता चुनने के बजाय बंद होकर विफल होता है।
जब सेटअप रनटाइम निष्पादित होता है, तब सेटअप रजिस्ट्री डायग्नोस्टिक्स डिस्क्रिप्टर विचलन की रिपोर्ट करते हैं, यदि setup-api ऐसे प्रोवाइडर या CLI बैकएंड को पंजीकृत करता है जिसे मैनिफ़ेस्ट डिस्क्रिप्टर घोषित नहीं करते, या यदि किसी डिस्क्रिप्टर के लिए कोई मेल खाता रनटाइम पंजीकरण नहीं है। ये डायग्नोस्टिक्स योगात्मक हैं और पुराने Plugin को अस्वीकार नहीं करते।
setup.providers संदर्भ
authEvidence प्रोवाइडर-स्वामित्व वाले स्थानीय क्रेडेंशियल मार्कर के लिए है, जिन्हें रनटाइम कोड लोड किए बिना सत्यापित किया जा सकता है। इन जाँचों को सस्ता और स्थानीय रहना आवश्यक है: कोई नेटवर्क कॉल नहीं, कोई कीचेन या सीक्रेट-मैनेजर रीड नहीं, कोई शेल कमांड नहीं और कोई प्रोवाइडर API प्रोब नहीं।
समर्थित प्रमाण प्रविष्टियाँ:
setup फ़ील्ड
uiHints संदर्भ
uiHints कॉन्फ़िग फ़ील्ड नामों से छोटे रेंडरिंग संकेतों तक का एक मैप है। नेस्टेड कॉन्फ़िग फ़ील्ड के लिए कुंजियों में डॉट का उपयोग किया जा सकता है, लेकिन कोई भी पथ खंड __proto__, constructor, या prototype नहीं हो सकता; सेटअप इन नामों को अस्वीकार करता है।
contracts संदर्भ
contracts का उपयोग केवल स्थिर क्षमता-स्वामित्व मेटाडेटा के लिए करें, जिसे OpenClaw Plugin रनटाइम आयात किए बिना पढ़ सके।
contracts.embeddedExtensionFactories को केवल बंडल किए गए Codex ऐप-सर्वर एक्सटेंशन फ़ैक्टरी के लिए रखा गया है। इसके बजाय बंडल किए गए टूल-परिणाम रूपांतरणों को contracts.agentToolResultMiddleware घोषित करना और api.registerAgentToolResultMiddleware(...) के साथ पंजीकृत करना चाहिए। इंस्टॉल किए गए Plugin केवल स्पष्ट रूप से सक्षम होने पर और केवल उन रनटाइम के लिए समान मिडलवेयर सीम का उपयोग कर सकते हैं, जिन्हें वे contracts.agentToolResultMiddleware में घोषित करते हैं।
जिन इंस्टॉल किए गए Plugin को होस्ट-विश्वसनीय प्री-टूल नीति स्तर की आवश्यकता है, उन्हें प्रत्येक पंजीकृत स्थानीय आईडी को contracts.trustedToolPolicies में घोषित करना और स्पष्ट रूप से सक्षम होना चाहिए। बंडल किए गए Plugin मौजूदा विश्वसनीय-नीति पथ बनाए रखते हैं, लेकिन अघोषित नीति आईडी वाले इंस्टॉल किए गए Plugin पंजीकरण से पहले अस्वीकार कर दिए जाते हैं। नीति आईडी पंजीकरण करने वाले Plugin के दायरे में होती हैं, इसलिए दो Plugin दोनों workflow-budget को घोषित और पंजीकृत कर सकते हैं; कोई एकल Plugin समान स्थानीय आईडी को दो बार पंजीकृत नहीं कर सकता।
रनटाइम api.registerTool(...) पंजीकरणों का contracts.tools से मेल खाना आवश्यक है। टूल खोज इस सूची का उपयोग केवल उन Plugin रनटाइम को लोड करने के लिए करती है, जो अनुरोधित टूल के स्वामी हो सकते हैं।
resolveExternalAuthProfiles लागू करने वाले प्रदाता Plugin को contracts.externalAuthProviders घोषित करना चाहिए; अघोषित बाहरी-प्रमाणीकरण हुक अनदेखे किए जाते हैं।
resolveUsageAuth और fetchUsageSnapshot दोनों लागू करने वाले प्रदाता Plugin को प्रत्येक स्वतः खोजी गई प्रदाता आईडी को contracts.usageProviders में घोषित करना चाहिए। उपयोग खोज रनटाइम कोड लोड करने से पहले इस अनुबंध को पढ़ती है, फिर केवल घोषित स्वामियों को लोड करने के बाद दोनों हुक सत्यापित करती है।
सामान्य एम्बेडिंग प्रदाताओं को api.registerEmbeddingProvider(...) के साथ पंजीकृत प्रत्येक अडैप्टर के लिए contracts.embeddingProviders घोषित करना चाहिए। मेमोरी खोज द्वारा उपयोग किए जाने वाले प्रदाताओं सहित पुनः उपयोग योग्य वेक्टर जनरेशन के लिए सामान्य अनुबंध का उपयोग करें। contracts.memoryEmbeddingProviders अप्रचलित मेमोरी-विशिष्ट संगतता है और केवल तब तक रहता है, जब तक मौजूदा प्रदाता सामान्य एम्बेडिंग प्रदाता सीम पर माइग्रेट नहीं हो जाते।
वर्कर प्रदाताओं को प्रत्येक api.registerWorkerProvider(...) आईडी को contracts.workerProviders में घोषित करना होगा। कोर provision को कॉल करने से पहले स्थायी आशय सहेजता है; प्रदाता बाहरी आवंटन से पहले अपनी सेटिंग सत्यापित करते हैं, और समान ऑपरेशन आईडी वाले दोहराए गए कॉल को समान लीज़ अपनानी होगी। कोर उस सत्यापित सेटिंग स्नैपशॉट को भी सहेजता है और नामित प्रोफ़ाइल बदले या हटाए जाने के बाद भी उसे leaseId के साथ inspect({ leaseId, profile }) और destroy({ leaseId, profile }) को भेजता है। विनाश आइडेम्पोटेंट है, निरीक्षण बंद active / destroyed / unknown स्थिति यूनियन लौटाता है, और SSH निजी-कुंजी सामग्री को केवल SecretRef के माध्यम से संदर्भित किया जाता है। प्रावधान किए गए SSH एंडपॉइंट में विश्वसनीय प्रावधान आउटपुट से एक सार्वजनिक hostKey भी ठीक algorithm base64 के रूप में शामिल होना चाहिए, बिना होस्टनाम या टिप्पणी के, ताकि कोर कनेक्ट होने से पहले होस्ट को पिन कर सके। गतिशील पहचान संदर्भ जारी करने वाले प्रदाता प्रामाणिक resolveSshIdentity({ leaseId, profile, keyRef }) लागू कर सकते हैं; इसके बिना प्रदाता कोर के सामान्य सीक्रेट रिज़ॉल्वर का उपयोग करते हैं। एक प्रामाणिक unknown सक्रिय स्थानीय रिकॉर्ड को अनाथ कर देता है; स्थायी विनाश अनुरोध के बाद यह विघटन की पुष्टि करता है।
contracts.gatewayMethodDispatch वर्तमान में "authenticated-request" स्वीकार करता है। यह उन नेटिव Plugin HTTP रूटों के लिए एक API स्वच्छता गेट है जो जानबूझकर Gateway कंट्रोल-प्लेन विधियों को इन-प्रोसेस डिस्पैच करते हैं, दुर्भावनापूर्ण नेटिव Plugins के विरुद्ध सैंडबॉक्स नहीं। इसका उपयोग केवल कड़ी समीक्षा वाले बंडल किए गए/ऑपरेटर सरफ़ेसों के लिए करें, जिन्हें पहले से Gateway HTTP प्रमाणीकरण की आवश्यकता होती है। Gateway रूट-वर्क प्रवेश बंद होने पर भी कोई अधिकार-प्राप्त रूट केवल तभी पहुँच योग्य रहता है, जब वह auth: "gateway" और रूट-विशिष्ट gatewayRuntimeScopeSurface: "trusted-operator" भी घोषित करता है; उसी Plugin के सामान्य सहोदर रूट प्रवेश सीमा के पीछे बने रहते हैं। इससे पूरे Plugin को प्रवेश बायपास दिए बिना निलंबन स्थिति और पुनः आरंभ तक पहुँच बनी रहती है। पार्सिंग और प्रतिक्रिया संरचना को डिस्पैच के बाहर सीमित रखें; महत्वपूर्ण या परिवर्तनकारी कार्य Gateway विधि डिस्पैच से होकर जाना चाहिए, जो प्रवेश और स्कोप प्रवर्तन का स्वामी है।
configContracts संदर्भ
मैनिफ़ेस्ट-स्वामित्व वाले उस कॉन्फ़िग व्यवहार के लिएconfigContracts का उपयोग करें, जिसकी सामान्य कोर सहायकों को Plugin रनटाइम आयात किए बिना आवश्यकता होती है: खतरनाक फ़्लैग की पहचान, SecretRef माइग्रेशन लक्ष्य और पुराने कॉन्फ़िग-पथ का संकुचन।
प्रत्येक
dangerousFlags प्रविष्टि इसका समर्थन करती है:
secretInputs इसका समर्थन करता है:
mediaUnderstandingProviderMetadata संदर्भ
जब किसी मीडिया-समझ प्रदाता के पास डिफ़ॉल्ट मॉडल, स्वचालित प्रमाणीकरण फ़ॉलबैक प्राथमिकता या नेटिव दस्तावेज़ समर्थन हो, जिसकी सामान्य कोर सहायकों को रनटाइम लोड होने से पहले आवश्यकता होती है, तबmediaUnderstandingProviderMetadata का उपयोग करें। कुंजियाँ contracts.mediaUnderstandingProviders में भी घोषित होनी चाहिए।
channelConfigs संदर्भ
जब किसी चैनल Plugin को रनटाइम लोड होने से पहले कम लागत वाले कॉन्फ़िग मेटाडेटा की आवश्यकता हो, तबchannelConfigs का उपयोग करें। जब कोई सेटअप प्रविष्टि उपलब्ध न हो, या जब setup.requiresRuntime: false सेटअप रनटाइम को अनावश्यक घोषित करे, तब केवल-पढ़ने योग्य चैनल सेटअप/स्थिति खोज कॉन्फ़िगर किए गए बाहरी चैनलों के लिए सीधे इस मेटाडेटा का उपयोग कर सकती है।
channelConfigs Plugin मैनिफ़ेस्ट मेटाडेटा है, कोई नया शीर्ष-स्तरीय उपयोगकर्ता कॉन्फ़िग अनुभाग नहीं। उपयोगकर्ता अब भी चैनल इंस्टेंस को channels.<channel-id> के अंतर्गत कॉन्फ़िगर करते हैं। Plugin रनटाइम कोड निष्पादित होने से पहले, OpenClaw यह तय करने के लिए मैनिफ़ेस्ट मेटाडेटा पढ़ता है कि उस कॉन्फ़िगर किए गए चैनल का स्वामी कौन-सा Plugin है।
किसी चैनल Plugin के लिए, configSchema और channelConfigs अलग-अलग पथों का वर्णन करते हैं:
configSchema,plugins.entries.<plugin-id>.configको सत्यापित करता हैchannelConfigs.<channel-id>.schema,channels.<channel-id>को सत्यापित करता है
channels[] घोषित करने वाले गैर-बंडल Plugins को मेल खाती channelConfigs प्रविष्टियाँ भी घोषित करनी चाहिए। इनके बिना OpenClaw अब भी Plugin लोड कर सकता है, लेकिन Plugin रनटाइम निष्पादित होने तक कोल्ड-पाथ कॉन्फ़िग स्कीमा, सेटअप और Control UI सरफ़ेस चैनल-स्वामित्व वाले विकल्प का आकार या केवल-प्रदर्शन UI संकेत नहीं जान सकते।
channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled और nativeSkillsAutoEnabled कमांड कॉन्फ़िग जाँचों के लिए स्थिर auto डिफ़ॉल्ट घोषित कर सकते हैं, जो चैनल रनटाइम लोड होने से पहले चलती हैं। बंडल किए गए चैनल अपने अन्य पैकेज-स्वामित्व वाले चैनल कैटलॉग मेटाडेटा के साथ package.json#openclaw.channel.commands के माध्यम से भी वही डिफ़ॉल्ट प्रकाशित कर सकते हैं।
किसी अन्य चैनल Plugin को प्रतिस्थापित करना
जब आपका Plugin ऐसे चैनल आईडी का पसंदीदा स्वामी हो, जिसे कोई अन्य Plugin भी प्रदान कर सकता है, तबpreferOver का उपयोग करें। सामान्य मामलों में बदला हुआ Plugin आईडी, बंडल किए गए Plugin का स्थान लेने वाला स्टैंडअलोन Plugin, या कॉन्फ़िग संगतता के लिए वही चैनल आईडी बनाए रखने वाला अनुरक्षित फ़ोर्क शामिल हैं।
channels.chat कॉन्फ़िगर किया जाता है, तो OpenClaw चैनल आईडी और पसंदीदा Plugin आईडी, दोनों पर विचार करता है। यदि कम-प्राथमिकता वाला Plugin केवल इसलिए चुना गया था क्योंकि वह बंडल में शामिल है या डिफ़ॉल्ट रूप से सक्षम है, तो OpenClaw प्रभावी रनटाइम कॉन्फ़िगरेशन में उसे अक्षम कर देता है, ताकि एक Plugin चैनल और उसके टूल का स्वामी हो। स्पष्ट उपयोगकर्ता चयन फिर भी प्रभावी रहता है: यदि उपयोगकर्ता दोनों Plugin को स्पष्ट रूप से सक्षम करता है (plugins.allow या किसी वास्तविक plugins.entries कॉन्फ़िगरेशन के माध्यम से), तो OpenClaw उस चयन को बनाए रखता है और अनुरोधित Plugin समूह को चुपचाप बदलने के बजाय डुप्लिकेट चैनल/टूल निदान रिपोर्ट करता है।
preferOver को केवल उन Plugin आईडी तक सीमित रखें जो वास्तव में वही चैनल प्रदान कर सकती हैं। यह कोई सामान्य प्राथमिकता फ़ील्ड नहीं है और यह उपयोगकर्ता कॉन्फ़िगरेशन कुंजियों का नाम नहीं बदलता।
modelSupport संदर्भ
जब Plugin रनटाइम लोड होने से पहले OpenClaw कोgpt-5.6-sol या claude-sonnet-4.6 जैसी संक्षिप्त मॉडल आईडी से आपके प्रदाता Plugin का अनुमान लगाना चाहिए, तब modelSupport का उपयोग करें।
- स्पष्ट
provider/modelसंदर्भ स्वामीprovidersकी मैनिफ़ेस्ट मेटाडेटा का उपयोग करते हैं modelPatterns,modelPrefixesसे अधिक प्राथमिकता रखते हैं- यदि एक गैर-बंडल Plugin और एक बंडल Plugin, दोनों मेल खाते हैं, तो गैर-बंडल Plugin को प्राथमिकता मिलती है
- शेष अस्पष्टता को तब तक अनदेखा किया जाता है, जब तक उपयोगकर्ता या कॉन्फ़िगरेशन किसी प्रदाता को निर्दिष्ट नहीं करता
modelPatterns प्रविष्टियों को compileSafeRegex के माध्यम से संकलित किया जाता है, जो नेस्टेड पुनरावृत्ति वाले पैटर्न (उदाहरण के लिए (a+)+$) को अस्वीकार करता है। सुरक्षा जाँच में विफल होने वाले पैटर्न को वाक्य-विन्यास की दृष्टि से अमान्य रेगेक्स की तरह चुपचाप छोड़ दिया जाता है। पैटर्न सरल रखें और नेस्टेड क्वांटिफ़ायर से बचें।
modelCatalog संदर्भ
जब Plugin रनटाइम लोड करने से पहले OpenClaw को प्रदाता मॉडल मेटाडेटा की जानकारी होनी चाहिए, तबmodelCatalog का उपयोग करें। यह स्थिर कैटलॉग पंक्तियों, प्रदाता उपनामों, दमन नियमों और खोज मोड के लिए मैनिफ़ेस्ट-स्वामित्व वाला स्रोत है। रनटाइम रीफ़्रेश अब भी प्रदाता रनटाइम कोड के अंतर्गत आता है, लेकिन मैनिफ़ेस्ट कोर को बताता है कि रनटाइम कब आवश्यक है।
aliases मॉडल-कैटलॉग योजना के लिए प्रदाता स्वामित्व खोज में भाग लेता है। उपनाम लक्ष्य उसी Plugin के स्वामित्व वाले शीर्ष-स्तरीय प्रदाता होने चाहिए। जब प्रदाता-फ़िल्टर की गई सूची किसी उपनाम का उपयोग करती है, तो OpenClaw प्रदाता रनटाइम लोड किए बिना स्वामी मैनिफ़ेस्ट को पढ़ सकता है और उपनाम के API/आधार URL ओवरराइड लागू कर सकता है। उपनाम बिना फ़िल्टर वाली कैटलॉग सूचियों का विस्तार नहीं करते; व्यापक सूचियाँ केवल स्वामी की कैनोनिकल प्रदाता पंक्तियाँ उत्सर्जित करती हैं।
suppressions पुराने प्रदाता रनटाइम suppressBuiltInModel हुक का स्थान लेता है। दमन प्रविष्टियों का पालन केवल तभी किया जाता है, जब प्रदाता Plugin के स्वामित्व में हो या उसे ऐसी modelCatalog.aliases कुंजी के रूप में घोषित किया गया हो जो किसी स्वामित्व वाले प्रदाता को लक्षित करती है। मॉडल रिज़ॉल्यूशन के दौरान अब रनटाइम दमन हुक नहीं बुलाए जाते।
प्रदाता फ़ील्ड:
मॉडल फ़ील्ड:
दमन फ़ील्ड:
केवल रनटाइम के डेटा को
modelCatalog में न रखें। static का उपयोग केवल तब करें, जब मैनिफ़ेस्ट पंक्तियाँ इतनी पूर्ण हों कि प्रोवाइडर-फ़िल्टर की गई सूची और पिकर सतहें रजिस्ट्री/रनटाइम खोज को छोड़ सकें। refreshable का उपयोग तब करें, जब मैनिफ़ेस्ट पंक्तियाँ सूचीबद्ध किए जा सकने वाले उपयोगी प्रारंभिक डेटा या पूरक हों, लेकिन रीफ़्रेश/कैश बाद में और पंक्तियाँ जोड़ सके; रीफ़्रेश की जा सकने वाली पंक्तियाँ अपने आप में प्रामाणिक नहीं होतीं। runtime का उपयोग तब करें, जब सूची जानने के लिए OpenClaw को प्रोवाइडर रनटाइम लोड करना आवश्यक हो।
modelIdNormalization संदर्भ
कम लागत वाली, प्रोवाइडर-स्वामित्व वाली मॉडल-आईडी सफ़ाई के लिएmodelIdNormalization का उपयोग करें, जिसे प्रोवाइडर रनटाइम लोड होने से पहले होना आवश्यक है। इससे छोटे मॉडल नामों, प्रोवाइडर-स्थानीय लेगेसी आईडी और प्रॉक्सी प्रीफ़िक्स नियमों जैसे उपनाम कोर मॉडल-चयन तालिकाओं के बजाय स्वामी Plugin मैनिफ़ेस्ट में रहते हैं।
providerEndpoints संदर्भ
एंडपॉइंट वर्गीकरण के लिएproviderEndpoints का उपयोग करें, जिसे सामान्य अनुरोध नीति को प्रोवाइडर रनटाइम लोड होने से पहले जानना आवश्यक है। प्रत्येक endpointClass का अर्थ अब भी कोर के स्वामित्व में है; होस्ट और बेस URL मेटाडेटा Plugin मैनिफ़ेस्ट के स्वामित्व में है।
आधिकारिक रूप से बाहरी किए गए प्रोवाइडर Plugin कोर डिस्ट्रीब्यूशन से बाहर रखे जाते हैं, इसलिए
इंस्टॉल होने तक उनके मैनिफ़ेस्ट दिखाई नहीं देते। उनके providerEndpoints को
scripts/lib/official-external-provider-catalog.json में भी प्रतिबिंबित किया जाना चाहिए, ताकि
Plugin के बिना भी एंडपॉइंट वर्गीकरण कार्य करता रहे; एक अनुबंध परीक्षण
इस प्रतिबिंब को लागू करता है।
एंडपॉइंट फ़ील्ड:
providerRequest संदर्भ
कम लागत वाले अनुरोध-संगतता मेटाडेटा के लिएproviderRequest का उपयोग करें, जिसकी सामान्य अनुरोध नीति को प्रोवाइडर रनटाइम लोड किए बिना आवश्यकता होती है। व्यवहार-विशिष्ट पेलोड पुनर्लेखन को प्रोवाइडर रनटाइम हुक या साझा प्रोवाइडर-परिवार हेल्पर में रखें।
secretProviderIntegrations संदर्भ
जब कोई Plugin पुनः उपयोग योग्य SecretRef exec प्रोवाइडर प्रीसेट प्रकाशित कर सकता हो, तबsecretProviderIntegrations का उपयोग करें। OpenClaw, Plugin रनटाइम लोड होने से पहले यह मेटाडेटा पढ़ता है, Plugin स्वामित्व को secrets.providers.<alias>.pluginIntegration में संग्रहीत करता है और वास्तविक सीक्रेट समाधान को SecretRef रनटाइम पर छोड़ देता है। प्रीसेट केवल बंडल किए गए Plugin और प्रबंधित Plugin इंस्टॉल रूट से खोजे गए इंस्टॉल किए हुए Plugin, जैसे git और ClawHub इंस्टॉल, के लिए उपलब्ध कराए जाते हैं।
providerAlias छोड़ दिया गया है, तो OpenClaw इंटीग्रेशन आईडी को SecretRef प्रोवाइडर उपनाम के रूप में उपयोग करता है। प्रोवाइडर उपनाम को सामान्य SecretRef प्रोवाइडर उपनाम पैटर्न से मेल खाना चाहिए, उदाहरण के लिए team-secrets या onepassword-work।
जब कोई ऑपरेटर प्रीसेट चुनता है, तो OpenClaw इस तरह का प्रोवाइडर संदर्भ लिखता है:
command/args प्रोवाइडर सीधे लिख सकते हैं।
वर्तमान में केवल source: "exec" प्रीसेट समर्थित हैं। command, ${node} होना चाहिए और args[0], ./ Plugin-रूट-सापेक्ष रिज़ॉल्वर स्क्रिप्ट होनी चाहिए। OpenClaw स्टार्टअप/रीलोड पर इसे वर्तमान Node एक्ज़ीक्यूटेबल और Plugin के भीतर पूर्ण स्क्रिप्ट पथ में साकार करता है। --require, --import, --loader, --env-file, --eval और --print जैसे Node विकल्प मैनिफ़ेस्ट प्रीसेट अनुबंध का भाग नहीं हैं। जिन ऑपरेटरों को गैर-Node कमांड की आवश्यकता है, वे स्वतंत्र मैन्युअल exec प्रोवाइडर सीधे कॉन्फ़िगर कर सकते हैं।
OpenClaw मैनिफ़ेस्ट प्रीसेट के लिए trustedDirs को Plugin रूट से और ${node} प्रीसेट के लिए वर्तमान Node एक्ज़ीक्यूटेबल डायरेक्टरी से प्राप्त करता है। मैनिफ़ेस्ट में लिखे गए trustedDirs को अनदेखा किया जाता है। timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv और allowInsecurePath जैसे अन्य exec प्रोवाइडर विकल्प सामान्य SecretRef exec प्रोवाइडर कॉन्फ़िगरेशन को यथावत भेजे जाते हैं।
modelPricing संदर्भ
जब किसी प्रोवाइडर को रनटाइम लोड होने से पहले कंट्रोल-प्लेन मूल्य-निर्धारण व्यवहार की आवश्यकता हो, तबmodelPricing का उपयोग करें। Gateway मूल्य-निर्धारण कैश प्रोवाइडर रनटाइम कोड आयात किए बिना यह मेटाडेटा पढ़ता है।
स्रोत फ़ील्ड:
OpenClaw प्रोवाइडर इंडेक्स
OpenClaw प्रोवाइडर इंडेक्स उन प्रोवाइडर के लिए OpenClaw-स्वामित्व वाला पूर्वावलोकन मेटाडेटा है, जिनके Plugin संभवतः अभी इंस्टॉल नहीं हुए हैं। यह किसी Plugin मैनिफ़ेस्ट का भाग नहीं है। Plugin मैनिफ़ेस्ट इंस्टॉल किए गए Plugin के लिए प्रामाणिक स्रोत बने रहते हैं। प्रोवाइडर इंडेक्स वह आंतरिक फ़ॉलबैक अनुबंध है, जिसका उपयोग भविष्य की इंस्टॉल-योग्य प्रोवाइडर और इंस्टॉल-पूर्व मॉडल पिकर सतहें तब करेंगी, जब कोई प्रोवाइडर Plugin इंस्टॉल नहीं है। कैटलॉग प्रामाणिकता क्रम:- उपयोगकर्ता कॉन्फ़िगरेशन।
- इंस्टॉल किया गया Plugin मैनिफ़ेस्ट
modelCatalog। - स्पष्ट रीफ़्रेश से मॉडल कैटलॉग कैश।
- OpenClaw प्रोवाइडर इंडेक्स पूर्वावलोकन पंक्तियाँ।
modelCatalog provider row shape का उपयोग करते हैं, लेकिन इन्हें स्थिर display metadata तक सीमित रहना चाहिए, जब तक कि api, baseUrl, pricing, या compatibility flags जैसे runtime adapter fields को जानबूझकर installed plugin manifest के साथ संरेखित न रखा गया हो। live /models discovery वाले providers को सामान्य listing या onboarding से provider APIs कॉल कराने के बजाय explicit model catalog cache path के माध्यम से refreshed rows लिखनी चाहिए।
Provider Index entries उन providers के लिए installable-plugin metadata भी रख सकती हैं, जिनका plugin core से बाहर स्थानांतरित हो गया है या किसी अन्य कारण से अभी installed नहीं है। यह metadata channel catalog pattern को प्रतिबिंबित करता है: package name, npm install spec, expected integrity, और सरल auth-choice labels किसी installable setup option को दिखाने के लिए पर्याप्त हैं। plugin install हो जाने के बाद, उसका manifest प्रभावी होता है और उस provider के लिए Provider Index entry की उपेक्षा की जाती है।
openclaw doctor --fix, legacy top-level manifest capability keys के एक छोटे, बंद समूह को contracts.* में migrate करता है: speechProviders, mediaUnderstandingProviders, imageGenerationProviders, और tools। इनमें से किसी को भी (या किसी अन्य capability list को) अब top-level manifest fields के रूप में नहीं पढ़ा जाता; सामान्य manifest loading इन्हें केवल contracts के अंतर्गत पहचानती है।
Manifest बनाम package.json
दोनों files अलग-अलग कार्य करती हैं:
यदि यह स्पष्ट न हो कि metadata का कोई भाग कहाँ होना चाहिए, तो इस नियम का उपयोग करें:
- यदि OpenClaw को plugin code load करने से पहले इसकी जानकारी होना आवश्यक है, तो इसे
openclaw.plugin.jsonमें रखें - यदि यह packaging, entry files, या npm install behavior से संबंधित है, तो इसे
package.jsonमें रखें
discovery को प्रभावित करने वाले package.json fields
कुछ pre-runtime plugin metadata जानबूझकरopenclaw.plugin.json के बजाय package.json में openclaw block के अंतर्गत रहता है। openclaw.bundle और openclaw.bundle.json, OpenClaw plugin contracts नहीं हैं; native plugins को openclaw.plugin.json तथा नीचे दिए गए supported package.json#openclaw fields का उपयोग करना चाहिए।
महत्वपूर्ण उदाहरण:
Manifest metadata निर्धारित करता है कि runtime load होने से पहले onboarding में कौन-से provider/channel/setup choices दिखाई देंगे। जब उपयोगकर्ता उन choices में से किसी एक को चुनता है, तो
package.json#openclaw.install onboarding को बताता है कि उस plugin को कैसे fetch या enable करना है। install hints को openclaw.plugin.json में न ले जाएँ।
openclaw.channel.cliAddOptions के लिए Commander’s long-option syntax का उपयोग करें, जैसे --initial-sync-limit <n>। non-negative integer parse करने के लिए valueType: "int" सेट करें, या plugin setup adapter को input मिलने से पहले comma-, semicolon-, या newline-delimited input को strings में विभाजित करने के लिए valueType: "list" सेट करें। parsed Commander value को अपरिवर्तित रूप से आगे भेजने के लिए valueType को छोड़ दें।
non-bundled plugin sources के लिए install और manifest registry loading के दौरान openclaw.install.minHostVersion लागू किया जाता है। invalid values अस्वीकार कर दी जाती हैं; newer-but-valid values पुराने hosts पर external plugins को छोड़ देती हैं। bundled source plugins को host checkout के साथ co-versioned माना जाता है।
openclaw.install.requiredPlatformPackages उन npm packages के लिए है जो optional, platform-specific aliases के माध्यम से आवश्यक native binaries उपलब्ध कराते हैं। प्रत्येक supported platform alias के लिए bare npm package name सूचीबद्ध करें। npm install के दौरान, OpenClaw केवल उस declared alias को verify करता है जिसके lockfile constraints current host से match करते हैं। यदि npm success report करता है लेकिन उस alias को छोड़ देता है, तो OpenClaw fresh cache के साथ एक बार retry करता है और alias के अब भी missing होने पर install को roll back कर देता है।
non-bundled plugin sources के लिए package install के दौरान openclaw.compat.pluginApi लागू किया जाता है। इसका उपयोग उस OpenClaw plugin SDK/runtime API floor के लिए करें जिसके विरुद्ध package बनाया गया था। यदि किसी plugin package को नए API की आवश्यकता है, लेकिन वह अन्य प्रवाहों के लिए कम install hint बनाए रखता है, तो यह minHostVersion से अधिक strict हो सकता है। Official OpenClaw release sync मौजूदा official plugin API floors को default रूप से OpenClaw release version तक बढ़ाता है, लेकिन plugin-only releases कम floor बनाए रख सकते हैं, जब package जानबूझकर पुराने hosts को support करता हो। केवल package version को compatibility contract के रूप में उपयोग न करें। peerDependencies.openclaw, npm package metadata ही रहता है; OpenClaw install compatibility decisions के लिए openclaw.compat.pluginApi contract का उपयोग करता है।
जब plugin ClawHub पर published हो, तो official install-on-demand metadata को clawhubSpec का उपयोग करना चाहिए; onboarding इसे पसंदीदा remote source मानता है और install के बाद ClawHub artifact facts record करता है। उन packages के लिए जो अभी ClawHub पर स्थानांतरित नहीं हुए हैं, npmSpec compatibility fallback बना रहता है।
Exact npm version pinning पहले से npmSpec में रहता है, उदाहरण के लिए "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"। Official external catalog entries को exact specs के साथ expectedIntegrity जोड़ना चाहिए, ताकि fetched npm artifact के pinned release से अब match न करने पर update प्रवाह fail closed हों। compatibility के लिए interactive onboarding अभी भी trusted registry npm specs प्रदान करता है, जिनमें bare package names और dist-tags शामिल हैं। Catalog diagnostics exact, floating, integrity-pinned, missing-integrity, package-name mismatch, और invalid default-choice sources के बीच अंतर कर सकते हैं। जब expectedIntegrity मौजूद हो लेकिन ऐसा कोई valid npm source न हो जिसे वह pin कर सके, तो वे चेतावनी भी देते हैं। जब expectedIntegrity मौजूद हो, तो install/update प्रवाह इसे लागू करते हैं; जब इसे छोड़ दिया जाता है, तो registry resolution को integrity pin के बिना record किया जाता है।
जब status, channel list, या SecretRef scans को पूरा runtime load किए बिना configured accounts की पहचान करनी हो, तो channel plugins को openclaw.setupEntry प्रदान करना चाहिए। setup entry को channel metadata के साथ setup-safe config, status, और secrets adapters उपलब्ध कराने चाहिए; network clients, gateway listeners, और transport runtimes को main extension entrypoint में रखें।
रनटाइम एंट्रीपॉइंट फ़ील्ड, स्रोत एंट्रीपॉइंट फ़ील्ड के लिए पैकेज-सीमा जाँचों को ओवरराइड नहीं करते। उदाहरण के लिए, openclaw.runtimeExtensions किसी सीमा से बाहर जाते openclaw.extensions पथ को लोड करने योग्य नहीं बना सकता।
openclaw.install.allowInvalidConfigRecovery जानबूझकर सीमित है। यह मनमाने ढंग से खराब कॉन्फ़िग को इंस्टॉल करने योग्य नहीं बनाता। वर्तमान में यह केवल इंस्टॉल प्रवाहों को विशिष्ट पुराने बंडल किए गए Plugin अपग्रेड विफलताओं से उबरने देता है, जैसे बंडल किए गए Plugin का पथ अनुपलब्ध होना या उसी बंडल किए गए Plugin के लिए पुरानी channels.<id> प्रविष्टि। असंबंधित कॉन्फ़िग त्रुटियाँ अब भी इंस्टॉल को अवरुद्ध करती हैं और ऑपरेटरों को openclaw doctor --fix पर भेजती हैं।
openclaw.channel.persistedAuthState एक छोटे जाँचकर्ता मॉड्यूल के लिए पैकेज मेटाडेटा है:
openclaw.channel.configuredState कम लागत वाली कॉन्फ़िगरेशन जाँचों का समर्थन करता है। जब पर्यावरण चर पर्याप्त हों, तो घोषणात्मक पर्यावरण मेटाडेटा को प्राथमिकता दें:
env.allOf का उपयोग करें और जब कोई भी एक गैर-रिक्त चर पर्याप्त हो, तब env.anyOf का उपयोग करें। यदि किसी छोटे गैर-रनटाइम जाँच को पर्यावरण मेटाडेटा से अधिक की आवश्यकता हो, तो persistedAuthState के लिए दिखाए अनुसार specifier के साथ exportName का उपयोग करें; जब env मौजूद होता है, तो OpenClaw उस मॉड्यूल को लोड किए बिना इसका उपयोग करता है। यदि जाँच को पूर्ण कॉन्फ़िग समाधान या वास्तविक चैनल रनटाइम की आवश्यकता हो, तो उस लॉजिक को इसके बजाय Plugin के config.hasConfiguredState हुक में रखें।
खोज प्राथमिकता (डुप्लिकेट Plugin आईडी)
OpenClaw तीन रूट से Plugin खोजता है, जिनकी जाँच इस क्रम में होती है: OpenClaw के साथ भेजे गए बंडल किए गए Plugin, वैश्विक इंस्टॉल रूट (~/.openclaw/extensions), और वर्तमान कार्यस्थान रूट (<workspace>/.openclaw/extensions), साथ ही कोई भी स्पष्ट plugins.load.paths प्रविष्टियाँ।
यदि दो खोजों में समान id हो, तो केवल सर्वोच्च-प्राथमिकता वाला मैनिफ़ेस्ट रखा जाता है; निम्न-प्राथमिकता वाले डुप्लिकेट को साथ में लोड करने के बजाय हटा दिया जाता है। प्राथमिकता, सर्वोच्च से निम्नतम:
- कॉन्फ़िग द्वारा चयनित —
plugins.entries.<id>में स्पष्ट रूप से पिन किया गया पथ - ट्रैक किए गए इंस्टॉल रिकॉर्ड से मेल खाने वाला वैश्विक इंस्टॉल —
openclaw plugin install/openclaw plugin updateके माध्यम से इंस्टॉल किया गया ऐसा Plugin, जिसे OpenClaw की इंस्टॉल ट्रैकिंग उसी आईडी के लिए पहचानती है, भले ही वह आईडी किसी बंडल किए गए Plugin की भी हो - बंडल किया गया — OpenClaw के साथ भेजे गए Plugin
- कार्यस्थान — वर्तमान कार्यस्थान के सापेक्ष खोजे गए Plugin
- कोई अन्य खोजा गया उम्मीदवार
- कार्यस्थान या वैश्विक रूट में बिना ट्रैकिंग के मौजूद किसी बंडल किए गए Plugin की फ़ोर्क की गई या पुरानी प्रति, बंडल किए गए बिल्ड को प्रतिस्थापित नहीं करेगी।
- किसी बंडल किए गए Plugin को ओवरराइड करने के लिए, या तो उस आईडी के लिए
openclaw plugin installचलाएँ ताकि ट्रैक किया गया वैश्विक इंस्टॉल बंडल की गई प्रति से उच्च प्राथमिकता पाए, याplugins.entries.<id>के माध्यम से किसी विशिष्ट पथ को पिन करें ताकि वह कॉन्फ़िग द्वारा चयनित प्राथमिकता से विजयी हो। - डुप्लिकेट हटाए जाने को लॉग किया जाता है, ताकि डॉक्टर और स्टार्टअप निदान छोड़ी गई प्रति की ओर संकेत कर सकें।
- कॉन्फ़िग द्वारा चयनित डुप्लिकेट ओवरराइड को निदान में स्पष्ट ओवरराइड के रूप में लिखा जाता है, लेकिन फिर भी चेतावनी दी जाती है ताकि पुराने फ़ोर्क और आकस्मिक प्रतिस्थापन दिखाई देते रहें।
JSON Schema आवश्यकताएँ
- प्रत्येक Plugin को JSON Schema प्रदान करना आवश्यक है, भले ही वह कोई कॉन्फ़िग स्वीकार न करता हो।
- रिक्त स्कीमा स्वीकार्य है (उदाहरण के लिए,
{ "type": "object", "additionalProperties": false })। - स्कीमा का सत्यापन कॉन्फ़िग पढ़ने/लिखने के समय होता है, रनटाइम पर नहीं।
- किसी बंडल किए गए Plugin को नई कॉन्फ़िग कुंजियों के साथ विस्तारित या फ़ोर्क करते समय, उसी समय उस Plugin के
openclaw.plugin.jsonconfigSchemaको भी अपडेट करें। बंडल किए गए Plugin के स्कीमा सख्त होते हैं, इसलिएmyNewKeyकोconfigSchema.propertiesमें जोड़े बिना उपयोगकर्ता कॉन्फ़िग मेंplugins.entries.<id>.config.myNewKeyजोड़ने पर Plugin रनटाइम लोड होने से पहले ही उसे अस्वीकार कर दिया जाएगा।
सत्यापन व्यवहार
- अज्ञात
channels.*कुंजियाँ त्रुटियाँ हैं, जब तक चैनल आईडी किसी Plugin मैनिफ़ेस्ट द्वारा घोषित न हो। यदि वही आईडीplugins.allow,plugins.entries, याplugins.installs(ऐसा Plugin जिसका संदर्भ दिया गया है, लेकिन जो वर्तमान में खोजने योग्य नहीं है) में भी दिखाई देती है, तो OpenClaw इसके बजाय इसे घटाकर चेतावनी कर देता है। - अज्ञात Plugin आईडी का संदर्भ देने वाले
plugins.entries.<id>,plugins.allow, औरplugins.denyचेतावनियाँ (“पुरानी कॉन्फ़िग प्रविष्टि अनदेखी की गई”) हैं, त्रुटियाँ नहीं, ताकि अपग्रेड और हटाए गए/पुनःनामित Plugin Gateway स्टार्टअप को अवरुद्ध न करें। - अज्ञात Plugin आईडी का संदर्भ देने वाला
plugins.slots.memoryएक त्रुटि है, ज्ञातmemory-lancedbआधिकारिक बाहरी Plugin को छोड़कर, जिसके लिए इसके बजाय चेतावनी दी जाती है। - यदि कोई Plugin इंस्टॉल है, लेकिन उसका मैनिफ़ेस्ट या स्कीमा खराब अथवा अनुपलब्ध है, तो सत्यापन विफल हो जाता है और डॉक्टर Plugin त्रुटि की रिपोर्ट करता है।
- यदि Plugin कॉन्फ़िग मौजूद है, लेकिन Plugin अक्षम है, तो कॉन्फ़िग रखा जाता है और डॉक्टर + लॉग में एक चेतावनी दिखाई जाती है।
plugins.* स्कीमा के लिए कॉन्फ़िगरेशन संदर्भ देखें।
टिप्पणियाँ
- स्थानीय फ़ाइल सिस्टम लोड सहित, मूल OpenClaw Plugin के लिए मैनिफ़ेस्ट आवश्यक है। रनटाइम अब भी Plugin मॉड्यूल को अलग से लोड करता है; मैनिफ़ेस्ट केवल खोज + सत्यापन के लिए है।
- मूल मैनिफ़ेस्ट को JSON5 के साथ पार्स किया जाता है, इसलिए टिप्पणियाँ, अंतिम अल्पविराम और उद्धरण-रहित कुंजियाँ स्वीकार की जाती हैं, बशर्ते अंतिम मान अब भी एक ऑब्जेक्ट हो।
- मैनिफ़ेस्ट लोडर केवल दस्तावेजीकृत मैनिफ़ेस्ट फ़ील्ड पढ़ता है। कस्टम शीर्ष-स्तरीय कुंजियों से बचें।
- जब किसी Plugin को उनकी आवश्यकता न हो, तो
channels,providers,cliBackends, औरskillsसभी को छोड़ा जा सकता है। providerCatalogEntryहल्का रहना चाहिए और व्यापक रनटाइम कोड आयात नहीं करना चाहिए; इसका उपयोग स्थिर प्रदाता कैटलॉग मेटाडेटा या सीमित खोज विवरणकों के लिए करें, अनुरोध-समय निष्पादन के लिए नहीं।- विशिष्ट Plugin प्रकारों का चयन
plugins.slots.*के माध्यम से होता है:plugins.slots.memoryके माध्यम सेkind: "memory"(डिफ़ॉल्टmemory-core),plugins.slots.contextEngineके माध्यम सेkind: "context-engine"(डिफ़ॉल्टlegacy)। - इस मैनिफ़ेस्ट में विशिष्ट Plugin प्रकार घोषित करें। रनटाइम-प्रविष्टि
OpenClawPluginDefinition.kindअप्रचलित है और केवल पुराने Plugin के लिए संगतता फ़ॉलबैक के रूप में बनी हुई है। setup.providers[].envVarsमें पर्यावरण-चर मेटाडेटा केवल घोषणात्मक है। स्थिति, ऑडिट, Cron डिलीवरी सत्यापन और अन्य केवल-पठन सतहें किसी पर्यावरण चर को कॉन्फ़िगर किया हुआ मानने से पहले अब भी Plugin विश्वास और प्रभावी सक्रियण नीति लागू करती हैं।- प्रदाता कोड की आवश्यकता वाले रनटाइम विज़ार्ड मेटाडेटा के लिए, प्रदाता रनटाइम हुक देखें।
- यदि आपका Plugin मूल मॉड्यूल पर निर्भर है, तो बिल्ड चरणों और पैकेज-मैनेजर अनुमति-सूची की किसी भी आवश्यकता का दस्तावेज़ीकरण करें (उदाहरण के लिए, pnpm
allow-build-scripts+pnpm rebuild <package>)।
संबंधित
Plugin बनाना
Plugin के साथ शुरुआत करना।
Plugin आर्किटेक्चर
आंतरिक आर्किटेक्चर और क्षमता मॉडल।
SDK अवलोकन
Plugin SDK संदर्भ और उपपथ आयात।