Plugin बनाना

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

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

openclaw plugins install clawhub:<package-name>

launch cutover के दौरान bare package specs अब भी npm से इंस्टॉल होते हैं। जब आप ClawHub resolution चाहते हैं, तो clawhub: prefix का उपयोग करें।

आवश्यकताएँ

• Node 22.19+, Node 23.11+, या Node 24+ और npm या pnpm जैसे package manager का उपयोग करें।
• TypeScript ESM modules से परिचित रहें।
• in-repo bundled Plugin कार्य के लिए, repository clone करें और pnpm install चलाएँ। source-checkout Plugin development केवल pnpm है क्योंकि OpenClaw bundled plugins को extensions/* workspace packages से load करता है।

Plugin का आकार चुनें

Quickstart

एक आवश्यक agent tool register करके minimal tool Plugin बनाएँ। यह सबसे छोटा उपयोगी Plugin shape है और package, manifest, entry point, और local proof दिखाता है।

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

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

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

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

tools register करना

Tools required या optional हो सकते हैं। Required tools हमेशा उपलब्ध होते हैं जब Plugin enabled होता है। Optional tools के लिए user opt-in आवश्यक है।

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(...) के साथ registered हर tool को Plugin manifest में भी declare करना होगा:

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

Users tools.allow के साथ opt in करते हैं:

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

Optional tools यह control करते हैं कि tool model को expose होता है या नहीं। जब कोई tool या hook model द्वारा चुने जाने के बाद और action चलने से पहले approval माँगना चाहिए, तो Plugin permission requests का उपयोग करें।

Side effects, unusual binaries, या उन capabilities के लिए optional tools का उपयोग करें जो default रूप से expose नहीं होनी चाहिए। Tool names core tools से conflict नहीं करने चाहिए; conflicts को skip किया जाता है और Plugin diagnostics में report किया जाता है। Malformed registrations, जिसमें parameters के बिना tool descriptors शामिल हैं, skip किए जाते हैं और उसी तरह report होते हैं। Registered tools typed functions हैं जिन्हें model policy और allowlist checks pass होने के बाद call कर सकता है।

Tool factories runtime-supplied context object receive करती हैं। जब किसी tool को current turn के active model के लिए log, display, या adapt करना हो, तो ctx.activeModel का उपयोग करें। object में provider, modelId, और modelRef शामिल हो सकते हैं। इसे informational runtime metadata मानें, local operator, installed Plugin code, या modified OpenClaw runtime के विरुद्ध security boundary नहीं। Sensitive local tools को फिर भी explicit Plugin या operator opt-in require करना चाहिए और active-model metadata missing या unsuitable होने पर fail closed होना चाहिए।

Manifest ownership और discovery declare करता है; execution फिर भी live registered tool implementation को call करता है। toolMetadata.<tool>.optional: true को api.registerTool(..., { optional: true }) के साथ aligned रखें ताकि OpenClaw tool को explicitly allowlist किए जाने तक उस Plugin runtime को load करने से बच सके।

Import conventions

Focused SDK subpaths से import करें:

deprecated root barrel से import न करें:

अपने Plugin package के भीतर, internal imports के लिए api.ts और runtime-api.ts जैसी local barrel files का उपयोग करें। अपने ही Plugin को SDK path के माध्यम से import न करें। Provider-specific helpers provider package में ही रहने चाहिए, जब तक seam सचमुच generic न हो।

Custom Gateway RPC methods एक advanced entry point हैं। उन्हें Plugin-specific prefix पर रखें; config.*, exec.approvals.*, operator.admin.*, wizard.*, और update.* जैसे core admin namespaces reserved रहते हैं और operator.admin पर resolve होते हैं। openclaw/plugin-sdk/gateway-method-runtime bridge उन Plugin HTTP routes के लिए reserved है जो contracts.gatewayMethodDispatch: ["authenticated-request"] declare करते हैं।

पूरे import map के लिए, Plugin SDK overview देखें।

Pre-submission checklist

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json manifest मौजूद और valid है OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Entry point defineChannelPluginEntry या definePluginEntry का उपयोग करता है OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s सभी imports focused plugin-sdk/<subpath> paths का उपयोग करते हैं OPENCLAW_DOCS_MARKER:calloutClose: