---
read_when:
- आपको पता होना चाहिए कि किस SDK उप-पथ से आयात करना है
- आप OpenClawPluginApi पर सभी पंजीकरण विधियों का संदर्भ चाहते हैं
- आप किसी विशिष्ट SDK एक्सपोर्ट को खोज रहे हैं
sidebarTitle: Plugin SDK overview
summary: इम्पोर्ट मैप, पंजीकरण API संदर्भ और SDK आर्किटेक्चर
title: Plugin SDK का अवलोकन
x-i18n:
generated_at: "2026-07-27T18:19:57Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: 4f490aa8670c57cfc1a635fb1f5d9950fa1cabdb3d45abbc2295da796edcd52e
source_path: plugins/sdk-overview.md
workflow: 16
---
Plugin SDK, plugins और core के बीच टाइप किया हुआ अनुबंध है। यह पृष्ठ
**क्या इम्पोर्ट करना है** और **आप क्या पंजीकृत कर सकते हैं** का संदर्भ है।
यह पृष्ठ OpenClaw के भीतर `openclaw/plugin-sdk/*` का उपयोग करने वाले
Plugin लेखकों के लिए है। Gateway के माध्यम से एजेंट चलाने वाले बाहरी ऐप्स,
स्क्रिप्ट, डैशबोर्ड, CI जॉब और IDE एक्सटेंशन के लिए इसके बजाय
[बाहरी ऐप्स के लिए Gateway एकीकरण](/hi/gateway/external-apps) का उपयोग करें।
इसके बजाय कोई व्यावहारिक मार्गदर्शिका खोज रहे हैं? [Plugins बनाना](/hi/plugins/building-plugins) से शुरू करें। चैनलों के लिए [चैनल plugins](/hi/plugins/sdk-channel-plugins), मॉडल प्रदाताओं के लिए [प्रदाता plugins](/hi/plugins/sdk-provider-plugins), स्थानीय AI CLI बैकएंड के लिए [CLI बैकएंड plugins](/hi/plugins/cli-backend-plugins), मूल एजेंट निष्पादकों के लिए [एजेंट हार्नेस plugins](/hi/plugins/sdk-agent-harness), और टूल या लाइफ़साइकल हुक के लिए [Plugin हुक](/hi/plugins/hooks) का उपयोग करें।
## इम्पोर्ट परंपरा
हमेशा किसी विशिष्ट सबपाथ से इम्पोर्ट करें:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-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 के लिए प्रतिमान नहीं है।
प्रदाता या चैनल के नाम वाले सुविधा सीम इम्पोर्ट न करें (उदाहरण के लिए
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`)।
बंडल किए गए plugins अपने स्वयं के `api.ts` /
`runtime-api.ts` बैरल के भीतर जेनेरिक SDK सबपाथ संयोजित करते हैं; core उपभोक्ताओं
को या तो उन Plugin-स्थानीय बैरल का उपयोग करना चाहिए या आवश्यकता वास्तव में
विभिन्न चैनलों पर लागू होने पर एक सीमित जेनेरिक SDK अनुबंध जोड़ना
चाहिए।
बंडल किए गए Plugin के सहायक सीम का एक छोटा समूह, जब उनका ट्रैक किया गया स्वामी
उपयोग मौजूद होता है, तब भी जनरेट किए गए एक्सपोर्ट मैप में दिखाई देता है। वे केवल
बंडल किए गए Plugin के रखरखाव के लिए मौजूद हैं और नए तृतीय-पक्ष
plugins के लिए अनुशंसित इम्पोर्ट पथ नहीं हैं।
`openclaw/plugin-sdk/discord` और `openclaw/plugin-sdk/telegram-account` को भी
ट्रैक किए गए स्वामी उपयोग के लिए अप्रचलित संगतता फ़साड के रूप में रखा गया है। उन
इम्पोर्ट पथों को नए plugins में कॉपी न करें; इसके बजाय इंजेक्ट किए गए रनटाइम सहायक और
जेनेरिक चैनल SDK सबपाथ का उपयोग करें।
## सबपाथ संदर्भ
Plugin SDK को क्षेत्र के अनुसार समूहित सीमित सबपाथ के समूह के रूप में उपलब्ध कराया
गया है (Plugin एंट्री, चैनल, प्रदाता, प्रमाणीकरण, रनटाइम, क्षमता, मेमोरी और आरक्षित
बंडल-Plugin सहायक)। समूहित और लिंक की गई पूरी सूची के लिए
[Plugin SDK सबपाथ](/hi/plugins/sdk-subpaths) देखें।
कंपाइलर एंट्रीपॉइंट सूची
`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 लौटाती है। दूसरा प्रदाता पंजीकृत करने पर वर्तमान प्रदाता बदल जाता है।
### क्षमता पंजीकरण
| विधि | यह क्या पंजीकृत करती है |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerProvider(...)` | टेक्स्ट अनुमान (LLM) |
| `api.registerWorkerProvider(...)` | क्लाउड-वर्कर लाइफ़साइकल लीज़ |
| `api.registerModelCatalogProvider(...)` | टेक्स्ट और मीडिया जनरेशन के लिए मॉडल कैटलॉग पंक्तियाँ |
| `api.registerAgentHarness(...)` | [प्रायोगिक](/hi/plugins/sdk-agent-harness) मूल एजेंट निष्पादक (Codex, Copilot) |
| `api.registerCliBackend(...)` | स्थानीय CLI अनुमान बैकएंड |
| `api.registerChannel(...)` | मैसेजिंग चैनल |
| `api.registerEmbeddingProvider(...)` | पुनः उपयोग योग्य वेक्टर एम्बेडिंग प्रदाता |
| `api.registerSpeechProvider(...)` | टेक्स्ट-टू-स्पीच / STT संश्लेषण |
| `api.registerRealtimeTranscriptionProvider(...)` | स्ट्रीमिंग रीयलटाइम ट्रांसक्रिप्शन |
| `api.registerRealtimeVoiceProvider(...)` | डुप्लेक्स रीयलटाइम वॉइस सत्र |
| `api.registerMediaUnderstandingProvider(...)` | इमेज/ऑडियो/वीडियो विश्लेषण |
| `api.registerTranscriptSourceProvider(...)` | लाइव या इम्पोर्ट किया हुआ मीटिंग ट्रांसक्रिप्ट स्रोत; मीटिंग plugins, `plugin-sdk/transcripts` से `createMeetingTranscriptSourceProvider` का उपयोग कर सकते हैं |
| `api.registerImageGenerationProvider(...)` | इमेज जनरेशन |
| `api.registerMusicGenerationProvider(...)` | संगीत जनरेशन |
| `api.registerVideoGenerationProvider(...)` | वीडियो जनरेशन |
| `api.registerWebFetchProvider(...)` | वेब फ़ेच / स्क्रेप प्रदाता |
| `api.registerWebSearchProvider(...)` | वेब खोज |
| `api.registerCompactionProvider(...)` | प्लग करने योग्य ट्रांसक्रिप्ट-Compaction बैकएंड |
वर्कर प्रदाताओं को `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`](/hi/plugins/tool-plugins) का उपयोग करें। मिश्रित plugins
या पूर्णतः डायनेमिक टूल पंजीकरण के लिए सीधे `api.registerTool(...)` का उपयोग करें।
| विधि | यह क्या पंजीकृत करती है |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerTool(tool, opts?)` | एजेंट टूल (आवश्यक या `{ optional: true }`) |
| `api.registerCommand(def)` | कस्टम कमांड (LLM को बायपास करती है) |
| `api.registerNodeHostCommand(command)` | `openclaw node run` द्वारा संभाली जाने वाली कमांड; वैकल्पिक `agentTool` मेटाडेटा, Node के कनेक्ट होने पर इसे एजेंट को दिखाई देने वाले टूल के रूप में उपलब्ध करा सकता है |
जब एजेंट को कमांड के स्वामित्व वाला एक छोटा रूटिंग संकेत चाहिए, तब Plugin कमांड
`agentPromptGuidance` सेट कर सकती हैं। उस टेक्स्ट को स्वयं कमांड तक सीमित रखें;
core प्रॉम्प्ट बिल्डर में प्रदाता या Plugin-विशिष्ट नीति न जोड़ें।
मार्गदर्शन प्रविष्टियाँ लीगेसी स्ट्रिंग हो सकती हैं, जो प्रत्येक प्रॉम्प्ट सतह पर
लागू होती हैं, या संरचित प्रविष्टियाँ हो सकती हैं:
```ts
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 कमांड के माध्यम से होता है।
### अवसंरचना
| विधि | यह क्या पंजीकृत करती है |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| `api.registerHook(events, handler, opts?)` | इवेंट हुक |
| `api.registerHttpRoute(params)` | Gateway HTTP एंडपॉइंट |
| `api.registerGatewayMethod(name, handler)` | Gateway RPC विधि |
| `api.registerGatewayDiscoveryService(service)` | स्थानीय Gateway खोज विज्ञापक |
| `api.registerCli(registrar, opts?)` | CLI उपकमांड |
| `api.registerNodeCliFeature(registrar, opts?)` | `openclaw nodes` के अंतर्गत Node सुविधा CLI |
| `api.registerService(service)` | पृष्ठभूमि सेवा |
| `api.registerInteractiveHandler(registration)` | इंटरैक्टिव हैंडलर |
| `api.registerAgentToolResultMiddleware(...)` | रनटाइम टूल-परिणाम मिडलवेयर |
| `api.registerMemoryPromptSupplement(builder)` | योगात्मक मेमोरी-समीपस्थ प्रॉम्प्ट अनुभाग |
| `api.registerMemoryPromptPreparation(prepare)` | मेमोरी-समीपस्थ प्रॉम्प्ट अनुभाग के लिए एसिंक तैयारी |
| `api.registerMemoryCorpusSupplement(adapter)` | योगात्मक मेमोरी खोज/पठन कॉर्पस |
| `api.registerHostedMediaResolver(resolver)` | ब्राउज़र-शैली के होस्टेड मीडिया URL के लिए रिज़ॉल्वर |
| `api.registerMcpServerConnectionResolver(...)` | स्थिर सर्वर नाम के लिए प्रति-अनुरोधकर्ता MCP ट्रांसपोर्ट (`url`/`headers`) |
| `api.registerTextTransforms(transforms)` | Plugin-स्वामित्व वाले प्रॉम्प्ट/संदेश संगतता टेक्स्ट पुनर्लेखन |
| `api.registerConfigMigration(migrate)` | Plugin रनटाइम लोड होने से पहले चलने वाला हल्का कॉन्फ़िग माइग्रेशन |
| `api.registerMigrationProvider(provider)` | `openclaw migrate` के लिए आयातक |
| `api.registerAutoEnableProbe(probe)` | कॉन्फ़िग जाँच जो इस Plugin को स्वतः सक्षम कर सकती है |
| `api.registerReload(registration)` | रीलोड प्रबंधन के लिए रीस्टार्ट/हॉट/नोऑप कॉन्फ़िग-प्रीफ़िक्स नीति |
| `api.registerNodeHostCommand(command)` | युग्मित Nodes के लिए उपलब्ध कमांड हैंडलर |
| `api.registerNodeInvokePolicy(policy)` | Node द्वारा इनवोक किए गए कमांड के लिए अनुमत-सूची/स्वीकृति नीति |
| `api.registerSecurityAuditCollector(collector)` | `openclaw security audit` के लिए निष्कर्ष संग्राहक |
#### अभिस्वीकृति के बाद का Webhook कार्य
जो Webhook रूट प्रसंस्करण पूरा होने से पहले अनुरोध को अभिस्वीकृत करते हैं, उन्हें
उस पृथक कार्य को उसके अपने ट्रैक किए गए प्रवेश रूट पर स्थानांतरित करना चाहिए:
```typescript
import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";
void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
runtime.error?.(`webhook प्रेषण विफल रहा: ${String(error)}`);
});
```
HTTP अनुरोध के अभी भी प्रवेशित होने के दौरान `runDetachedWebhookWork(...)` को समकालिक रूप से
कॉल करें। सहायक तुरंत एक स्वतंत्र रूट आरक्षित करता है, फिर अगली माइक्रोटास्क में
कॉलबैक शुरू करता है, ताकि अनुरोध हैंडलर पहले अपनी
अभिस्वीकृति लिख सके। लौटाया गया प्रॉमिस कॉलबैक परिणाम अपनाता है; अस्वीकृति प्रबंधन का
उत्तरदायित्व फिर भी कॉलर का है। इससे अभिस्वीकृति के बाद का कतार कार्य स्वीकार होता रहता है और
रीस्टार्ट या निलंबन ड्रेन उसके लिए प्रतीक्षा करते हैं। लौटने से पहले सभी प्रसंस्करण की
प्रतीक्षा करने वाले हैंडलरों को इस सहायक की आवश्यकता नहीं है।
#### अनुरोधकर्ता-दायरे वाले MCP कनेक्शन
MCP सर्वर **पहचान** (नाम, टूल फ़िल्टर) को `mcp.servers`, किसी
नेटिव Plugin के `mcpServers` मैनिफ़ेस्ट फ़ील्ड या किसी बंडल मैनिफ़ेस्ट में स्थिर रखें। वैकल्पिक रूप से कनेक्शन रिज़ॉल्वर पंजीकृत करें, ताकि प्रत्येक विश्वसनीय
संदेश अनुरोधकर्ता को अपना अलग ट्रांसपोर्ट मिले:
```ts
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 भी कर सकते हैं।
| विधि | वह अनुबंध जिसका स्वामित्व इसके पास है |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.session.state.registerSessionExtension(...)` | Plugin-स्वामित्व वाली, JSON-संगत सत्र स्थिति, जिसे Gateway सत्रों के माध्यम से प्रक्षेपित किया जाता है |
| `api.session.workflow.enqueueNextTurnInjection(...)` | एक सत्र के लिए अगले एजेंट टर्न में अंतःक्षेपित टिकाऊ, ठीक-एक-बार संदर्भ |
| `api.registerTrustedToolPolicy(...)` | मैनिफ़ेस्ट-नियंत्रित विश्वसनीय प्री-Plugin टूल नीति, जो टूल पैरामीटर को अवरुद्ध या पुनर्लिखित कर सकती है |
| `api.registerToolMetadata(...)` | टूल कार्यान्वयन को बदले बिना टूल कैटलॉग प्रदर्शन मेटाडेटा |
| `api.registerCommand(...)` | सीमित-दायरे वाले Plugin कमांड; कमांड परिणाम `continueAgent: true` या `suppressReply: true` सेट कर सकते हैं; Discord नेटिव कमांड `descriptionLocalizations` का समर्थन करते हैं |
| `api.session.controls.registerControlUiDescriptor(...)` | सत्र, टूल, रन, सेटिंग या टैब सतहों के लिए Control UI योगदान वर्णनकर्ता |
| `api.lifecycle.registerRuntimeLifecycle(...)` | रीसेट/हटाने/रीलोड पथों पर Plugin-स्वामित्व वाले रनटाइम संसाधनों के लिए क्लीनअप कॉलबैक |
| `api.agent.events.registerAgentEventSubscription(...)` | वर्कफ़्लो स्थिति और मॉनिटर के लिए स्वच्छ की गई ईवेंट सदस्यताएँ |
| `api.runContext.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | प्रति-रन Plugin अस्थायी स्थिति, जिसे टर्मिनल रन जीवनचक्र पर साफ़ किया जाता है |
| `api.session.workflow.registerSessionSchedulerJob(...)` | Plugin-स्वामित्व वाले शेड्यूलर जॉब के लिए क्लीनअप मेटाडेटा; यह कार्य शेड्यूल नहीं करता या टास्क रिकॉर्ड नहीं बनाता |
| `api.session.workflow.sendSessionAttachment(...)` | केवल-बंडल होस्ट-मध्यस्थ फ़ाइल अटैचमेंट वितरण, सक्रिय प्रत्यक्ष-आउटबाउंड सत्र रूट पर |
| `api.session.workflow.scheduleSessionTurn(...)` / `unscheduleSessionTurnsByTag(...)` | केवल-बंडल Cron-समर्थित शेड्यूल किए गए सत्र टर्न और टैग-आधारित क्लीनअप |
| `api.session.controls.registerSessionAction(...)` | टाइप किए गए सत्र एक्शन, जिन्हें क्लाइंट Gateway के माध्यम से डिस्पैच कर सकते हैं |
एक `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 अनुदान का अनुरोध या इसकी आवश्यकता नहीं रखते।
```typescript
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 उपभोक्ताओं के उदाहरण:
| Plugin प्रारूप | उपयोग किए गए हुक |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| अनुमोदन वर्कफ़्लो | सत्र एक्सटेंशन, कमांड निरंतरता, अगले-टर्न अंतःक्षेपण, UI वर्णनकर्ता |
| बजट/कार्यस्थान नीति गेट | विश्वसनीय टूल नीति, टूल मेटाडेटा, सत्र प्रक्षेपण |
| पृष्ठभूमि जीवनचक्र मॉनिटर | रनटाइम जीवनचक्र क्लीनअप, एजेंट ईवेंट सदस्यता, सत्र शेड्यूलर स्वामित्व/क्लीनअप, Heartbeat प्रॉम्प्ट योगदान, UI वर्णनकर्ता |
| सेटअप या ऑनबोर्डिंग विज़ार्ड | सत्र एक्सटेंशन, सीमित-दायरे वाले कमांड, Control UI वर्णनकर्ता |
आरक्षित कोर एडमिन नेमस्पेस (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) हमेशा `operator.admin` ही रहते हैं, भले ही कोई Plugin
अधिक संकीर्ण Gateway विधि स्कोप निर्दिष्ट करने का प्रयास करे। Plugin-स्वामित्व वाली विधियों के लिए
Plugin-विशिष्ट उपसर्गों को प्राथमिकता दें।
बंडल किए गए plugins और मेल खाते
मैनिफ़ेस्ट अनुबंधों वाले स्पष्ट रूप से सक्षम इंस्टॉल किए गए plugins `api.registerAgentToolResultMiddleware(...)` का उपयोग तब कर सकते हैं,
जब उन्हें निष्पादन के बाद और रनटाइम द्वारा परिणाम को मॉडल में
वापस देने से पहले टूल परिणाम को पुनर्लिखना हो। यह tokenjuice जैसे असिंक्रोनस
आउटपुट रिड्यूसर के लिए विश्वसनीय, रनटाइम-निरपेक्ष सीम है।
Plugins को प्रत्येक लक्षित
रनटाइम के लिए `contracts.agentToolResultMiddleware` घोषित करना आवश्यक है, उदाहरण के लिए `["openclaw", "codex"]`। उस
अनुबंध या स्पष्ट सक्षमता के बिना इंस्टॉल किए गए plugins यह मिडलवेयर पंजीकृत नहीं कर सकते; ऐसे कार्यों के लिए
सामान्य OpenClaw Plugin हुक रखें जिन्हें प्री-मॉडल टूल-परिणाम
समय की आवश्यकता नहीं है। पुराना
केवल-एम्बेडेड-रनर एक्सटेंशन फ़ैक्टरी पंजीकरण पथ हटा दिया गया है।
### Gateway खोज पंजीकरण
`api.registerGatewayDiscoveryService(...)` किसी Plugin को सक्रिय
Gateway का विज्ञापन mDNS/Bonjour जैसे स्थानीय खोज ट्रांसपोर्ट पर करने देता है। स्थानीय खोज सक्षम होने पर OpenClaw
Gateway स्टार्टअप के दौरान सेवा को कॉल करता है, वर्तमान
Gateway पोर्ट और गैर-गोपनीय TXT संकेत डेटा पास करता है, और Gateway शटडाउन के दौरान लौटाए गए
`stop` हैंडलर को कॉल करता है।
```typescript
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` प्रदान करें जो उस
पंजीयक द्वारा उजागर किए गए प्रत्येक शीर्ष-स्तरीय कमांड रूट को समेटते हों।
```typescript
api.registerCli(
async ({ program }) => {
const { registerMatrixCli } = await import("./src/cli.js");
registerMatrixCli({ program });
},
{
descriptors: [
{
name: "matrix",
description: "Matrix खातों, सत्यापन, डिवाइस और प्रोफ़ाइल स्थिति को प्रबंधित करें",
hasSubcommands: true,
},
],
},
);
```
नेस्टेड कमांड समाधान किए गए पैरेंट कमांड को `program` के रूप में प्राप्त करते हैं:
```typescript
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](/hi/plugins/cli-backend-plugins) देखें।
### विशिष्ट स्लॉट
| विधि | यह क्या पंजीकृत करती है |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | संदर्भ इंजन (एक समय में एक सक्रिय)। जब होस्ट मॉडल/प्रोवाइडर/मोड निदान प्रदान कर सकता है, तब जीवनचक्र कॉलबैक को `runtimeSettings` प्राप्त होता है; पुराने सख्त इंजनों को उस कुंजी के बिना पुनः आज़माया जाता है। |
| `api.registerMemoryCapability(capability)` | एकीकृत मेमोरी क्षमता |
### अप्रचलित मेमोरी एम्बेडिंग अडैप्टर
| विधि | यह क्या पंजीकृत करती है |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | सक्रिय 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 के लिए संगतता ऋण के रूप में रिपोर्ट करता है।
### इवेंट और जीवनचक्र
| विधि | यह क्या करती है |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | टाइप किया हुआ जीवनचक्र हुक |
| `api.onConversationBindingResolved(handler)` | वार्तालाप बाइंडिंग कॉलबैक |
उदाहरणों, सामान्य हुक नामों और गार्ड
सिमैंटिक्स के लिए [Plugin हुक](/hi/plugins/hooks) देखें।
### हुक निर्णय सिमैंटिक्स
`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 प्रोजेक्शन](/hi/plugins/hooks#safe-external-cron-projection) देखें।
### API ऑब्जेक्ट फ़ील्ड
| फ़ील्ड | प्रकार | विवरण |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Plugin आईडी |
| `api.name` | `string` | प्रदर्शन नाम |
| `api.version` | `string?` | Plugin संस्करण (वैकल्पिक) |
| `api.description` | `string?` | Plugin विवरण (वैकल्पिक) |
| `api.source` | `string` | Plugin स्रोत पथ |
| `api.rootDir` | `string?` | Plugin रूट डायरेक्टरी (वैकल्पिक) |
| `api.config` | `OpenClawConfig` | वर्तमान कॉन्फ़िगरेशन स्नैपशॉट (उपलब्ध होने पर सक्रिय इन-मेमोरी रनटाइम स्नैपशॉट) |
| `api.pluginConfig` | `Record` | `plugins.entries..config` से Plugin-विशिष्ट कॉन्फ़िगरेशन |
| `api.runtime` | `PluginRuntime` | [रनटाइम सहायक](/hi/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | स्कोप्ड लॉगर (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | वर्तमान लोड मोड; `"setup-runtime"` हल्की, पूर्ण-एंट्री-पूर्व स्टार्टअप/सेटअप अवधि है |
| `api.resolvePath(input)` | `(string) => string` | Plugin रूट के सापेक्ष पथ का समाधान करें |
## आंतरिक मॉड्यूल परिपाटी
अपने Plugin के भीतर, आंतरिक इंपोर्ट के लिए स्थानीय बैरल फ़ाइलों का उपयोग करें:
```text
my-plugin/
api.ts # बाहरी उपभोक्ताओं के लिए सार्वजनिक निर्यात
runtime-api.ts # केवल आंतरिक रनटाइम निर्यात
index.ts # Plugin प्रवेश बिंदु
setup-entry.ts # हल्की, केवल-सेटअप एंट्री (वैकल्पिक)
```
प्रोडक्शन कोड से कभी भी अपने स्वयं के Plugin को `openclaw/plugin-sdk/`
के माध्यम से इम्पोर्ट न करें। आंतरिक इम्पोर्ट को `./api.ts` या
`./runtime-api.ts` के माध्यम से रूट करें। SDK पथ केवल बाहरी अनुबंध है।
फ़साड द्वारा लोड किए गए बंडल 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` प्रोवाइडर बिल्डर
के साथ ऑनबोर्डिंग/कॉन्फ़िग हेल्पर एक्सपोर्ट करता है।
एक्सटेंशन के प्रोडक्शन कोड को भी `openclaw/plugin-sdk/`
इम्पोर्ट से बचना चाहिए। यदि कोई हेल्पर वास्तव में साझा है, तो दो Plugin को एक-दूसरे से जोड़ने के बजाय
उसे `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, या किसी अन्य
क्षमता-उन्मुख सरफ़ेस जैसे तटस्थ SDK सबपाथ में प्रोमोट करें।
## संबंधित
`definePluginEntry` और `defineChannelPluginEntry` विकल्प।
संपूर्ण `api.runtime` नेमस्पेस संदर्भ।
पैकेजिंग, मैनिफ़ेस्ट और कॉन्फ़िग स्कीमा।
परीक्षण यूटिलिटी और लिंट नियम।
अप्रचलित सरफ़ेस से माइग्रेट करना।
विस्तृत आर्किटेक्चर और क्षमता मॉडल।