---
read_when:
    - إضافة قدرة أساسية جديدة وسطح تسجيل للإضافات
    - تحديد ما إذا كانت الشيفرة تنتمي إلى النواة، أو إضافة خاصة بمورّد، أو إضافة ميزات
    - توصيل مساعد runtime جديد للقنوات أو الأدوات
sidebarTitle: Adding Capabilities
summary: دليل للمساهمين لإضافة قدرة مشتركة جديدة إلى نظام الإضافات في OpenClaw
title: إضافة القدرات (دليل المساهمين)
x-i18n:
    generated_at: "2026-04-05T12:57:44Z"
    model: gpt-5.4
    provider: openai
    source_hash: 29604d88e6df5205b835d71f3078b6223c58b6294135c3e201756c1bcac33ea3
    source_path: tools/capability-cookbook.md
    workflow: 15
---

# إضافة القدرات

<Info>
  هذا **دليل للمساهمين** لمطوري نواة OpenClaw. إذا كنت
  تبني إضافة خارجية، فراجع [بناء الإضافات](/ar/plugins/building-plugins)
  بدلًا من ذلك.
</Info>

استخدم هذا عندما يحتاج OpenClaw إلى نطاق جديد مثل إنشاء الصور، أو إنشاء
الفيديو، أو أي مجال ميزات مستقبلي مدعوم من مورّد.

القاعدة:

- plugin = حد الملكية
- capability = عقد أساسي مشترك

هذا يعني أنه يجب ألا تبدأ بتوصيل مورّد مباشرةً إلى قناة أو
أداة. ابدأ بتعريف القدرة.

## متى يجب إنشاء قدرة

أنشئ قدرة جديدة عندما تكون جميع الشروط التالية صحيحة:

1. يمكن منطقيًا لأكثر من مورّد واحد تنفيذها
2. يجب أن تستهلكها القنوات أو الأدوات أو إضافات الميزات دون الاهتمام
   بالمورّد
3. تحتاج النواة إلى امتلاك سلوك التراجع، أو السياسة، أو التكوين، أو التسليم

إذا كان العمل خاصًا بمورّد فقط ولا يوجد بعد عقد مشترك، فتوقف وعرّف
العقد أولًا.

## التسلسل القياسي

1. عرّف العقد الأساسي المكتوب الأنواع.
2. أضف تسجيل الإضافات لهذا العقد.
3. أضف مساعد runtime مشتركًا.
4. وصّل إضافة مورّد حقيقية واحدة كإثبات.
5. انقل مستهلكي الميزات/القنوات إلى مساعد runtime.
6. أضف اختبارات العقد.
7. وثّق التكوين المواجه للمشغّل ونموذج الملكية.

## ما الذي يذهب إلى أين

النواة:

- أنواع الطلب/الاستجابة
- سجل الموفّرين + التحليل
- سلوك التراجع
- مخطط التكوين بالإضافة إلى بيانات التوثيق الوصفية `title` / `description` المنشورة على عُقد الكائنات المتداخلة، وwildcard، وعناصر المصفوفات، وعُقد التركيب
- سطح مساعد runtime

إضافة المورّد:

- استدعاءات API الخاصة بالمورّد
- معالجة المصادقة الخاصة بالمورّد
- تطبيع الطلبات الخاصة بالمورّد
- تسجيل تنفيذ القدرة

إضافة الميزة/القناة:

- تستدعي `api.runtime.*` أو مساعد `plugin-sdk/*-runtime` المطابق
- لا تستدعي تنفيذ مورّد مباشرةً أبدًا

## قائمة التحقق الخاصة بالملفات

بالنسبة إلى قدرة جديدة، توقّع أن تلمس هذه المناطق:

- `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`
- حزمة إضافة مضمّنة واحدة أو أكثر
- التكوين/الوثائق/الاختبارات

## مثال: إنشاء الصور

يتبع إنشاء الصور البنية القياسية:

1. تعرّف النواة `ImageGenerationProvider`
2. تكشف النواة عن `registerImageGenerationProvider(...)`
3. تكشف النواة عن `runtime.imageGeneration.generate(...)`
4. تسجل إضافات `openai` و`google` و`fal` و`minimax` تنفيذات مدعومة من المورّد
5. يمكن للمورّدين المستقبليين تسجيل العقد نفسه دون تغيير القنوات/الأدوات

مفتاح التكوين منفصل عن توجيه تحليل الرؤية:

- `agents.defaults.imageModel` = تحليل الصور
- `agents.defaults.imageGenerationModel` = إنشاء الصور

أبقِ هذين منفصلين حتى يظل سلوك التراجع والسياسة واضحين.

## قائمة التحقق الخاصة بالمراجعة

قبل شحن قدرة جديدة، تحقّق من:

- عدم استيراد أي قناة/أداة لشيفرة مورّد مباشرةً
- أن مساعد runtime هو المسار المشترك
- أن اختبار عقد واحدًا على الأقل يؤكد الملكية المضمّنة
- أن وثائق التكوين تسمّي النموذج الجديد/مفتاح التكوين الجديد
- أن وثائق الإضافات تشرح حد الملكية

إذا تخطّى طلب سحب طبقة القدرة وضمّن سلوك مورّد بشكل صلب داخل
قناة/أداة، فأعِده وحدد العقد أولًا.
