Plugin maintainer reference

جزئیات داخلی Plugin

این مرجع عمیق معماری برای سیستم پلاگین OpenClaw است. برای راهنماهای عملی، از یکی از صفحه‌های متمرکز زیر شروع کنید.

نصب و استفاده از پلاگین‌ها

راهنمای کاربر نهایی برای افزودن، فعال‌سازی و عیب‌یابی پلاگین‌ها.

ساخت پلاگین‌ها

آموزش ساخت نخستین پلاگین با کوچک‌ترین مانیفست عملیاتی.

پلاگین‌های کانال

یک پلاگین کانال پیام‌رسانی بسازید.

پلاگین‌های ارائه‌دهنده

یک پلاگین ارائه‌دهنده مدل بسازید.

نمای کلی SDK

مرجع نگاشت import و API ثبت.

مدل عمومی قابلیت‌ها

قابلیت‌ها مدل عمومی پلاگین بومی درون OpenClaw هستند. هر پلاگین بومی OpenClaw برای یک یا چند نوع قابلیت ثبت می‌شود:

قابلیت	روش ثبت	پلاگین‌های نمونه
استنتاج متنی	`api.registerProvider(...)`	`anthropic`, `openai`
بک‌اند استنتاج CLI	`api.registerCliBackend(...)`	`anthropic`, `openai`
تعبیه‌سازی‌ها	`api.registerEmbeddingProvider(...)`	پلاگین‌های برداری متعلق به ارائه‌دهنده
گفتار	`api.registerSpeechProvider(...)`	`elevenlabs`, `microsoft`
رونویسی بلادرنگ	`api.registerRealtimeTranscriptionProvider(...)`	`openai`
صدای بلادرنگ	`api.registerRealtimeVoiceProvider(...)`	`google`, `openai`
درک رسانه	`api.registerMediaUnderstandingProvider(...)`	`google`, `openai`
منبع رونوشت‌ها	`api.registerTranscriptSourceProvider(...)`	`discord`, `google-meet`, `teams-meetings`, `zoom-meetings`
تولید تصویر	`api.registerImageGenerationProvider(...)`	`fal`, `google`, `openai`
تولید موسیقی	`api.registerMusicGenerationProvider(...)`	`fal`, `google`, `minimax`
تولید ویدئو	`api.registerVideoGenerationProvider(...)`	`fal`, `google`, `qwen`
واکشی وب	`api.registerWebFetchProvider(...)`	`firecrawl`
جست‌وجوی وب	`api.registerWebSearchProvider(...)`	`brave`, `firecrawl`, `google`
کانال / پیام‌رسانی	`api.registerChannel(...)`	`matrix`, `msteams`
کشف Gateway	`api.registerGatewayDiscoveryService(...)`	`bonjour`

رویکرد سازگاری خارجی

مدل قابلیت در هسته پیاده‌سازی شده و اکنون پلاگین‌های همراه/بومی از آن استفاده می‌کنند، اما سازگاری پلاگین‌های خارجی همچنان به معیار سخت‌گیرانه‌تری از «چون export شده است، پس ثابت است» نیاز دارد.

وضعیت پلاگین	راهنمایی
پلاگین‌های خارجی موجود	یکپارچه‌سازی‌های مبتنی بر hook را فعال نگه دارید؛ این خط مبنای سازگاری است.
پلاگین‌های همراه/بومی جدید	ثبت صریح قابلیت را به دسترسی‌های ویژه فروشنده یا طراحی‌های جدید صرفاً مبتنی بر hook ترجیح دهید.
پلاگین‌های خارجی که ثبت قابلیت را به‌کار می‌گیرند	مجاز است، اما سطوح کمکی مختص قابلیت را در حال تکامل در نظر بگیرید، مگر اینکه مستندات آن‌ها را پایدار اعلام کنند.

ثبت قابلیت مسیر موردنظر است. در دوره گذار، hookهای قدیمی همچنان امن‌ترین مسیر بدون ایجاد شکست برای پلاگین‌های خارجی هستند. همه زیرمسیرهای کمکی exportشده ارزش یکسانی ندارند — قراردادهای محدود و مستند را به exportهای کمکی اتفاقی ترجیح دهید.

شکل‌های پلاگین

OpenClaw هر پلاگین بارگذاری‌شده را بر اساس رفتار واقعی ثبت آن، نه صرفاً فراداده ایستا، در یک شکل دسته‌بندی می‌کند:

قابلیت ساده

دقیقاً یک نوع قابلیت را ثبت می‌کند (برای مثال، پلاگینی صرفاً ارائه‌دهنده مانند arcee یا chutes).

قابلیت ترکیبی

چند نوع قابلیت را ثبت می‌کند (برای مثال، openai مالک استنتاج متنی، گفتار، درک رسانه و تولید تصویر است).

صرفاً مبتنی بر hook

فقط hookها (نوع‌دار یا سفارشی) را ثبت می‌کند و هیچ قابلیت، ابزار، فرمان یا سرویسی ندارد.

فاقد قابلیت

ابزارها، فرمان‌ها، سرویس‌ها یا مسیرها را ثبت می‌کند، اما قابلیتی ثبت نمی‌کند.

برای مشاهده شکل و جزئیات قابلیت‌های یک پلاگین از openclaw plugins inspect <id> استفاده کنید. برای جزئیات، مرجع CLI را ببینید.

نشانه‌های سازگاری

openclaw doctor، openclaw plugins inspect <id>، openclaw status --all و openclaw plugins doctor این اعلان‌های سازگاری را نمایش می‌دهند:

نشانه	معنا
پیکربندی معتبر	پیکربندی بدون مشکل تجزیه می‌شود و پلاگین‌ها تفکیک می‌شوند
صرفاً مبتنی بر hook (اطلاع‌رسانی)	پلاگین فقط hook ثبت می‌کند؛ مسیری پشتیبانی‌شده است، اما هنوز به ثبت قابلیت مهاجرت نکرده است
API منسوخ تعبیه‌سازی حافظه (هشدار)	پلاگین غیرهمراه به‌جای `registerEmbeddingProvider` از API قدیمی ارائه‌دهنده تعبیه‌سازی مختص حافظه استفاده می‌کند
خطای قطعی	پیکربندی نامعتبر است یا بارگذاری پلاگین ناموفق بوده است

هیچ‌یک از نشانه‌های توصیه‌ای/هشداردهنده در حال حاضر پلاگین شما را از کار نمی‌اندازند. این نشانه‌ها در openclaw status --all و openclaw plugins doctor نیز ظاهر می‌شوند.

نمای کلی معماری

سیستم پلاگین OpenClaw چهار لایه دارد:

مانیفست + کشف

OpenClaw پلاگین‌های کاندید را از مسیرهای پیکربندی‌شده، ریشه‌های فضای کاری، ریشه‌های سراسری پلاگین و پلاگین‌های همراه پیدا می‌کند. فرایند کشف ابتدا مانیفست‌های بومی openclaw.plugin.json و سپس مانیفست‌های بسته پشتیبانی‌شده را می‌خواند.

فعال‌سازی + اعتبارسنجی

هسته تعیین می‌کند که یک پلاگین کشف‌شده فعال، غیرفعال یا مسدود باشد، یا برای یک جایگاه انحصاری مانند حافظه انتخاب شود.

بارگذاری زمان اجرا

پلاگین‌های بومی OpenClaw درون همان فرایند بارگذاری می‌شوند و قابلیت‌ها را در یک رجیستری مرکزی ثبت می‌کنند. JavaScript بسته‌بندی‌شده از طریق require بومی بارگذاری می‌شود؛ TypeScript منبع محلی شخص ثالث، مسیر جایگزین اضطراری Jiti است. بسته‌های سازگار بدون import کردن کد زمان اجرا به رکوردهای رجیستری نرمال‌سازی می‌شوند.

مصرف سطوح

سایر بخش‌های OpenClaw رجیستری را می‌خوانند تا ابزارها، کانال‌ها، راه‌اندازی ارائه‌دهنده، hookها، مسیرهای HTTP، فرمان‌های CLI و سرویس‌ها را ارائه کنند.

به‌طور مشخص برای CLI پلاگین، کشف فرمان ریشه در دو مرحله تقسیم می‌شود:

فراداده زمان تجزیه از registerCli(..., { descriptors: [...] }) می‌آید
ماژول واقعی CLI پلاگین می‌تواند lazy باقی بماند و هنگام نخستین فراخوانی ثبت شود

این کار ضمن اینکه به OpenClaw امکان می‌دهد نام فرمان‌های ریشه را پیش از تجزیه رزرو کند، کد CLI متعلق به پلاگین را درون خود پلاگین نگه می‌دارد.

مرز طراحی مهم:

اعتبارسنجی مانیفست/پیکربندی باید بدون اجرای کد پلاگین و بر اساس فراداده مانیفست/شِما انجام شود
کشف قابلیت‌های بومی می‌تواند کد ورودی پلاگین مورد اعتماد را برای ساخت یک snapshot رجیستری غیرفعال‌کننده‌نشده بارگذاری کند
رفتار بومی زمان اجرا از مسیر register(api) ماژول پلاگین همراه با api.registrationMode === "full" می‌آید

این جداسازی به OpenClaw امکان می‌دهد پیش از فعال‌شدن کامل زمان اجرا، پیکربندی را اعتبارسنجی کند، پلاگین‌های مفقود/غیرفعال را توضیح دهد و راهنمایی‌های UI/شِما را بسازد.

snapshot فراداده پلاگین و جدول جست‌وجو

راه‌اندازی Gateway برای snapshot پیکربندی فعلی، یک PluginMetadataSnapshot می‌سازد. این snapshot فقط شامل فراداده است: نمایه پلاگین‌های نصب‌شده، رجیستری مانیفست، تشخیص‌های مانیفست، نگاشت‌های مالک، نرمال‌ساز شناسه پلاگین و رکوردهای مانیفست را ذخیره می‌کند. ماژول‌های بارگذاری‌شده پلاگین، SDKهای ارائه‌دهنده، محتوای بسته یا exportهای زمان اجرا را نگه نمی‌دارد.

اعتبارسنجی پیکربندی آگاه از پلاگین، فعال‌سازی خودکار هنگام راه‌اندازی و bootstrap پلاگین Gateway، به‌جای بازسازی مستقل فراداده مانیفست/نمایه، از آن snapshot استفاده می‌کنند. PluginLookUpTable از همان snapshot مشتق می‌شود و برنامه پلاگین راه‌اندازی را برای پیکربندی فعلی زمان اجرا به آن می‌افزاید.

پس از راه‌اندازی، Gateway snapshot فراداده فعلی را به‌عنوان یک محصول قابل‌جایگزینی زمان اجرا نگه می‌دارد. کشف مکرر ارائه‌دهنده در زمان اجرا می‌تواند این snapshot را به عاریت بگیرد تا برای هر گذر کاتالوگ ارائه‌دهنده، نمایه نصب‌شده و رجیستری مانیفست را دوباره نسازد. هنگام خاموش‌شدن Gateway، تغییر پیکربندی/موجودی پلاگین و نوشتن نمایه نصب‌شده، snapshot پاک یا جایگزین می‌شود؛ اگر snapshot فعلی سازگاری وجود نداشته باشد، فراخوان‌ها به مسیر سرد مانیفست/نمایه بازمی‌گردند. بررسی‌های سازگاری باید ریشه‌های کشف پلاگین مانند plugins.load.paths و فضای کاری پیش‌فرض عامل را نیز شامل شوند، زیرا پلاگین‌های فضای کاری بخشی از دامنه فراداده هستند.

snapshot و جدول جست‌وجو تصمیم‌های مکرر راه‌اندازی را در مسیر سریع نگه می‌دارند:

مالکیت کانال
راه‌اندازی معوق کانال
شناسه‌های پلاگین راه‌اندازی
مالکیت ارائه‌دهنده و بک‌اند CLI
مالکیت ارائه‌دهنده راه‌اندازی، نام مستعار فرمان، ارائه‌دهنده کاتالوگ مدل و قرارداد مانیفست
اعتبارسنجی شِمای پیکربندی پلاگین و شِمای پیکربندی کانال
تصمیم‌های فعال‌سازی خودکار هنگام راه‌اندازی

مرز ایمنی، جایگزینی snapshot است، نه تغییر آن. هرگاه پیکربندی، موجودی پلاگین، رکوردهای نصب یا سیاست پایدارشده نمایه تغییر کرد، snapshot را دوباره بسازید. آن را یک رجیستری سراسری و گسترده با قابلیت تغییر در نظر نگیرید و snapshotهای تاریخی نامحدود را نگه ندارید. بارگذاری پلاگین زمان اجرا از snapshotهای فراداده جدا باقی می‌ماند تا وضعیت قدیمی زمان اجرا پشت یک cache فراداده پنهان نشود.

قاعده cache در جزئیات داخلی معماری پلاگین مستند شده است: فراداده مانیفست و کشف تازه است، مگر اینکه فراخواننده برای جریان فعلی یک snapshot، جدول جست‌وجو یا رجیستری مانیفست صریح در اختیار داشته باشد. cacheهای پنهان فراداده و TTLهای مبتنی بر ساعت دیواری بخشی از بارگذاری پلاگین نیستند. فقط cacheهای بارگذار زمان اجرا، ماژول و آرتیفکت وابستگی می‌توانند پس از بارگذاری واقعی کد یا آرتیفکت‌های نصب‌شده پایدار بمانند.

برخی فراخواننده‌های مسیر سرد هنوز رجیستری‌های مانیفست را مستقیماً از نمایهٔ پایدارشدهٔ Pluginهای نصب‌شده بازسازی می‌کنند، به‌جای آنکه یک PluginLookUpTable از Gateway دریافت کنند. اکنون آن مسیر رجیستری را در صورت نیاز بازسازی می‌کند؛ وقتی فراخواننده از قبل جدول جست‌وجوی فعلی یا یک رجیستری مانیفست صریح در اختیار دارد، ترجیحاً آن را از طریق جریان‌های زمان اجرا عبور دهید.

برنامه‌ریزی فعال‌سازی

برنامه‌ریزی فعال‌سازی بخشی از صفحهٔ کنترل است. فراخواننده‌ها می‌توانند پیش از بارگذاری رجیستری‌های گسترده‌تر زمان اجرا، بپرسند کدام Pluginها برای یک فرمان، ارائه‌دهنده، کانال، مسیر، مهار عامل یا قابلیت مشخص مرتبط‌اند.

برنامه‌ریز، رفتار فعلی مانیفست را سازگار نگه می‌دارد:

فیلدهای activation.* راهنماهای صریح برنامه‌ریز هستند
providers، channels، commandAliases، setup.providers، contracts.tools و هوک‌ها همچنان سازوکار جایگزین مالکیت مانیفست باقی می‌مانند
API برنامه‌ریزِ فقط شناسه‌ها برای فراخواننده‌های موجود همچنان در دسترس است
API طرح، برچسب‌های دلیل را گزارش می‌کند تا عیب‌یابی بتواند راهنماهای صریح را از سازوکار جایگزین مالکیت متمایز کند

Pluginهای کانال و ابزار مشترک پیام

Pluginهای کانال برای کنش‌های عادی گپ نیازی به ثبت ابزار جداگانه‌ای برای ارسال، ویرایش یا واکنش ندارند. OpenClaw یک ابزار مشترک message را در هسته نگه می‌دارد و Pluginهای کانال مالک کشف و اجرای مختص کانال در پشت آن هستند.

مرز فعلی چنین است:

هسته مالک میزبان ابزار مشترک message، سیم‌کشی پرامپت، ثبت و مدیریت نشست/رشته و اعزام اجرا است
Pluginهای کانال مالک کشف کنش محدودشده، کشف قابلیت و هر قطعهٔ شِمای مختص کانال هستند
Pluginهای کانال مالک دستور زبان مکالمهٔ نشست مختص ارائه‌دهنده هستند؛ مانند اینکه شناسه‌های مکالمه چگونه شناسه‌های رشته را کدگذاری می‌کنند یا چگونه از مکالمه‌های والد ارث می‌برند
Pluginهای کانال کنش نهایی را از طریق آداپتور کنش خود اجرا می‌کنند

برای Pluginهای کانال، سطح SDK برابر با ChannelMessageActionAdapter.describeMessageTool(...) است. این فراخوانی یکپارچهٔ کشف به Plugin اجازه می‌دهد کنش‌های قابل‌مشاهده، قابلیت‌ها و مشارکت‌های شِمای خود را با هم بازگرداند تا این بخش‌ها از یکدیگر منحرف نشوند.

نام کنش‌های پیام از واژگانی عمداً بسته و تحت مالکیت هسته استفاده می‌کند تا هر انتقال‌دهنده بتواند هر کنش را رندر کند. Pluginها نام کنش‌ها را از طریق یک PR هسته اضافه می‌کنند؛ ثبت در زمان اجرا عمداً پشتیبانی نمی‌شود.

هنگامی که یک پارامتر مختص کانالِ ابزار پیام، منبع رسانه‌ای مانند مسیر محلی یا URL رسانهٔ راه‌دور را حمل می‌کند، Plugin باید mediaSourceParams را نیز از describeMessageTool(...) بازگرداند. هسته از آن فهرست صریح برای اعمال عادی‌سازی مسیر سندباکس و راهنماهای دسترسی به رسانهٔ خروجی استفاده می‌کند، بدون آنکه نام پارامترهای تحت مالکیت Plugin را به‌صورت ثابت در کد وارد کند. در آنجا نگاشت‌های محدود به کنش را ترجیح دهید، نه یک فهرست تخت برای کل کانال؛ تا پارامتر رسانه‌ای مختص نمایه در کنش‌های نامرتبطی مانند send عادی‌سازی نشود.

هسته دامنهٔ زمان اجرا را به آن مرحلهٔ کشف منتقل می‌کند. فیلدهای مهم عبارت‌اند از:

accountId
currentChannelId
currentThreadTs
currentMessageId
sessionKey
sessionId
agentId
requesterSenderId ورودی مورد اعتماد

این موضوع برای Pluginهای حساس به زمینه اهمیت دارد. یک کانال می‌تواند بر اساس حساب فعال، اتاق/رشته/پیام فعلی یا هویت درخواست‌کنندهٔ مورد اعتماد، کنش‌های پیام را پنهان یا آشکار کند، بدون آنکه شاخه‌های مختص کانال را در ابزار هستهٔ message به‌صورت ثابت در کد وارد کند.

به همین دلیل تغییرات مسیریابی اجراکنندهٔ تعبیه‌شده همچنان کار Plugin محسوب می‌شوند: اجراکننده مسئول انتقال هویت گپ/نشست فعلی به مرز کشف Plugin است تا ابزار مشترک message سطح درستِ تحت مالکیت کانال را برای نوبت فعلی ارائه کند.

برای کمک‌کننده‌های اجرای تحت مالکیت کانال، Pluginهای کانال باید زمان اجرای اجرا را در ماژول‌های Plugin خود نگه دارند. هسته دیگر مالک زمان‌های اجرای کنش پیام Discord، Slack، Telegram یا WhatsApp در src/agents/tools نیست. ما زیرمسیرهای جداگانهٔ plugin-sdk/*-action-runtime را منتشر نمی‌کنیم و این Pluginها باید کد زمان اجرای محلی خود را مستقیماً از ماژول‌های تحت مالکیت Plugin خود وارد کنند.

همین مرز به‌طور کلی برای درزهای SDK با نام ارائه‌دهنده نیز اعمال می‌شود: هسته نباید barrelهای سهولت‌بخش مختص کانال را برای Discord، Signal، Slack، WhatsApp یا Pluginهای مشابه وارد کند. اگر هسته به رفتاری نیاز دارد، یا باید barrel خودِ Plugin همراهِ api.ts / runtime-api.ts را مصرف کند یا آن نیاز را به قابلیتی عمومی و محدود در SDK مشترک ارتقا دهد.

Pluginهای همراه نیز از همین قاعده پیروی می‌کنند. runtime-api.ts یک Plugin همراه نباید facade نشان‌دارِ openclaw/plugin-sdk/<plugin-id> خودش را دوباره صادر کند. این facadeهای نشان‌دار به‌عنوان shimهای سازگاری برای Pluginهای خارجی و مصرف‌کنندگان قدیمی‌تر باقی می‌مانند، اما Pluginهای همراه باید از خروجی‌های محلی به‌همراه زیرمسیرهای عمومی و محدود SDK مانند openclaw/plugin-sdk/channel-policy، openclaw/plugin-sdk/runtime-store یا openclaw/plugin-sdk/webhook-ingress استفاده کنند. کد جدید نباید facadeهای SDK مختص شناسهٔ Plugin اضافه کند، مگر آنکه مرز سازگاری یک زیست‌بوم خارجی موجود به آن نیاز داشته باشد.

به‌طور مشخص برای نظرسنجی‌ها، دو مسیر اجرا وجود دارد:

outbound.sendPoll خط مبنای مشترک برای کانال‌هایی است که با مدل عمومی نظرسنجی سازگارند
actions.handleAction("poll") مسیر ترجیحی برای معناشناسی نظرسنجی مختص کانال یا پارامترهای اضافی نظرسنجی است

اکنون هسته تجزیهٔ مشترک نظرسنجی را تا پس از آنکه اعزام نظرسنجی Plugin کنش را رد کند به تعویق می‌اندازد؛ بنابراین کنترل‌کننده‌های نظرسنجی تحت مالکیت Plugin می‌توانند فیلدهای نظرسنجی مختص کانال را بپذیرند، بدون آنکه ابتدا تجزیه‌گر عمومی نظرسنجی مانع آن‌ها شود.

برای توالی کامل راه‌اندازی، به جزئیات داخلی معماری Plugin مراجعه کنید.

مدل مالکیت قابلیت

OpenClaw یک Plugin بومی را مرز مالکیت یک شرکت یا یک ویژگی در نظر می‌گیرد، نه مجموعه‌ای درهم از یکپارچه‌سازی‌های نامرتبط.

یعنی:

یک Plugin شرکتی معمولاً باید مالک همهٔ سطوح روبه‌OpenClaw آن شرکت باشد
یک Plugin ویژگی معمولاً باید مالک کل سطح ویژگی‌ای باشد که معرفی می‌کند
کانال‌ها باید به‌جای پیاده‌سازی مجدد و موردی رفتار ارائه‌دهنده، قابلیت‌های مشترک هسته را مصرف کنند

فروشندهٔ چندقابلیتی

google مالک استنتاج متن، بک‌اند CLI، تعبیه‌ها، گفتار، صدای بلادرنگ، درک رسانه، تولید تصویر/موسیقی/ویدئو و جست‌وجوی وب است. openai مالک استنتاج متن، تعبیه‌ها، گفتار، رونویسی بلادرنگ، صدای بلادرنگ، درک رسانه و تولید تصویر/ویدئو است. minimax مالک استنتاج متن به‌همراه درک رسانه، گفتار، تولید تصویر/موسیقی/ویدئو و جست‌وجوی وب است.

فروشندهٔ تک‌قابلیتی

arcee و chutes فقط مالک استنتاج متن هستند؛ microsoft فقط مالک گفتار است. یک Plugin فروشنده می‌تواند تا زمانی که نیازمند پوشش بخش‌های بیشتری از سطح آن فروشنده شود، به همین اندازه محدود باقی بماند.

Plugin ویژگی

voice-call مالک انتقال تماس، ابزارها، CLI، مسیرها و پل‌زنی جریان رسانهٔ Twilio است، اما به‌جای واردکردن مستقیم Pluginهای فروشنده، قابلیت‌های مشترک گفتار، رونویسی بلادرنگ و صدای بلادرنگ را مصرف می‌کند.

وضعیت نهایی موردنظر چنین است:

سطح روبه‌OpenClaw یک فروشنده در یک Plugin قرار می‌گیرد، حتی اگر مدل‌های متن، گفتار، تصاویر و ویدئو را دربر گیرد
فروشندگان دیگر نیز می‌توانند همین کار را برای حوزهٔ سطح خود انجام دهند
کانال‌ها اهمیتی نمی‌دهند کدام Plugin فروشنده مالک ارائه‌دهنده است؛ آن‌ها قرارداد قابلیت مشترک ارائه‌شده توسط هسته را مصرف می‌کنند

تمایز کلیدی این است:

Plugin = مرز مالکیت
قابلیت = قرارداد هسته که چندین Plugin می‌توانند آن را پیاده‌سازی یا مصرف کنند

بنابراین اگر OpenClaw دامنهٔ جدیدی مانند ویدئو اضافه کند، پرسش نخست این نیست که «کدام ارائه‌دهنده باید مدیریت ویدئو را به‌صورت ثابت در کد وارد کند؟» پرسش نخست این است که «قرارداد قابلیت ویدئوی هسته چیست؟» پس از ایجاد این قرارداد، Pluginهای فروشنده می‌توانند برای آن ثبت شوند و Pluginهای کانال/ویژگی می‌توانند آن را مصرف کنند.

اگر قابلیت هنوز وجود ندارد، اقدام درست معمولاً این است:

تعریف قابلیت

قابلیت مفقود را در هسته تعریف کنید.

ارائه از طریق SDK

آن را به‌شکلی نوع‌دار از طریق API/زمان اجرای Plugin ارائه کنید.

سیم‌کشی مصرف‌کنندگان

کانال‌ها/ویژگی‌ها را به آن قابلیت متصل کنید.

پیاده‌سازی‌های فروشنده

اجازه دهید Pluginهای فروشنده پیاده‌سازی‌ها را ثبت کنند.

این کار مالکیت را صریح نگه می‌دارد و هم‌زمان از رفتار هسته‌ای وابسته به یک فروشندهٔ واحد یا مسیر کد موردیِ مختص یک Plugin جلوگیری می‌کند.

لایه‌بندی قابلیت

هنگام تصمیم‌گیری دربارهٔ محل قرارگیری کد، از این مدل ذهنی استفاده کنید:

لایهٔ قابلیت هسته

هماهنگ‌سازی مشترک، خط‌مشی، سازوکار جایگزین، قواعد ادغام پیکربندی، معناشناسی تحویل و قراردادهای نوع‌دار.

لایهٔ Plugin فروشنده

APIهای مختص فروشنده، احراز هویت، کاتالوگ‌های مدل، سنتز گفتار، تولید تصویر، بک‌اندهای ویدئو و نقاط پایانی مصرف.

لایهٔ Plugin کانال/ویژگی

یکپارچه‌سازی Discord/Slack/تماس صوتی/و غیره که قابلیت‌های هسته را مصرف می‌کند و آن‌ها را روی یک سطح ارائه می‌دهد.

برای مثال، TTS از این ساختار پیروی می‌کند:

هسته مالک خط‌مشی TTS هنگام پاسخ، ترتیب سازوکارهای جایگزین، ترجیحات و تحویل کانال است
elevenlabs، google، microsoft و openai مالک پیاده‌سازی‌های سنتز هستند
voice-call کمک‌کنندهٔ زمان اجرای TTS تلفنی را مصرف می‌کند

همین الگو باید برای قابلیت‌های آینده ترجیح داده شود.

نمونهٔ Plugin شرکتی چندقابلیتی

یک Plugin شرکتی باید از بیرون یکپارچه به نظر برسد. اگر OpenClaw قراردادهای مشترکی برای مدل‌ها، گفتار، رونویسی بلادرنگ، صدای بلادرنگ، درک رسانه، تولید تصویر، تولید ویدئو، واکشی وب و جست‌وجوی وب داشته باشد، یک فروشنده می‌تواند مالک همهٔ سطوح خود در یک مکان باشد:

  export default definePluginEntry({  id: "exampleai",  name: "ExampleAI",  description: "مدل‌ها و قابلیت‌های رسانه‌ای ExampleAI.",  register(api) {    api.registerProvider({      id: "exampleai",      // هوک‌های احراز هویت/کاتالوگ مدل/زمان اجرا    });     api.registerSpeechProvider({      id: "exampleai",      // پیکربندی گفتار فروشنده — رابط SpeechProviderPlugin را مستقیماً پیاده‌سازی کنید    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      describeImage: (req) => exampleAiMedia.describeImage(req),      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),      describeVideo: (req) => exampleAiMedia.describeVideo(req),    });     api.registerWebSearchProvider({      id: "exampleai-search",      createTool() {        // ابزار جست‌وجوی وب تحت مالکیت فروشنده را بازگردانید.      },    });  },});

آنچه اهمیت دارد نام دقیق کمک‌کننده‌ها نیست. ساختار اهمیت دارد:

یک Plugin مالک سطح فروشنده است
هسته همچنان مالک قراردادهای قابلیت است
ترجمهٔ درخواست ارائه‌دهنده و کمک‌کننده‌های HTTP در Plugin فروشنده باقی می‌مانند
Pluginهای کانال و ویژگی کمک‌کننده‌های api.runtime.* را مصرف می‌کنند، نه کد فروشنده را
آزمون‌های قرارداد می‌توانند تأیید کنند که Plugin قابلیت‌هایی را که ادعای مالکیتشان را دارد ثبت کرده است

نمونهٔ قابلیت: درک ویدئو

OpenClaw از قبل درک تصویر/صدا/ویدئو را به‌عنوان یک قابلیت مشترک در نظر می‌گیرد. همان مدل مالکیت در اینجا نیز اعمال می‌شود:

هسته قرارداد را تعریف می‌کند

هسته، قرارداد درک رسانه را تعریف می‌کند.

Pluginهای ارائه‌دهندگان ثبت می‌شوند

Pluginهای ارائه‌دهندگان، در صورت کاربرد، describeImage، transcribeAudio و describeVideo را ثبت می‌کنند.

مصرف‌کنندگان از رفتار مشترک استفاده می‌کنند

کانال‌ها و Pluginهای قابلیت به‌جای اتصال مستقیم به کد ارائه‌دهنده، رفتار مشترک هسته را مصرف می‌کنند.

این کار از گنجاندن پیش‌فرض‌های ویدیویی یک ارائه‌دهنده در هسته جلوگیری می‌کند. Plugin مالک سطح ارائه‌دهنده است؛ هسته مالک قرارداد قابلیت و رفتار جایگزین است.

تولید ویدیو نیز از همین توالی استفاده می‌کند: هسته مالک قرارداد نوع‌دار قابلیت و ابزار کمکی زمان اجرا است و Pluginهای ارائه‌دهندگان، پیاده‌سازی‌های api.registerVideoGenerationProvider(...) را برای آن ثبت می‌کنند.

به یک چک‌لیست عملی برای عرضه نیاز دارید؟ راهنمای عملی قابلیت‌ها را ببینید.

قراردادها و اعمال آن‌ها

سطح API مربوط به Plugin عمداً در OpenClawPluginApi نوع‌دار و متمرکز شده است. این قرارداد، نقاط ثبت پشتیبانی‌شده و ابزارهای کمکی زمان اجرایی را تعریف می‌کند که یک Plugin می‌تواند به آن‌ها متکی باشد.

دلیل اهمیت این موضوع:

نویسندگان Plugin یک استاندارد داخلی پایدار در اختیار دارند
هسته می‌تواند مالکیت تکراری، مانند ثبت شناسه یک ارائه‌دهنده توسط دو Plugin، را رد کند
راه‌اندازی می‌تواند برای ثبت‌های نامعتبر، اطلاعات تشخیصی قابل‌اقدام ارائه کند
آزمون‌های قرارداد می‌توانند مالکیت Pluginهای همراه را اعمال و از انحراف بی‌سروصدا جلوگیری کنند

اعمال قرارداد در دو لایه انجام می‌شود:

اعمال ثبت در زمان اجرا

رجیستری Plugin هنگام بارگذاری Pluginها، ثبت‌ها را اعتبارسنجی می‌کند. برای نمونه، شناسه‌های تکراری ارائه‌دهنده، شناسه‌های تکراری ارائه‌دهنده گفتار و ثبت‌های نامعتبر، به‌جای رفتار تعریف‌نشده، اطلاعات تشخیصی Plugin ایجاد می‌کنند.

آزمون‌های قرارداد

Pluginهای همراه هنگام اجرای آزمون‌ها در رجیستری‌های قرارداد ثبت می‌شوند تا OpenClaw بتواند مالکیت را به‌صراحت بررسی کند. در حال حاضر، این سازوکار برای ارائه‌دهندگان مدل، ارائه‌دهندگان گفتار، ارائه‌دهندگان جست‌وجوی وب و مالکیت ثبت‌های همراه استفاده می‌شود.

اثر عملی آن این است که OpenClaw از ابتدا می‌داند هر سطح متعلق به کدام Plugin است. به‌این‌ترتیب، هسته و کانال‌ها می‌توانند یکپارچه با یکدیگر ترکیب شوند، زیرا مالکیت به‌جای ضمنی‌بودن، اعلام‌شده، نوع‌دار و آزمون‌پذیر است.

چه چیزی باید در قرارداد باشد

قراردادهای خوب

نوع‌دار
کوچک
ویژه یک قابلیت
تحت مالکیت هسته
قابل‌استفاده مجدد توسط چندین Plugin
قابل‌مصرف توسط کانال‌ها/قابلیت‌ها بدون نیاز به شناخت ارائه‌دهنده

قراردادهای بد

سیاست ویژه ارائه‌دهنده که در هسته پنهان شده است
راه‌های فرار موردی برای Plugin که رجیستری را دور می‌زنند
دسترسی مستقیم کد کانال به پیاده‌سازی یک ارائه‌دهنده
اشیای موردی زمان اجرا که بخشی از OpenClawPluginApi یا api.runtime نیستند

در صورت تردید، سطح انتزاع را بالاتر ببرید: ابتدا قابلیت را تعریف کنید، سپس اجازه دهید Pluginها به آن متصل شوند.

مدل اجرا

Pluginهای بومی OpenClaw درون‌فرایندی و همراه با Gateway اجرا می‌شوند. آن‌ها در محیط ایزوله اجرا نمی‌شوند. یک Plugin بومی بارگذاری‌شده، همان مرز اعتماد در سطح فرایند را دارد که کد هسته دارد.

بسته‌های سازگار به‌طور پیش‌فرض ایمن‌ترند، زیرا OpenClaw در حال حاضر آن‌ها را بسته‌های فراداده/محتوا در نظر می‌گیرد. در نسخه‌های فعلی، این مورد عمدتاً به‌معنای Skills همراه است.

برای Pluginهای غیرهمراه از فهرست‌های مجاز و مسیرهای صریح نصب/بارگذاری استفاده کنید. Pluginهای فضای کاری را کد زمان توسعه در نظر بگیرید، نه پیش‌فرض‌های محیط عملیاتی.

برای نام بسته‌های فضای کاری همراه، شناسه Plugin را به نام npm متصل نگه دارید: به‌طور پیش‌فرض @openclaw/<id>، یا هنگامی که بسته عمداً نقش محدودتری برای Plugin ارائه می‌دهد، یک پسوند نوع‌دار تأییدشده مانند -provider، -plugin، -speech، -sandbox یا -media-understanding.

Note

نکته اعتماد: plugins.allow به شناسه‌های Plugin اعتماد می‌کند، نه منشأ منبع. یک Plugin فضای کاری با شناسه یکسان با Plugin همراه، هنگامی که آن Plugin فضای کاری فعال یا در فهرست مجاز باشد، عمداً نسخه همراه را تحت‌الشعاع قرار می‌دهد. این رفتار عادی است و برای توسعه محلی، آزمایش وصله‌ها و اصلاحات فوری کاربرد دارد. اعتماد به Plugin همراه از تصویر لحظه‌ای منبع — مانیفست و کد موجود روی دیسک در زمان بارگذاری — تعیین می‌شود، نه از فراداده نصب. یک رکورد نصب خراب یا جایگزین‌شده نمی‌تواند بی‌سروصدا سطح اعتماد Plugin همراه را فراتر از آنچه منبع واقعی ادعا می‌کند گسترش دهد.

مرز برون‌بری

OpenClaw قابلیت‌ها را برون‌بری می‌کند، نه تسهیلات پیاده‌سازی را.

ثبت قابلیت را عمومی نگه دارید. برون‌بری ابزارهای کمکی غیرقراردادی را حذف کنید:

زیرمسیرهای ابزار کمکی ویژه Plugin همراه
زیرمسیرهای زیرساخت زمان اجرا که برای API عمومی در نظر گرفته نشده‌اند
ابزارهای کمکی تسهیل‌کننده ویژه ارائه‌دهنده
ابزارهای کمکی راه‌اندازی/آغازبه‌کار که جزئیات پیاده‌سازی هستند

زیرمسیرهای رزروشده ابزار کمکی Pluginهای همراه از نگاشت برون‌بری تولیدشده SDK کنار گذاشته شده‌اند. ابزارهای کمکی ویژه هر مالک را در بسته Plugin متعلق به آن نگه دارید؛ تنها رفتار قابل‌استفاده مجدد میزبان را به قراردادهای عمومی SDK مانند plugin-sdk/gateway-runtime، plugin-sdk/security-runtime و قابلیت‌های تزریق‌شده API مربوط به Plugin ارتقا دهید.

جزئیات داخلی و مرجع

برای پایپ‌لاین بارگذاری، مدل رجیستری، هوک‌های زمان اجرای ارائه‌دهنده، مسیرهای HTTP مربوط به Gateway، طرح‌واره‌های ابزار پیام، تفکیک هدف کانال، کاتالوگ‌های ارائه‌دهنده، Pluginهای موتور زمینه و راهنمای افزودن یک قابلیت جدید، جزئیات داخلی معماری Plugin را ببینید.

مطالب مرتبط

Was this useful?