Plugin सेटअप और कॉन्फ़िगरेशन

Plugin पैकेजिंग (package.json मेटाडेटा), मैनिफ़ेस्ट (openclaw.plugin.json), सेटअप प्रविष्टियों और कॉन्फ़िग स्कीमा के लिए संदर्भ।

पैकेज मेटाडेटा

आपके package.json में एक openclaw फ़ील्ड होना आवश्यक है, जो Plugin सिस्टम को बताता है कि आपका Plugin क्या प्रदान करता है:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "मेरा चैनल",      "blurb": "चैनल का संक्षिप्त विवरण।"    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

openclaw फ़ील्ड

openclaw.channel

openclaw.channel रनटाइम लोड होने से पहले चैनल खोज और सेटअप सतहों के लिए कम लागत वाला पैकेज मेटाडेटा है।

चैनल-स्वामित्व वाले सेटअप फ़ील्ड

चैनल Plugin को defineChannelSetupContract(...) के साथ रनटाइम कोड में सेटअप फ़ील्ड एक बार परिभाषित करने चाहिए और openclaw.channel.setup.fields के अंतर्गत उनका संगत क्रमांकन-योग्य प्रक्षेपण प्रकाशित करना चाहिए। रनटाइम परिभाषा Plugin-स्थानीय इनपुट प्रकार का अनुमान लगाती है, निर्देशित और गैर-इंटरैक्टिव दोनों मानों को पार्स करती है और चैनल-विशिष्ट कुंजियों को कोर प्रकारों से बाहर रखती है। पैकेज मेटाडेटा openclaw channels add <channel-id> --help और openclaw channels add --channel <channel-id> --help को Plugin लोड किए बिना केवल चयनित चैनल के विकल्प खोजने देता है।

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "सेवा एंडपॉइंट" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "ट्रांसपोर्ट स्वामी" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "सेवा एंडपॉइंट" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "ट्रांसपोर्ट स्वामी" }          }        ]      }    }  }}

समर्थित फ़ील्ड प्रकार string, boolean, integer, string-list और choice हैं। क्रेडेंशियल के लिए sensitive: true का उपयोग करें। प्रत्येक फ़ील्ड कुंजी अपने दीर्घ CLI फ़्लैग के camelCased एट्रिब्यूट नाम के बराबर होनी चाहिए, जिसमें कोई निषेधात्मक रूप भी शामिल है, जैसे --api-token के लिए apiToken। जब सकारात्मक और --no-* दोनों रूप आवश्यक हों, तब बूलियन फ़ील्ड cli.negatedFlags जोड़ सकते हैं। channel, account और अकाउंट प्रदर्शन name साझा नियंत्रण आवरण बने रहते हैं।

जारी किया गया setup/ChannelSetupInput अडैप्टर मौजूदा बाहरी Plugin के लिए उपलब्ध रहता है। नए Plugin को setupContract उजागर करना चाहिए; दोनों मौजूद होने पर OpenClaw हमेशा इसे प्राथमिकता देता है।

उदाहरण:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "मेरा चैनल",      "selectionLabel": "मेरा चैनल (स्व-होस्टेड)",      "detailLabel": "मेरा चैनल बॉट",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-आधारित स्व-होस्टेड चैट एकीकरण।",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "मार्गदर्शिका:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure निम्न का समर्थन करता है:

• configured: कॉन्फ़िगर की गई/स्थिति-शैली सूची सतहों में चैनल शामिल करें
• setup: इंटरैक्टिव सेटअप/कॉन्फ़िगर चयनकर्ताओं में चैनल शामिल करें
• docs: दस्तावेज़/नेविगेशन सतहों में चैनल को सार्वजनिक-सामना वाला चिह्नित करें

openclaw.install

openclaw.install पैकेज मेटाडेटा है, मैनिफ़ेस्ट मेटाडेटा नहीं।

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

स्थगित पूर्ण लोड

चैनल Plugin निम्न के साथ स्थगित लोडिंग चुन सकते हैं:

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

सक्षम होने पर, OpenClaw सुनना शुरू करने से पहले के स्टार्टअप चरण में केवल setupEntry लोड करता है, यहाँ तक कि पहले से कॉन्फ़िगर किए गए चैनलों के लिए भी। Gateway के सुनना शुरू करने के बाद पूर्ण प्रविष्टि लोड होती है।

यदि आपकी सेटअप/पूर्ण प्रविष्टि Gateway RPC विधियाँ पंजीकृत करती है, तो उन्हें Plugin-विशिष्ट उपसर्ग पर रखें। आरक्षित कोर व्यवस्थापक नेमस्पेस (config.*, exec.approvals.*, wizard.*, update.*) कोर के स्वामित्व में रहते हैं और हमेशा operator.admin में सामान्यीकृत होते हैं।

Plugin मैनिफ़ेस्ट

प्रत्येक नेटिव Plugin को पैकेज रूट में openclaw.plugin.json देना आवश्यक है। OpenClaw इसका उपयोग Plugin कोड निष्पादित किए बिना कॉन्फ़िगरेशन सत्यापित करने के लिए करता है।

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

चैनल Plugin के लिए channels जोड़ें (और प्रदाता Plugin providers जोड़ते हैं):

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

बिना कॉन्फ़िगरेशन वाले Plugin को भी स्कीमा देना आवश्यक है। खाली स्कीमा मान्य है:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

पूर्ण स्कीमा संदर्भ के लिए Plugin मैनिफ़ेस्ट देखें।

ClawHub पर प्रकाशन

Skills और Plugin पैकेज अलग-अलग ClawHub प्रकाशन कमांड का उपयोग करते हैं। Plugin पैकेज के लिए पैकेज-विशिष्ट कमांड का उपयोग करें:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

सेटअप प्रविष्टि

setup-entry.ts, index.ts का एक हल्का विकल्प है, जिसे OpenClaw तब लोड करता है जब उसे केवल सेटअप सतहों की आवश्यकता होती है (ऑनबोर्डिंग, कॉन्फ़िगरेशन मरम्मत, अक्षम चैनल निरीक्षण):

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

यह सेटअप प्रवाहों के दौरान भारी रनटाइम कोड (क्रिप्टो लाइब्रेरी, CLI पंजीकरण, पृष्ठभूमि सेवाएँ) लोड करने से बचाता है।

साइडकार मॉड्यूल में सेटअप-सुरक्षित निर्यात रखने वाले बंडल किए गए कार्यस्थान चैनल defineSetupPluginEntry(...) के बजाय openclaw/plugin-sdk/channel-entry-contract से defineBundledChannelSetupEntry(...) का उपयोग कर सकते हैं। वह बंडल किया गया अनुबंध वैकल्पिक runtime निर्यात का भी समर्थन करता है, ताकि सेटअप-समय की रनटाइम वायरिंग हल्की और स्पष्ट बनी रह सके।

सीमित सेटअप सहायक आयात

तेज़ सेटअप-मात्र पथों के लिए, जब आपको सेटअप सतह के केवल एक भाग की आवश्यकता हो, तो व्यापक plugin-sdk/setup अम्ब्रेला के बजाय सीमित सेटअप सहायक सीम को प्राथमिकता दें:

जब आपको moveSingleAccountChannelSectionToDefaultAccount(...) जैसे कॉन्फ़िगरेशन-पैच सहायकों सहित पूर्ण साझा सेटअप टूलबॉक्स चाहिए, तो व्यापक plugin-sdk/setup सीम का उपयोग करें।

स्थिर सेटअप विज़ार्ड पाठ के लिए createSetupTranslator(...) का उपयोग करें। यह इसी क्रम में OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES और LANG से पहला गैर-रिक्त मान उपयोग करता है, फिर अंग्रेज़ी पर वापस जाता है। स्पष्ट अंग्रेज़ी ओवरराइड के लिए OPENCLAW_LOCALE=en सेट करें। Plugin-विशिष्ट सेटअप पाठ को Plugin-स्वामित्व वाले कोड में रखें और साझा कैटलॉग कुंजियों का उपयोग केवल सामान्य सेटअप लेबल, स्थिति पाठ और आधिकारिक बंडल किए गए Plugin के सेटअप पाठ के लिए करें।

सेटअप पैच अडैप्टर आयात के समय हॉट-पाथ सुरक्षित रहते हैं। उनकी बंडल की गई एकल-अकाउंट प्रोमोशन अनुबंध-सतह लुकअप आलसी है, इसलिए plugin-sdk/setup-runtime को आयात करने से अडैप्टर के वास्तव में उपयोग किए जाने से पहले बंडल की गई अनुबंध-सतह खोज तुरंत लोड नहीं होती।

चैनल-स्वामित्व वाले सेटअप इनपुट फ़ील्ड

ChannelSetupInput सेटअप कॉलर और चैनल Plugin द्वारा साझा किया जाने वाला एक सामान्य आवरण है। इसके स्थायी रूप से टाइप किए गए फ़ील्ड name, token, tokenFile, useEnv, allowFrom और defaultTo हैं। अतिरिक्त Plugin-स्वामित्व वाली कुंजियाँ अब भी रनटाइम इनपुट ऑब्जेक्ट पर मौजूद हो सकती हैं, लेकिन साझा प्रकार किसी इंडेक्स सिग्नेचर को घोषित नहीं करता। प्रत्येक Plugin को अपने सेटअप फ़ील्ड घोषित करके सीमित करना या अडैप्टर सीमा पर Plugin-स्वामित्व वाले स्कीमा से उन्हें सत्यापित करना आवश्यक है:

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

चैनल-विशिष्ट फ़ील्ड, जिन्हें पहले सीधे ChannelSetupInput पर घोषित किया गया था, बाहरी स्रोत संगतता के लिए अस्थायी रूप से टाइप किए हुए हैं। वे बहिष्कृत हैं। 2026-07-22 को 426 प्रकाशित आउट-ऑफ़-ट्री चैनल plugins की रजिस्ट्री जाँच में ऐसे 21 फ़ील्ड हटा दिए गए जिनके कोई रीडर नहीं थे और ज्ञात रीडर वाले 22 फ़ील्ड बनाए रखे गए। जैसे ही कोई प्रकाशित plugin किसी बनाए रखे गए फ़ील्ड को पढ़ना बंद करता है, उसे हटा दिया जाता है; किसी संस्करण सीमा की आवश्यकता नहीं है। नए और बंडल किए गए plugins को इस स्तर पर निर्भर नहीं होना चाहिए; उनके स्वामित्व वाले फ़ील्ड स्थानीय रूप से घोषित करें।

चैनल-स्वामित्व वाले एकल खाते का प्रोमोशन

जब कोई चैनल एकल-खाता शीर्ष-स्तरीय कॉन्फ़िगरेशन से channels.<id>.accounts.* में अपग्रेड होता है, तो डिफ़ॉल्ट साझा व्यवहार प्रोमोट किए गए खाता-स्कोप वाले मानों को accounts.default में ले जाता है।

प्रत्येक चैनल plugin अपने सेटअप अडैप्टर के माध्यम से उस प्रोमोशन को विस्तृत या सीमित कर सकता है:

• singleAccountKeysToMove: अतिरिक्त शीर्ष-स्तरीय कुंजियाँ जिन्हें प्रोमोट किए गए खाते में ले जाना चाहिए
• namedAccountPromotionKeys: जब नामित खाते पहले से मौजूद हों, तो केवल ये कुंजियाँ प्रोमोट किए गए खाते में जाती हैं; साझा नीति/डिलीवरी कुंजियाँ चैनल रूट पर रहती हैं
• resolveSingleAccountPromotionTarget(...): चुनें कि कौन-सा मौजूदा खाता प्रोमोट किए गए मान प्राप्त करेगा

singleAccountKeysToMove की उपस्थिति दर्शाती है कि प्रोमोशन अनुबंध पूरा हो गया है। लेगेसी कुंजी प्रोमोशन से बाहर रहने के लिए फ़ील्ड को खाली ऐरे होने पर भी घोषित करें। फ़ील्ड छोड़ने वाले अडैप्टर पहले से प्रकाशित plugins के लिए रीडर-समर्थित पूर्व-घोषणा प्रोमोशन स्तर बनाए रखते हैं। 2026-07-22 की रजिस्ट्री जाँच में ऐसे 23 कुंजियाँ हटा दी गईं जिनके कोई प्रकाशित आश्रित नहीं थे और छह सामान्य कुंजियों के साथ केवल सेटअप वाली rooms कुंजी बनाए रखी गई। जैसे ही किसी बनाए रखी गई कुंजी के प्रकाशित रीडर घोषणाओं पर माइग्रेट होते हैं, उसे हटा दिया जाता है; किसी संस्करण सीमा की आवश्यकता नहीं है।

जब doctor को हल्के बंडल किए गए सेटअप आर्टिफ़ैक्ट से ये घोषणाएँ लोड करनी हों, तो plugin पैकेज मेनिफ़ेस्ट में openclaw.setupFeatures.configPromotion: true घोषित करें। केवल सेटअप वाली plugin सतह और पूर्ण चैनल plugin को समान घोषणाएँ उजागर करनी चाहिए।

पहले से रिज़ॉल्व किए गए plugin के साथ moveSingleAccountChannelSectionToDefaultAccount(...) को कॉल करते समय, उसके सेटअप अडैप्टर को setupSurface के रूप में पास करें। कॉलर द्वारा दी गई सेटअप सतहों को लोड किए गए और बंडल किए गए लुकअप पर प्राथमिकता मिलती है, जिससे स्कोप किए गए या केवल सेटअप वाले plugins वैश्विक पंजीकरण से स्वतंत्र रहते हैं।

कॉन्फ़िगरेशन स्कीमा

Plugin कॉन्फ़िगरेशन को आपके मेनिफ़ेस्ट के JSON Schema के विरुद्ध सत्यापित किया जाता है। उपयोगकर्ता plugins को इस प्रकार कॉन्फ़िगर करते हैं:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

पंजीकरण के दौरान आपके plugin को यह कॉन्फ़िगरेशन api.pluginConfig के रूप में मिलता है।

चैनल-विशिष्ट कॉन्फ़िगरेशन के लिए इसके बजाय चैनल कॉन्फ़िगरेशन अनुभाग का उपयोग करें:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

चैनल कॉन्फ़िगरेशन स्कीमा बनाना

Zod स्कीमा को plugin-स्वामित्व वाले कॉन्फ़िगरेशन आर्टिफ़ैक्ट द्वारा उपयोग किए जाने वाले ChannelConfigSchema रैपर में बदलने के लिए buildChannelConfigSchema का उपयोग करें:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

यदि आप अनुबंध पहले से JSON Schema या TypeBox के रूप में लिखते हैं, तो प्रत्यक्ष सहायक का उपयोग करें ताकि OpenClaw मेटाडेटा पथों पर Zod-से-JSON-Schema रूपांतरण छोड़ सके:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

तृतीय-पक्ष plugins के लिए, कोल्ड-पाथ अनुबंध अब भी plugin मेनिफ़ेस्ट है: जनरेट किए गए JSON Schema को openclaw.plugin.json#channelConfigs में प्रतिबिंबित करें ताकि कॉन्फ़िगरेशन स्कीमा, सेटअप और UI सतहें रनटाइम कोड लोड किए बिना channels.<id> का निरीक्षण कर सकें।

सेटअप विज़ार्ड

चैनल plugins openclaw onboard के लिए इंटरैक्टिव सेटअप विज़ार्ड प्रदान कर सकते हैं। विज़ार्ड, ChannelPlugin पर एक ChannelSetupWizard ऑब्जेक्ट होता है:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard में textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize और अन्य भी समर्थित हैं। पूर्ण बंडल किए गए उदाहरण के लिए Discord plugin का src/setup-core.ts देखें।

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

प्रकाशन और इंस्टॉल करना

बाहरी plugins: ClawHub पर प्रकाशित करें, फिर इंस्टॉल करें:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

रिपॉज़िटरी के भीतर के plugins: इन्हें बंडल किए गए plugin वर्कस्पेस ट्री के अंतर्गत रखें; बिल्ड के दौरान इनकी स्वचालित रूप से खोज की जाती है।

बंडल किया गया पैकेज मेटाडेटा स्पष्ट होता है, Gateway स्टार्टअप पर बिल्ड किए गए JavaScript से अनुमानित नहीं। रनटाइम निर्भरताएँ उनका स्वामित्व रखने वाले plugin पैकेज में होती हैं; पैकेज किया गया OpenClaw स्टार्टअप कभी भी plugin निर्भरताओं की मरम्मत या प्रतिलिपि नहीं करता।

संबंधित

• Plugins बनाना — आरंभ करने की चरण-दर-चरण मार्गदर्शिका
• Plugin मेनिफ़ेस्ट — पूर्ण मेनिफ़ेस्ट स्कीमा संदर्भ
• SDK प्रवेश बिंदु — definePluginEntry और defineChannelPluginEntry