---
read_when:
    - افزودن یک قابلیت هسته‌ای جدید و سطح ثبت Plugin
    - تصمیم‌گیری درباره اینکه کد باید در هسته، یک Plugin فروشنده، یا یک Plugin ویژگی قرار بگیرد
    - سیم‌کشی یک راهنمای اجرایی جدید برای کانال‌ها یا ابزارها
sidebarTitle: Adding capabilities
summary: راهنمای مشارکت‌کنندگان برای افزودن یک قابلیت مشترک جدید به سامانه Plugin در OpenClaw
title: افزودن قابلیت‌ها (راهنمای مشارکت‌کنندگان)
x-i18n:
    generated_at: "2026-06-27T18:09:00Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b8a25122a7b76ff5bbb7616748d5fad2397502f9accb5428134a75d65e872034
    source_path: plugins/adding-capabilities.md
    workflow: 16
---

<Info>
  این یک **راهنمای مشارکت‌کننده** برای توسعه‌دهندگان هسته OpenClaw است. اگر در حال
  ساخت یک Plugin خارجی هستید، به‌جای آن [ساخت Pluginها](/fa/plugins/building-plugins)
  را ببینید. برای مرجع عمیق معماری (مدل قابلیت، مالکیت،
  خط لوله بارگذاری، کمک‌کننده‌های زمان اجرا)، [درونیات Plugin](/fa/plugins/architecture) را ببینید.
</Info>

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

قاعده:

- **Plugin** = مرز مالکیت
- **قابلیت** = قرارداد مشترک هسته

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

## چه زمانی یک قابلیت ایجاد کنیم

وقتی **همه** موارد زیر درست هستند، یک قابلیت جدید ایجاد کنید:

1. بیش از یک فروشنده بتواند به‌طور معقول آن را پیاده‌سازی کند.
2. کانال‌ها، ابزارها، یا Pluginهای قابلیت باید بدون اهمیت دادن به فروشنده از آن استفاده کنند.
3. هسته باید مالک رفتار جایگزینی، سیاست، پیکربندی، یا تحویل باشد.

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

## توالی استاندارد

1. قرارداد تایپ‌شده هسته را تعریف کنید.
2. ثبت Plugin را برای آن قرارداد اضافه کنید.
3. یک کمک‌کننده مشترک زمان اجرا اضافه کنید.
4. یک Plugin فروشنده واقعی را به‌عنوان اثبات متصل کنید.
5. مصرف‌کنندگان قابلیت/کانال را به کمک‌کننده زمان اجرا منتقل کنید.
6. تست‌های قرارداد را اضافه کنید.
7. پیکربندی و مدل مالکیت روبه‌روی اپراتور را مستند کنید.

## چه چیزی کجا قرار می‌گیرد

**هسته:**

- نوع‌های درخواست/پاسخ.
- رجیستری ارائه‌دهنده + حل‌وفصل.
- رفتار جایگزینی.
- شِمای پیکربندی همراه با فراداده مستندات `title` / `description` منتشرشده روی گره‌های آبجکت تودرتو، وایلدکارت، آیتم آرایه، و ترکیب.
- سطح کمک‌کننده زمان اجرا.

**Plugin فروشنده:**

- فراخوانی‌های API فروشنده.
- مدیریت احراز هویت فروشنده.
- نرمال‌سازی درخواست ویژه فروشنده.
- ثبت پیاده‌سازی قابلیت.

**Plugin قابلیت/کانال:**

- `api.runtime.*` یا کمک‌کننده متناظر `plugin-sdk/*-runtime` را فراخوانی می‌کند.
- هرگز پیاده‌سازی فروشنده را مستقیما فراخوانی نمی‌کند.

## مرزهای ارائه‌دهنده و مهار

وقتی رفتار به قرارداد ارائه‌دهنده مدل تعلق دارد نه حلقه عمومی عامل، از **قلاب‌های ارائه‌دهنده** استفاده کنید. نمونه‌ها شامل پارامترهای درخواست ویژه ارائه‌دهنده پس از انتخاب انتقال، ترجیح پروفایل احراز هویت، همپوشانی‌های پرامپت، و مسیریابی جایگزین پیگیری پس از جابه‌جایی مدل/پروفایل هستند.

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

هر دو مرز را باریک نگه دارید:

- هسته مالک سیاست تلاش دوباره/جایگزینی است.
- Pluginهای ارائه‌دهنده مالک اشاره‌های درخواست/احراز هویت/مسیریابی ویژه ارائه‌دهنده هستند.
- Pluginهای مهار مالک طبقه‌بندی تلاش ویژه زمان اجرا هستند.
- Pluginهای شخص ثالث اشاره برمی‌گردانند، نه جهش مستقیم در وضعیت هسته.

## چک‌لیست فایل

برای یک قابلیت جدید، انتظار داشته باشید این نواحی را تغییر دهید:

- `src/<capability>/types.ts`
- `src/<capability>/...registry/runtime.ts`
- `src/plugins/types.ts`
- `src/plugins/registry.ts`
- `src/plugins/captured-registration.ts`
- `src/plugins/contracts/registry.ts`
- `src/plugins/runtime/types-core.ts`
- `src/plugins/runtime/index.ts`
- `src/plugin-sdk/<capability>.ts`
- `src/plugin-sdk/<capability>-runtime.ts`
- یک یا چند بسته Plugin باندل‌شده.
- پیکربندی، مستندات، تست‌ها.

## مثال کامل: تولید تصویر

تولید تصویر از شکل استاندارد پیروی می‌کند:

1. هسته `ImageGenerationProvider` را تعریف می‌کند.
2. هسته `registerImageGenerationProvider(...)` را در دسترس می‌گذارد.
3. هسته `runtime.imageGeneration.generate(...)` را در دسترس می‌گذارد.
4. Pluginهای `openai`، `google`، `fal`، و `minimax` پیاده‌سازی‌های دارای پشتوانه فروشنده را ثبت می‌کنند.
5. فروشنده‌های آینده همان قرارداد را بدون تغییر کانال‌ها/ابزارها ثبت می‌کنند.

کلید پیکربندی عمدا از مسیریابی تحلیل بینایی جدا است:

- `agents.defaults.imageModel` تصاویر را تحلیل می‌کند.
- `agents.defaults.imageGenerationModel` تصاویر را تولید می‌کند.

این‌ها را جدا نگه دارید تا جایگزینی و سیاست صریح بمانند.

## ارائه‌دهنده‌های جاسازی

برای ارائه‌دهنده‌های جاسازی برداری قابل استفاده مجدد، از `embeddingProviders` استفاده کنید. این قرارداد
عمدا گسترده‌تر از حافظه است: ابزارها، جست‌وجو، بازیابی، واردکننده‌ها، یا
Pluginهای قابلیت آینده می‌توانند بدون وابستگی به موتور حافظه از جاسازی‌ها استفاده کنند.

جست‌وجوی حافظه می‌تواند از `embeddingProviders` عمومی استفاده کند. قرارداد قدیمی‌تر
`memoryEmbeddingProviders` یک سازگاری منسوخ‌شده است تا زمانی که ارائه‌دهنده‌های
ویژه حافظه موجود مهاجرت کنند؛ ارائه‌دهنده‌های جاسازی قابل استفاده مجدد جدید باید از
`embeddingProviders` استفاده کنند.

## چک‌لیست بازبینی

پیش از انتشار یک قابلیت جدید، بررسی کنید:

- هیچ کانال/ابزاری کد فروشنده را مستقیما وارد نمی‌کند.
- کمک‌کننده زمان اجرا مسیر مشترک است.
- دست‌کم یک تست قرارداد مالکیت باندل‌شده را اثبات می‌کند.
- مستندات پیکربندی نام مدل/کلید پیکربندی جدید را ذکر می‌کنند.
- مستندات Plugin مرز مالکیت را توضیح می‌دهند.

اگر یک PR لایه قابلیت را دور می‌زند و رفتار فروشنده را در یک کانال/ابزار سخت‌کد می‌کند، آن را برگردانید و ابتدا قرارداد را تعریف کنید.

## مرتبط

- [درونیات Plugin](/fa/plugins/architecture) — مدل قابلیت، مالکیت، خط لوله بارگذاری، کمک‌کننده‌های زمان اجرا.
- [ساخت Pluginها](/fa/plugins/building-plugins) — آموزش اولین Plugin.
- [نمای کلی SDK](/fa/plugins/sdk-overview) — نقشه ایمپورت و مرجع API ثبت.
- [ایجاد Skills](/fa/tools/creating-skills) — سطح همراه مشارکت‌کننده.