ساخت Pluginها

Pluginها بدون تغییر هسته، OpenClaw را گسترش می‌دهند. یک Plugin می‌تواند یک کانال پیام‌رسانی، ارائه‌دهنده مدل، بک‌اند محلی CLI، ابزار عامل، هوک، ارائه‌دهنده رسانه یا قابلیت دیگری متعلق به Plugin اضافه کند.

نیازی نیست یک Plugin خارجی را به مخزن OpenClaw اضافه کنید. بسته را در 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 Pluginهای یکپارچه‌شده را از بسته‌های فضای کاری extensions/* کشف می‌کند.

انتخاب ساختار 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"] }, // یا ["my-plugin"] برای همه ابزارهای یک 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 وارد کنید:

از barrel ریشه منسوخ‌شده وارد نکنید:

در بسته Plugin خود، برای واردسازی‌های داخلی از فایل‌های barrel محلی مانند api.ts و runtime-api.ts استفاده کنید. Plugin خود را از طریق یک مسیر SDK وارد نکنید. کمک‌کننده‌های مختص ارائه‌دهنده باید در بسته ارائه‌دهنده باقی بمانند، مگر اینکه مرز واقعاً عمومی باشد.

متدهای سفارشی RPC در Gateway یک نقطه ورود پیشرفته هستند. آن‌ها را روی یک پیشوند مختص Plugin نگه دارید؛ فضاهای نام مدیریتی هسته مانند config.*، exec.approvals.*، operator.admin.*، wizard.* و update.* رزروشده باقی می‌مانند و به operator.admin تفکیک می‌شوند. پل openclaw/plugin-sdk/gateway-method-runtime برای مسیرهای HTTP در Plugin که contracts.gatewayMethodDispatch: ["authenticated-request"] را اعلان می‌کنند، رزرو شده است.

برای نقشه کامل واردسازی، به نمای کلی SDK مربوط به Plugin مراجعه کنید.

چک‌لیست پیش از ارسال

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: