OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Plugin बनाना

Plugins, core को बदले बिना OpenClaw का विस्तार करते हैं। कोई plugin messaging channel, model provider, local CLI backend, agent tool, hook, media provider, या plugin के स्वामित्व वाली कोई अन्य capability जोड़ सकता है।

आपको OpenClaw repository में कोई external plugin जोड़ने की आवश्यकता नहीं है। package को ClawHub पर publish करें और users इसे इसके साथ install करते हैं:

bash
openclaw plugins install clawhub:<package-name>

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

आवश्यकताएँ

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

plugin shape चुनें

Channel plugin

OpenClaw को messaging platform से connect करें।
Provider plugin

model, media, search, fetch, speech, या realtime provider जोड़ें।
CLI backend plugin

OpenClaw model fallback के ज़रिए local AI CLI चलाएँ।
Tool plugin

agent tools register करें।

Quickstart

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

  • package metadata बनाएँ

    package.json
    {"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.plugin.json
    {"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}}

    Published external plugins को runtime entries को built JavaScript files की ओर point करना चाहिए। पूरे entry point contract के लिए SDK entry points देखें।

    हर plugin को manifest चाहिए, भले ही उसमें कोई config न हो। Runtime tools contracts.tools में होने चाहिए ताकि OpenClaw हर plugin runtime को eagerly load किए बिना ownership discover कर सके। activation.onStartup को सोच-समझकर set करें। यह example Gateway startup पर start होता है।

    Host-trusted plugin surfaces भी manifest-gated हैं और installed plugins के लिए explicit enablement की आवश्यकता होती है। यदि कोई installed plugin api.registerAgentToolResultMiddleware(...) register करता है, तो contracts.agentToolResultMiddleware में हर target runtime declare करें। यदि यह api.registerTrustedToolPolicy(...) register करता है, तो contracts.trustedToolPolicies में हर policy id declare करें। ये declarations install-time inspection और runtime registration को aligned रखते हैं।

    हर manifest field के लिए, Plugin manifest देखें।

  • tool register करें

    index.ts
    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}` }],        };      },    });  },});

    non-channel plugins के लिए definePluginEntry का उपयोग करें। Channel plugins defineChannelPluginEntry का उपयोग करते हैं।

  • runtime test करें

    installed या external plugin के लिए, loaded runtime inspect करें:

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

    यदि plugin कोई CLI command register करता है, तो वह command भी run करें। उदाहरण के लिए, demo command के पास openclaw demo-plugin ping जैसा execution proof होना चाहिए।

    इस repository में bundled plugin के लिए, OpenClaw source-checkout plugin packages को extensions/* workspace से discover करता है। सबसे निकट targeted test चलाएँ:

    bash
    pnpm test -- extensions/my-plugin/pnpm check

  • package install test करें

    package-ready plugin publish करने से पहले, वही install shape test करें जो users को मिलेगा। पहले build step जोड़ें, openclaw.extensions जैसी runtime entries को built JavaScript जैसे ./dist/index.js की ओर point करें, और सुनिश्चित करें कि npm pack में वह dist/ output शामिल हो। TypeScript source entries केवल source checkouts और local development paths के लिए हैं।

    फिर plugin pack करें और tarball को npm-pack: के साथ install करें:

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

    npm-pack: OpenClaw के managed per-plugin npm project का उपयोग करता है, इसलिए यह runtime dependency mistakes पकड़ता है जिन्हें source checkout testing छिपा सकती है। यह package और dependency shape को prove करता है, catalog-linked official trust को नहीं। Runtime imports dependencies या optionalDependencies में होने चाहिए; केवल devDependencies में छोड़ी गई dependencies managed runtime project के लिए install नहीं की जाएँगी।

    official या privileged plugin behavior के final proof के रूप में raw archive/path install का उपयोग न करें। Raw sources local debugging के लिए उपयोगी हैं, लेकिन वे npm या ClawHub installs जैसा dependency path prove नहीं करते। यदि आपका plugin trusted official plugin status पर निर्भर करता है, तो catalog-backed official install या official trust record करने वाले published package path के ज़रिए दूसरा proof जोड़ें। install-root और dependency ownership details के लिए Plugin dependency resolution देखें।

  • Publish करें

    publishing से पहले package validate करें:

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

    canonical ClawHub snippets docs/snippets/plugin-publish/ में रहते हैं।

  • Install करें

    published package को ClawHub के ज़रिए install करें:

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

    • tools register करना

    Tools required या optional हो सकते हैं। Required tools तब हमेशा available होते हैं जब plugin enabled होता है। Optional tools के लिए user opt-in चाहिए।

    typescript
    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 करना चाहिए:

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

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

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

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

    Optional tools का उपयोग side effects, unusual binaries, या ऐसी capabilities के लिए करें जिन्हें 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 मिलता है। जब किसी 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 की आवश्यकता होनी चाहिए और 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 plugin runtime को तब तक load करने से बच सके जब तक tool explicitly allowlisted न हो।

    Import conventions

    focused SDK subpaths से import करें:

    typescript

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

    typescript

    अपने plugin package के भीतर, internal imports के लिए api.ts और runtime-api.ts जैसी local barrel files का उपयोग करें। SDK path के ज़रिए अपने ही plugin को 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:

    Was this useful?
    On this page

    On this page