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

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

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

आपके package.json में एक openclaw फ़ील्ड चाहिए जो प्लगइन सिस्टम को बताती है कि आपका 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",  "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 रनटाइम लोड होने से पहले चैनल खोज और सेटअप सतहों के लिए किफायती पैकेज मेटाडेटा है।

उदाहरण:

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

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

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

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

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

यदि आपकी सेटअप/पूर्ण प्रविष्टि Gateway RPC मेथड पंजीकृत करती है, तो उन्हें Plugin-विशिष्ट प्रिफ़िक्स पर रखें। आरक्षित core admin namespace (config.*, exec.approvals.*, wizard.*, update.*) core के स्वामित्व में रहते हैं और हमेशा 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 के लिए, kind और channels जोड़ें:

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

यहां तक कि बिना कॉन्फ़िग वाले plugins को भी schema भेजना होगा। खाली schema मान्य है:

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

पूरे schema संदर्भ के लिए Plugin मैनिफेस्ट देखें.

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 रजिस्ट्रेशन, बैकग्राउंड सेवाएं) लोड करने से बचाता है।

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

सीमित सेटअप helper imports

हॉट setup-only paths के लिए, जब आपको setup surface के केवल एक भाग की आवश्यकता हो, तो व्यापक plugin-sdk/setup umbrella के बजाय सीमित setup helper seams को प्राथमिकता दें:

जब आपको साझा setup toolbox पूरा चाहिए, जिसमें moveSingleAccountChannelSectionToDefaultAccount(...) जैसे config-patch helpers शामिल हों, तब व्यापक plugin-sdk/setup seam का उपयोग करें।

स्थिर setup wizard copy के लिए createSetupTranslator(...) का उपयोग करें। यह CLI wizard locale (OPENCLAW_LOCALE, फिर system locale variables) का अनुसरण करता है और English पर fallback करता है। Plugin-specific setup text को plugin-owned code में रखें और shared catalog keys का उपयोग केवल सामान्य setup labels, status text, और official bundled plugin setup copy के लिए करें।

setup patch adapters import पर hot-path safe रहते हैं। उनका bundled single-account promotion contract-surface lookup lazy है, इसलिए plugin-sdk/setup-runtime import करने से adapter के वास्तव में उपयोग होने से पहले bundled contract-surface discovery eager load नहीं होती।

चैनल-स्वामित्व वाला single-account promotion

जब कोई चैनल single-account top-level config से channels.<id>.accounts.* पर upgrade करता है, तो default shared behavior promoted account-scoped values को accounts.default में ले जाना है।

बंडल किए गए चैनल अपनी setup contract surface के माध्यम से उस promotion को सीमित या override कर सकते हैं:

• singleAccountKeysToMove: अतिरिक्त top-level keys जिन्हें promoted account में जाना चाहिए
• namedAccountPromotionKeys: जब named accounts पहले से मौजूद हों, तो केवल ये keys promoted account में जाती हैं; shared policy/delivery keys channel root पर रहती हैं
• resolveSingleAccountPromotionTarget(...): चुनें कि किस existing account को promoted values मिलेंगी

कॉन्फ़िग schema

Plugin config आपके manifest में JSON Schema के विरुद्ध validate किया जाता है। उपयोगकर्ता plugins को इसके माध्यम से configure करते हैं:

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

आपका Plugin registration के दौरान इस config को api.pluginConfig के रूप में प्राप्त करता है।

Channel-specific config के लिए, इसके बजाय channel config section का उपयोग करें:

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

channel config schemas बनाना

Zod schema को plugin-owned config artifacts द्वारा उपयोग किए जाने वाले ChannelConfigSchema wrapper में बदलने के लिए 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);

यदि आप contract को पहले से JSON Schema या TypeBox के रूप में author करते हैं, तो direct helper का उपयोग करें ताकि OpenClaw metadata paths पर Zod-to-JSON-Schema conversion छोड़ सके:

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

Third-party plugins के लिए, cold-path contract अभी भी plugin manifest है: generated JSON Schema को openclaw.plugin.json#channelConfigs में mirror करें ताकि config schema, setup, और UI surfaces runtime code load किए बिना channels.<id> का निरीक्षण कर सकें।

सेटअप wizards

Channel plugins openclaw onboard के लिए interactive setup wizards प्रदान कर सकते हैं। wizard ChannelPlugin पर एक ChannelSetupWizard object है:

 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 type credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, और अधिक का समर्थन करता है। पूरे उदाहरणों के लिए bundled plugin packages देखें (उदाहरण के लिए 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 }

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

बाहरी 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 वर्कस्पेस ट्री के अंतर्गत रखें और बिल्ड के दौरान वे स्वतः खोज लिए जाते हैं।

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

openclaw plugins install <package-name>

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

संबंधित

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