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

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

कस्टम 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 SDK संगतता फ़ील्ड में TypeScript @deprecated एनोटेशन होते हैं, जिन्हें संपादक माइग्रेशन चेतावनियों के रूप में दिखाते हैं। बिल्ड समय पर उन्हें लागू करने के लिए, @typescript-eslint/no-deprecated जैसा प्रकार-सजग नियम सक्षम करें। Oxlint प्रकार-सजग नहीं है, इसलिए वह इन एनोटेशन को लागू नहीं कर सकता।

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

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: