ساخت Plugin‌ها

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

لازم نیست یک Plugin خارجی را به مخزن OpenClaw اضافه کنید. بسته را در ClawHub منتشر کنید تا کاربران آن را با دستور زیر نصب کنند:

openclaw plugins install clawhub:<package-name>

در دوره گذار راه‌اندازی، مشخصات بسته بدون پیشوند همچنان از npm نصب می‌شوند. وقتی می‌خواهید تفکیک نام از طریق ClawHub انجام شود، از پیشوند clawhub: استفاده کنید.

الزامات

• Node 22.19+، Node 23.11+ یا Node 24+، و npm یا pnpm.
• ماژول‌های ESM در TypeScript.
• برای کار روی 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"] }, // 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 استفاده کنید. 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: