Plugin SDK का अवलोकन

Plugin SDK, plugins और core के बीच टाइप किया हुआ अनुबंध है। यह पृष्ठ क्या इम्पोर्ट करना है और आप क्या पंजीकृत कर सकते हैं का संदर्भ है।

इम्पोर्ट परंपरा

हमेशा किसी विशिष्ट सबपाथ से इम्पोर्ट करें:

प्रत्येक सबपाथ एक छोटा, स्व-निहित मॉड्यूल है। इससे स्टार्टअप तेज़ रहता है और चक्रीय निर्भरता संबंधी समस्याएँ रुकती हैं। चैनल-विशिष्ट एंट्री/बिल्ड सहायकों के लिए, openclaw/plugin-sdk/channel-core को प्राथमिकता दें; व्यापक समग्र सतह और buildChannelConfigSchema जैसे साझा सहायकों के लिए openclaw/plugin-sdk/core रखें।

चैनल कॉन्फ़िगरेशन के लिए, चैनल के स्वामित्व वाला JSON Schema openclaw.plugin.json#channelConfigs के माध्यम से प्रकाशित करें। plugin-sdk/channel-config-schema सबपाथ साझा स्कीमा प्रिमिटिव और जेनेरिक बिल्डर के लिए है। OpenClaw के बंडल किए गए plugins, बनाए रखे गए बंडल-चैनल स्कीमा के लिए plugin-sdk/bundled-channel-config-schema का उपयोग करते हैं। वह बंडल स्कीमा सबपाथ नए plugins के लिए प्रतिमान नहीं है।

सबपाथ संदर्भ

Plugin SDK को क्षेत्र के अनुसार समूहित सीमित सबपाथ के समूह के रूप में उपलब्ध कराया गया है (Plugin एंट्री, चैनल, प्रदाता, प्रमाणीकरण, रनटाइम, क्षमता, मेमोरी और आरक्षित बंडल-Plugin सहायक)। समूहित और लिंक की गई पूरी सूची के लिए Plugin SDK सबपाथ देखें।

कंपाइलर एंट्रीपॉइंट सूची scripts/lib/plugin-sdk-entrypoints.json में रहती है; टाइप किए हुए सार्वजनिक एक्सपोर्ट में scripts/lib/plugin-sdk-private-local-only-subpaths.json में सूचीबद्ध आंतरिक सबपाथ शामिल नहीं होते। उस सूची की प्रोडक्शन एंट्रियाँ अलग से प्रकाशित आधिकारिक plugins के लिए केवल-JavaScript होस्ट रनटाइम एक्सपोर्ट बनाए रखती हैं, जबकि केवल-परीक्षण एंट्रियाँ एक्सपोर्ट नहीं की जातीं। सार्वजनिक एक्सपोर्ट की संख्या का ऑडिट करने के लिए pnpm plugin-sdk:surface चलाएँ। पर्याप्त पुराने और बंडल किए गए एक्सटेंशन के प्रोडक्शन कोड द्वारा अप्रयुक्त अप्रचलित सार्वजनिक सबपाथ scripts/lib/plugin-sdk-deprecated-public-subpaths.json में ट्रैक किए जाते हैं; व्यापक अप्रचलित री-एक्सपोर्ट बैरल scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json में ट्रैक किए जाते हैं।

पंजीकरण API

register(api) कॉलबैक को इन विधियों वाला एक OpenClawPluginApi ऑब्जेक्ट मिलता है:

किसी सत्र के लिए बाहरी टीम-चैट सतह उपलब्ध कराने वाले plugins, openclaw/plugin-sdk/session-discussion द्वारा एक्सपोर्ट किए गए एकल प्रोसेस-व्यापी प्रदाता को पंजीकृत कर सकते हैं। इसकी info({ sessionKey }) विधि बताती है कि चर्चा अनुपलब्ध है, खोलने के लिए तैयार है या पहले से खुली है; open({ sessionKey }) चर्चा बनाती या समाधान करती है और उसके एम्बेड तथा बाहरी URL लौटाती है। दूसरा प्रदाता पंजीकृत करने पर वर्तमान प्रदाता बदल जाता है।

क्षमता पंजीकरण

वर्कर प्रदाताओं को contracts.workerProviders में अपना आईडी भी घोषित करना होगा। Core, provision(profile, operationId) से पहले स्थायी अभिप्राय सहेजता है। प्रदाता बाहरी आवंटन से पहले सेटिंग्स सत्यापित करते हैं और स्थायी प्रोफ़ाइल अस्वीकृति के लिए WorkerProviderError थ्रो करते हैं। ऑपरेशन आईडी दोहराए जाने पर provision को उसी लीज़ को अपनाना होगा। Core सत्यापित प्रोफ़ाइल सेटिंग्स को लीज़ के साथ सहेजता है और वह स्नैपशॉट destroy({ leaseId, profile }) को देता है, जिसे आइडेम्पोटेंट होना चाहिए, तथा inspect({ leaseId, profile }) को देता है, जो active, destroyed या unknown लौटाता है। इससे प्रदाता Gateway पुनः शुरू होने या नामित प्रोफ़ाइल हटाए जाने के बाद लाइफ़साइकल कॉल रूट कर सकते हैं। SSH एंडपॉइंट, keyRef के लिए SecretRef का उपयोग करते हैं, इनलाइन कुंजी सामग्री का कभी नहीं, और विश्वसनीय प्रोविज़निंग आउटपुट से एक hostKey को होस्टनाम या टिप्पणी के बिना ठीक algorithm base64 के रूप में शामिल करते हैं। Core, hostKey पिन करता है और पहले कनेक्शन से मिली कुंजी पर कभी भरोसा नहीं करता। डायनेमिक keyRef बनाने वाला प्रदाता resolveSshIdentity({ leaseId, profile, keyRef }) लागू कर सकता है; मौजूद होने पर वह रिज़ॉल्वर प्रामाणिक होता है, जबकि इसके बिना प्रदाता कॉन्फ़िगर किए गए जेनेरिक सीक्रेट रिज़ॉल्वर का उपयोग करते हैं। नवीकरणीय लीज़ वाले प्रदाता renew(leaseId) भी लागू कर सकते हैं। अस्थायी या अनिश्चित विफलताओं पर inspect को थ्रो करना होगा; केवल प्रामाणिक अनुपस्थिति के लिए unknown लौटाएँ। Core किसी सक्रिय स्थानीय रिकॉर्ड को अनाथ चिह्नित करता है, या सहेजे गए नष्ट करने के अनुरोध के बाद अनुपस्थिति को टियरडाउन पूर्ण होने के रूप में मानता है।

api.registerEmbeddingProvider(...) के साथ पंजीकृत एम्बेडिंग प्रदाताओं को Plugin मैनिफ़ेस्ट में contracts.embeddingProviders में भी सूचीबद्ध होना चाहिए। यह पुनः उपयोग योग्य वेक्टर जनरेशन के लिए जेनेरिक एम्बेडिंग सतह है। मेमोरी खोज इस जेनेरिक प्रदाता सतह का उपयोग कर सकती है। पुराना api.registerMemoryEmbeddingProvider(...) और contracts.memoryEmbeddingProviders सीम, मौजूदा मेमोरी-विशिष्ट प्रदाताओं के माइग्रेट होने तक अप्रचलित संगतता है।

जो मेमोरी-विशिष्ट प्रदाता अब भी रनटाइम batchEmbed(...) उपलब्ध कराते हैं, वे मौजूदा प्रति-फ़ाइल बैचिंग अनुबंध पर बने रहते हैं, जब तक उनका रनटाइम स्पष्ट रूप से sourceWideBatchEmbed: true सेट न करे। इस ऑप्ट-इन से मेमोरी होस्ट, होस्ट बैच सीमाओं तक कई बदली हुई मेमोरी फ़ाइलों और सक्षम स्रोतों के चंक एक batchEmbed(...) कॉल में सबमिट कर सकता है। JSONL अनुरोध फ़ाइलें अपलोड करने वाले बैच अडैप्टर को प्रदाता जॉब उनके अनुरोध-संख्या सीमा के साथ-साथ अपलोड-आकार सीमा से पहले भी विभाजित करने होंगे। प्रदाता को batch.chunks के समान क्रम में प्रत्येक इनपुट चंक के लिए एक एम्बेडिंग लौटानी होगी; जब प्रदाता फ़ाइल-स्थानीय बैच अपेक्षित करता हो या बड़े स्रोत-व्यापी जॉब में इनपुट क्रम सुरक्षित न रख सके, तो फ़्लैग छोड़ दें।

टूल और कमांड

निश्चित टूल नामों वाले सरल, केवल-टूल plugins के लिए defineToolPlugin का उपयोग करें। मिश्रित plugins या पूर्णतः डायनेमिक टूल पंजीकरण के लिए सीधे api.registerTool(...) का उपयोग करें।

जब एजेंट को कमांड के स्वामित्व वाला एक छोटा रूटिंग संकेत चाहिए, तब Plugin कमांड agentPromptGuidance सेट कर सकती हैं। उस टेक्स्ट को स्वयं कमांड तक सीमित रखें; core प्रॉम्प्ट बिल्डर में प्रदाता या Plugin-विशिष्ट नीति न जोड़ें।

मार्गदर्शन प्रविष्टियाँ लीगेसी स्ट्रिंग हो सकती हैं, जो प्रत्येक प्रॉम्प्ट सतह पर लागू होती हैं, या संरचित प्रविष्टियाँ हो सकती हैं:

agentPromptGuidance: [  "वैश्विक कमांड संकेत।",  { text: "इसे केवल मुख्य OpenClaw प्रॉम्प्ट में दिखाएँ।", surfaces: ["openclaw_main"] },];

संरचित surfaces में openclaw_main, codex_app_server, cli_backend, acp_backend, या subagent शामिल हो सकते हैं। pi_main, openclaw_main के लिए एक बहिष्कृत उपनाम बना हुआ है। जानबूझकर सभी सतहों के लिए मार्गदर्शन देने हेतु surfaces को छोड़ दें। खाली surfaces सरणी पास न करें; इसे अस्वीकार कर दिया जाता है, ताकि दायरे की आकस्मिक हानि वैश्विक प्रॉम्प्ट टेक्स्ट न बन जाए।

नेटिव Codex app-server डेवलपर निर्देश अन्य प्रॉम्प्ट सतहों की तुलना में अधिक सख्त हैं: केवल codex_app_server के लिए स्पष्ट रूप से दायरे में रखा गया मार्गदर्शन ही उस उच्च-प्राथमिकता लेन में प्रोन्नत किया जाता है। संगतता के लिए लेगेसी स्ट्रिंग मार्गदर्शन और बिना दायरे वाला संरचित मार्गदर्शन गैर-Codex प्रॉम्प्ट सतहों के लिए उपलब्ध रहता है।

Node-होस्ट कमांड कनेक्ट किए गए Node होस्ट पर चलते हैं, Gateway प्रक्रिया के भीतर नहीं। यदि agentTool मौजूद है, तो सफल Gateway कनेक्शन के बाद Node एक डिस्क्रिप्टर प्रकाशित करता है; Gateway इसे एजेंट रन के लिए केवल तभी उपलब्ध कराता है, जब वह Node कनेक्ट हो और केवल तब, जब डिस्क्रिप्टर का command, Node की स्वीकृत कमांड सतह में हो। किसी गैर-खतरनाक कमांड को डिफ़ॉल्ट Node कमांड अनुमत-सूची में शामिल करने के लिए agentTool.defaultPlatforms सेट करें; अन्यथा स्पष्ट gateway.nodes.commands.allow या Node-इनवोक नीति आवश्यक करें। agentTool.name प्रदाता-सुरक्षित होना चाहिए: किसी अक्षर से शुरू हो, केवल अक्षरों, अंकों, अंडरस्कोर या हाइफ़न का उपयोग करे और 64 वर्णों के भीतर रहे। MCP-समर्थित Node टूल agentTool.mcp मेटाडेटा सेट कर सकते हैं, ताकि कैटलॉग और टूल-खोज सतहें रिमोट MCP सर्वर/टूल पहचान दिखा सकें, लेकिन निष्पादन फिर भी विज्ञापित Node कमांड के माध्यम से होता है।

अवसंरचना

अभिस्वीकृति के बाद का Webhook कार्य

जो Webhook रूट प्रसंस्करण पूरा होने से पहले अनुरोध को अभिस्वीकृत करते हैं, उन्हें उस पृथक कार्य को उसके अपने ट्रैक किए गए प्रवेश रूट पर स्थानांतरित करना चाहिए:

 void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {  runtime.error?.(`webhook प्रेषण विफल रहा: ${String(error)}`);});

HTTP अनुरोध के अभी भी प्रवेशित होने के दौरान runDetachedWebhookWork(...) को समकालिक रूप से कॉल करें। सहायक तुरंत एक स्वतंत्र रूट आरक्षित करता है, फिर अगली माइक्रोटास्क में कॉलबैक शुरू करता है, ताकि अनुरोध हैंडलर पहले अपनी अभिस्वीकृति लिख सके। लौटाया गया प्रॉमिस कॉलबैक परिणाम अपनाता है; अस्वीकृति प्रबंधन का उत्तरदायित्व फिर भी कॉलर का है। इससे अभिस्वीकृति के बाद का कतार कार्य स्वीकार होता रहता है और रीस्टार्ट या निलंबन ड्रेन उसके लिए प्रतीक्षा करते हैं। लौटने से पहले सभी प्रसंस्करण की प्रतीक्षा करने वाले हैंडलरों को इस सहायक की आवश्यकता नहीं है।

अनुरोधकर्ता-दायरे वाले MCP कनेक्शन

MCP सर्वर पहचान (नाम, टूल फ़िल्टर) को mcp.servers, किसी नेटिव Plugin के mcpServers मैनिफ़ेस्ट फ़ील्ड या किसी बंडल मैनिफ़ेस्ट में स्थिर रखें। वैकल्पिक रूप से कनेक्शन रिज़ॉल्वर पंजीकृत करें, ताकि प्रत्येक विश्वसनीय संदेश अनुरोधकर्ता को अपना अलग ट्रांसपोर्ट मिले:

api.registerMcpServerConnectionResolver({  serverName: "user-email",  resolve: async (ctx) => {    // ctx.requesterSenderId होस्ट द्वारा विश्वसनीय है; यहाँ प्रेषक पहचान कभी न गढ़ें।    const token = await lookupUserToken(ctx.requesterSenderId);    if (!token) {      return null; // वर्तमान रन के लिए इस सर्वर को छोड़ दें    }    return {      url: "https://mcp.example.com/email",      headers: { Authorization: `Bearer ${token}` },    };  },});

अनुबंध टिप्पणियाँ:

• रिज़ॉल्वर संदर्भ में केवल विश्वसनीय होस्ट पहचान होती है (requesterSenderId, वैकल्पिक agentAccountId / messageChannel)। भविष्य के विश्वसनीय फ़ील्ड (उदाहरण के लिए, Cron/उप-एजेंट उपयोगकर्ता संदर्भ) योगात्मक रूप से जोड़े जा सकते हैं।
• एक Plugin एक सर्वर नाम का स्वामी होता है: किसी अन्य Plugin से समान serverName के लिए डुप्लिकेट registerMcpServerConnectionResolver को त्रुटि निदान के साथ अस्वीकार किया जाता है (पहला पंजीकरण प्रभावी रहता है), इसलिए कनेक्शन स्वामित्व कभी भी Plugin लोड क्रम पर निर्भर नहीं होता।
• टूल नाम पूर्ण घोषित सर्वर समुच्चय से निकाले जाते हैं, ताकि आंशिक रिज़ॉल्यूशन अनुरोधकर्ताओं या टर्न के बीच सुरक्षित सर्वर नामों को कभी न बदले। कोर यह सत्यापित नहीं करता कि विभिन्न अनुरोधकर्ता एंडपॉइंट समान टूल स्कीमा प्रदान करते हैं; रिज़ॉल्वर को प्रत्येक अनुरोधकर्ता को उसी तार्किक सेवा पर इंगित करना चाहिए, अन्यथा टूल स्कीमा (और प्रॉम्प्ट-कैश स्थिरता) प्रत्येक अनुरोधकर्ता के अनुसार भिन्न हो जाते हैं।
• विश्वसनीय requesterSenderId के बिना रन (Cron, उप-एजेंट, Heartbeat, सार्वजनिक Gateway) अनुरोधकर्ता-दायरे वाले सर्वर कभी मूर्त रूप नहीं देते। कोई साझा फ़ॉलबैक कनेक्शन नहीं है।
• resolve प्रति सर्वर 10 सेकंड तक सीमित है; टाइमआउट या अपवाद उस सर्वर को रन से छोड़ देता है, बिना स्थिर MCP को विफल किए।
• रिज़ॉल्व किए गए कनेक्शनों को प्रति अनुरोधकर्ता अधिकतम हर 5 मिनट में पुनः सत्यापित किया जाता है: रोटेशन नए क्रेडेंशियल के साथ ट्रांसपोर्ट को फिर से बनाता है, और null परिणाम उसे निरस्त कर देता है (कैश किया गया रनटाइम सत्र के बीच में भी निपटाया जाता है)। इसलिए निरस्त या रोटेट किया गया क्रेडेंशियल 5 मिनट तक उपयोग में रह सकता है।
• रिज़ॉल्व किए गए headers कभी लॉग या स्थायी रूप से संग्रहीत नहीं किए जाते; कोर क्रेडेंशियल रोटेशन का पता लगाने के लिए केवल एक क्षणिक इन-मेमोरी कुंजीबद्ध डाइजेस्ट (प्रक्रिया-स्थानीय HMAC) रखता है और रिज़ॉल्व किए गए हेडर/URL क्रेडेंशियल मानों को लॉग/डीबग-कैप्चर रिडैक्शन रजिस्ट्री में पंजीकृत करता है।
• अनुरोधकर्ता-दायरे वाले सर्वर MCP App दृश्य नहीं बनाते: कोई दृश्य अनुरोधकर्ता-प्रमाणित रन से अधिक समय तक रहता है और Gateway दृश्य सीमा में अनुरोधकर्ता पहचान नहीं होती, इसलिए इन सर्वरों के लिए ऐप पूर्वावलोकन फ़ेल-क्लोज़्ड रहते हैं। टूल परिणाम अप्रभावित रहते हैं।
• रिज़ॉल्वर के बिना स्थिर सर्वर मौजूदा सत्र-दायरे वाले जीवनचक्र को बनाए रखते हैं।
• हार्नेस वितरण नियम: अनुरोधकर्ता-दायरे वाले सर्वर कभी भी हार्नेस-नेटिव MCP क्लाइंट कॉन्फ़िग (Codex थ्रेड mcp_servers, CLI -c mcp_servers=…, या किसी अन्य सत्र-साझा MCP प्रोजेक्शन) में प्रवेश नहीं करते। इसके बजाय हार्नेस उन्हें रन-दायरे वाले टूल के रूप में वितरित करते हैं:
  • एम्बेडेड रनर: सत्र MCP रनटाइम + बंडल टूल (स्थिर + दायरे वाले)।
  • Codex app-server: materializeRequesterScopedMcpToolsForHarnessRun के माध्यम से डायनेमिक टूल (केवल दायरे वाले; स्थिर सर्वर Codex के नेटिव MCP क्लाइंट पर बने रहते हैं)।
• दायरे वाले टूल विनिर्देश उस सत्र में पहले सफल रिज़ॉल्व के बाद सत्र-स्थिर रहते हैं, इसलिए साझा-थ्रेड हार्नेस (Codex) प्रेषक बदलने पर थ्रेड रोटेट नहीं करते। किसी भी अनुरोधकर्ता के रिज़ॉल्व होने से पहले, कोई दायरे वाला विनिर्देश विज्ञापित नहीं होता।
• साझा-थ्रेड हार्नेस पर अप्रमाणित अनुरोधकर्ता फिर भी विज्ञापित दायरे वाले टूल देखते हैं; किसी एक को कॉल करने पर उस अनुरोधकर्ता के लिए साफ़ कनेक्ट-नहीं टूल त्रुटि लौटती है। OpenClaw कभी किसी अन्य अनुरोधकर्ता के क्रेडेंशियल पर फ़ॉलबैक नहीं करता।

मेमोरी प्रॉम्प्ट पूरक बिल्डरों को वैकल्पिक agentId, agentSessionKey, और sandboxed संदर्भ मिलता है। मेमोरी कॉर्पस पूरक search और get कॉल को वैकल्पिक agentId और sandboxed संदर्भ मिलता है। एजेंट-स्वामित्व वाले स्टोरेज वाले Plugins को पंजीकरण के दौरान एक वैश्विक पथ कैप्चर करने के बजाय प्रत्येक कॉल के लिए उस स्टोरेज को रिज़ॉल्व करना चाहिए। यदि किसी बहु-एजेंट संचालन में एजेंट आईडी आवश्यक हो लेकिन अनुपस्थित हो, तो कोई मनमाना एजेंट चुनने के बजाय फ़ेल-क्लोज़्ड करें।

जब प्रॉम्प्ट टेक्स्ट एसिंक Plugin स्थिति पर निर्भर हो, तब registerMemoryPromptPreparation(...) का उपयोग करें। कॉलबैक प्रत्येक पूर्ण एजेंट प्रॉम्प्ट से पहले एक बार चलता है और समकालिक मेमोरी प्रॉम्प्ट बिल्डरों के समान टूल, एजेंट, सत्र और सैंडबॉक्स संदर्भ प्राप्त करता है। स्थायी स्थिति लोड करने से पहले वर्तमान स्टोरेज-स्वामी इंस्टेंस को सत्यापित करें, फिर केवल उस रन की पंक्तियाँ लौटाएँ। OpenClaw उन पंक्तियों को फ़्रीज़ करता है और अपरिवर्तनीय परिणाम को समकालिक प्रॉम्प्ट संयोजन को सौंपता है। स्थायित्व, परमाणु प्रतिस्थापन और स्वामी-निष्कासन विलोपन को स्वामी Plugin के भीतर रखें; किसी प्रॉम्प्ट बिल्डर से फ़ाइलों की पोलिंग या पठन न करें।

Telegram इंटरैक्टिव हैंडलर सफल होने के बाद टेक्स्ट को Telegram के सामान्य इनबाउंड एजेंट पथ से रूट करने के लिए { submitText } लौटा सकते हैं। इनबाउंड नीति द्वारा टेक्स्ट छोड़ दिए जाने या प्रसंस्करण विफल होने पर OpenClaw कॉलबैक बटन बनाए रखता है, ताकि अवरोधक स्थिति बदलने के बाद उपयोगकर्ता पुनः प्रयास कर सके। यह परिणाम फ़ील्ड Telegram-विशिष्ट है; अन्य चैनल अपने स्वयं के इंटरैक्टिव परिणाम अनुबंध बनाए रखते हैं।

वर्कफ़्लो Plugins के लिए होस्ट हुक

होस्ट हुक उन Plugins के लिए SDK सीम हैं, जिन्हें केवल प्रदाता, चैनल या टूल जोड़ने के बजाय होस्ट जीवनचक्र में भाग लेना होता है। वे सामान्य अनुबंध हैं; Plan Mode उनका उपयोग कर सकता है, लेकिन स्वीकृति वर्कफ़्लो, वर्कस्पेस नीति गेट, पृष्ठभूमि मॉनिटर, सेटअप विज़ार्ड और UI सहयोगी Plugins भी कर सकते हैं।

एक surface: "tab" वर्णनकर्ता Control UI में साइडबार टैब जोड़ता है। सक्रिय plugins के टैब वर्णनकर्ता Gateway हेलो (controlUiTabs) में डैशबोर्ड क्लाइंटों को बताए जाते हैं, इसलिए टैब केवल Plugin के सक्षम रहने पर दिखाई देता है। बंडल किए गए plugins अपने टैब के लिए प्रथम-श्रेणी का डैशबोर्ड दृश्य भेज सकते हैं; अन्य plugins path को Plugin HTTP रूट पर सेट कर सकते हैं (देखें api.registerHttpRoute(...)), जिसे डैशबोर्ड सैंडबॉक्स किए गए फ़्रेम में रेंडर करता है। icon डैशबोर्ड आइकन नाम का संकेत है, group साइडबार अनुभाग चुनता है (control या agent), order Plugin टैब के बीच क्रम निर्धारित करता है, और requiredScopes उन कनेक्शनों से टैब छिपाता है जिनके पास वे ऑपरेटर स्कोप नहीं हैं:

Gateway-संरक्षित बाहरी टैब के लिए, वर्णनकर्ता path को उसी Plugin के auth: "gateway" HTTP रूट के अंतर्गत पंजीकृत करें। प्रमाणित बूटस्ट्रैप के बाद, ब्राउज़र को उस Plugin और रूट मूल तक सीमित एक अल्पकालिक, HttpOnly अनुदान मिलता है, ताकि सैंडबॉक्स किया गया फ़्रेम Gateway बेयरर टोकन को अपने URL या JavaScript में कॉपी किए बिना लोड हो सके। प्रमाणित पैरेंट बाहरी टैब के सक्रिय रहने पर और नेविगेशन या ब्राउज़र फिर से शुरू होने के बाद उसे माउंट करने से पहले अनुदान नवीनीकृत करता है। यह माउंट करने से पहले उसी अपारदर्शी सैंडबॉक्स से अनुदान की जाँच भी करता है, ताकि ब्राउज़र के वे गोपनीयता मोड जो कुकी अवरुद्ध करते हैं, अनुपलब्ध पैनल के साथ सुरक्षित रूप से विफल हों। फ़्रेम अनुदान केवल GET और HEAD स्वीकार करता है और हमेशा operator.read वहन करता है; requiredScopes टैब की दृश्यता नियंत्रित करता है, लेकिन कुकी अनुदान का दायरा कभी नहीं बढ़ाता। परिवर्तन स्पष्ट Gateway-प्रमाणित पैरेंट या बेयरर सतहों पर ही रहते हैं। बाहरी टैब के लिए HTTPS/Tailscale Serve या ब्राउज़र-विश्वसनीय लूपबैक ओरिजिन आवश्यक है; LAN होस्ट पर सादा HTTP ऐसा पैनल माउंट करने के बजाय सुरक्षित-संदर्भ त्रुटि दिखाता है जो प्रमाणित नहीं हो सकता। तृतीय-पक्ष कुकी का पूर्ण अवरोध भी Gateway-संरक्षित टैब को अनुपलब्ध बना देता है। सभी नेटिव Plugin सतहों की तरह, फ़्रेम इंस्टॉल किए गए Plugin की विश्वास सीमा के भीतर रहता है; OpenClaw इंस्टॉल किए गए plugins को परस्पर पृथक ब्राउज़र सुरक्षा प्रिंसिपल नहीं मानता। कुकी अनुदान ब्राउज़र की होस्टनाम सीमा का उपयोग करते हैं, पोर्ट सीमा का नहीं। परस्पर अविश्वसनीय सेवाओं को Gateway होस्टनाम पर, अन्य पोर्ट पर भी, सह-होस्ट न करें। Plugin-प्रबंधित प्रमाणीकरण द्वारा समर्थित टैब अपना प्रत्यक्ष iframe व्यवहार बनाए रखते हैं और इस Gateway अनुदान का अनुरोध या इसकी आवश्यकता नहीं रखते।

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "दैनिकी",  description: "स्क्रीन स्नैपशॉट से बनी समयरेखा के रूप में आपका दिन।",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

नए Plugin कोड के लिए समूहीकृत नेमस्पेस का उपयोग करें:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

समतुल्य सपाट विधियाँ मौजूदा plugins के लिए अप्रचलित संगतता उपनामों के रूप में उपलब्ध रहती हैं। ऐसा नया Plugin कोड न जोड़ें जो सीधे api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn, या api.unscheduleSessionTurnsByTag को कॉल करता हो।

scheduleSessionTurn(...) Gateway Cron शेड्यूलर पर सत्र-सीमित सुविधा है। Cron समय-निर्धारण का स्वामी है और टर्न चलने पर पृष्ठभूमि टास्क रिकॉर्ड बनाता है; Plugin SDK केवल लक्ष्य सत्र, Plugin-स्वामित्व वाली नामकरण व्यवस्था और क्लीनअप को सीमित करता है। जब कार्य को ही टिकाऊ बहु-चरणीय Task Flow स्थिति चाहिए, तब शेड्यूल किए गए टर्न के भीतर api.runtime.tasks.managedFlows का उपयोग करें।

अनुबंध जानबूझकर अधिकार विभाजित करते हैं:

• बाहरी plugins सत्र एक्सटेंशन, UI वर्णनकर्ता, कमांड, टूल मेटाडेटा, अगले-टर्न अंतःक्षेपण और सामान्य हुक के स्वामी हो सकते हैं।
• विश्वसनीय टूल नीतियाँ सामान्य before_tool_call हुक से पहले चलती हैं और होस्ट-विश्वसनीय होती हैं। बंडल नीतियाँ पहले चलती हैं; इंस्टॉल किए गए Plugin की नीतियों को स्पष्ट सक्षमता के साथ उनके स्थानीय आईडी contracts.trustedToolPolicies में चाहिए, और वे Plugin-लोड क्रम में इसके बाद चलती हैं। नीति आईडी पंजीकरण करने वाले Plugin तक सीमित होते हैं।
• आरक्षित कमांड स्वामित्व केवल-बंडल है। बाहरी plugins को अपने कमांड नाम या उपनाम उपयोग करने चाहिए।
• allowPromptInjection=false प्रॉम्प्ट बदलने वाले हुक अक्षम करता है, जिनमें agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, और enqueueNextTurnInjection शामिल हैं।

गैर-Plan उपभोक्ताओं के उदाहरण:

Gateway खोज पंजीकरण

api.registerGatewayDiscoveryService(...) किसी Plugin को सक्रिय Gateway का विज्ञापन mDNS/Bonjour जैसे स्थानीय खोज ट्रांसपोर्ट पर करने देता है। स्थानीय खोज सक्षम होने पर OpenClaw Gateway स्टार्टअप के दौरान सेवा को कॉल करता है, वर्तमान Gateway पोर्ट और गैर-गोपनीय TXT संकेत डेटा पास करता है, और Gateway शटडाउन के दौरान लौटाए गए stop हैंडलर को कॉल करता है।

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Gateway खोज plugins को विज्ञापित TXT मानों को गोपनीय जानकारी या प्रमाणीकरण नहीं मानना चाहिए। खोज एक रूटिंग संकेत है; Gateway प्रमाणीकरण और TLS पिनिंग अब भी विश्वास के स्वामी हैं।

CLI पंजीकरण मेटाडेटा

api.registerCli(registrar, opts?) दो प्रकार के कमांड मेटाडेटा स्वीकार करता है:

• commands: पंजीयक के स्वामित्व वाले स्पष्ट कमांड नाम
• descriptors: CLI सहायता, रूटिंग और आलसी Plugin CLI पंजीकरण के लिए पार्स-समय कमांड वर्णनकर्ता
• parentPath: नेस्टेड कमांड समूहों के लिए वैकल्पिक पैरेंट कमांड पथ, जैसे ["nodes"]

युग्मित-Node सुविधाओं के लिए, api.registerNodeCliFeature(registrar, opts?) को प्राथमिकता दें। यह api.registerCli(..., { parentPath: ["nodes"] }) के चारों ओर एक छोटा रैपर है और openclaw nodes canvas जैसे कमांड को स्पष्ट रूप से Plugin-स्वामित्व वाली Node सुविधाएँ बनाता है।

यदि आप चाहते हैं कि कोई Plugin कमांड सामान्य रूट CLI पथ में आलसी रूप से लोड हो, तो ऐसे descriptors प्रदान करें जो उस पंजीयक द्वारा उजागर किए गए प्रत्येक शीर्ष-स्तरीय कमांड रूट को समेटते हों।

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Matrix खातों, सत्यापन, डिवाइस और प्रोफ़ाइल स्थिति को प्रबंधित करें",        hasSubcommands: true,      },    ],  },);

नेस्टेड कमांड समाधान किए गए पैरेंट कमांड को program के रूप में प्राप्त करते हैं:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "युग्मित नोड से कैनवास सामग्री कैप्चर या रेंडर करें",        hasSubcommands: true,      },    ],  },);

commands का अकेले उपयोग केवल तभी करें, जब आपको लेज़ी रूट CLI पंजीकरण की आवश्यकता न हो। वह तत्पर संगतता पथ अब भी समर्थित है, लेकिन वह पार्स-समय लेज़ी लोडिंग के लिए डिस्क्रिप्टर-समर्थित प्लेसहोल्डर इंस्टॉल नहीं करता।

CLI बैकएंड पंजीकरण

api.registerCliBackend(...) किसी Plugin को claude-cli या my-cli जैसे स्थानीय AI CLI बैकएंड के लिए डिफ़ॉल्ट कॉन्फ़िगरेशन का स्वामी बनने देता है।

• बैकएंड id, my-cli/gpt-5 जैसे मॉडल संदर्भों में प्रोवाइडर प्रीफ़िक्स बन जाता है।
• बैकएंड config प्रामाणिक कमांड अडैप्टर है: argv, परिवेश, पार्सर, सत्र, इमेज और विश्वसनीयता व्यवहार Plugin कोड में रहते हैं।
• उपयोगकर्ता मॉडल संदर्भों या मॉडल-स्कोप्ड agentRuntime.id के माध्यम से बैकएंड चुनते हैं; openclaw.json अडैप्टर को दोबारा नहीं लिखता।
• जब पंजीकृत स्थिर फ़ील्ड को रनटाइम-सजग नॉर्मलाइज़ेशन पास की आवश्यकता हो, तब normalizeConfig का उपयोग करें।
• CLI डायलेक्ट से संबंधित अनुरोध-स्कोप्ड argv पुनर्लेखन के लिए resolveExecutionArgs का उपयोग करें, जैसे OpenClaw के चिंतन स्तरों को किसी नेटिव प्रयास फ़्लैग से मैप करना। हुक को ctx.executionMode प्राप्त होता है; अस्थायी /btw कॉल के लिए बैकएंड-नेटिव आइसोलेशन फ़्लैग जोड़ने हेतु "side-question" का उपयोग करें। यदि वे फ़्लैग किसी अन्यथा हमेशा-सक्रिय CLI के नेटिव टूल को विश्वसनीय रूप से अक्षम करते हैं, तो sideQuestionToolMode: "disabled" भी घोषित करें।
• बैकएंड-स्वामित्व वाले लॉन्च परिवेश या अस्थायी प्रमाणीकरण/कॉन्फ़िगरेशन ब्रिज के लिए prepareExecution का उपयोग करें। इसका ctx.contextTokenBudget रन के लिए चुनी गई प्रभावी टोकन सीमा है, ताकि नेटिव-Compaction बैकएंड प्रोवाइडर-विशिष्ट कोर शाखाओं के बिना अपनी सीमा को संरेखित कर सकें। जब बैकएंड स्टेजिंग को बंडल की गई MCP सेटिंग विस्तारित करनी हो, तब इसे कोर द्वारा तैयार ctx.env भी प्राप्त होता है।
• जो बैकएंड किसी विशिष्ट रन के लिए सभी नेटिव टूल अक्षम कर सकते हैं, वे nativeToolMode: "selectable" घोषित कर सकते हैं। प्रतिबंधित कॉल एक सटीक ctx.toolAvailability.native सूची और कैनोनिकल ctx.toolAvailability.openClaw नाम पास करते हैं। toolAvailabilityEnforcement: "execution-args" घोषित करें और अंतिम नए/पुनरारंभ argv में अनुबंध लागू करें, या "prepare-execution" घोषित करें, उसे स्टेज की गई नीति में लागू करें और toolAvailabilityEnforced: true लौटाएँ। OpenClaw cron toolsAllow जैसी रनटाइम सीमाओं के लिए नेटिव टूल अक्षम करता है और घोषित प्रवर्तन पथ अधूरा होने पर सुरक्षित रूप से विफल होता है।

आरंभ से अंत तक लेखन मार्गदर्शिका के लिए, CLI बैकएंड Plugin देखें।

विशिष्ट स्लॉट

अप्रचलित मेमोरी एम्बेडिंग अडैप्टर

• registerMemoryCapability विशिष्ट मेमोरी-Plugin API है।
• registerMemoryCapability होस्ट-प्रबंधित निर्यातों के लिए publicArtifacts.listArtifacts(...) भी उजागर कर सकता है। उन घोषित आर्टिफ़ैक्ट की गणना करने वाले सहायक Plugin, केंद्रित सार्वजनिक उपभोक्ता API उपलब्ध होने तक, बनाए रखे गए openclaw/plugin-sdk/memory-host-core फ़साड से listActiveMemoryPublicArtifacts(...) का उपयोग करना जारी रखते हैं; उन्हें किसी अन्य Plugin के निजी लेआउट में प्रवेश नहीं करना चाहिए।
• MemoryFlushPlan.model सक्रिय फ़ॉलबैक शृंखला को विरासत में लिए बिना फ़्लश टर्न को ollama/qwen3:8b जैसे किसी सटीक provider/model संदर्भ पर पिन कर सकता है।
• registerMemoryEmbeddingProvider अप्रचलित है। नए एम्बेडिंग प्रोवाइडर को api.registerEmbeddingProvider(...) और contracts.embeddingProviders का उपयोग करना चाहिए।
• मौजूदा मेमोरी-विशिष्ट प्रोवाइडर माइग्रेशन अवधि के दौरान काम करना जारी रखते हैं, लेकिन Plugin निरीक्षण इसे गैर-बंडल Plugin के लिए संगतता ऋण के रूप में रिपोर्ट करता है।

इवेंट और जीवनचक्र

उदाहरणों, सामान्य हुक नामों और गार्ड सिमैंटिक्स के लिए Plugin हुक देखें।

हुक निर्णय सिमैंटिक्स

before_install एक Plugin-रनटाइम जीवनचक्र हुक है, ऑपरेटर इंस्टॉल नीति सतह नहीं। जब अनुमति/अवरोध निर्णय को CLI और Gateway-समर्थित इंस्टॉल या अपडेट पथों को समाहित करना हो, तब security.installPolicy का उपयोग करें।

• before_tool_call: { block: true } लौटाना अंतिम है। किसी भी हैंडलर द्वारा इसे सेट करने के बाद, कम प्राथमिकता वाले हैंडलर छोड़ दिए जाते हैं।
• before_tool_call: { block: false } लौटाना कोई निर्णय न होने के रूप में माना जाता है (block को छोड़ने के समान), ओवरराइड के रूप में नहीं।
• before_install: { block: true } लौटाना अंतिम है। किसी भी हैंडलर द्वारा इसे सेट करने के बाद, कम प्राथमिकता वाले हैंडलर छोड़ दिए जाते हैं।
• before_install: { block: false } लौटाना कोई निर्णय न होने के रूप में माना जाता है (block को छोड़ने के समान), ओवरराइड के रूप में नहीं।
• reply_dispatch: { handled: true, ... } लौटाना अंतिम है। किसी भी हैंडलर द्वारा डिस्पैच का दावा करने के बाद, कम प्राथमिकता वाले हैंडलर और डिफ़ॉल्ट मॉडल डिस्पैच पथ छोड़ दिए जाते हैं।
• message_sending: { cancel: true } लौटाना अंतिम है। किसी भी हैंडलर द्वारा इसे सेट करने के बाद, कम प्राथमिकता वाले हैंडलर छोड़ दिए जाते हैं।
• message_sending: { cancel: false } लौटाना कोई निर्णय न होने के रूप में माना जाता है (cancel को छोड़ने के समान), ओवरराइड के रूप में नहीं।
• message_received: जब आपको इनबाउंड थ्रेड/विषय रूटिंग की आवश्यकता हो, तब टाइप किए गए threadId फ़ील्ड का उपयोग करें। चैनल-विशिष्ट अतिरिक्त मानों के लिए metadata रखें।
• message_sending: चैनल-विशिष्ट metadata पर फ़ॉलबैक करने से पहले टाइप किए गए replyToId / threadId रूटिंग फ़ील्ड का उपयोग करें।
• gateway_start: आंतरिक gateway:startup हुक पर निर्भर रहने के बजाय Gateway-स्वामित्व वाली स्टार्टअप स्थिति के लिए ctx.config, ctx.workspaceDir और ctx.getCron?.() का उपयोग करें। इस समय Cron अब भी लोड हो रहा हो सकता है।
• cron_reconciled: स्टार्टअप या शेड्यूलर रीलोड के बाद पूर्ण बाहरी cron प्रोजेक्शन फिर से बनाएँ। इसमें reason और प्रभावी enabled स्थिति शामिल है, जिसमें enabled: false भी है, जबकि ctx.getCron?.() सटीक समन्वित शेड्यूलर लौटाता है। स्थायी प्रोजेक्शन कार्य में ctx.abortSignal पास करें; उस शेड्यूलर स्नैपशॉट के प्रतिस्थापित होने या Gateway के बंद होने पर यह निरस्त हो जाता है।
• cron_changed: Gateway-स्वामित्व वाले cron जीवनचक्र परिवर्तनों का निरीक्षण करें। scheduled और removed इवेंट कमिट-पश्चात समन्वय संकेत हैं, क्रमबद्ध डेल्टा लॉग नहीं। जब जॉब का अगला वेक नहीं होता, तब शेड्यूल किए गए इवेंट का event.nextRunAtMs अनुपस्थित होता है; हटाए गए इवेंट में हटाए गए जॉब का स्नैपशॉट अब भी रहता है।

बाहरी वेक शेड्यूलर को cron_changed इवेंट को डीबाउंस या समेकित करना चाहिए, फिर cron_reconciled द्वारा अंतिम बार कैप्चर किए गए शेड्यूलर से पूर्ण स्थायी दृश्य दोबारा पढ़ना चाहिए। cron_changed संदर्भ से शेड्यूलर न अपनाएँ: किसी पुराने शेड्यूलर का अलग हुआ संकेत बाद के रीलोड के साथ ओवरलैप कर सकता है।

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

स्थायी प्रतिस्थापन, पुनः प्रयास/बैकऑफ़ और स्वच्छ शटडाउन वाले सिंगल-फ़्लाइट अडैप्टर के लिए सुरक्षित बाहरी cron प्रोजेक्शन देखें।

API ऑब्जेक्ट फ़ील्ड

आंतरिक मॉड्यूल परिपाटी

अपने Plugin के भीतर, आंतरिक इंपोर्ट के लिए स्थानीय बैरल फ़ाइलों का उपयोग करें:

my-plugin/  api.ts            # बाहरी उपभोक्ताओं के लिए सार्वजनिक निर्यात  runtime-api.ts    # केवल आंतरिक रनटाइम निर्यात  index.ts          # Plugin प्रवेश बिंदु  setup-entry.ts    # हल्की, केवल-सेटअप एंट्री (वैकल्पिक)

फ़साड द्वारा लोड किए गए बंडल Plugin के सार्वजनिक सरफ़ेस (api.ts, runtime-api.ts, index.ts, setup-entry.ts, और इसी तरह की सार्वजनिक एंट्री फ़ाइलें), OpenClaw के पहले से चल रहे होने पर सक्रिय रनटाइम कॉन्फ़िग स्नैपशॉट को प्राथमिकता देते हैं। यदि अभी तक कोई रनटाइम स्नैपशॉट मौजूद नहीं है, तो वे डिस्क पर मौजूद रिज़ॉल्व की गई कॉन्फ़िग फ़ाइल का उपयोग करते हैं। पैकेज किए गए बंडल Plugin फ़साड को OpenClaw के Plugin फ़साड लोडर के माध्यम से लोड किया जाना चाहिए; dist/extensions/... से सीधे इम्पोर्ट करने पर वे मैनिफ़ेस्ट और रनटाइम साइडकार जाँच बायपास हो जाती हैं, जिनका उपयोग पैकेज किए गए इंस्टॉल Plugin-स्वामित्व वाले कोड के लिए करते हैं।

प्रोवाइडर Plugin एक सीमित, Plugin-स्थानीय अनुबंध बैरल उपलब्ध करा सकते हैं, जब कोई हेल्पर जानबूझकर प्रोवाइडर-विशिष्ट हो और अभी किसी सामान्य SDK सबपाथ में उपयुक्त न हो। बंडल उदाहरण:

• Anthropic: Claude बीटा-हेडर और service_tier स्ट्रीम हेल्पर के लिए सार्वजनिक api.ts / contract-api.ts सीम।
• @openclaw/openai-provider: api.ts प्रोवाइडर बिल्डर, डिफ़ॉल्ट-मॉडल हेल्पर और रियलटाइम प्रोवाइडर बिल्डर एक्सपोर्ट करता है।
• @openclaw/openrouter-provider: api.ts प्रोवाइडर बिल्डर के साथ ऑनबोर्डिंग/कॉन्फ़िग हेल्पर एक्सपोर्ट करता है।

संबंधित