---
read_when:
    - أنت تبني Plugin لـ OpenClaw
    - تحتاج إلى شحن مخطط إعدادات لـ Plugin أو تصحيح أخطاء التحقق من صحة Plugin
summary: متطلبات بيان Plugin + مخطط JSON ‏(التحقق الصارم من صحة الإعدادات)
title: بيان Plugin
x-i18n:
    generated_at: "2026-04-19T01:11:10Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181
    source_path: plugins/manifest.md
    workflow: 15
---

# بيان Plugin ‏(`openclaw.plugin.json`)

هذه الصفحة مخصصة لـ **بيان Plugin الأصلي في OpenClaw** فقط.

للاطلاع على تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles).

تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة:

- حزمة Codex: `.codex-plugin/plugin.json`
- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي
  من دون بيان
- حزمة Cursor: `.cursor-plugin/plugin.json`

يكتشف OpenClaw تلقائيًا تخطيطات الحزم هذه أيضًا، لكنها لا تُتحقَّق
مقابل مخطط `openclaw.plugin.json` الموضح هنا.

بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية إضافةً إلى
جذور Skills المعلنة، وجذور أوامر Claude، وقيم Claude bundle الافتراضية في `settings.json`،
وقيم Claude bundle الافتراضية لـ LSP، وحِزم الخطافات المدعومة عندما يطابق التخطيط
توقعات وقت التشغيل في OpenClaw.

يجب على كل Plugin أصلي في OpenClaw **أن يوفّر** ملف `openclaw.plugin.json` في
**جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من صحة الإعدادات
**من دون تنفيذ شيفرة Plugin**. وتُعامَل البيانات المفقودة أو غير الصالحة على أنها
أخطاء في Plugin وتمنع التحقق من صحة الإعدادات.

راجع دليل نظام Plugins الكامل: [Plugins](/ar/tools/plugin).
وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية:
[نموذج القدرات](/ar/plugins/architecture#public-capability-model).

## ما الذي يفعله هذا الملف

يمثل `openclaw.plugin.json` البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل
شيفرة Plugin الخاصة بك.

استخدمه من أجل:

- هوية Plugin
- التحقق من صحة الإعدادات
- بيانات المصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل Plugin
- تلميحات تفعيل منخفضة التكلفة يمكن لواجهات مستوى التحكم فحصها قبل تحميل وقت التشغيل
- واصفات إعداد منخفضة التكلفة يمكن لواجهات الإعداد/التهيئة الأولية فحصها قبل
  تحميل وقت التشغيل
- بيانات الأسماء المستعارة والتفعيل التلقائي التي يجب حلّها قبل تحميل وقت تشغيل Plugin
- بيانات وصفية مختصرة لملكية عائلة النماذج يجب أن تفعّل Plugin تلقائيًا قبل تحميل وقت التشغيل
- لقطات ثابتة لملكية القدرات تُستخدم لربط التوافق المضمّن وتغطية العقود
- بيانات وصفية منخفضة التكلفة لمشغّل QA يمكن للمضيف المشترك `openclaw qa` فحصها
  قبل تحميل وقت تشغيل Plugin
- بيانات وصفية لإعدادات خاصة بالقنوات يجب دمجها في أسطح الفهرسة والتحقق
  من دون تحميل وقت التشغيل
- تلميحات واجهة الإعدادات

لا تستخدمه من أجل:

- تسجيل سلوك وقت التشغيل
- تعريف نقاط دخول الشيفرة
- بيانات تثبيت npm الوصفية

فهذه تنتمي إلى شيفرة Plugin وملف `package.json` الخاص بك.

## مثال أدنى

```json
{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
```

## مثال متقدم

```json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}
```

## مرجع الحقول ذات المستوى الأعلى

| الحقل                               | مطلوب | النوع                             | المعنى                                                                                                                                                                                                      |
| ----------------------------------- | ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                | نعم    | `string`                          | المعرّف القياسي لـ Plugin. هذا هو المعرّف المستخدم في `plugins.entries.<id>`.                                                                                                                              |
| `configSchema`                      | نعم    | `object`                          | مخطط JSON مضمن لإعدادات هذا Plugin.                                                                                                                                                                         |
| `enabledByDefault`                  | لا     | `true`                            | يحدد أن Plugin المضمّن مفعّل افتراضيًا. احذف هذا الحقل، أو اضبطه على أي قيمة ليست `true`، لترك Plugin معطّلًا افتراضيًا.                                                                                 |
| `legacyPluginIds`                   | لا     | `string[]`                        | معرّفات قديمة تُطبَّع إلى معرّف Plugin القياسي هذا.                                                                                                                                                         |
| `autoEnableWhenConfiguredProviders` | لا     | `string[]`                        | معرّفات مقدّمي الخدمة التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النماذج.                                                                                     |
| `kind`                              | لا     | `"memory"` \| `"context-engine"`  | يعرّف نوع Plugin حصريًا يُستخدم بواسطة `plugins.slots.*`.                                                                                                                                                  |
| `channels`                          | لا     | `string[]`                        | معرّفات القنوات التي يملكها هذا Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات.                                                                                                                         |
| `providers`                         | لا     | `string[]`                        | معرّفات مقدّمي الخدمة التي يملكها هذا Plugin.                                                                                                                                                                |
| `modelSupport`                      | لا     | `object`                          | بيانات وصفية مختصرة مملوكة للبيان لعائلة النماذج، تُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل.                                                                                                         |
| `providerEndpoints`                 | لا     | `object[]`                        | بيانات وصفية للمضيف/`baseUrl` مملوكة للبيان لمسارات مقدّمي الخدمة التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل المزوّد.                                                                               |
| `cliBackends`                       | لا     | `string[]`                        | معرّفات الواجهات الخلفية للاستدلال في CLI التي يملكها هذا Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع الإعدادات الصريحة.                                                                  |
| `syntheticAuthRefs`                 | لا     | `string[]`                        | مراجع مزوّد الخدمة أو الواجهة الخلفية لـ CLI التي يجب اختبار خطاف المصادقة الاصطناعية المملوك لـ Plugin لها أثناء الاكتشاف البارد للنماذج قبل تحميل وقت التشغيل.                                          |
| `nonSecretAuthMarkers`              | لا     | `string[]`                        | قيم مؤقتة لمفاتيح API مملوكة لـ Plugin المضمّن تمثل حالة اعتماد محلية أو OAuth أو بيانات اعتماد محيطية غير سرية.                                                                                         |
| `commandAliases`                    | لا     | `object[]`                        | أسماء أوامر يملكها هذا Plugin ويجب أن تنتج إعدادات واعية بـ Plugin وتشخيصات CLI قبل تحميل وقت التشغيل.                                                                                                    |
| `providerAuthEnvVars`               | لا     | `Record<string, string[]>`        | بيانات وصفية منخفضة التكلفة لمتغيرات البيئة الخاصة بمصادقة مزوّد الخدمة يمكن لـ OpenClaw فحصها من دون تحميل شيفرة Plugin.                                                                                |
| `providerAuthAliases`               | لا     | `Record<string, string>`          | معرّفات مقدّمي خدمة يجب أن تعيد استخدام معرّف مزوّد خدمة آخر لأجل البحث عن المصادقة، مثل مزوّد برمجي يشارك مفتاح API وملفات تعريف المصادقة الخاصة بالمزوّد الأساسي.                                       |
| `channelEnvVars`                    | لا     | `Record<string, string[]>`        | بيانات وصفية منخفضة التكلفة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل شيفرة Plugin. استخدم هذا للحالات المدفوعة بمتغيرات البيئة لإعداد القنوات أو أسطح المصادقة التي يجب أن تراها أدوات البدء/الإعداد العامة. |
| `providerAuthChoices`               | لا     | `object[]`                        | بيانات وصفية منخفضة التكلفة لخيارات المصادقة لمحددات التهيئة الأولية، وحلّ المزوّد المفضل، وربط أعلام CLI البسيطة.                                                                                       |
| `activation`                        | لا     | `object`                          | تلميحات تفعيل منخفضة التكلفة للتحميل الذي تحفزه المزوّدات والأوامر والقنوات والمسارات والقدرات. بيانات وصفية فقط؛ ما يزال وقت تشغيل Plugin يملك السلوك الفعلي.                                             |
| `setup`                             | لا     | `object`                          | واصفات إعداد/تهيئة أولية منخفضة التكلفة يمكن لواجهات الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin.                                                                                              |
| `qaRunners`                         | لا     | `object[]`                        | واصفات منخفضة التكلفة لمشغلات QA يستخدمها المضيف المشترك `openclaw qa` قبل تحميل وقت تشغيل Plugin.                                                                                                        |
| `contracts`                         | لا     | `object`                          | لقطة ثابتة للقدرات المضمّنة من أجل الكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، والبحث على الويب، وملكية الأدوات.                    |
| `channelConfigs`                    | لا     | `Record<string, object>`          | بيانات وصفية لإعدادات القنوات مملوكة للبيان تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل.                                                                                                         |
| `skills`                            | لا     | `string[]`                        | أدلة Skills التي يجب تحميلها، نسبةً إلى جذر Plugin.                                                                                                                                                         |
| `name`                              | لا     | `string`                          | اسم Plugin مقروء للبشر.                                                                                                                                                                                      |
| `description`                       | لا     | `string`                          | ملخص قصير يظهر في أسطح Plugin.                                                                                                                                                                               |
| `version`                           | لا     | `string`                          | إصدار معلوماتي لـ Plugin.                                                                                                                                                                                   |
| `uiHints`                           | لا     | `Record<string, object>`          | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات.                                                                                                                                 |

## مرجع `providerAuthChoices`

يصف كل إدخال في `providerAuthChoices` خيارًا واحدًا للتهيئة الأولية أو المصادقة.
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل المزوّد.

| الحقل                 | مطلوب | النوع                                            | المعنى                                                                                         |
| --------------------- | ------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `provider`            | نعم    | `string`                                         | معرّف مزوّد الخدمة الذي ينتمي إليه هذا الخيار.                                                  |
| `method`              | نعم    | `string`                                         | معرّف طريقة المصادقة التي سيتم التوجيه إليها.                                                   |
| `choiceId`            | نعم    | `string`                                         | معرّف ثابت لخيار المصادقة تستخدمه مسارات التهيئة الأولية وCLI.                                 |
| `choiceLabel`         | لا     | `string`                                         | تسمية موجهة للمستخدم. إذا لم تُحدَّد، يعود OpenClaw إلى `choiceId`.                            |
| `choiceHint`          | لا     | `string`                                         | نص مساعد قصير لأداة الاختيار.                                                                  |
| `assistantPriority`   | لا     | `number`                                         | تُرتَّب القيم الأقل أولًا في أدوات الاختيار التفاعلية التي يقودها المساعد.                     |
| `assistantVisibility` | لا     | `"visible"` \| `"manual-only"`                   | يُخفي الخيار من أدوات اختيار المساعد مع الاستمرار في السماح باختياره يدويًا عبر CLI.          |
| `deprecatedChoiceIds` | لا     | `string[]`                                       | معرّفات خيارات قديمة يجب أن تعيد توجيه المستخدمين إلى هذا الخيار البديل.                       |
| `groupId`             | لا     | `string`                                         | معرّف مجموعة اختياري لتجميع الخيارات المرتبطة.                                                 |
| `groupLabel`          | لا     | `string`                                         | تسمية موجهة للمستخدم لتلك المجموعة.                                                            |
| `groupHint`           | لا     | `string`                                         | نص مساعد قصير للمجموعة.                                                                        |
| `optionKey`           | لا     | `string`                                         | مفتاح خيار داخلي لمسارات المصادقة البسيطة ذات العلم الواحد.                                    |
| `cliFlag`             | لا     | `string`                                         | اسم علم CLI، مثل `--openrouter-api-key`.                                                       |
| `cliOption`           | لا     | `string`                                         | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key <key>`.                                      |
| `cliDescription`      | لا     | `string`                                         | الوصف المستخدم في مساعدة CLI.                                                                  |
| `onboardingScopes`    | لا     | `Array<"text-inference" \| "image-generation">`  | أسطح التهيئة الأولية التي يجب أن يظهر فيها هذا الخيار. إذا لم يُحدَّد، فالقيمة الافتراضية هي `["text-inference"]`. |

## مرجع `commandAliases`

استخدم `commandAliases` عندما يملك Plugin اسم أمر في وقت التشغيل قد يضعه المستخدمون
عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw
هذه البيانات الوصفية للتشخيصات من دون استيراد شيفرة وقت تشغيل Plugin.

```json
{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}
```

| الحقل        | مطلوب | النوع             | المعنى                                                                      |
| ------------ | ------ | ----------------- | --------------------------------------------------------------------------- |
| `name`       | نعم    | `string`          | اسم الأمر الذي ينتمي إلى هذا Plugin.                                       |
| `kind`       | لا     | `"runtime-slash"` | يحدد الاسم المستعار كأمر slash للدردشة بدلًا من أمر CLI جذري.              |
| `cliCommand` | لا     | `string`          | أمر CLI جذري مرتبط يُقترح لعمليات CLI، إذا كان موجودًا.                    |

## مرجع `activation`

استخدم `activation` عندما يستطيع Plugin أن يعلن بتكلفة منخفضة عن أحداث مستوى التحكم
التي يجب أن تفعّله لاحقًا.

## مرجع `qaRunners`

استخدم `qaRunners` عندما يساهم Plugin بواحد أو أكثر من مشغلات النقل تحت الجذر
المشترك `openclaw qa`. أبقِ هذه البيانات الوصفية منخفضة التكلفة وثابتة؛ فما يزال
وقت تشغيل Plugin يملك تسجيل CLI الفعلي عبر سطح `runtime-api.ts`
خفيف الوزن الذي يصدّر `qaRunnerCliRegistrations`.

```json
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "تشغيل مسار QA الحي لـ Matrix المعتمد على Docker مقابل خادم منزلي مؤقت"
    }
  ]
}
```

| الحقل         | مطلوب | النوع    | المعنى                                                            |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `commandName` | نعم    | `string` | الأمر الفرعي المُركّب تحت `openclaw qa`، مثل `matrix`.            |
| `description` | لا     | `string` | نص مساعدة احتياطي يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. |

هذه الكتلة هي بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا
تستبدل `register(...)` أو `setupEntry` أو غيرها من نقاط دخول
وقت التشغيل/Plugin. يستخدمها المستهلكون الحاليون كتلميح للتضييق قبل تحميل
أوسع للـ Plugin، لذلك فإن غياب بيانات التفعيل الوصفية يكلّف عادةً في الأداء فقط؛
ولا ينبغي أن يغيّر الصحة ما دامت بدائل ملكية البيان القديمة لا تزال موجودة.

```json
{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}
```

| الحقل            | مطلوب | النوع                                                 | المعنى                                                        |
| ---------------- | ------ | ----------------------------------------------------- | ------------------------------------------------------------- |
| `onProviders`    | لا     | `string[]`                                            | معرّفات مزوّدي الخدمة التي يجب أن تفعّل هذا Plugin عند طلبها. |
| `onCommands`     | لا     | `string[]`                                            | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin.                 |
| `onChannels`     | لا     | `string[]`                                            | معرّفات القنوات التي يجب أن تفعّل هذا Plugin.                 |
| `onRoutes`       | لا     | `string[]`                                            | أنواع المسارات التي يجب أن تفعّل هذا Plugin.                  |
| `onCapabilities` | لا     | `Array<"provider" \| "channel" \| "tool" \| "hook">`  | تلميحات قدرات عامة تُستخدم في تخطيط التفعيل على مستوى التحكم. |

المستهلكون الفعليون الحاليون:

- يعود تخطيط CLI المحفَّز بالأوامر إلى
  `commandAliases[].cliCommand` أو `commandAliases[].name`
  القديمين
- يعود تخطيط الإعداد/القناة المحفَّز بالقنوات إلى ملكية
  `channels[]` القديمة عندما تكون بيانات تفعيل القناة الصريحة غير موجودة
- يعود تخطيط الإعداد/وقت التشغيل المحفَّز بالمزوّد إلى
  ملكية `providers[]` و`cliBackends[]` ذات المستوى الأعلى القديمة عندما تكون
  بيانات تفعيل المزوّد الصريحة غير موجودة

## مرجع `setup`

استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات وصفية منخفضة التكلفة
يملكها Plugin قبل تحميل وقت التشغيل.

```json
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

يبقى `cliBackends` ذو المستوى الأعلى صالحًا ويستمر في وصف الواجهات الخلفية
للاستدلال في CLI. ويُعد `setup.cliBackends` سطح الواصفات الخاص بالإعداد
لمسارات مستوى التحكم/الإعداد التي يجب أن تبقى بيانات وصفية فقط.

عند وجودهما، يكون `setup.providers` و`setup.cliBackends` هما سطح البحث المفضل
المعتمد على الواصفات أولًا لاكتشاف الإعداد. وإذا كان الواصف يضيّق فقط نطاق
Plugin المرشح وما زال الإعداد يحتاج إلى خطافات وقت إعداد أغنى في وقت التشغيل،
فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه باعتباره
مسار التنفيذ الاحتياطي.

ولأن بحث الإعداد قد ينفّذ شيفرة `setup-api` يملكها Plugin، يجب أن تبقى
القيم المطَبَّعة لـ `setup.providers[].id` و`setup.cliBackends[]` فريدة على مستوى
جميع Plugins المكتشفة. وتفشل الملكية الملتبسة بشكل مغلق بدلًا من اختيار
فائز وفق ترتيب الاكتشاف.

### مرجع `setup.providers`

| الحقل         | مطلوب | النوع      | المعنى                                                                                |
| ------------- | ------ | ---------- | ------------------------------------------------------------------------------------- |
| `id`          | نعم    | `string`   | معرّف مزوّد الخدمة المعروض أثناء الإعداد أو التهيئة الأولية. احرص على بقاء المعرّفات المطَبَّعة فريدة عالميًا. |
| `authMethods` | لا     | `string[]` | معرّفات طرق الإعداد/المصادقة التي يدعمها هذا المزوّد من دون تحميل وقت التشغيل الكامل. |
| `envVars`     | لا     | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. |

### حقول `setup`

| الحقل              | مطلوب | النوع      | المعنى                                                                                          |
| ------------------ | ------ | ---------- | ----------------------------------------------------------------------------------------------- |
| `providers`        | لا     | `object[]` | واصفات إعداد مزوّد الخدمة المعروضة أثناء الإعداد والتهيئة الأولية.                              |
| `cliBackends`      | لا     | `string[]` | معرّفات الواجهات الخلفية في وقت الإعداد المستخدمة في بحث الإعداد المعتمد على الواصفات أولًا. احرص على بقاء المعرّفات المطَبَّعة فريدة عالميًا. |
| `configMigrations` | لا     | `string[]` | معرّفات ترحيل الإعدادات التي يملكها سطح إعداد هذا Plugin.                                       |
| `requiresRuntime`  | لا     | `boolean`  | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث المعتمد على الواصفات.         |

## مرجع `uiHints`

يمثل `uiHints` خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة.

```json
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "تُستخدم لطلبات OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
```

يمكن أن يتضمن كل تلميح حقل ما يلي:

| الحقل         | النوع      | المعنى                                  |
| ------------- | ---------- | --------------------------------------- |
| `label`       | `string`   | تسمية الحقل الموجهة للمستخدم.           |
| `help`        | `string`   | نص مساعد قصير.                          |
| `tags`        | `string[]` | وسوم واجهة مستخدم اختيارية.             |
| `advanced`    | `boolean`  | يحدد الحقل على أنه متقدم.               |
| `sensitive`   | `boolean`  | يحدد الحقل على أنه سري أو حساس.         |
| `placeholder` | `string`   | نص العنصر النائب لمدخلات النماذج.       |

## مرجع `contracts`

استخدم `contracts` فقط لبيانات وصفية ثابتة لملكية القدرات يمكن لـ OpenClaw
قراءتها من دون استيراد وقت تشغيل Plugin.

```json
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

كل قائمة اختيارية:

| الحقل                            | النوع      | المعنى                                                       |
| -------------------------------- | ---------- | ------------------------------------------------------------ |
| `speechProviders`                | `string[]` | معرّفات مزوّدي الكلام التي يملكها هذا Plugin.                |
| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ الفوري التي يملكها هذا Plugin.          |
| `realtimeVoiceProviders`         | `string[]` | معرّفات مزوّدي الصوت الفوري التي يملكها هذا Plugin.          |
| `mediaUnderstandingProviders`    | `string[]` | معرّفات مزوّدي فهم الوسائط التي يملكها هذا Plugin.           |
| `imageGenerationProviders`       | `string[]` | معرّفات مزوّدي توليد الصور التي يملكها هذا Plugin.           |
| `videoGenerationProviders`       | `string[]` | معرّفات مزوّدي توليد الفيديو التي يملكها هذا Plugin.         |
| `webFetchProviders`              | `string[]` | معرّفات مزوّدي جلب الويب التي يملكها هذا Plugin.             |
| `webSearchProviders`             | `string[]` | معرّفات مزوّدي البحث على الويب التي يملكها هذا Plugin.       |
| `tools`                          | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin لفحوصات العقود المضمّنة. |

## مرجع `channelConfigs`

استخدم `channelConfigs` عندما يحتاج Plugin القناة إلى بيانات وصفية منخفضة التكلفة للإعدادات
قبل تحميل وقت التشغيل.

```json
{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "رابط Homeserver",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "اتصال Matrix homeserver",
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

يمكن أن يتضمن كل إدخال قناة ما يلي:

| الحقل         | النوع                    | المعنى                                                                                   |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
| `schema`      | `object`                 | مخطط JSON لـ `channels.<id>`. وهو مطلوب لكل إدخال إعداد قناة مُعلَن.                    |
| `uiHints`     | `Record<string, object>` | تسميات واجهة المستخدم/العناصر النائبة/تلميحات الحساسية الاختيارية لذلك القسم من إعدادات القناة. |
| `label`       | `string`                 | تسمية القناة التي تُدمج في أسطح الاختيار والمعاينة عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. |
| `description` | `string`                 | وصف قصير للقناة لأسطح المعاينة والفهرسة.                                                |
| `preferOver`  | `string[]`               | معرّفات Plugins قديمة أو أقل أولوية يجب أن تتفوق عليها هذه القناة في أسطح الاختيار.     |

## مرجع `modelSupport`

استخدم `modelSupport` عندما يجب على OpenClaw أن يستنتج Plugin مزوّد الخدمة الخاص بك من
معرّفات النماذج المختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل Plugin.

```json
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
```

يطبق OpenClaw ترتيب الأولوية التالي:

- تستخدم مراجع `provider/model` الصريحة البيانات الوصفية `providers` الخاصة بالبيان المالك
- تتفوق `modelPatterns` على `modelPrefixes`
- إذا طابق كل من Plugin غير مضمّن وPlugin مضمّن، يفوز Plugin غير المضمّن
- يُتجاهل الغموض المتبقي إلى أن يحدد المستخدم أو الإعدادات مزوّدًا

الحقول:

| الحقل           | النوع      | المعنى                                                                          |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | بادئات تُطابق باستخدام `startsWith` مع معرّفات النماذج المختصرة.                |
| `modelPatterns` | `string[]` | مصادر Regex تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف الشخصي.    |

أصبحت مفاتيح القدرات القديمة ذات المستوى الأعلى مهملة. استخدم `openclaw doctor --fix`
لنقل `speechProviders` و`realtimeTranscriptionProviders` و`realtimeVoiceProviders`
و`mediaUnderstandingProviders` و`imageGenerationProviders` و`videoGenerationProviders`
و`webFetchProviders` و`webSearchProviders` تحت `contracts`؛ فلم يعد تحميل
البيان العادي يتعامل مع تلك الحقول ذات المستوى الأعلى على أنها
ملكية للقدرات.

## البيان مقابل package.json

يؤدي الملفان وظيفتين مختلفتين:

| الملف                   | استخدمه من أجل                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات وصفية لخيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل شيفرة Plugin |
| `package.json`         | بيانات npm الوصفية، وتثبيت الاعتماديات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وضبط التثبيت، والإعداد، أو بيانات الفهرسة الوصفية |

إذا لم تكن متأكدًا من المكان الذي تنتمي إليه قطعة من البيانات الوصفية، فاستخدم هذه القاعدة:

- إذا كان يجب على OpenClaw معرفتها قبل تحميل شيفرة Plugin، فضعها في `openclaw.plugin.json`
- إذا كانت تتعلق بالتغليف، أو ملفات الدخول، أو سلوك تثبيت npm، فضعها في `package.json`

### حقول `package.json` التي تؤثر في الاكتشاف

توجد بعض البيانات الوصفية الخاصة بالـ Plugin قبل وقت التشغيل عمدًا داخل `package.json`
تحت كتلة `openclaw` بدلًا من `openclaw.plugin.json`.

أمثلة مهمة:

| الحقل                                                             | المعنى                                                                                                                                   |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions`                                             | يعرّف نقاط دخول Plugin الأصلية.                                                                                                          |
| `openclaw.setupEntry`                                             | نقطة دخول خفيفة للإعداد فقط تُستخدم أثناء التهيئة الأولية وبدء تشغيل القنوات المؤجل.                                                     |
| `openclaw.channel`                                                | بيانات وصفية خفيفة لفهرسة القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار.                                   |
| `openclaw.channel.configuredState`                                | بيانات وصفية خفيفة لمدقق حالة التكوين يمكنها الإجابة عن "هل يوجد إعداد قائم يعتمد على البيئة فقط؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.channel.persistedAuthState`                             | بيانات وصفية خفيفة لمدقق حالة المصادقة المحفوظة يمكنها الإجابة عن "هل يوجد أي تسجيل دخول قائم بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath`         | تلميحات التثبيت/التحديث للـ Plugins المضمّنة والمنشورة خارجيًا.                                                                         |
| `openclaw.install.defaultChoice`                                  | مسار التثبيت المفضل عندما تتوفر مصادر تثبيت متعددة.                                                                                      |
| `openclaw.install.minHostVersion`                                 | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد أدنى semver مثل `>=2026.3.22`.                                                   |
| `openclaw.install.allowInvalidConfigRecovery`                     | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمّن عندما تكون الإعدادات غير صالحة.                                                         |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح بتحميل أسطح القنوات الخاصة بالإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل.                                                  |

يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل البيانات.
وتُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتجاوز Plugin
على المضيفين الأقدم.

إن `openclaw.install.allowInvalidConfigRecovery` ضيق عمدًا. فهو لا
يجعل الإعدادات المعطوبة العشوائية قابلة للتثبيت. حاليًا، يسمح فقط
لمسارات التثبيت بالتعافي من حالات فشل محددة لترقية Plugins المضمّنة القديمة،
مثل غياب مسار Plugin مضمّن أو وجود إدخال `channels.<id>` قديم لذلك
Plugin المضمّن نفسه. وما تزال أخطاء الإعدادات غير المرتبطة تمنع التثبيت
وتوجّه المشغّلين إلى `openclaw doctor --fix`.

يمثل `openclaw.channel.persistedAuthState` بيانات حزمة وصفية لوحدة فحص صغيرة:

```json
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
```

استخدمه عندما تحتاج مسارات الإعداد أو Doctor أو حالة التكوين إلى
فحص مصادقة منخفض التكلفة بنعم/لا قبل تحميل Plugin القناة الكامل. يجب أن يكون
التصدير الهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ لا توجّهها عبر شريط
وقت تشغيل القناة الكامل.

ويتبع `openclaw.channel.configuredState` البنية نفسها لفحوصات
الحالة المكوّنة منخفضة التكلفة المعتمدة على البيئة فقط:

```json
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
```

استخدمه عندما تستطيع قناة الإجابة عن حالة التكوين من البيئة أو من
مدخلات صغيرة أخرى لا تتعلق بوقت التشغيل. وإذا كان الفحص يحتاج إلى الحل الكامل
للإعدادات أو إلى وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق داخل خطاف
`config.hasConfiguredState` الخاص بـ Plugin بدلًا من ذلك.

## متطلبات مخطط JSON

- **يجب على كل Plugin أن يوفّر مخطط JSON**، حتى إذا كان لا يقبل أي إعدادات.
- يُقبل مخطط فارغ (مثلًا، `{ "type": "object", "additionalProperties": false }`).
- تُتحقَّق المخططات في وقت قراءة/كتابة الإعدادات، وليس في وقت التشغيل.

## سلوك التحقق

- مفاتيح `channels.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة معلنًا من
  خلال بيان Plugin.
- يجب أن تشير `plugins.entries.<id>` و`plugins.allow` و`plugins.deny` و`plugins.slots.*`
  إلى معرّفات Plugin **قابلة للاكتشاف**. المعرّفات غير المعروفة هي **أخطاء**.
- إذا كان Plugin مثبتًا لكن بيانه أو مخططه مكسورًا أو مفقودًا،
  فسيفشل التحقق وسيبلّغ Doctor عن خطأ Plugin.
- إذا كان إعداد Plugin موجودًا لكن Plugin **معطّلًا**، فسيُحتفظ بالإعداد
  وستظهر **تحذير** في Doctor والسجلات.

راجع [مرجع الإعدادات](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.

## ملاحظات

- البيان **مطلوب لـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات.
- ما يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالبيان مخصص فقط
  للاكتشاف + التحقق.
- تُحلَّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات، والفواصل اللاحقة،
  والمفاتيح غير الموضوعة بين علامتَي اقتباس ما دامت القيمة النهائية ما تزال كائنًا.
- لا يقرأ محمّل البيان سوى حقول البيان الموثقة. تجنّب إضافة
  مفاتيح مخصصة ذات مستوى أعلى هنا.
- يمثل `providerAuthEnvVars` مسار البيانات الوصفية منخفض التكلفة لفحوصات المصادقة، والتحقق من
  علامات البيئة، وأسوح مصادقة مزوّد الخدمة المشابهة التي يجب ألا تشغّل وقت تشغيل Plugin
  فقط لفحص أسماء متغيرات البيئة.
- يتيح `providerAuthAliases` لمتغيرات مزوّد الخدمة إعادة استخدام
  متغيرات بيئة المصادقة، وملفات تعريف المصادقة، والمصادقة المعتمدة على الإعدادات، وخيار
  التهيئة الأولية لمفتاح API الخاص بمزوّد خدمة آخر من دون ترميز هذه العلاقة
  صراحةً في النواة.
- يتيح `providerEndpoints` لـ Plugins مزوّدي الخدمة امتلاك بيانات وصفية بسيطة لمطابقة
  المضيف/`baseUrl` لنقاط النهاية. استخدمه فقط لفئات نقاط النهاية التي تدعمها النواة
  بالفعل؛ وما يزال Plugin يملك سلوك وقت التشغيل.
- يمثل `syntheticAuthRefs` مسار البيانات الوصفية منخفض التكلفة لخطافات المصادقة
  الاصطناعية المملوكة لمزوّد الخدمة التي يجب أن تكون مرئية لاكتشاف النماذج البارد قبل وجود
  سجل وقت التشغيل. أدرج فقط المراجع التي ينفّذ فيها مزوّد الخدمة أو الواجهة الخلفية لـ CLI
  في وقت التشغيل `resolveSyntheticAuth` فعليًا.
- يمثل `nonSecretAuthMarkers` مسار البيانات الوصفية منخفض التكلفة لعلامات
  مفاتيح API المؤقتة المملوكة لـ Plugin المضمّن، مثل العلامات المحلية أو OAuth أو بيانات الاعتماد المحيطية.
  تتعامل النواة مع هذه العلامات على أنها غير سرية لعرض المصادقة وعمليات تدقيق الأسرار من دون
  ترميز مزوّد الخدمة المالك صراحةً.
- يمثل `channelEnvVars` مسار البيانات الوصفية منخفض التكلفة للرجوع إلى
  متغيرات بيئة الصدفة، ومطالبات الإعداد، وأسوح القنوات المشابهة التي يجب ألا تشغّل وقت تشغيل Plugin
  فقط لفحص أسماء متغيرات البيئة.
- يمثل `providerAuthChoices` مسار البيانات الوصفية منخفض التكلفة لمحددات خيارات المصادقة،
  وحل `--auth-choice`، وربط المزوّد المفضل، وتسجيل أعلام CLI البسيطة الخاصة بالتهيئة الأولية
  قبل تحميل وقت تشغيل المزوّد. أما بيانات المعالج الإرشادي في وقت التشغيل
  التي تتطلب شيفرة المزوّد، فراجع
  [خطافات وقت تشغيل المزوّد](/ar/plugins/architecture#provider-runtime-hooks).
- تُختار أنواع Plugin الحصرية من خلال `plugins.slots.*`.
  - يُختار `kind: "memory"` بواسطة `plugins.slots.memory`.
  - يُختار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
    (الافتراضي: `legacy` المضمّن).
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا
  يحتاجها Plugin.
- إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي
  متطلبات لقائمة السماح الخاصة بمدير الحزم (مثلًا، pnpm `allow-build-scripts`
  - `pnpm rebuild <package>`).

## ذو صلة

- [بناء Plugins](/ar/plugins/building-plugins) — البدء باستخدام Plugins
- [معمارية Plugin](/ar/plugins/architecture) — المعمارية الداخلية
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK
