---
read_when:
    - افزودن یک قابلیت هستهٔ جدید و سطح ثبت Plugin
    - تصمیم‌گیری درباره اینکه کد در هسته، یک Plugin فروشنده، یا یک Plugin ویژگی قرار می‌گیرد
    - اتصال یک کمک‌کنندهٔ زمان اجرا جدید برای کانال‌ها یا ابزارها
sidebarTitle: Adding Capabilities
summary: راهنمای مشارکت‌کنندگان برای افزودن یک قابلیت مشترک جدید به سیستم Plugin در OpenClaw
title: افزودن قابلیت‌ها (راهنمای مشارکت‌کنندگان)
x-i18n:
    generated_at: "2026-04-29T23:40:30Z"
    model: gpt-5.5
    provider: openai
    source_hash: a2879b8a4a215dcc44086181e49c510edae93caff01e52c2f5e6b79e6cb02d7b
    source_path: tools/capability-cookbook.md
    workflow: 16
---

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

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

قاعده:

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

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

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

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

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

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

## ترتیب استاندارد

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

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

هسته:

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

Plugin فروشنده:

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

Plugin ویژگی/کانال:

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

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

وقتی رفتار به قرارداد ارائه‌دهنده مدل تعلق دارد، نه به حلقه عمومی عامل، از hookهای ارائه‌دهنده
استفاده کنید. نمونه‌ها شامل پارامترهای درخواست مخصوص ارائه‌دهنده پس از انتخاب انتقال، ترجیح
auth-profile، هم‌پوشانی‌های پرامپت، و مسیریابی fallback پیگیری پس از failover مدل/پروفایل هستند.

وقتی رفتار به زمان اجرایی تعلق دارد که در حال اجرای یک نوبت است، از hookهای agent harness
استفاده کنید. Harnessها می‌توانند نتیجه تلاش‌های موفق اما غیرقابل استفاده، مانند پاسخ‌های خالی،
فقط reasoning، یا فقط planning را طبقه‌بندی کنند تا سیاست fallback مدل بیرونی بتواند درباره
تلاش دوباره تصمیم بگیرد.

هر دو درز را محدود نگه دارید:

- هسته مالک سیاست تلاش دوباره/fallback است
- Pluginهای ارائه‌دهنده مالک راهنمایی‌های مخصوص ارائه‌دهنده برای درخواست/احراز هویت/مسیریابی هستند
- Pluginهای harness مالک طبقه‌بندی تلاش مخصوص زمان اجرا هستند
- 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` = تولید تصاویر

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

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

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

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

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

## مرتبط

- [Plugin](/fa/tools/plugin)
- [ساخت Skills](/fa/tools/creating-skills)
- [ابزارها و Pluginها](/fa/tools)
