Plugin आर्किटेक्चर के आंतरिक तंत्र

​

लोड पाइपलाइन

1. संभावित Plugin रूट खोजता है
2. नेटिव या संगत बंडल मैनिफ़ेस्ट और पैकेज मेटाडेटा पढ़ता है
3. असुरक्षित उम्मीदवारों को अस्वीकार करता है
4. Plugin कॉन्फ़िग को सामान्यीकृत करता है (plugins.enabled, allow, deny, entries, slots, load.paths)
5. प्रत्येक उम्मीदवार को सक्षम करना है या नहीं, यह तय करता है
6. सक्षम नेटिव मॉड्यूल लोड करता है: निर्मित बंडल मॉड्यूल नेटिव लोडर का उपयोग करते हैं; तृतीय-पक्ष स्थानीय स्रोत TypeScript आपातकालीन Jiti फ़ॉलबैक का उपयोग करता है
7. नेटिव register(api) हुक कॉल करता है और पंजीकरणों को Plugin रजिस्ट्री में एकत्र करता है
8. रजिस्ट्री को कमांड/रनटाइम सतहों के लिए उपलब्ध कराता है

• उसकी रिज़ॉल्व की गई एंट्री Plugin रूट से बाहर निकलती है
• उसका पथ (या उसकी रूट डायरेक्टरी) सभी उपयोगकर्ताओं द्वारा लिखने योग्य है
• गैर-बंडल Plugin के लिए, पथ का स्वामित्व वर्तमान uid (या root) से मेल नहीं खाता

​

मैनिफ़ेस्ट-प्रथम व्यवहार

• Plugin की पहचान करना
• घोषित चैनल/Skills/कॉन्फ़िग स्कीमा या बंडल क्षमताएँ खोजना
• plugins.entries.<id>.config को सत्यापित करना
• Control UI लेबल/प्लेसहोल्डर को विस्तृत करना
• इंस्टॉल/कैटलॉग मेटाडेटा दिखाना
• Plugin रनटाइम लोड किए बिना हल्के सक्रियण और सेटअप विवरण सुरक्षित रखना

• CLI लोडिंग उन Plugin तक सीमित होती है जिनके स्वामित्व में अनुरोधित प्राथमिक कमांड है
• चैनल सेटअप/Plugin रिज़ॉल्यूशन उन Plugin तक सीमित होता है जिनके स्वामित्व में अनुरोधित चैनल id है
• स्पष्ट प्रोवाइडर सेटअप/रनटाइम रिज़ॉल्यूशन उन Plugin तक सीमित होता है जिनके स्वामित्व में अनुरोधित प्रोवाइडर id है
• Gateway स्टार्टअप योजना स्पष्ट स्टार्टअप इंपोर्ट के लिए activation.onStartup का उपयोग करती है; स्टार्टअप मेटाडेटा रहित Plugin केवल अधिक सीमित सक्रियण ट्रिगर के माध्यम से लोड होते हैं

​

Plugin कैश सीमा

• PluginLoaderCacheState और संगत सक्रिय रनटाइम रजिस्ट्रियाँ
• समान रनटाइम सतह को बार-बार इंपोर्ट करने से बचने के लिए उपयोग किए जाने वाले jiti/मॉड्यूल कैश और सार्वजनिक-सतह लोडर कैश
• इंस्टॉल की गई Plugin कलाकृतियों के लिए फ़ाइलसिस्टम कैश
• पथ सामान्यीकरण या डुप्लिकेट रिज़ॉल्यूशन के लिए अल्पकालिक प्रति-कॉल मैप

• डिस्कवरी परिणाम
• प्रत्यक्ष मैनिफ़ेस्ट रजिस्ट्रियाँ
• इंस्टॉल किए गए Plugin इंडेक्स से पुनर्निर्मित मैनिफ़ेस्ट रजिस्ट्रियाँ
• प्रोवाइडर स्वामी लुकअप, मॉडल दमन, प्रोवाइडर नीति या सार्वजनिक-कलाकृति मेटाडेटा
• मैनिफ़ेस्ट से निकला कोई भी अन्य उत्तर, जहाँ परिवर्तित मैनिफ़ेस्ट, इंस्टॉल किया गया इंडेक्स या लोड पथ अगली मेटाडेटा रीड पर दिखाई देना चाहिए

​

रजिस्ट्री मॉडल

• Plugin मॉड्यूल -> रजिस्ट्री पंजीकरण
• कोर रनटाइम -> रजिस्ट्री उपभोग

​

वार्तालाप बाइंडिंग कॉलबैक

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // अब इस Plugin + वार्तालाप के लिए एक बाइंडिंग मौजूद है।
        console.log(event.binding?.conversationId);
        return;
      }

      // अनुरोध अस्वीकार कर दिया गया था; कोई भी स्थानीय लंबित स्थिति साफ़ करें।
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" या "denied"
• decision: "allow-once", "allow-always" या "deny"
• binding: स्वीकृत अनुरोधों के लिए रिज़ॉल्व की गई बाइंडिंग
• request: मूल अनुरोध सारांश, अलग करने का संकेत, प्रेषक id और वार्तालाप मेटाडेटा

​

प्रोवाइडर रनटाइम हुक

• रनटाइम से पहले हल्के लुकअप के लिए मैनिफ़ेस्ट मेटाडेटा: setup.providers[].envVars, providerAuthAliases, providerAuthChoices और channelConfigs।
• कॉन्फ़िग-समय हुक: catalog तथा applyConfigDefaults।
• रनटाइम हुक: प्रमाणीकरण, मॉडल रिज़ॉल्यूशन, स्ट्रीम रैपिंग, चिंतन स्तर, रीप्ले नीति और उपयोग एंडपॉइंट को कवर करने वाले 40+ वैकल्पिक हुक। हुक क्रम और उपयोग देखें।

​

हुक क्रम और उपयोग

​

प्रोवाइडर उदाहरण

api.registerProvider({
  id: "example-proxy",
  label: "उदाहरण प्रॉक्सी",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "स्वचालित" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

अंतर्निहित उदाहरण

​

रनटाइम सहायक

const clip = await api.runtime.tts.textToSpeech({
  text: "OpenClaw की ओर से नमस्ते",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "OpenClaw की ओर से नमस्ते",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech फ़ाइल/वॉइस-नोट सतहों के लिए सामान्य कोर TTS आउटपुट पेलोड लौटाता है।
• कोर tts कॉन्फ़िगरेशन और प्रोवाइडर चयन का उपयोग करता है।
• PCM ऑडियो बफ़र + सैंपल दर लौटाता है। Plugins को प्रोवाइडरों के लिए पुनः सैंपल/एनकोड करना होगा।
• listVoices प्रत्येक प्रोवाइडर के लिए वैकल्पिक है। विक्रेता-स्वामित्व वाले वॉइस चयनकर्ताओं या सेटअप प्रवाहों के लिए इसका उपयोग करें।
• कोर प्रोवाइडर listVoices हुक को समाधान की गई अनुरोध समय-सीमा देता है; प्रोवाइडर-विशिष्ट टाइमआउट सेटिंग इसे ओवरराइड कर सकती हैं।
• वॉइस सूचियों में प्रोवाइडर-सजग चयनकर्ताओं के लिए स्थान-विशेष, लिंग और व्यक्तित्व टैग जैसे अधिक समृद्ध मेटाडेटा शामिल हो सकते हैं।
• OpenAI और ElevenLabs वर्तमान में टेलीफ़ोनी का समर्थन करते हैं। Microsoft नहीं करता।

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme स्पीच",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• TTS नीति, फ़ॉलबैक और उत्तर वितरण को कोर में रखें।
• विक्रेता-स्वामित्व वाले सिंथेसिस व्यवहार के लिए स्पीच प्रोवाइडरों का उपयोग करें।
• पुराने Microsoft edge इनपुट को microsoft प्रोवाइडर आईडी में सामान्यीकृत किया जाता है।
• पसंदीदा स्वामित्व मॉडल कंपनी-उन्मुख है: जैसे-जैसे OpenClaw इन क्षमता अनुबंधों को जोड़ता है, एक विक्रेता Plugin टेक्स्ट, स्पीच, इमेज और भविष्य के मीडिया प्रोवाइडरों का स्वामित्व ले सकता है।

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• ऑर्केस्ट्रेशन, फ़ॉलबैक, कॉन्फ़िगरेशन और चैनल वायरिंग को कोर में रखें।
• विक्रेता व्यवहार को प्रोवाइडर Plugin में रखें।
• योगात्मक विस्तार टाइप किया हुआ रहना चाहिए: नई वैकल्पिक विधियाँ, नए वैकल्पिक परिणाम फ़ील्ड, नई वैकल्पिक क्षमताएँ।
• वीडियो जनरेशन पहले से इसी पैटर्न का पालन करता है:
  • कोर क्षमता अनुबंध और रनटाइम सहायक का स्वामी है
  • विक्रेता Plugins api.registerVideoGenerationProvider(...) पंजीकृत करते हैं
  • फ़ीचर/चैनल Plugins api.runtime.videoGeneration.* का उपयोग करते हैं

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "मुद्रित फ़ील्ड को सत्य का स्रोत मानें।" },
  ],
  instructions: "इकाइयाँ और खोजने योग्य टैग लौटाएँ।",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // जब MIME का विश्वसनीय रूप से अनुमान न लगाया जा सके, तब वैकल्पिक:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* इमेज/ऑडियो/वीडियो समझ के लिए पसंदीदा साझा सतह है।
• extractStructuredWithModel(...) सीमित प्रोवाइडर-स्वामित्व वाले, इमेज-प्रथम निष्कर्षण के लिए Plugin-सामना करने वाला सीमांत है। कम-से-कम एक इमेज इनपुट शामिल करें; टेक्स्ट इनपुट पूरक संदर्भ हैं। उत्पाद Plugins अपने रूट और स्कीमा के स्वामी हैं, जबकि OpenClaw प्रोवाइडर/रनटाइम सीमा का स्वामी है।
• कोर मीडिया-समझ ऑडियो कॉन्फ़िगरेशन (tools.media.audio) और प्रोवाइडर फ़ॉलबैक क्रम का उपयोग करता है।
• जब कोई ट्रांसक्रिप्शन आउटपुट उत्पन्न नहीं होता (उदाहरण के लिए छोड़ा गया/असमर्थित इनपुट), तब { text: undefined } लौटाता है।

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "इस क्वेरी को केंद्रित अनुवर्ती खोजों में विस्तृत करें।",
  toolsAlsoAllow: ["my_plugin_progress"],
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider और model प्रत्येक रन के वैकल्पिक ओवरराइड हैं, स्थायी सत्र परिवर्तन नहीं।
• toolsAlsoAllow कॉल करने वाले Plugin द्वारा पंजीकृत सटीक, विशिष्ट स्वामित्व वाले टूल नाम स्वीकार करता है। कोर और अस्पष्ट नाम अस्वीकार किए जाते हैं। यह सामान्य प्रोफ़ाइल के अतिरिक्त है, लेकिन ऑपरेटर की अनुमति-सूचियाँ और निषेध प्रामाणिक बने रहते हैं।
• OpenClaw केवल विश्वसनीय कॉलरों के लिए उन ओवरराइड फ़ील्ड का सम्मान करता है।
• Plugin-स्वामित्व वाले फ़ॉलबैक रन के लिए, ऑपरेटरों को plugins.entries.<id>.subagent.allowModelOverride: true के साथ स्पष्ट रूप से सहमति देनी होगी।
• विश्वसनीय Plugins को विशिष्ट कैनोनिकल provider/model लक्ष्यों तक सीमित करने के लिए plugins.entries.<id>.subagent.allowedModels, या किसी भी लक्ष्य को स्पष्ट रूप से अनुमति देने के लिए "*" का उपयोग करें।
• अविश्वसनीय Plugin सबएजेंट रन फिर भी काम करते हैं, लेकिन ओवरराइड अनुरोध चुपचाप फ़ॉलबैक करने के बजाय अस्वीकार किए जाते हैं।
• Plugin द्वारा बनाए गए सबएजेंट सत्रों को बनाने वाले Plugin की आईडी से टैग किया जाता है। फ़ॉलबैक api.runtime.subagent.deleteSession(...) केवल उन स्वामित्व वाले सत्रों को हटा सकता है; मनमाना सत्र हटाने के लिए अब भी व्यवस्थापक-स्कोप वाला Gateway अनुरोध आवश्यक है।

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw Plugin रनटाइम सहायक",
    count: 5,
  },
});

• प्रोवाइडर चयन, क्रेडेंशियल समाधान और साझा अनुरोध अर्थविज्ञान को कोर में रखें।
• विक्रेता-विशिष्ट खोज ट्रांसपोर्ट के लिए वेब-खोज प्रोवाइडरों का उपयोग करें।
• api.runtime.webSearch.* उन फ़ीचर/चैनल Plugins के लिए पसंदीदा साझा सतह है जिन्हें एजेंट टूल रैपर पर निर्भर हुए बिना खोज व्यवहार चाहिए।

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "एक मित्रवत लॉब्स्टर शुभंकर", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): कॉन्फ़िगर की गई इमेज-जेनरेशन प्रदाता शृंखला का उपयोग करके एक इमेज जनरेट करें।
• listProviders(...): उपलब्ध इमेज-जेनरेशन प्रदाताओं और उनकी क्षमताओं की सूची दिखाएँ।

​

Gateway HTTP रूट

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: Gateway HTTP सर्वर के अंतर्गत रूट पथ।
• auth: आवश्यक, "gateway" या "plugin"। सामान्य Gateway प्रमाणीकरण आवश्यक बनाने के लिए "gateway" या Plugin-प्रबंधित प्रमाणीकरण/Webhook सत्यापन के लिए "plugin" का उपयोग करें।
• match: वैकल्पिक। "exact" (डिफ़ॉल्ट) या "prefix"।
• handleUpgrade: उसी रूट पर WebSocket अपग्रेड अनुरोधों के लिए वैकल्पिक हैंडलर।
• replaceExisting: वैकल्पिक। उसी Plugin को अपना मौजूदा रूट पंजीकरण बदलने देता है।
• handler: जब रूट ने अनुरोध संभाल लिया हो, तब true लौटाएँ।

• api.registerHttpHandler(...) हटा दिया गया है और इससे Plugin-लोड त्रुटि होगी। इसके बजाय api.registerHttpRoute(...) का उपयोग करें।
• Plugin रूट को auth स्पष्ट रूप से घोषित करना होगा।
• सटीक path + match विरोध तब तक अस्वीकार किए जाते हैं, जब तक replaceExisting: true न हो, और कोई Plugin किसी अन्य Plugin के रूट को नहीं बदल सकता।
• अलग-अलग auth स्तरों वाले ओवरलैपिंग रूट अस्वीकार किए जाते हैं। exact/prefix फ़ॉलथ्रू शृंखलाओं को केवल समान प्रमाणीकरण स्तर पर रखें।
• auth: "plugin" रूट को ऑपरेटर रनटाइम स्कोप अपने-आप नहीं मिलते। वे Plugin-प्रबंधित Webhook/हस्ताक्षर सत्यापन के लिए हैं, विशेषाधिकार-प्राप्त Gateway सहायक कॉल के लिए नहीं।
• auth: "gateway" रूट Gateway अनुरोध रनटाइम स्कोप के भीतर चलते हैं। डिफ़ॉल्ट सतह (gatewayRuntimeScopeSurface: "write-default") जानबूझकर सीमित है:
  • साझा-सीक्रेट बेयरर प्रमाणीकरण (gateway.auth.mode = "token" / "password") और किसी भी गैर-विश्वसनीय-प्रॉक्सी प्रमाणीकरण विधि को केवल एक operator.write स्कोप मिलता है, भले ही कॉलर x-openclaw-scopes भेजे
  • स्पष्ट x-openclaw-scopes हेडर के बिना trusted-proxy कॉलर भी पुरानी केवल-operator.write सतह बनाए रखते हैं
  • x-openclaw-scopes भेजने वाले trusted-proxy कॉलर को इसके बजाय घोषित स्कोप मिलते हैं
  • पहचान-युक्त प्रमाणीकरण मोड के लिए x-openclaw-scopes का हमेशा सम्मान करने हेतु कोई रूट gatewayRuntimeScopeSurface: "trusted-operator" चुन सकता है (हेडर अनुपस्थित होने पर पूर्ण CLI डिफ़ॉल्ट स्कोप सेट का उपयोग किया जाता है)
• auth: "gateway" रूट द्वारा समर्थित सैंडबॉक्स किए गए बाहरी Control UI टैब, केवल प्रमाणित बूटस्ट्रैप द्वारा जारी अल्पकालिक हस्ताक्षरित कुकी अनुदान का उपयोग करते हैं; Plugin-प्रमाणीकरण टैब अपना सीधा iframe पथ बनाए रखते हैं। माउंट करने से पहले, पैरेंट उसी अपारदर्शी सैंडबॉक्स में रूट-स्वामित्व वाली जाँच चलाता है और ब्राउज़र की गोपनीयता नीति द्वारा कुकी अवरुद्ध होने पर फ़ेल-क्लोज़ करता है। अनुदान स्वामी Plugin, मेल खाने वाले रूट रूट और वर्तमान प्रमाणीकरण जनरेशन से बँधा होता है; इसका प्रक्रिया-यादृच्छिक कुकी नाम समान होस्ट के विश्वसनीय Gateways को एक-दूसरे को अधिलेखित करने से रोकता है, लेकिन कुकी कभी भी TCP पोर्ट को अलग नहीं करती। इसलिए Gateway होस्टनेम एक क्रेडेंशियल सीमा है: उस होस्टनेम पर अलग-अलग पोर्ट सहित, परस्पर अविश्वसनीय सेवाओं को सह-होस्ट न करें। रूट डिस्पैच किसी अन्य Plugin के स्वामित्व वाले नेस्टेड रूट के विरुद्ध पुनः उपयोग को अस्वीकार करता है। चूँकि कुकी के संदर्भ में सैंडबॉक्स वंशज क्रॉस-साइट होते हैं, इसलिए अनुदान केवल operator.read के साथ GET और HEAD स्वीकार करता है; म्यूटेशन और WebSocket अपग्रेड स्पष्ट Gateway-प्रमाणित सतहों पर बने रहते हैं। कुकी जानबूझकर CHIPS का उपयोग नहीं कर सकती: वर्तमान ब्राउज़र विभाजन कुंजी में क्रॉस-साइट-पूर्वज बिट शामिल करते हैं, इसलिए नेस्टेड अपारदर्शी सैंडबॉक्स फ़्रेम समान-रूट एसेट की पहुँच खो देंगे। कुकी के लिए सुरक्षित कॉन्टेक्स्ट और क्रॉस-साइट कुकी हेतु ब्राउज़र अनुमति आवश्यक है, इसलिए Gateway-प्रमाणीकरण वाले बाहरी टैब सामान्य-HTTP LAN मूल पर या तृतीय-पक्ष कुकी पूर्णतः अवरुद्ध होने पर उपलब्ध नहीं होते; संगत कुकी नीति के साथ HTTPS/Tailscale Serve या ब्राउज़र-विश्वसनीय लूपबैक का उपयोग करें।
• अनुदान Gateway बेयरर-टोकन के प्रकटीकरण और आकस्मिक रूट/स्कोप पुनः उपयोग को रोकता है; यह नेटिव Plugins के बीच सुरक्षा सीमा नहीं बनाता। नेटिव Plugin कोड और उसके द्वारा प्रदान की जाने वाली UI सामग्री उसी विश्वसनीय इन-प्रोसेस Plugin सीमा का हिस्सा बने रहते हैं।
• व्यावहारिक नियम: यह न मानें कि Gateway-प्रमाणीकरण वाला Plugin रूट अप्रत्यक्ष एडमिन सतह है। यदि आपके रूट को केवल-एडमिन व्यवहार चाहिए, तो trusted-operator स्कोप सतह चुनें, पहचान-युक्त प्रमाणीकरण मोड आवश्यक बनाएँ और स्पष्ट x-openclaw-scopes हेडर अनुबंध का दस्तावेज़ीकरण करें।
• रूट मिलान और प्रमाणीकरण के बाद, सामान्य हैंडलर Gateway रूट-वर्क प्रवेश में भाग लेते हैं। तैयार हो रहा या पुनः आरंभ हो रहा Gateway हैंडलर को चलाने से पहले 503 लौटाता है। इसका सीमित अपवाद मैनिफ़ेस्ट-अधिकृत auth: "gateway" रूट है, जो रूट-विशिष्ट trusted-operator सतह भी चुनता है; वह पहुँच योग्य रहता है, ताकि निलंबन नियंत्रण डिस्पैच अटक न जाए, जबकि उसी Plugin के सामान्य सहोदर रूट प्रवेश सीमा के पीछे रहते हैं। WebSocket handleUpgrade स्वामित्व समान परमाण्विक प्रवेश सीमा का उपयोग करता है; हैंडलर द्वारा सॉकेट स्वीकार किए जाने के बाद, सॉकेट का आगामी जीवनकाल Plugin-स्वामित्व वाला होता है और इस सीमा द्वारा ट्रैक नहीं किया जाता।

​

Plugin SDK इंपोर्ट पथ

• index.js — बंडल किए गए Plugin की एंट्री
• api.js — सहायक/टाइप बैरल
• runtime-api.js — केवल-रनटाइम बैरल
• setup-entry.js — सेटअप Plugin एंट्री

​

संदेश टूल स्कीमा

• अर्थपूर्ण प्रस्तुति ब्लॉक (text, context, divider, chart, table, buttons, select) के लिए presentation
• पिन की गई डिलीवरी अनुरोधों के लिए delivery-pin

​

चैनल लक्ष्य समाधान

• messaging.inferTargetChatType({ to }) तय करता है कि डायरेक्टरी लुकअप से पहले सामान्यीकृत लक्ष्य को direct, group, या channel के रूप में माना जाना चाहिए।
• messaging.targetResolver.looksLikeId(raw, normalized) कोर को बताता है कि किसी इनपुट को डायरेक्टरी खोज के बजाय सीधे आईडी-जैसे समाधान पर जाना चाहिए या नहीं।
• messaging.targetResolver.reservedLiterals उन स्वतंत्र शब्दों को सूचीबद्ध करता है जो उस प्रदाता के लिए चैनल/सेशन संदर्भ हैं। समाधान आरक्षित लिटरल अस्वीकार करने से पहले कॉन्फ़िगर की गई डायरेक्टरी प्रविष्टियों को बनाए रखता है, फिर डायरेक्टरी में मिलान न मिलने पर फ़ेल-क्लोज़ करता है।
• messaging.targetResolver.resolveTarget(...) तब Plugin फ़ॉलबैक होता है, जब सामान्यीकरण या डायरेक्टरी में मिलान न मिलने के बाद कोर को अंतिम प्रदाता-स्वामित्व वाले समाधान की आवश्यकता होती है।
• messaging.resolveOutboundSessionRoute(...) लक्ष्य हल हो जाने के बाद प्रदाता-विशिष्ट सेशन रूट निर्माण का स्वामित्व रखता है।

• पीयर/ग्रुप खोजने से पहले होने वाले श्रेणी निर्णयों के लिए inferTargetChatType का उपयोग करें।
• “इसे स्पष्ट/नेटिव लक्ष्य आईडी मानें” जाँच के लिए looksLikeId का उपयोग करें।
• प्रदाता-विशिष्ट सामान्यीकरण फ़ॉलबैक के लिए resolveTarget का उपयोग करें, व्यापक डायरेक्टरी खोज के लिए नहीं।
• चैट आईडी, थ्रेड आईडी, JID, हैंडल और रूम आईडी जैसी प्रदाता-नेटिव आईडी को सामान्य SDK फ़ील्ड में नहीं, बल्कि target मानों या प्रदाता-विशिष्ट पैरामीटर में रखें।

​

कॉन्फ़िगरेशन-समर्थित डायरेक्टरियाँ

• अनुमति-सूची द्वारा संचालित DM पीयर
• कॉन्फ़िगर किए गए चैनल/ग्रुप मैप
• अकाउंट-स्कोप वाले स्थिर डायरेक्टरी फ़ॉलबैक

• क्वेरी फ़िल्टरिंग
• सीमा लागू करना
• डुप्लिकेट हटाने/सामान्यीकरण के सहायक
• ChannelDirectoryEntry[] बनाना

​

प्रदाता कैटलॉग

• { provider } एक प्रदाता प्रविष्टि के लिए
• { providers } एकाधिक प्रदाता प्रविष्टियों के लिए

• simple: सामान्य API-कुंजी या परिवेश-संचालित प्रदाता
• profile: प्रमाणीकरण प्रोफ़ाइल मौजूद होने पर दिखाई देने वाले प्रदाता
• paired: एकाधिक संबंधित प्रदाता प्रविष्टियाँ संश्लेषित करने वाले प्रदाता
• late: अन्य निहित प्रदाताओं के बाद अंतिम चरण

• discovery अभी भी विरासती उपनाम के रूप में काम करता है, लेकिन अप्रचलन चेतावनी देता है
• यदि catalog और discovery दोनों पंजीकृत हैं, तो OpenClaw catalog का उपयोग करता है और चेतावनी देता है
• augmentModelCatalog अप्रचलित है; बंडल किए गए प्रदाताओं को registerModelCatalogProvider के माध्यम से पूरक पंक्तियाँ प्रकाशित करनी चाहिए

​

केवल-पढ़ने योग्य चैनल निरीक्षण

• resolveAccount(...) रनटाइम मार्ग है। यह मान सकता है कि क्रेडेंशियल पूरी तरह साकार हो चुके हैं और आवश्यक सीक्रेट अनुपलब्ध होने पर तुरंत विफल हो सकता है।
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, और डॉक्टर/कॉन्फ़िगरेशन सुधार प्रवाह जैसे केवल-पढ़ने योग्य कमांड मार्गों को केवल कॉन्फ़िगरेशन का वर्णन करने के लिए रनटाइम क्रेडेंशियल साकार करने की आवश्यकता नहीं होनी चाहिए।

• केवल वर्णनात्मक खाता स्थिति लौटाएँ।
• enabled और configured को सुरक्षित रखें।
• प्रासंगिक होने पर क्रेडेंशियल स्रोत/स्थिति फ़ील्ड शामिल करें, जैसे:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• केवल केवल-पढ़ने योग्य उपलब्धता की रिपोर्ट करने के लिए आपको अपरिष्कृत टोकन मान लौटाने की आवश्यकता नहीं है। स्थिति-शैली कमांडों के लिए tokenStatus: "available" (और उससे मेल खाता स्रोत फ़ील्ड) लौटाना पर्याप्त है।
• जब कोई क्रेडेंशियल SecretRef के माध्यम से कॉन्फ़िगर हो, लेकिन वर्तमान कमांड मार्ग में अनुपलब्ध हो, तब configured_unavailable का उपयोग करें।

​

पैकेज पैक

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• स्वयं चैनल पंजीकरण
• Gateway के सुनना शुरू करने से पहले उपलब्ध होना आवश्यक कोई भी HTTP रूट
• उसी अवधि में मौजूद होना आवश्यक कोई भी Gateway विधि, टूल या सेवा

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

चैनल कैटलॉग मेटाडेटा

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (स्वयं-होस्ट किया गया)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Nextcloud Talk Webhook बॉट के माध्यम से स्वयं-होस्ट की गई चैट।",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: अधिक समृद्ध कैटलॉग/स्थिति सतहों के लिए द्वितीयक लेबल
• docsLabel: दस्तावेज़ लिंक के लिए लिंक पाठ ओवरराइड करें
• preferOver: कम प्राथमिकता वाली Plugin/चैनल आईडी जिनसे इस कैटलॉग प्रविष्टि को ऊपर रहना चाहिए
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: चयन-सतह पाठ नियंत्रण
• markdownCapable: आउटबाउंड स्वरूपण निर्णयों के लिए चैनल को Markdown-सक्षम चिह्नित करता है
• exposure.configured: false पर सेट होने पर चैनल को कॉन्फ़िगर किए गए चैनलों की सूची सतहों से छिपाता है
• exposure.setup: false पर सेट होने पर चैनल को इंटरैक्टिव सेटअप/कॉन्फ़िगरेशन चयनकर्ताओं से छिपाता है
• exposure.docs: दस्तावेज़ नेविगेशन सतहों के लिए चैनल को आंतरिक/निजी चिह्नित करता है
• quickstartAllowFrom: चैनल को मानक त्वरित-आरंभ allowFrom प्रवाह में शामिल करता है
• forceAccountBinding: केवल एक खाता मौजूद होने पर भी स्पष्ट खाता बाइंडिंग आवश्यक करता है
• preferSessionLookupForAnnounceTarget: घोषणा लक्ष्य हल करते समय सत्र खोज को प्राथमिकता देता है

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

संदर्भ इंजन plugins

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

नई क्षमता जोड़ना

1. कोर अनुबंध परिभाषित करें। तय करें कि साझा व्यवहार के किन हिस्सों का स्वामित्व कोर के पास होना चाहिए: नीति, फ़ॉलबैक, कॉन्फ़िगरेशन मर्ज, जीवनचक्र, चैनल-संबंधी सिमैंटिक्स और रनटाइम हेल्पर का आकार।
2. टाइपयुक्त Plugin पंजीकरण/रनटाइम सतहें जोड़ें। सबसे छोटी उपयोगी टाइपयुक्त क्षमता सतह के साथ OpenClawPluginApi और/या api.runtime का विस्तार करें।
3. कोर + चैनल/फ़ीचर उपभोक्ताओं को जोड़ें। चैनलों और फ़ीचर Plugins को किसी विक्रेता कार्यान्वयन को सीधे इंपोर्ट करने के बजाय कोर के माध्यम से नई क्षमता का उपयोग करना चाहिए।
4. विक्रेता कार्यान्वयन पंजीकृत करें। इसके बाद विक्रेता Plugins अपने बैकएंड को क्षमता के साथ पंजीकृत करते हैं।
5. अनुबंध कवरेज जोड़ें। परीक्षण जोड़ें, ताकि स्वामित्व और पंजीकरण का आकार समय के साथ स्पष्ट बना रहे।

​

क्षमता चेकलिस्ट

• src/<capability>/types.ts में कोर अनुबंध प्रकार
• src/<capability>/runtime.ts में कोर रनर/रनटाइम हेल्पर
• src/plugins/types.ts में Plugin API पंजीकरण सतह
• src/plugins/registry.ts में Plugin रजिस्ट्री वायरिंग
• जब फ़ीचर/चैनल Plugins को इसका उपयोग करना हो, तब src/plugins/runtime/* में Plugin रनटाइम एक्सपोज़र
• src/test-utils/plugin-registration.ts में कैप्चर/परीक्षण हेल्पर
• src/plugins/contracts/registry.ts में स्वामित्व/अनुबंध अभिकथन
• docs/ में ऑपरेटर/Plugin दस्तावेज़

​

क्षमता टेम्पलेट

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• क्षमता अनुबंध + ऑर्केस्ट्रेशन का स्वामित्व कोर के पास है
• विक्रेता कार्यान्वयनों का स्वामित्व विक्रेता Plugins के पास है
• फ़ीचर/चैनल Plugins रनटाइम हेल्पर का उपयोग करते हैं
• अनुबंध परीक्षण स्वामित्व को स्पष्ट बनाए रखते हैं

​

संबंधित

• Plugin आर्किटेक्चर — सार्वजनिक क्षमता मॉडल और आकार
• Plugin SDK उपपथ
• Plugin SDK सेटअप
• Plugins बनाना