Plugin बनाना

Plugins, core को बदले बिना 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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

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() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

outputSchema वैकल्पिक है। यह कोड मोड और टूल खोज द्वारा उपयोग किए जाने वाले संरचित details मान का वर्णन करता है। कैटलॉग कॉल निष्पादन से पहले अमान्य स्कीमा अस्वीकार करते हैं और टूल हुक के बाद अंतिम मान को सत्यापित करते हैं। स्थिर JSON परिणाम के बिना टूल के लिए इसे छोड़ दें। पूर्ण अनुबंध के लिए टूल Plugins देखें।

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 अनुमति अनुरोधों का उपयोग करें।

साइड इफ़ेक्ट, असामान्य बाइनरी या ऐसी क्षमताओं के लिए वैकल्पिक टूल का उपयोग करें जिन्हें डिफ़ॉल्ट रूप से प्रस्तुत नहीं किया जाना चाहिए। टूल नाम core टूल नामों से टकराने नहीं चाहिए; टकराव छोड़ दिए जाते हैं और 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.* जैसे core व्यवस्थापक नेमस्पेस आरक्षित रहते हैं और 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: