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": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "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 रनटाइम लोड होने से पहले चैनल खोज और सेटअप सतहों के लिए सस्ता पैकेज मेटाडेटा है।

उदाहरण:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "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"    }  }}

विलंबित पूर्ण लोड

चैनल Plugins विलंबित लोडिंग को इस तरह ऑप्ट इन कर सकते हैं:

{  "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"      }    }  }}

चैनल Plugins के लिए, kind और channels जोड़ें:

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

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

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

पूर्ण स्कीमा संदर्भ के लिए Plugin manifest देखें।

ClawHub प्रकाशन

Plugin पैकेजों के लिए, पैकेज-विशिष्ट ClawHub कमांड का उपयोग करें:

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(...) का उपयोग करें। यह CLI विज़ार्ड लोकेल (OPENCLAW_LOCALE, फिर सिस्टम लोकेल वेरिएबल) का पालन करता है और अंग्रेज़ी पर वापस जाता है। Plugin-विशिष्ट सेटअप टेक्स्ट को Plugin-स्वामित्व वाले कोड में रखें और साझा कैटलॉग कुंजियों का उपयोग केवल सामान्य सेटअप लेबल, स्थिति टेक्स्ट, और आधिकारिक बंडल किए गए Plugin सेटअप कॉपी के लिए करें।

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

चैनल-स्वामित्व वाला एकल-अकाउंट प्रमोशन

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

बंडल किए गए चैनल अपने सेटअप अनुबंध सतह के माध्यम से उस प्रमोशन को संकीर्ण या ओवरराइड कर सकते हैं:

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

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

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

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

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

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

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

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

Plugin-स्वामित्व वाले कॉन्फ़िग आर्टिफ़ैक्ट द्वारा उपयोग किए जाने वाले ChannelConfigSchema रैपर में Zod स्कीमा बदलने के लिए 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())),  }),);

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

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

चैनल Plugin 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 प्रकार credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, और अन्य का समर्थन करता है। पूर्ण उदाहरणों के लिए बंडल किए गए Plugin पैकेज देखें (उदाहरण के लिए Discord Plugin src/channel.setup.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 }

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

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

openclaw plugins install @myorg/openclaw-my-plugin

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

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

रेपो के भीतर के Plugin: इन्हें बंडल किए गए Plugin वर्कस्पेस ट्री के अंतर्गत रखें और बिल्ड के दौरान ये अपने आप खोज लिए जाते हैं।

उपयोगकर्ता इंस्टॉल कर सकते हैं:

openclaw plugins install <package-name>

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

संबंधित

• Plugin बनाना — शुरू करने के लिए चरण-दर-चरण गाइड
• Plugin मेनिफेस्ट — पूरा मेनिफेस्ट स्कीमा संदर्भ
• SDK एंट्री पॉइंट — definePluginEntry और defineChannelPluginEntry