Plugin maintainer reference

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

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

نصب و استفاده از Pluginها

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

ساخت Pluginها

آموزش ساخت نخستین Plugin با کوچک‌ترین مانیفست قابل‌استفاده.

Pluginهای کانال

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

Pluginهای ارائه‌دهنده

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

نمای کلی SDK

مرجع نگاشت واردسازی و API ثبت.

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

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

قابلیت	روش ثبت	نمونه Pluginها
استنتاج متنی	`api.registerProvider(...)`	`anthropic`, `openai`
بک‌اند استنتاج CLI	`api.registerCliBackend(...)`	`anthropic`, `openai`
تعبیه‌سازی‌ها	`api.registerEmbeddingProvider(...)`	Pluginهای برداری متعلق به ارائه‌دهنده
گفتار	`api.registerSpeechProvider(...)`	`elevenlabs`, `microsoft`
رونویسی بلادرنگ	`api.registerRealtimeTranscriptionProvider(...)`	`openai`
صدای بلادرنگ	`api.registerRealtimeVoiceProvider(...)`	`google`, `openai`
درک رسانه	`api.registerMediaUnderstandingProvider(...)`	`google`, `openai`
منبع رونویسی‌ها	`api.registerTranscriptSourceProvider(...)`	`discord`
تولید تصویر	`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`

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

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

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

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

شکل‌های Plugin

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

قابلیت ساده

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

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

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

صرفاً قلابی

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

فاقد قابلیت

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

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

قلاب‌های قدیمی

قلاب before_agent_start همچنان به‌عنوان مسیر سازگاری برای Pluginهای صرفاً قلابی پشتیبانی می‌شود. Pluginهای قدیمیِ واقعی هنوز به آن وابسته‌اند.

مسیر پیش‌رو:

فعال نگه داشتن آن
مستندسازی آن به‌عنوان قابلیت قدیمی
ترجیح before_model_resolve برای کارهای بازنویسی مدل/ارائه‌دهنده
ترجیح before_prompt_build برای کارهای تغییر اعلان
حذف آن تنها پس از کاهش استفاده واقعی و اثبات ایمنی مهاجرت توسط پوشش نمونه‌های آزمایشی

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

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

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

هیچ‌یک از نشانه‌های توصیه‌ای/هشداردهنده امروز موجب ازکارافتادن Plugin شما نمی‌شوند. این نشانه‌ها در openclaw status --all و openclaw plugins doctor نیز ظاهر می‌شوند.

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

سیستم Plugin در OpenClaw چهار لایه دارد:

مانیفست و کشف

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

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

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

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

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

مصرف سطح‌ها

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

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

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

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

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

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

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

تصویر لحظه‌ای فراداده Plugin و جدول جست‌وجو

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

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

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

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

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

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

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

برخی فراخواننده‌های مسیر سرد همچنان رجیستری‌های مانیفست را مستقیماً از نمایه پایدار 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 اجازه می‌دهد کنش‌های قابل‌مشاهده، قابلیت‌ها و مشارکت‌های طرح‌واره خود را با هم بازگرداند تا این بخش‌ها از یکدیگر منحرف نشوند.

هنگامی که پارامتر مختص کانالِ ابزار پیام، منبع رسانه‌ای مانند مسیر محلی یا 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 با نام ارائه‌دهنده نیز صدق می‌کند: هسته نباید بسته‌های تجمیعی تسهیل‌کننده مختص کانال را برای Discord، Signal، Slack، WhatsApp یا Pluginهای مشابه وارد کند. اگر هسته به رفتاری نیاز دارد، باید بسته تجمیعی api.ts / runtime-api.ts خودِ Plugin همراه را مصرف کند یا آن نیاز را به یک قابلیت عمومی محدود در SDK مشترک ارتقا دهد.

Pluginهای همراه از همین قاعده پیروی می‌کنند. runtime-api.ts یک Plugin همراه نباید نمای برندشده openclaw/plugin-sdk/<plugin-id> خود را دوباره صادر کند. آن نماهای برندشده به‌عنوان لایه‌های سازگاری برای Pluginهای خارجی و مصرف‌کنندگان قدیمی‌تر باقی می‌مانند، اما Pluginهای همراه باید از صادرات محلی به‌همراه زیرمسیرهای عمومی محدود SDK مانند openclaw/plugin-sdk/channel-policy، openclaw/plugin-sdk/runtime-store یا openclaw/plugin-sdk/webhook-ingress استفاده کنند. کد جدید نباید نماهای 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/voice-call/و موارد مشابه که قابلیت‌های هسته را مصرف و آن‌ها را روی یک سطح ارائه می‌کند.

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

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

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

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

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

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

آنچه اهمیت دارد نام دقیق ابزارهای کمکی نیست؛ ساختار مهم است:

یک 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 همراه را فراتر از ادعاهای منبع واقعی گسترش دهد.

مرز صدور

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

ثبت قابلیت را عمومی نگه دارید. صدور کمک‌تابع‌های خارج از قرارداد را محدود کنید:

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

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

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

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

مرتبط

Was this useful?