Plugin प्रवेश बिंदु

​

पैकेज एंट्रियाँ

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions और setupEntry स्रोत एंट्रियाँ हैं, जिनका उपयोग वर्कस्पेस और git चेकआउट डेवलपमेंट के लिए किया जाता है।
• इंस्टॉल किए गए पैकेजों के लिए runtimeExtensions और runtimeSetupEntry को प्राथमिकता दी जाती है: इनसे npm पैकेज रनटाइम TypeScript कंपाइलेशन छोड़ सकते हैं।
• मौजूद होने पर runtimeExtensions की ऐरे लंबाई extensions से मेल खानी चाहिए (एंट्रियाँ स्थान के अनुसार जोड़ी जाती हैं)। runtimeSetupEntry के लिए setupEntry आवश्यक है।
• यदि कोई runtimeExtensions/runtimeSetupEntry आर्टिफ़ैक्ट घोषित है, लेकिन मौजूद नहीं है, तो इंस्टॉल/डिस्कवरी पैकेजिंग त्रुटि के साथ विफल हो जाती है; OpenClaw चुपचाप स्रोत पर फ़ॉलबैक नहीं करता। स्रोत फ़ॉलबैक (नीचे) केवल तभी लागू होता है, जब कोई रनटाइम एंट्री बिल्कुल घोषित न हो।
• यदि कोई इंस्टॉल किया गया पैकेज केवल TypeScript स्रोत एंट्री घोषित करता है, तो OpenClaw मेल खाने वाले बिल्ट dist/*.js (या .mjs/.cjs) पीयर को खोजकर उसका उपयोग करता है; अन्यथा वह TypeScript स्रोत पर फ़ॉलबैक करता है।
• सभी एंट्री पथ plugin पैकेज डायरेक्टरी के अंदर ही रहने चाहिए। रनटाइम एंट्रियाँ और अनुमानित बिल्ट-JS पीयर बाहर निकलने वाले extensions या setupEntry स्रोत पथ को मान्य नहीं बनाते।

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema वैकल्पिक है; इसे छोड़ने पर सख़्त खाली ऑब्जेक्ट स्कीमा का उपयोग होता है (जेनरेट किए गए मेनिफ़ेस्ट में फिर भी configSchema शामिल होता है)।
• execute सामान्य स्ट्रिंग या JSON-सीरियलाइज़ करने योग्य मान लौटाता है; सहायक इसे टेक्स्ट टूल रिज़ल्ट के रूप में रैप करता है, जिसमें details मूल (स्ट्रिंग में अपरिवर्तित) रिटर्न मान पर सेट होता है।
• outputSchema वैकल्पिक रूप से Code Mode और Tool Search के लिए उस मूल details मान का वर्णन करता है। कैटलॉग कॉल निष्पादन से पहले अमान्य स्कीमा अस्वीकार करते हैं और अंतिम मान लौटाने से पहले उसे सत्यापित करते हैं।
• कस्टम टूल रिज़ल्ट के लिए, openclaw/plugin-sdk/tool-results textResult और jsonResult निर्यात करता है।
• टूल नाम स्थिर होते हैं, इसलिए openclaw plugins build घोषित टूलों से contracts.tools व्युत्पन्न करता है और नामों को हाथ से दोहराने की आवश्यकता नहीं होती।
• रनटाइम लोडिंग सख़्त रहती है: इंस्टॉल किए गए plugins को फिर भी openclaw.plugin.json और package.json openclaw.extensions की आवश्यकता होती है। OpenClaw अनुपस्थित मेनिफ़ेस्ट डेटा का अनुमान लगाने के लिए कभी भी plugin कोड निष्पादित नहीं करता।

​

definePluginEntry

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id आपके openclaw.plugin.json मेनिफ़ेस्ट से मेल खाना चाहिए।
• बाहरी सेशन कैटलॉग openclaw/plugin-sdk/session-catalog और api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }) का उपयोग करते हैं। कोर sessions.catalog.* Gateway विधियों का स्वामी है; प्रोवाइडर RPC पंजीकृत किए बिना होस्ट, सेशन और सामान्यीकृत ट्रांसक्रिप्ट प्रोजेक्शन लौटाते हैं। सूची प्रोवाइडर को प्रत्येक होस्ट के पूर्ण होते ही वैकल्पिक onHost(host) कॉलबैक कॉल करना चाहिए; लौटी हुई होस्ट ऐरे अंतिम संगतता स्नैपशॉट के रूप में आवश्यक रहती है।
• kind अप्रचलित है: इसके बजाय openclaw.plugin.json मेनिफ़ेस्ट के kind फ़ील्ड में एक एक्सक्लूसिव स्लॉट ("memory" या "context-engine") घोषित करें। रनटाइम-एंट्री kind केवल पुराने plugins के लिए संगतता फ़ॉलबैक के रूप में बनी हुई है।
• लेज़ी मूल्यांकन के लिए configSchema एक फ़ंक्शन हो सकता है। OpenClaw पहली बार एक्सेस करने पर स्कीमा को रिज़ॉल्व करके मेमोइज़ करता है, इसलिए महँगे स्कीमा बिल्डर केवल एक बार चलते हैं।
• एक nodeHostCommands डिस्क्रिप्टर isAvailable({ config, env }) परिभाषित कर सकता है। false लौटाने से वह कमांड और उसकी क्षमता हेडलेस Node की Gateway घोषणा से छूट जाती है। OpenClaw इसका मूल्यांकन Node-लोकल स्टार्टअप कॉन्फ़िगरेशन के संदर्भ में करता है; कमांड हैंडलर को इनवोक किए जाने पर फिर भी उपलब्धता सत्यापित करनी चाहिए।

​

defineChannelPluginEntry

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

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime, "cli-metadata" और "tool-discovery" को छोड़कर हर मोड में चलता है। रनटाइम संदर्भ यहाँ संग्रहीत करें, आम तौर पर createPluginRuntimeStore के माध्यम से।
• registerCliMetadata, "cli-metadata", "discovery" और "full" के लिए चलता है। इसे चैनल-स्वामित्व वाले CLI डिस्क्रिप्टरों के प्रामाणिक स्थान के रूप में उपयोग करें, ताकि रूट सहायता सक्रिय न हो, डिस्कवरी स्नैपशॉट में स्थिर कमांड मेटाडेटा शामिल हो और सामान्य CLI पंजीकरण पूर्ण plugin लोड के साथ संगत बना रहे।
• registerFull केवल "full" और "tool-discovery" के लिए चलता है। "tool-discovery" के लिए यह चैनल पंजीकरण के बजाय चलता है: OpenClaw registerChannel/setRuntime को पूरी तरह छोड़ देता है और केवल registerFull कॉल करता है, इसलिए स्वतंत्र टूल डिस्कवरी या निष्पादन के लिए आपके चैनल को आवश्यक कोई भी प्रोवाइडर/टूल पंजीकरण वहाँ होना चाहिए, सामान्य चैनल सेटअप के पीछे नहीं।
• डिस्कवरी पंजीकरण निष्क्रिय होता है, इंपोर्ट-मुक्त नहीं: स्नैपशॉट बनाने के लिए OpenClaw विश्वसनीय plugin एंट्री और चैनल plugin मॉड्यूल का मूल्यांकन कर सकता है। शीर्ष-स्तरीय इंपोर्ट को दुष्प्रभाव-मुक्त रखें और सॉकेट, क्लाइंट, वर्कर और सेवाओं को केवल "full" वाले पथों के पीछे रखें।
• definePluginEntry की तरह, configSchema भी एक लेज़ी फ़ैक्टरी हो सकता है; OpenClaw पहली बार एक्सेस करने पर रिज़ॉल्व किए गए स्कीमा को मेमोइज़ करता है।

• Plugin-स्वामित्व वाले रूट CLI कमांड के लिए api.registerCli(..., { descriptors: [...] }) का उपयोग करें, जिन्हें आप रूट CLI पार्स ट्री से गायब किए बिना लेज़ी-लोड करना चाहते हैं। डिस्क्रिप्टर नामों का मिलान अक्षरों, संख्याओं, हाइफ़न और अंडरस्कोर से होना चाहिए और शुरुआत किसी अक्षर या संख्या से होनी चाहिए; OpenClaw अन्य प्रारूपों को अस्वीकार करता है और सहायता रेंडर करने से पहले विवरणों से टर्मिनल नियंत्रण अनुक्रम हटा देता है। रजिस्ट्रार द्वारा प्रदर्शित प्रत्येक शीर्ष-स्तरीय कमांड रूट को कवर करें। अकेला commands तत्पर संगतता पथ पर रहता है।
• युग्मित-Node सुविधा कमांड के लिए api.registerNodeCliFeature(...) का उपयोग करें, ताकि वे openclaw nodes के अंतर्गत आएँ (registerCli(registrar, { parentPath: ["nodes"], ... }) के समतुल्य)।
• अन्य नेस्टेड Plugin कमांड के लिए, parentPath जोड़ें और रजिस्ट्रार को दिए गए program ऑब्जेक्ट पर कमांड पंजीकृत करें; Plugin को कॉल करने से पहले OpenClaw इसे पैरेंट कमांड में रिज़ॉल्व करता है।
• चैनल Plugin के लिए, CLI डिस्क्रिप्टर registerCliMetadata से पंजीकृत करें और registerFull को केवल रनटाइम कार्य पर केंद्रित रखें।
• यदि registerFull Gateway RPC विधियाँ भी पंजीकृत करता है, तो उन्हें Plugin-विशिष्ट प्रीफ़िक्स पर रखें। आरक्षित कोर एडमिन नेमस्पेस (config.*, exec.approvals.*, wizard.*, update.*) को हमेशा operator.admin में परिवर्तित किया जाता है।

​

defineSetupPluginEntry

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

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* सेटअप-सुरक्षित रूट */
      },
    });
  },
});

​

पंजीकरण मोड

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // केवल-क्षमता सतहें (प्रदाता/टूल) पंजीकृत करें, चैनल नहीं।
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // भारी केवल-रनटाइम पंजीकरण
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

Plugin प्रारूप

​

संबंधित

• SDK अवलोकन - पंजीकरण API और उपपथ संदर्भ
• रनटाइम सहायक - api.runtime और createPluginRuntimeStore
• सेटअप और कॉन्फ़िगरेशन - मैनिफ़ेस्ट, सेटअप एंट्री, स्थगित लोडिंग
• चैनल Plugin - ChannelPlugin ऑब्जेक्ट बनाना
• प्रदाता Plugin - प्रदाता पंजीकरण और हुक