Plugin आंतरिक संरचना

यह OpenClaw Plugin सिस्टम के लिए गहन आर्किटेक्चर संदर्भ है। व्यावहारिक गाइड के लिए, नीचे दिए गए केंद्रित पेजों में से किसी एक से शुरू करें।

सार्वजनिक क्षमता मॉडल

क्षमताएं OpenClaw के भीतर सार्वजनिक native plugin मॉडल हैं। हर native OpenClaw Plugin एक या अधिक क्षमता प्रकारों के लिए register करता है:

बाहरी compatibility दृष्टिकोण

Capability मॉडल core में landed है और आज bundled/native Plugin द्वारा उपयोग किया जाता है, लेकिन external Plugin compatibility के लिए अभी भी "यह export किया गया है, इसलिए frozen है" से अधिक कड़ी कसौटी चाहिए।

Capability registration इच्छित दिशा है। संक्रमण के दौरान external Plugin के लिए Legacy hooks सबसे सुरक्षित no-breakage path बने रहते हैं। Exported helper subpaths सभी समान नहीं हैं — incidental helper exports की तुलना में संकीर्ण documented contracts को प्राथमिकता दें।

Plugin shapes

OpenClaw हर loaded Plugin को उसके actual registration behavior के आधार पर shape में वर्गीकृत करता है (सिर्फ static metadata के आधार पर नहीं):

किसी Plugin की shape और capability breakdown देखने के लिए openclaw plugins inspect <id> का उपयोग करें। विवरण के लिए CLI संदर्भ देखें।

Legacy hooks

before_agent_start hook hook-only Plugin के लिए compatibility path के रूप में supported रहता है। Legacy real-world Plugin अभी भी इस पर निर्भर हैं।

दिशा:

• इसे काम करते रहने दें
• इसे legacy के रूप में document करें
• model/provider override work के लिए before_model_resolve को प्राथमिकता दें
• prompt mutation work के लिए before_prompt_build को प्राथमिकता दें
• केवल तब हटाएं जब वास्तविक उपयोग घट जाए और fixture coverage migration safety साबित करे

Compatibility signals

जब आप openclaw doctor या openclaw plugins inspect <id> चलाते हैं, तो आपको इनमें से कोई label दिख सकता है:

न तो hook-only और न ही before_agent_start आज आपके Plugin को तोड़ेगा: hook-only advisory है, और before_agent_start केवल warning trigger करता है। ये signals openclaw status --all और openclaw plugins doctor में भी दिखाई देते हैं।

Architecture अवलोकन

OpenClaw के Plugin सिस्टम में चार layers हैं:

विशेष रूप से Plugin CLI के लिए, root command discovery दो phases में split है:

• parse-time metadata registerCli(..., { descriptors: [...] }) से आता है
• वास्तविक Plugin CLI module lazy रह सकता है और first invocation पर register कर सकता है

इससे Plugin-owned CLI code Plugin के भीतर रहता है, जबकि OpenClaw parsing से पहले भी root command names reserve कर सकता है।

महत्वपूर्ण design boundary:

• manifest/config validation को Plugin code execute किए बिना manifest/schema metadata से काम करना चाहिए
• native capability discovery trusted Plugin entry code load करके non-activating registry snapshot बना सकता है
• native runtime behavior Plugin module के register(api) path से आता है, जहां api.registrationMode === "full"

यह split OpenClaw को full runtime active होने से पहले config validate करने, missing/disabled Plugin समझाने, और UI/schema hints बनाने देता है।

Plugin metadata snapshot और lookup table

Gateway startup मौजूदा config snapshot के लिए एक PluginMetadataSnapshot बनाता है। Snapshot metadata-only है: यह installed Plugin index, manifest registry, manifest diagnostics, owner maps, Plugin id normalizer, और manifest records store करता है। यह loaded Plugin modules, provider SDKs, package contents, या runtime exports नहीं रखता।

Plugin-aware config validation, startup auto-enable, और Gateway Plugin bootstrap उस snapshot को consume करते हैं, बजाय manifest/index metadata को independently rebuild करने के। PluginLookUpTable उसी snapshot से derive होता है और मौजूदा runtime config के लिए startup Plugin plan जोड़ता है।

Startup के बाद, Gateway मौजूदा metadata snapshot को replaceable runtime product के रूप में रखता है। Repeated runtime provider discovery हर provider-catalog pass के लिए installed index और manifest registry reconstruct करने के बजाय वह snapshot borrow कर सकता है। Gateway shutdown, config/Plugin inventory changes, और installed index writes पर snapshot cleared या replaced होता है; compatible current snapshot मौजूद न होने पर callers cold manifest/index path पर fall back करते हैं। Compatibility checks में plugins.load.paths और default agent workspace जैसे Plugin discovery roots शामिल होने चाहिए, क्योंकि workspace Plugin metadata scope का हिस्सा हैं।

Snapshot और lookup table repeated startup decisions को fast path पर रखते हैं:

• channel ownership
• deferred channel startup
• startup Plugin ids
• provider और CLI backend ownership
• setup provider, command alias, model catalog provider, और manifest contract ownership
• Plugin config schema और channel config schema validation
• startup auto-enable decisions

Safety boundary snapshot replacement है, mutation नहीं। Config, Plugin inventory, install records, या persisted index policy बदलने पर snapshot rebuild करें। इसे broad mutable global registry के रूप में न मानें, और unbounded historical snapshots न रखें। Runtime Plugin loading metadata snapshots से अलग रहता है ताकि stale runtime state metadata cache के पीछे hidden न हो सके।

Cache rule Plugin architecture internals में documented है: manifest और discovery metadata fresh होते हैं जब तक कोई caller मौजूदा flow के लिए explicit snapshot, lookup table, या manifest registry न रखता हो। Hidden metadata caches और wall-clock TTLs Plugin loading का हिस्सा नहीं हैं। केवल runtime loader, module, और dependency-artifact caches code या installed artifacts वास्तव में loaded होने के बाद persist रह सकते हैं।

कुछ cold-path callers अभी भी Gateway PluginLookUpTable पाने के बजाय persisted installed Plugin index से सीधे manifest registries reconstruct करते हैं। अब वह path registry को demand पर reconstruct करता है; जब caller के पास पहले से current lookup table या explicit manifest registry हो, तो runtime flows में उसे pass करना prefer करें।

Activation planning

Activation planning control plane का हिस्सा है। Callers broad runtime registries load करने से पहले पूछ सकते हैं कि किसी concrete command, provider, channel, route, agent harness, या capability के लिए कौन से Plugin relevant हैं।

Planner मौजूदा manifest behavior को compatible रखता है:

• activation.* फ़ील्ड स्पष्ट प्लानर संकेत हैं
• providers, channels, commandAliases, setup.providers, contracts.tools, और hooks मैनिफ़ेस्ट स्वामित्व फ़ॉलबैक बने रहते हैं
• केवल-ids प्लानर API मौजूदा कॉलरों के लिए उपलब्ध रहती है
• प्लान API कारण लेबल रिपोर्ट करता है ताकि डायग्नॉस्टिक्स स्पष्ट संकेतों को स्वामित्व फ़ॉलबैक से अलग कर सकें

चैनल Plugin और साझा message टूल

चैनल Plugin को सामान्य चैट कार्रवाइयों के लिए अलग send/edit/react टूल रजिस्टर करने की आवश्यकता नहीं है। OpenClaw core में एक साझा message टूल रखता है, और चैनल Plugin उसके पीछे चैनल-विशिष्ट खोज और निष्पादन के स्वामी होते हैं।

वर्तमान सीमा यह है:

• core साझा message टूल होस्ट, prompt wiring, session/thread bookkeeping, और execution dispatch का स्वामी है
• चैनल Plugin scoped action discovery, capability discovery, और किसी भी चैनल-विशिष्ट schema fragments के स्वामी हैं
• चैनल Plugin प्रदाता-विशिष्ट session conversation grammar के स्वामी हैं, जैसे conversation ids thread ids को कैसे encode करते हैं या parent conversations से कैसे inherit करते हैं
• चैनल Plugin अपने action adapter के माध्यम से अंतिम कार्रवाई निष्पादित करते हैं

चैनल Plugin के लिए, SDK surface ChannelMessageActionAdapter.describeMessageTool(...) है। वह एकीकृत discovery call Plugin को अपनी visible actions, capabilities, और schema contributions साथ में लौटाने देता है ताकि वे हिस्से अलग-अलग दिशा में न जाएं।

जब कोई चैनल-विशिष्ट message-tool param किसी स्थानीय path या remote media URL जैसे media source को रखता है, तो Plugin को describeMessageTool(...) से mediaSourceParams भी लौटाना चाहिए। Core उस स्पष्ट सूची का उपयोग sandbox path normalization और outbound media-access hints लागू करने के लिए करता है, बिना Plugin-owned param नामों को hardcode किए। वहां action-scoped maps को प्राथमिकता दें, न कि एक channel-wide flat list, ताकि profile-only media param असंबंधित actions जैसे send पर normalize न हो।

Core उस discovery step में runtime scope पास करता है। महत्वपूर्ण फ़ील्ड में शामिल हैं:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• विश्वसनीय inbound requesterSenderId

यह context-sensitive Plugin के लिए महत्वपूर्ण है। कोई चैनल active account, current room/thread/message, या trusted requester identity के आधार पर message actions छिपा या दिखा सकता है, बिना core message टूल में चैनल-विशिष्ट branches को hardcode किए।

इसीलिए embedded-runner routing बदलाव अभी भी Plugin कार्य हैं: runner की ज़िम्मेदारी है कि वह current chat/session identity को Plugin discovery boundary में forward करे ताकि साझा message टूल वर्तमान turn के लिए सही channel-owned surface expose करे।

Channel-owned execution helpers के लिए, bundled Plugin को execution runtime अपने extension modules के अंदर ही रखना चाहिए। Core अब src/agents/tools के अंतर्गत Discord, Slack, Telegram, या WhatsApp message-action runtimes का स्वामी नहीं है। हम अलग plugin-sdk/*-action-runtime subpaths publish नहीं करते, और bundled Plugin को अपने extension-owned modules से अपना local runtime code सीधे import करना चाहिए।

यही सीमा सामान्य रूप से provider-named SDK seams पर लागू होती है: core को Slack, Discord, Signal, WhatsApp, या समान extensions के लिए channel-specific convenience barrels import नहीं करने चाहिए। यदि core को किसी behavior की आवश्यकता है, तो या तो bundled Plugin के अपने api.ts / runtime-api.ts barrel का उपयोग करें या आवश्यकता को shared SDK में एक संकीर्ण generic capability में promote करें।

Bundled Plugin भी यही नियम अपनाते हैं। किसी bundled Plugin के runtime-api.ts को अपने ही branded openclaw/plugin-sdk/<plugin-id> facade को re-export नहीं करना चाहिए। वे branded facades external Plugin और पुराने consumers के लिए compatibility shims बने रहते हैं, लेकिन bundled Plugin को local exports और openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store, या openclaw/plugin-sdk/webhook-ingress जैसे संकीर्ण generic SDK subpaths का उपयोग करना चाहिए। नया code plugin-id-specific SDK facades नहीं जोड़ना चाहिए, जब तक किसी मौजूदा external ecosystem की compatibility boundary इसकी मांग न करे।

Polls के लिए विशेष रूप से, दो execution paths हैं:

• outbound.sendPoll उन चैनलों के लिए साझा baseline है जो common poll model में फिट होते हैं
• actions.handleAction("poll") channel-specific poll semantics या अतिरिक्त poll parameters के लिए preferred path है

Core अब shared poll parsing को तब तक defer करता है जब तक Plugin poll dispatch कार्रवाई को decline नहीं कर देता, ताकि Plugin-owned poll handlers generic poll parser से पहले blocked हुए बिना channel-specific poll fields स्वीकार कर सकें।

पूरा startup sequence देखने के लिए Plugin architecture internals देखें।

क्षमता स्वामित्व मॉडल

OpenClaw native Plugin को किसी कंपनी या feature के लिए ownership boundary मानता है, असंबंधित integrations का संग्रह नहीं।

इसका मतलब है:

• company Plugin को आमतौर पर उस कंपनी के सभी OpenClaw-facing surfaces का स्वामी होना चाहिए
• feature Plugin को आमतौर पर अपने द्वारा पेश किए गए पूरे feature surface का स्वामी होना चाहिए
• channels को provider behavior को ad hoc फिर से लागू करने के बजाय shared core capabilities का उपयोग करना चाहिए

इच्छित अंतिम स्थिति यह है:

• OpenAI एक ही Plugin में रहता है, भले ही वह text models, speech, images, और future video तक फैला हो
• दूसरा vendor अपने surface area के लिए ऐसा ही कर सकता है
• channels को इस बात की परवाह नहीं होती कि provider का स्वामी कौन-सा vendor Plugin है; वे core द्वारा expose किए गए shared capability contract का उपयोग करते हैं

मुख्य अंतर यह है:

• Plugin = ownership boundary
• capability = core contract जिसे कई Plugin implement या consume कर सकते हैं

इसलिए यदि OpenClaw video जैसा नया domain जोड़ता है, तो पहला प्रश्न यह नहीं है कि "किस provider को video handling hardcode करनी चाहिए?" पहला प्रश्न यह है कि "core video capability contract क्या है?" जब वह contract मौजूद हो जाता है, vendor Plugin उसके विरुद्ध register कर सकते हैं और channel/feature Plugin उसका उपयोग कर सकते हैं।

यदि capability अभी मौजूद नहीं है, तो सही कदम आमतौर पर यह है:

यह स्वामित्व को स्पष्ट रखता है और ऐसे core behavior से बचाता है जो किसी एक vendor या one-off plugin-specific code path पर निर्भर हो।

क्षमता layering

Code कहां होना चाहिए, यह तय करते समय इस mental model का उपयोग करें:

उदाहरण के लिए, TTS यह shape अपनाता है:

• core reply-time TTS policy, fallback order, prefs, और channel delivery का स्वामी है
• openai, elevenlabs, और microsoft synthesis implementations के स्वामी हैं
• voice-call telephony TTS runtime helper का उपयोग करता है

Future capabilities के लिए भी इसी pattern को प्राथमिकता दी जानी चाहिए।

Multi-capability company Plugin उदाहरण

Company Plugin को बाहर से cohesive महसूस होना चाहिए। यदि OpenClaw के पास models, speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch, और web search के लिए shared contracts हैं, तो कोई vendor अपने सभी surfaces का स्वामी एक ही जगह हो सकता है:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          provider: "exampleai",          model: req.model,          input: req.input,        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          provider: "exampleai",          model: req.model,          input: req.input,        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

महत्व exact helper names का नहीं है। Shape मायने रखता है:

• एक Plugin vendor surface का स्वामी है
• core फिर भी capability contracts का स्वामी है
• channels और feature Plugin api.runtime.* helpers का उपयोग करते हैं, vendor code का नहीं
• contract tests assert कर सकते हैं कि Plugin ने वे capabilities register की हैं जिनका वह स्वामी होने का दावा करता है

क्षमता उदाहरण: video understanding

OpenClaw पहले से image/audio/video understanding को एक साझा capability मानता है। वही ownership model वहां लागू होता है:

यह core में किसी एक provider की video assumptions bake करने से बचाता है। Plugin vendor surface का स्वामी है; core capability contract और fallback behavior का स्वामी है।

Video generation पहले से इसी sequence का उपयोग करता है: core typed capability contract और runtime helper का स्वामी है, और vendor Plugin उसके विरुद्ध api.registerVideoGenerationProvider(...) implementations register करते हैं।

Concrete rollout checklist चाहिए? Capability Cookbook देखें।

Contracts और enforcement

Plugin API surface जानबूझकर OpenClawPluginApi में typed और centralized है। वह contract supported registration points और runtime helpers define करता है जिन पर कोई Plugin भरोसा कर सकता है।

यह क्यों महत्वपूर्ण है:

• Plugin authors को एक stable internal standard मिलता है
• core duplicate ownership को reject कर सकता है, जैसे दो Plugin का same provider id register करना
• startup malformed registration के लिए actionable diagnostics surface कर सकता है
• contract tests bundled-plugin ownership enforce कर सकते हैं और silent drift रोक सकते हैं

Enforcement की दो layers हैं:

व्यावहारिक प्रभाव यह है कि OpenClaw पहले से जानता है कि कौन सा Plugin किस सतह का स्वामी है। इससे कोर और चैनल सहजता से संयोजित हो पाते हैं, क्योंकि स्वामित्व अंतर्निहित होने के बजाय घोषित, टाइप किया हुआ, और परीक्षण योग्य होता है।

अनुबंध में क्या होना चाहिए

संदेह होने पर, अमूर्तन स्तर बढ़ाएँ: पहले क्षमता परिभाषित करें, फिर Plugins को उसमें प्लग इन करने दें।

निष्पादन मॉडल

नेटिव OpenClaw Plugins Gateway के साथ इन-प्रोसेस चलते हैं। वे सैंडबॉक्स्ड नहीं होते। लोड किए गए नेटिव Plugin की प्रक्रिया-स्तरीय विश्वास सीमा कोर कोड जैसी ही होती है।

संगत बंडल डिफॉल्ट रूप से अधिक सुरक्षित होते हैं, क्योंकि OpenClaw वर्तमान में उन्हें मेटाडेटा/कंटेंट पैक मानता है। मौजूदा रिलीज में, इसका अर्थ मुख्य रूप से बंडल किए गए Skills है।

बंडल में शामिल नहीं किए गए Plugins के लिए अनुमति-सूचियों और स्पष्ट install/load पथों का उपयोग करें। वर्कस्पेस Plugins को विकास-समय का कोड मानें, उत्पादन डिफॉल्ट नहीं।

बंडल किए गए वर्कस्पेस पैकेज नामों के लिए, Plugin id को npm नाम में एंकर रखें: डिफॉल्ट रूप से @openclaw/<id>, या स्वीकृत टाइप किया हुआ suffix जैसे -provider, -plugin, -speech, -sandbox, या -media-understanding जब पैकेज जानबूझकर संकीर्ण Plugin भूमिका उजागर करता है।

निर्यात सीमा

OpenClaw क्षमताएँ निर्यात करता है, इम्प्लीमेंटेशन सुविधा नहीं।

क्षमता पंजीकरण को सार्वजनिक रखें। गैर-अनुबंध helper exports को कम करें:

• बंडल किए गए Plugin-विशिष्ट helper subpaths
• रनटाइम plumbing subpaths जो सार्वजनिक API के रूप में अभिप्रेत नहीं हैं
• वेंडर-विशिष्ट सुविधा helpers
• setup/onboarding helpers जो इम्प्लीमेंटेशन विवरण हैं

आरक्षित बंडल किए गए Plugin helper subpaths को जनरेट किए गए SDK export map से हटा दिया गया है। स्वामी-विशिष्ट helpers को स्वामी Plugin package के अंदर रखें; केवल पुन: उपयोग योग्य host व्यवहार को generic SDK अनुबंधों जैसे plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, और plugin-sdk/plugin-config-runtime में promote करें।

आंतरिक विवरण और संदर्भ

लोड pipeline, रजिस्ट्री मॉडल, प्रोवाइडर रनटाइम hooks, Gateway HTTP routes, message tool schemas, channel target resolution, provider catalogs, context engine plugins, और नई क्षमता जोड़ने की गाइड के लिए, Plugin architecture internals देखें।

संबंधित

• Plugins बनाना
• Plugin manifest
• Plugin SDK setup