Plugin बनाना

Plugins, कोर में बदलाव किए बिना OpenClaw का विस्तार करते हैं। कोई Plugin मैसेजिंग चैनल, मॉडल प्रदाता, स्थानीय CLI बैकएंड, एजेंट टूल, हुक, मीडिया प्रदाता, या Plugin के स्वामित्व वाली कोई अन्य क्षमता जोड़ सकता है।

आपको OpenClaw रिपॉज़िटरी में बाहरी Plugin जोड़ने की आवश्यकता नहीं है। पैकेज को ClawHub पर प्रकाशित करें और उपयोगकर्ता इसे इस कमांड से इंस्टॉल करें:

openclaw plugins install clawhub:<package-name>

लॉन्च बदलाव के दौरान बिना प्रीफ़िक्स वाले पैकेज विनिर्देश अभी भी npm से इंस्टॉल होते हैं। जब आप ClawHub रिज़ॉल्यूशन चाहते हों, तो clawhub: प्रीफ़िक्स का उपयोग करें।

आवश्यकताएँ

• Node 22.22.3+, Node 24.15+, या Node 25.9+, और npm या pnpm।
• TypeScript ESM मॉड्यूल।
• रिपॉज़िटरी में बंडल किए गए Plugin पर काम करने के लिए, रिपॉज़िटरी क्लोन करें और pnpm install चलाएँ। सोर्स-चेकआउट Plugin डेवलपमेंट केवल pnpm के साथ होता है, क्योंकि OpenClaw extensions/* वर्कस्पेस पैकेजों से बंडल किए गए Plugins खोजता है।

Plugin का स्वरूप चुनें

त्वरित शुरुआत

एक आवश्यक एजेंट टूल पंजीकृत करके न्यूनतम टूल Plugin बनाएँ। यह सबसे छोटा उपयोगी Plugin स्वरूप है और पैकेज, मैनिफ़ेस्ट, एंट्री पॉइंट तथा स्थानीय सत्यापन को समाहित करता है।

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

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

openclaw plugins inspect my-plugin --runtime --json

pnpm test extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

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

openclaw plugins install clawhub:your-org/your-plugin

टूल पंजीकृत करना

टूल आवश्यक या वैकल्पिक हो सकते हैं। Plugin सक्षम होने पर आवश्यक टूल हमेशा उपलब्ध रहते हैं। OpenClaw द्वारा स्वामी Plugin रनटाइम लोड किए जाने से पहले वैकल्पिक टूल के लिए उपयोगकर्ता की स्पष्ट सहमति आवश्यक होती है।

टूल फ़ैक्टरियों को विश्वसनीय रनटाइम संदर्भ मिलता है, जिसमें deliveryContext, उपलब्ध होने पर सक्रिय प्लेटफ़ॉर्म वार्तालाप के लिए nativeChannelId, और requesterSenderId शामिल हैं।

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

api.registerTool(...) के साथ पंजीकृत प्रत्येक टूल को Plugin मैनिफ़ेस्ट में भी घोषित किया जाना चाहिए:

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

उपयोगकर्ता tools.allow से सहमति देते हैं:

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

वैकल्पिक टूल यह नियंत्रित करते हैं कि कोई टूल मॉडल के सामने प्रस्तुत किया जाए या नहीं। जब किसी टूल या हुक को मॉडल द्वारा चुने जाने के बाद और कार्रवाई चलने से पहले अनुमोदन माँगना चाहिए, तब Plugin अनुमति अनुरोध का उपयोग करें।

साइड इफ़ेक्ट, असामान्य बाइनरी या ऐसी क्षमताओं के लिए वैकल्पिक टूल का उपयोग करें जिन्हें डिफ़ॉल्ट रूप से प्रस्तुत नहीं किया जाना चाहिए। टूल नामों का कोर टूल नामों से टकराव नहीं होना चाहिए; टकरावों को छोड़ दिया जाता है और Plugin डायग्नोस्टिक्स में रिपोर्ट किया जाता है। विकृत पंजीकरणों को भी उसी तरह छोड़कर रिपोर्ट किया जाता है: गैर-रिक्त name का अभाव, गैर-फ़ंक्शन execute, या parameters ऑब्जेक्ट के बिना टूल डिस्क्रिप्टर।

टूल फ़ैक्टरियों को रनटाइम द्वारा प्रदत्त संदर्भ ऑब्जेक्ट मिलता है। जब किसी टूल को वर्तमान टर्न के सक्रिय मॉडल के अनुसार लॉग करना, प्रदर्शित करना या अनुकूलित होना हो, तब ctx.activeModel का उपयोग करें; इसमें provider, modelId, और modelRef शामिल हो सकते हैं। इसे सूचनात्मक रनटाइम मेटाडेटा मानें, न कि स्थानीय ऑपरेटर, इंस्टॉल किए गए Plugin कोड या संशोधित OpenClaw रनटाइम के विरुद्ध सुरक्षा सीमा। संवेदनशील स्थानीय टूल के लिए फिर भी स्पष्ट Plugin या ऑपरेटर सहमति आवश्यक होनी चाहिए और सक्रिय-मॉडल मेटाडेटा अनुपलब्ध या अनुपयुक्त होने पर उन्हें सुरक्षित रूप से विफल होना चाहिए।

मैनिफ़ेस्ट स्वामित्व और खोज घोषित करता है; निष्पादन फिर भी लाइव पंजीकृत टूल कार्यान्वयन को कॉल करता है। toolMetadata.<tool>.optional: true को api.registerTool(..., { optional: true }) के साथ संरेखित रखें, ताकि OpenClaw टूल को स्पष्ट रूप से अनुमति-सूची में जोड़े जाने तक उस Plugin रनटाइम को लोड करने से बच सके।

इंपोर्ट परंपराएँ

केंद्रित SDK उपपथों से इंपोर्ट करें:

बहिष्कृत रूट बैरल से इंपोर्ट न करें:

अपने Plugin पैकेज के भीतर, आंतरिक इंपोर्ट के लिए api.ts और runtime-api.ts जैसी स्थानीय बैरल फ़ाइलों का उपयोग करें। अपने ही Plugin को किसी SDK पथ के माध्यम से इंपोर्ट न करें। प्रदाता-विशिष्ट सहायक प्रदाता पैकेज में ही रहने चाहिए, जब तक कि सीम वास्तव में सामान्य न हो।

कस्टम Gateway RPC विधियाँ एक उन्नत एंट्री पॉइंट हैं। उन्हें Plugin-विशिष्ट प्रीफ़िक्स पर रखें; config.*, exec.approvals.*, operator.admin.*, wizard.*, और update.* जैसे कोर व्यवस्थापक नेमस्पेस आरक्षित रहते हैं और operator.admin में रिज़ॉल्व होते हैं। openclaw/plugin-sdk/gateway-method-runtime ब्रिज उन Plugin HTTP रूटों के लिए आरक्षित है जो contracts.gatewayMethodDispatch: ["authenticated-request"] घोषित करते हैं।

संपूर्ण इंपोर्ट मैप के लिए, Plugin SDK अवलोकन देखें।

सबमिशन-पूर्व चेकलिस्ट

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json में सही openclaw मेटाडेटा है OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json मैनिफ़ेस्ट मौजूद और मान्य है OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s एंट्री पॉइंट defineChannelPluginEntry या definePluginEntry का उपयोग करता है OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s सभी इंपोर्ट केंद्रित plugin-sdk/<subpath> पथों का उपयोग करते हैं OPENCLAW_DOCS_MARKER:calloutClose: