package.json मेटाडेटा), मैनिफेस्ट (openclaw.plugin.json), सेटअप एंट्री, और कॉन्फ़िग स्कीमा के लिए संदर्भ।
पैकेज मेटाडेटा
आपकेpackage.json को एक openclaw फ़ील्ड चाहिए जो Plugin सिस्टम को बताता है कि आपका Plugin क्या उपलब्ध कराता है:
- Channel plugin
- Provider plugin / ClawHub baseline
यदि आप Plugin को ClawHub पर बाहरी रूप से प्रकाशित करते हैं, तो वे
compat और build फ़ील्ड आवश्यक हैं। कैननिकल प्रकाशन स्निपेट docs/snippets/plugin-publish/ में हैं।openclaw फ़ील्ड
एंट्री पॉइंट फ़ाइलें (पैकेज रूट के सापेक्ष)।
हल्की सेटअप-केवल एंट्री (वैकल्पिक)।
सेटअप, पिकर, क्विकस्टार्ट, और स्थिति सतहों के लिए चैनल कैटलॉग मेटाडेटा।
इस Plugin द्वारा पंजीकृत प्रदाता आईडी।
इंस्टॉल संकेत:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery।स्टार्टअप व्यवहार फ़्लैग।
openclaw.channel
openclaw.channel रनटाइम लोड होने से पहले चैनल खोज और सेटअप सतहों के लिए सस्ता पैकेज मेटाडेटा है।
| फ़ील्ड | प्रकार | इसका अर्थ |
|---|---|---|
id | string | कैननिकल चैनल आईडी। |
label | string | प्राथमिक चैनल लेबल। |
selectionLabel | string | पिकर/सेटअप लेबल, जब यह label से अलग होना चाहिए। |
detailLabel | string | अधिक समृद्ध चैनल कैटलॉग और स्थिति सतहों के लिए द्वितीयक विवरण लेबल। |
docsPath | string | सेटअप और चयन लिंक के लिए दस्तावेज़ पथ। |
docsLabel | string | दस्तावेज़ लिंक के लिए इस्तेमाल किया गया ओवरराइड लेबल, जब यह चैनल आईडी से अलग होना चाहिए। |
blurb | string | छोटा ऑनबोर्डिंग/कैटलॉग विवरण। |
order | number | चैनल कैटलॉग में क्रम। |
aliases | string[] | चैनल चयन के लिए अतिरिक्त लुकअप उपनाम। |
preferOver | string[] | कम-प्राथमिकता वाले Plugin/चैनल आईडी जिनसे इस चैनल को ऊपर रैंक करना चाहिए। |
systemImage | string | चैनल UI कैटलॉग के लिए वैकल्पिक आइकन/सिस्टम-इमेज नाम। |
selectionDocsPrefix | string | चयन सतहों में दस्तावेज़ लिंक से पहले का उपसर्ग टेक्स्ट। |
selectionDocsOmitLabel | boolean | चयन कॉपी में लेबल वाले दस्तावेज़ लिंक के बजाय दस्तावेज़ पथ सीधे दिखाएँ। |
selectionExtras | string[] | चयन कॉपी में जोड़ी गई अतिरिक्त छोटी स्ट्रिंग। |
markdownCapable | boolean | आउटबाउंड फ़ॉर्मैटिंग निर्णयों के लिए चैनल को मार्कडाउन-सक्षम चिह्नित करता है। |
exposure | object | सेटअप, कॉन्फ़िगर की गई सूचियों, और दस्तावेज़ सतहों के लिए चैनल दृश्यता नियंत्रण। |
quickstartAllowFrom | boolean | इस चैनल को मानक क्विकस्टार्ट allowFrom सेटअप फ़्लो में शामिल करें। |
forceAccountBinding | boolean | केवल एक खाता मौजूद होने पर भी स्पष्ट खाता बाइंडिंग आवश्यक करें। |
preferSessionLookupForAnnounceTarget | boolean | इस चैनल के लिए घोषणा लक्ष्य हल करते समय सत्र लुकअप को प्राथमिकता दें। |
exposure समर्थन करता है:
configured: चैनल को कॉन्फ़िगर की गई/स्थिति-शैली सूची सतहों में शामिल करेंsetup: चैनल को इंटरैक्टिव सेटअप/कॉन्फ़िगर पिकर में शामिल करेंdocs: चैनल को दस्तावेज़/नेविगेशन सतहों में सार्वजनिक-फेसिंग के रूप में चिह्नित करें
showConfigured और showInSetup लेगेसी उपनामों के रूप में समर्थित रहते हैं। exposure को प्राथमिकता दें।openclaw.install
openclaw.install पैकेज मेटाडेटा है, मैनिफेस्ट मेटाडेटा नहीं।
| फ़ील्ड | प्रकार | इसका अर्थ |
|---|---|---|
clawhubSpec | string | इंस्टॉल/अपडेट और ऑनबोर्डिंग इंस्टॉल-ऑन-डिमांड फ़्लो के लिए कैननिकल ClawHub स्पेक। |
npmSpec | string | इंस्टॉल/अपडेट फ़ॉलबैक फ़्लो के लिए कैननिकल npm स्पेक। |
localPath | string | स्थानीय विकास या बंडल किया गया इंस्टॉल पथ। |
defaultChoice | "clawhub" | "npm" | "local" | जब कई स्रोत उपलब्ध हों तो पसंदीदा इंस्टॉल स्रोत। |
minHostVersion | string | >=x.y.z या >=x.y.z-prerelease के रूप में न्यूनतम समर्थित OpenClaw संस्करण। |
expectedIntegrity | string | पिन किए गए इंस्टॉल के लिए अपेक्षित npm डिस्ट इंटीग्रिटी स्ट्रिंग, आमतौर पर sha512-...। |
allowInvalidConfigRecovery | boolean | बंडल किए गए-Plugin रीइंस्टॉल फ़्लो को विशिष्ट पुराने-कॉन्फ़िग विफलताओं से रिकवर करने देता है। |
requiredPlatformPackages | string[] | npm इंस्टॉल के दौरान सत्यापित आवश्यक प्लेटफ़ॉर्म-विशिष्ट npm उपनाम। |
Onboarding behavior
Onboarding behavior
इंटरैक्टिव ऑनबोर्डिंग इंस्टॉल-ऑन-डिमांड सतहों के लिए भी
openclaw.install का उपयोग करती है। यदि आपका Plugin रनटाइम लोड होने से पहले प्रदाता ऑथ विकल्प या चैनल सेटअप/कैटलॉग मेटाडेटा एक्सपोज़ करता है, तो ऑनबोर्डिंग वह विकल्प दिखा सकती है, ClawHub, npm, या स्थानीय इंस्टॉल के लिए पूछ सकती है, Plugin को इंस्टॉल या सक्षम कर सकती है, फिर चयनित फ़्लो जारी रख सकती है। ClawHub ऑनबोर्डिंग विकल्प clawhubSpec का उपयोग करते हैं और मौजूद होने पर प्राथमिकता पाते हैं; npm विकल्पों के लिए रजिस्ट्री npmSpec के साथ भरोसेमंद कैटलॉग मेटाडेटा चाहिए; सटीक संस्करण और expectedIntegrity वैकल्पिक npm पिन हैं। यदि expectedIntegrity मौजूद है, तो इंस्टॉल/अपडेट फ़्लो इसे npm के लिए लागू करते हैं। “क्या दिखाना है” मेटाडेटा openclaw.plugin.json में और “इसे कैसे इंस्टॉल करना है” मेटाडेटा package.json में रखें।minHostVersion enforcement
minHostVersion enforcement
यदि
minHostVersion सेट है, तो इंस्टॉल और गैर-बंडल मैनिफेस्ट-रजिस्ट्री लोडिंग दोनों इसे लागू करते हैं। पुराने होस्ट बाहरी Plugins को छोड़ देते हैं; अमान्य संस्करण स्ट्रिंग अस्वीकार कर दी जाती हैं। बंडल किए गए स्रोत Plugins को होस्ट चेकआउट के साथ समान-संस्करण माना जाता है।Pinned npm installs
Pinned npm installs
पिन किए गए npm इंस्टॉल के लिए, सटीक संस्करण
npmSpec में रखें और अपेक्षित आर्टिफैक्ट इंटीग्रिटी जोड़ें:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery टूटे हुए कॉन्फ़िग के लिए सामान्य बाइपास नहीं है। यह केवल संकीर्ण बंडल किए गए-Plugin रिकवरी के लिए है, ताकि रीइंस्टॉल/सेटअप उसी Plugin के लिए गायब बंडल किए गए Plugin पथ या पुराने channels.<id> एंट्री जैसे ज्ञात अपग्रेड अवशेषों की मरम्मत कर सके। यदि कॉन्फ़िग असंबंधित कारणों से टूटा है, तो इंस्टॉल फिर भी बंद होकर विफल होता है और ऑपरेटर को openclaw doctor --fix चलाने को कहता है।विलंबित पूर्ण लोड
चैनल Plugins विलंबित लोडिंग को इस तरह ऑप्ट इन कर सकते हैं:setupEntry लोड करता है, यहां तक कि पहले से कॉन्फ़िगर किए गए चैनलों के लिए भी। पूर्ण एंट्री gateway के सुनना शुरू करने के बाद लोड होती है।
यदि आपकी सेटअप/पूर्ण एंट्री gateway RPC मेथड पंजीकृत करती है, तो उन्हें Plugin-विशिष्ट उपसर्ग पर रखें। आरक्षित कोर एडमिन नेमस्पेस (config.*, exec.approvals.*, wizard.*, update.*) कोर-स्वामित्व में रहते हैं और हमेशा operator.admin पर हल होते हैं।
Plugin मैनिफेस्ट
हर नेटिव Plugin को पैकेज रूट में एकopenclaw.plugin.json शिप करना होगा। OpenClaw इसका उपयोग Plugin कोड चलाए बिना कॉन्फ़िग सत्यापित करने के लिए करता है।
kind और channels जोड़ें:
ClawHub प्रकाशन
Plugin पैकेजों के लिए, पैकेज-विशिष्ट ClawHub कमांड का उपयोग करें:पुराना केवल-Skills प्रकाशन उपनाम Skills के लिए है। Plugin पैकेजों को हमेशा
clawhub package publish का उपयोग करना चाहिए।सेटअप एंट्री
setup-entry.ts फ़ाइल index.ts का हल्का विकल्प है, जिसे OpenClaw तब लोड करता है जब उसे केवल सेटअप सतहों की आवश्यकता होती है (ऑनबोर्डिंग, कॉन्फ़िग मरम्मत, अक्षम चैनल निरीक्षण)।
defineSetupPluginEntry(...) के बजाय openclaw/plugin-sdk/channel-entry-contract से defineBundledChannelSetupEntry(...) का उपयोग कर सकते हैं। वह बंडल अनुबंध एक वैकल्पिक runtime निर्यात का भी समर्थन करता है, ताकि सेटअप-समय रनटाइम वायरिंग हल्की और स्पष्ट रह सके।
जब OpenClaw पूर्ण एंट्री के बजाय setupEntry का उपयोग करता है
जब OpenClaw पूर्ण एंट्री के बजाय setupEntry का उपयोग करता है
- चैनल अक्षम है, लेकिन उसे सेटअप/ऑनबोर्डिंग सतहों की आवश्यकता है।
- चैनल सक्षम है, लेकिन कॉन्फ़िगर नहीं किया गया है।
- विलंबित लोडिंग सक्षम है (
deferConfiguredChannelFullLoadUntilAfterListen)।
setupEntry को क्या पंजीकृत करना चाहिए
setupEntry को क्या पंजीकृत करना चाहिए
- चैनल Plugin ऑब्जेक्ट (
defineSetupPluginEntryके माध्यम से)। - Gateway listen से पहले आवश्यक कोई भी HTTP रूट।
- स्टार्टअप के दौरान आवश्यक कोई भी Gateway मेथड।
config.* या update.* जैसे आरक्षित कोर एडमिन नेमस्पेस से बचना चाहिए।setupEntry में क्या शामिल नहीं होना चाहिए
setupEntry में क्या शामिल नहीं होना चाहिए
- CLI पंजीकरण।
- पृष्ठभूमि सेवाएँ।
- भारी रनटाइम इंपोर्ट (क्रिप्टो, SDKs)।
- केवल स्टार्टअप के बाद आवश्यक Gateway मेथड।
संकीर्ण सेटअप हेल्पर इंपोर्ट
हॉट सेटअप-केवल पाथ के लिए, जब आपको सेटअप सतह के केवल एक भाग की आवश्यकता हो, तो व्यापकplugin-sdk/setup अम्ब्रेला के बजाय संकीर्ण सेटअप हेल्पर सीम को प्राथमिकता दें:
| इंपोर्ट पाथ | इसका उपयोग किसके लिए करें | मुख्य निर्यात |
|---|---|---|
plugin-sdk/setup-runtime | सेटअप-समय रनटाइम हेल्पर जो setupEntry / विलंबित चैनल स्टार्टअप में उपलब्ध रहते हैं | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | अप्रचलित संगतता उपनाम; plugin-sdk/setup-runtime का उपयोग करें | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | सेटअप/इंस्टॉल CLI/आर्काइव/दस्तावेज़ हेल्पर | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
moveSingleAccountChannelSectionToDefaultAccount(...) जैसे कॉन्फ़िग-पैच हेल्पर शामिल हों, तो व्यापक plugin-sdk/setup सीम का उपयोग करें।
स्थिर सेटअप विज़ार्ड कॉपी के लिए createSetupTranslator(...) का उपयोग करें। यह
CLI विज़ार्ड लोकेल (OPENCLAW_LOCALE, फिर सिस्टम लोकेल वेरिएबल) का पालन करता है और
अंग्रेज़ी पर वापस जाता है। Plugin-विशिष्ट सेटअप टेक्स्ट को Plugin-स्वामित्व वाले कोड में रखें और
साझा कैटलॉग कुंजियों का उपयोग केवल सामान्य सेटअप लेबल, स्थिति टेक्स्ट, और आधिकारिक
बंडल किए गए Plugin सेटअप कॉपी के लिए करें।
सेटअप पैच अडैप्टर इंपोर्ट पर हॉट-पाथ सुरक्षित रहते हैं। उनका बंडल किया गया एकल-अकाउंट प्रमोशन अनुबंध-सतह लुकअप आलसी है, इसलिए plugin-sdk/setup-runtime इंपोर्ट करने से अडैप्टर के वास्तव में उपयोग होने से पहले बंडल अनुबंध-सतह डिस्कवरी तुरंत लोड नहीं होती।
चैनल-स्वामित्व वाला एकल-अकाउंट प्रमोशन
जब कोई चैनल एकल-अकाउंट टॉप-लेवल कॉन्फ़िग सेchannels.<id>.accounts.* में अपग्रेड करता है, तो डिफ़ॉल्ट साझा व्यवहार प्रमोट किए गए अकाउंट-स्कोप्ड मानों को accounts.default में ले जाना है।
बंडल किए गए चैनल अपने सेटअप अनुबंध सतह के माध्यम से उस प्रमोशन को संकीर्ण या ओवरराइड कर सकते हैं:
singleAccountKeysToMove: अतिरिक्त टॉप-लेवल कुंजियाँ जिन्हें प्रमोट किए गए अकाउंट में जाना चाहिएnamedAccountPromotionKeys: जब नामित अकाउंट पहले से मौजूद हों, तो केवल ये कुंजियाँ प्रमोट किए गए अकाउंट में जाती हैं; साझा नीति/डिलीवरी कुंजियाँ चैनल रूट पर रहती हैंresolveSingleAccountPromotionTarget(...): चुनें कि कौन सा मौजूदा अकाउंट प्रमोट किए गए मान प्राप्त करता है
Matrix वर्तमान बंडल उदाहरण है। यदि ठीक एक नामित Matrix अकाउंट पहले से मौजूद है, या यदि
defaultAccount Ops जैसी मौजूदा गैर-कैनोनिकल कुंजी की ओर इशारा करता है, तो प्रमोशन नया accounts.default एंट्री बनाने के बजाय उस अकाउंट को संरक्षित रखता है।कॉन्फ़िग स्कीमा
Plugin कॉन्फ़िग आपके मैनिफ़ेस्ट में JSON Schema के विरुद्ध वैलिडेट किया जाता है। उपयोगकर्ता Plugin को इसके माध्यम से कॉन्फ़िगर करते हैं:api.pluginConfig के रूप में प्राप्त करता है।
चैनल-विशिष्ट कॉन्फ़िग के लिए, इसके बजाय चैनल कॉन्फ़िग सेक्शन का उपयोग करें:
चैनल कॉन्फ़िग स्कीमा बनाना
Plugin-स्वामित्व वाले कॉन्फ़िग आर्टिफ़ैक्ट द्वारा उपयोग किए जाने वालेChannelConfigSchema रैपर में Zod स्कीमा बदलने के लिए buildChannelConfigSchema का उपयोग करें:
openclaw.plugin.json#channelConfigs में मिरर करें, ताकि कॉन्फ़िग स्कीमा, सेटअप, और UI सतहें रनटाइम कोड लोड किए बिना channels.<id> का निरीक्षण कर सकें।
सेटअप विज़ार्ड
चैनल Pluginopenclaw onboard के लिए इंटरैक्टिव सेटअप विज़ार्ड दे सकते हैं। विज़ार्ड ChannelPlugin पर एक ChannelSetupWizard ऑब्जेक्ट होता है:
ChannelSetupWizard प्रकार credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, और अन्य का समर्थन करता है। पूर्ण उदाहरणों के लिए बंडल किए गए Plugin पैकेज देखें (उदाहरण के लिए Discord Plugin src/channel.setup.ts)।
साझा allowFrom प्रॉम्प्ट
साझा allowFrom प्रॉम्प्ट
DM अलाउलिस्ट प्रॉम्प्ट के लिए जिन्हें केवल मानक
note -> prompt -> parse -> merge -> patch फ़्लो की आवश्यकता होती है, openclaw/plugin-sdk/setup से साझा सेटअप हेल्पर को प्राथमिकता दें: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...), और createNestedChannelParsedAllowFromPrompt(...)।मानक चैनल सेटअप स्थिति
मानक चैनल सेटअप स्थिति
चैनल सेटअप स्थिति ब्लॉक के लिए जो केवल लेबल, स्कोर, और वैकल्पिक अतिरिक्त पंक्तियों से बदलते हैं, हर Plugin में वही
status ऑब्जेक्ट हाथ से बनाने के बजाय openclaw/plugin-sdk/setup से createStandardChannelSetupStatus(...) को प्राथमिकता दें।वैकल्पिक चैनल सेटअप सतह
वैकल्पिक चैनल सेटअप सतह
वैकल्पिक सेटअप सतहों के लिए जो केवल कुछ संदर्भों में दिखनी चाहिए, जब आपको उस वैकल्पिक-इंस्टॉल सतह के केवल एक हिस्से की आवश्यकता हो, तो
openclaw/plugin-sdk/channel-setup से createOptionalChannelSetupSurface का उपयोग करें:plugin-sdk/channel-setup निम्न-स्तरीय createOptionalChannelSetupAdapter(...) और createOptionalChannelSetupWizard(...) बिल्डर भी उपलब्ध कराता है।जनरेट किए गए वैकल्पिक अडैप्टर/विज़ार्ड वास्तविक कॉन्फ़िग राइट पर fail closed करते हैं। वे validateInput, applyAccountConfig, और finalize में एक ही install-required संदेश का पुनः उपयोग करते हैं, और docsPath सेट होने पर दस्तावेज़ लिंक जोड़ते हैं।बाइनरी-समर्थित सेटअप हेल्पर
बाइनरी-समर्थित सेटअप हेल्पर
बाइनरी-समर्थित सेटअप UI के लिए, हर चैनल में वही बाइनरी/स्थिति glue कॉपी करने के बजाय साझा प्रत्यायोजित हेल्पर को प्राथमिकता दें:
createDetectedBinaryStatus(...)उन स्थिति ब्लॉक के लिए जो केवल लेबल, संकेत, स्कोर, और बाइनरी डिटेक्शन से बदलते हैंcreateCliPathTextInput(...)पाथ-समर्थित टेक्स्ट इनपुट के लिएcreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...), औरcreateDelegatedResolveConfigured(...)जबsetupEntryको आलसी रूप से किसी भारी पूर्ण विज़ार्ड को फ़ॉरवर्ड करना होcreateDelegatedTextInputShouldPrompt(...)जबsetupEntryको केवलtextInputs[*].shouldPromptनिर्णय प्रत्यायोजित करना हो
प्रकाशित करना और इंस्टॉल करना
बाहरी Plugin: ClawHub पर प्रकाशित करें, फिर इंस्टॉल करें:- npm
- केवल ClawHub
- npm पैकेज स्पेक
npm-स्रोत वाले इंस्टॉल के लिए,
openclaw plugins install पैकेज को ~/.openclaw/npm/projects के अंतर्गत प्रति-Plugin प्रोजेक्ट में इंस्टॉल करता है, जिसमें लाइफसाइकल स्क्रिप्ट अक्षम रहती हैं। Plugin निर्भरता ट्री को शुद्ध JS/TS रखें और ऐसे पैकेजों से बचें जिन्हें postinstall बिल्ड की आवश्यकता होती है।Gateway स्टार्टअप Plugin निर्भरताएं इंस्टॉल नहीं करता। npm/git/ClawHub इंस्टॉल फ्लो निर्भरता अभिसरण के स्वामी हैं; स्थानीय Plugin की निर्भरताएं पहले से इंस्टॉल होनी चाहिए।
संबंधित
- Plugin बनाना — शुरू करने के लिए चरण-दर-चरण गाइड
- Plugin मेनिफेस्ट — पूरा मेनिफेस्ट स्कीमा संदर्भ
- SDK एंट्री पॉइंट —
definePluginEntryऔरdefineChannelPluginEntry