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

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

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

القاعدة:

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

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

## متى تنشئ إمكانية

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

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

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

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

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

## ماذا يوضع وأين

النواة:

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

Plugin المزود:

- استدعاءات API الخاصة بالمزود
- معالجة المصادقة الخاصة بالمزود
- توحيد الطلبات الخاصة بالمزود
- تسجيل تنفيذ الإمكانية

Plugin الميزة/القناة:

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

## أسطح المزود وharness

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

استخدم خطافات Agent harness عندما ينتمي السلوك إلى وقت التشغيل
الذي ينفذ دورًا. يمكن لـ Harnesses تصنيف نتائج المحاولات الناجحة ولكن غير القابلة للاستخدام
مثل الاستجابات الفارغة، أو المعتمدة على reasoning فقط، أو التخطيط فقط حتى تتمكن
سياسة الرجوع الاحتياطي الخارجية للنموذج من اتخاذ قرار إعادة المحاولة.

أبقِ كلا السطحين ضيقين:

- النواة تملك سياسة إعادة المحاولة/الرجوع الاحتياطي
- Plugins المزودين تملك تلميحات الطلب/المصادقة/التوجيه الخاصة بالمزود
- Plugins الـ harness تملك التصنيف الخاص بوقت التشغيل للمحاولات
- تعيد Plugins الخارجية تلميحات، لا تعديلات مباشرة على حالة النواة

## قائمة مراجعة الملفات

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

- `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. تسجل Plugins `openai` و`google` و`fal` و`minimax` عمليات تنفيذ مدعومة من مزود
5. يمكن للمزودين المستقبليين تسجيل العقد نفسه من دون تغيير القنوات/الأدوات

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

- `agents.defaults.imageModel` = تحليل الصور
- `agents.defaults.imageGenerationModel` = توليد الصور

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

## قائمة مراجعة المراجعة

قبل شحن إمكانية جديدة، تحقق من:

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

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

## ذو صلة

- [Plugin](/ar/tools/plugin)
- [إنشاء Skills](/ar/tools/creating-skills)
- [الأدوات وPlugins](/ar/tools)
