---
read_when:
    - أنت تبني Plugin لـ OpenClaw
    - تحتاج إلى إصدار مخطط تهيئة Plugin أو تصحيح أخطاء التحقق من صحة Plugin
summary: متطلبات ملف بيان Plugin + مخطط JSON (التحقق الصارم من الإعدادات)
title: بيان Plugin
x-i18n:
    generated_at: "2026-05-02T20:51:11Z"
    model: gpt-5.5
    provider: openai
    source_hash: 2988275b976df8b883a4042ee389197e617d50e63f5a478ce248e7a643bb12fb
    source_path: plugins/manifest.md
    workflow: 16
---

هذه الصفحة مخصصة لـ **ملف بيان 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، وافتراضيات `settings.json` لحزمة Claude،
وافتراضيات LSP لحزمة Claude، وحزم الخطافات المدعومة عندما يطابق التخطيط
توقعات وقت تشغيل OpenClaw.

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

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

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

`openclaw.plugin.json` هو بيانات التعريف التي يقرأها OpenClaw **قبل أن يحمّل كود
Plugin الخاص بك**. يجب أن يكون كل ما يلي خفيفاً بما يكفي للفحص دون تشغيل
وقت تشغيل Plugin.

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

- هوية Plugin، والتحقق من التكوين، وتلميحات واجهة مستخدم التكوين
- بيانات تعريف المصادقة، والتهيئة الأولية، والإعداد (الاسم المستعار، التفعيل التلقائي، متغيرات بيئة المزوّد، خيارات المصادقة)
- تلميحات التفعيل لأسطح مستوى التحكم
- ملكية عائلة النماذج المختصرة
- لقطات ملكية القدرات الثابتة (`contracts`)
- بيانات تعريف مشغّل ضمان الجودة التي يمكن لمضيف `openclaw qa` المشترك فحصها
- بيانات تعريف التكوين الخاصة بالقناة المدمجة في أسطح الفهرس والتحقق

**لا تستخدمه من أجل:** تسجيل سلوك وقت التشغيل، أو إعلان نقاط دخول الكود،
أو بيانات تعريف تثبيت 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-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "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 Schema مضمّن لإعدادات هذا الـ 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.                                                                                                                                                                                  |
| `providerDiscoveryEntry`             | لا    | `string`                         | مسار وحدة اكتشاف مزوّدين خفيفة، نسبةً إلى جذر الـ Plugin، لبيانات تعريف كتالوج المزوّدين ضمن نطاق البيان، والتي يمكن تحميلها دون تفعيل وقت تشغيل الـ Plugin الكامل.                                                         |
| `modelSupport`                       | لا    | `object`                         | بيانات تعريف مختصرة لعائلات النماذج يملكها البيان، وتُستخدم لتحميل الـ Plugin تلقائيًا قبل وقت التشغيل.                                                                                                                       |
| `modelCatalog`                       | لا    | `object`                         | بيانات تعريف تصريحية لكتالوج النماذج للمزوّدين الذين يملكهم هذا الـ Plugin. هذا هو عقد مستوى التحكم للقوائم المستقبلية للقراءة فقط، والإعداد الأولي، ومنتقيات النماذج، والأسماء المستعارة، والكبت دون تحميل وقت تشغيل الـ Plugin. |
| `modelPricing`                       | لا    | `object`                         | سياسة بحث عن الأسعار الخارجية يملكها المزوّد. استخدمها لاستثناء المزوّدين المحليين/ذاتيّي الاستضافة من كتالوجات الأسعار البعيدة أو ربط مراجع المزوّدين بمعرّفات كتالوج OpenRouter/LiteLLM دون ترميز معرّفات المزوّدين في النواة. |
| `modelIdNormalization`               | لا    | `object`                         | تنظيف الأسماء المستعارة/البادئات لمعرّفات النماذج يملكه المزوّد، ويجب تشغيله قبل تحميل وقت تشغيل المزوّد.                                                                                                                    |
| `providerEndpoints`                  | لا    | `object[]`                       | بيانات تعريف المضيف/baseUrl لنقاط النهاية يملكها البيان لمسارات المزوّدين التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل المزوّد.                                                                                           |
| `providerRequest`                    | لا    | `object`                         | بيانات تعريف خفيفة لعائلة المزوّد وتوافق الطلبات، تُستخدم بواسطة سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد.                                                                                                            |
| `cliBackends`                        | لا    | `string[]`                       | معرّفات خلفيات الاستدلال في CLI التي يملكها هذا الـ Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع إعدادات صريحة.                                                                                                 |
| `syntheticAuthRefs`                  | لا    | `string[]`                       | مراجع المزوّد أو خلفية CLI التي ينبغي فحص خطاف المصادقة الاصطناعي المملوك للـ Plugin الخاص بها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل.                                                                            |
| `nonSecretAuthMarkers`               | لا    | `string[]`                       | قيم مفاتيح API نائبة يملكها Plugin مضمّن، وتمثّل حالة اعتماد غير سرية محلية أو عبر OAuth أو محيطة.                                                                                                                           |
| `commandAliases`                     | لا    | `object[]`                       | أسماء أوامر يملكها هذا الـ Plugin، وينبغي أن تنتج تشخيصات إعدادات وCLI واعية بالـ Plugin قبل تحميل وقت التشغيل.                                                                                                               |
| `providerAuthEnvVars`                | لا    | `Record<string, string[]>`       | بيانات تعريف بيئة توافقية مهملة للبحث عن مصادقة/حالة المزوّد. فضّل `setup.providers[].envVars` للـ Plugins الجديدة؛ لا يزال OpenClaw يقرأ هذا أثناء نافذة الإهمال.                                                           |
| `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`                         | لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات.                         |
| `mediaUnderstandingProviderMetadata` | لا    | `Record<string, object>`         | إعدادات افتراضية خفيفة لفهم الوسائط لمعرّفات المزوّدين المعلنة في `contracts.mediaUnderstandingProviders`.                                                                                                                     |
| `imageGenerationProviderMetadata`    | لا    | `Record<string, object>`         | بيانات تعريف خفيفة لمصادقة توليد الصور لمعرّفات المزوّدين المعلنة في `contracts.imageGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة وحراس base-url الذين يملكهم المزوّد.                                    |
| `videoGenerationProviderMetadata`    | لا    | `Record<string, object>`         | بيانات تعريف خفيفة لمصادقة توليد الفيديو لمعرّفات المزوّدين المعلنة في `contracts.videoGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة وحراس base-url الذين يملكهم المزوّد.                                  |
| `musicGenerationProviderMetadata`    | لا    | `Record<string, object>`         | بيانات تعريف خفيفة لمصادقة توليد الموسيقى لمعرّفات المزوّدين المعلنة في `contracts.musicGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة وحراس base-url الذين يملكهم المزوّد.                                 |
| `toolMetadata`                       | لا    | `Record<string, object>`         | بيانات تعريف خفيفة للتوافر للأدوات المملوكة للـ Plugin والمعلنة في `contracts.tools`. استخدمها عندما ينبغي ألا تحمّل أداة وقت التشغيل إلا إذا وُجدت أدلة إعدادات أو بيئة أو مصادقة.                                      |
| `channelConfigs`                     | لا    | `Record<string, object>`         | بيانات تعريف إعدادات قنوات يملكها البيان، وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل.                                                                                                                              |
| `skills`                             | لا    | `string[]`                       | أدلة Skills المراد تحميلها، نسبةً إلى جذر الـ Plugin.                                                                                                                                                                           |
| `name`                               | لا    | `string`                         | اسم Plugin قابل للقراءة البشرية.                                                                                                                                                                                                |
| `description`                        | لا       | `string`                         | ملخص قصير يُعرض في واجهات Plugin.                                                                                                                                                                                             |
| `version`                            | لا       | `string`                         | إصدار Plugin لأغراض معلوماتية.                                                                                                                                                                                                       |
| `uiHints`                            | لا       | `Record<string, object>`         | تسميات واجهة المستخدم والعناصر النائبة وتلميحات الحساسية لحقول التهيئة.                                                                                                                                                                   |

## مرجع بيانات تعريف موفّر التوليد

تصف حقول بيانات تعريف موفّر التوليد إشارات المصادقة الثابتة للموفّرين
المُعلنين في قائمة `contracts.*GenerationProviders` المطابقة.
يقرأ OpenClaw هذه الحقول قبل تحميل وقت تشغيل الموفّر حتى تتمكن أدوات النواة من
تحديد ما إذا كان موفّر التوليد متاحًا دون استيراد كل
Plugin موفّر.

استخدم هذه الحقول فقط للحقائق التصريحية منخفضة التكلفة. يبقى النقل، وتحويلات
الطلبات، وتحديث الرمز، والتحقق من بيانات الاعتماد، وسلوك التوليد الفعلي
في وقت تشغيل Plugin.

```json
{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}
```

يدعم كل إدخال بيانات تعريف ما يلي:

| الحقل           | مطلوب | النوع      | ما يعنيه                                                                                                                       |
| --------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `aliases`       | لا       | `string[]` | معرّفات موفّر إضافية يجب احتسابها كأسماء مستعارة ثابتة للمصادقة لموفّر التوليد.                                       |
| `authProviders` | لا       | `string[]` | معرّفات موفّر يجب أن تُحتسب ملفات تعريف المصادقة المكوّنة لها كمصادقة لموفّر التوليد هذا.                                      |
| `configSignals` | لا       | `object[]` | إشارات توافر منخفضة التكلفة تعتمد على الإعداد فقط للموفّرين المحليين أو ذاتيي الاستضافة الذين يمكن إعدادهم دون ملفات تعريف مصادقة أو متغيرات بيئة. |
| `authSignals`   | لا       | `object[]` | إشارات مصادقة صريحة. عند وجودها، تستبدل مجموعة الإشارات الافتراضية من معرّف الموفّر و`aliases` و`authProviders`.     |

يدعم كل إدخال `configSignals` ما يلي:

| الحقل         | مطلوب | النوع      | ما يعنيه                                                                                                                                                                           |
| ------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rootPath`    | نعم      | `string`   | مسار نقطي إلى كائن إعداد يملكه Plugin لفحصه، مثل `plugins.entries.example.config`.                                                                                    |
| `overlayPath` | لا       | `string`   | مسار نقطي داخل إعداد الجذر يجب أن يعلو كائنه فوق كائن الجذر قبل تقييم الإشارة. استخدم هذا للإعدادات الخاصة بالإمكانية مثل `image` أو `video` أو `music`. |
| `required`    | لا       | `string[]` | مسارات نقطية داخل الإعداد الفعّال يجب أن تحتوي على قيم مكوّنة. يجب أن تكون السلاسل غير فارغة؛ ويجب ألا تكون الكائنات والمصفوفات فارغة.                                                |
| `requiredAny` | لا       | `string[]` | مسارات نقطية داخل الإعداد الفعّال يجب أن يحتوي واحد منها على الأقل على قيمة مكوّنة.                                                                                                  |
| `mode`        | لا       | `object`   | حارس وضع نصي اختياري داخل الإعداد الفعّال. استخدم هذا عندما ينطبق التوافر المعتمد على الإعداد فقط على وضع واحد.                                                                |

يدعم كل حارس `mode` ما يلي:

| الحقل        | مطلوب | النوع      | ما يعنيه                                                                      |
| ------------ | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `path`       | لا       | `string`   | مسار نقطي داخل الإعداد الفعّال. القيمة الافتراضية هي `mode`.                          |
| `default`    | لا       | `string`   | قيمة الوضع المراد استخدامها عندما يحذف الإعداد المسار.                                  |
| `allowed`    | لا       | `string[]` | إذا كان موجودًا، تمر الإشارة فقط عندما يكون الوضع الفعّال واحدًا من هذه القيم. |
| `disallowed` | لا       | `string[]` | إذا كان موجودًا، تفشل الإشارة عندما يكون الوضع الفعّال واحدًا من هذه القيم.       |

يدعم كل إدخال `authSignals` ما يلي:

| الحقل             | مطلوب | النوع    | ما يعنيه                                                                                                                                                                 |
| ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | نعم      | `string` | معرّف الموفّر المراد فحصه في ملفات تعريف المصادقة المكوّنة.                                                                                                                             |
| `providerBaseUrl` | لا       | `object` | حارس اختياري يجعل الإشارة تُحتسب فقط عندما يستخدم الموفّر المكوّن المشار إليه عنوان URL أساسيًا مسموحًا به. استخدم هذا عندما يكون اسم مستعار للمصادقة صالحًا فقط لواجهات API معيّنة. |

يدعم كل حارس `providerBaseUrl` ما يلي:

| الحقل             | مطلوب | النوع      | ما يعنيه                                                                                                                                        |
| ----------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | نعم      | `string`   | معرّف إعداد الموفّر الذي يجب فحص `baseUrl` الخاص به.                                                                                                |
| `defaultBaseUrl`  | لا       | `string`   | عنوان URL الأساسي المفترض عندما يحذف إعداد الموفّر `baseUrl`.                                                                                         |
| `allowedBaseUrls` | نعم      | `string[]` | عناوين URL الأساسية المسموح بها لإشارة المصادقة هذه. تُتجاهل الإشارة عندما لا يطابق عنوان URL الأساسي المكوّن أو الافتراضي إحدى هذه القيم المطبّعة. |

## مرجع بيانات تعريف الأدوات

يستخدم `toolMetadata` أشكال `configSignals` و`authSignals` نفسها مثل
بيانات تعريف موفّر التوليد، مع الفهرسة حسب اسم الأداة. يعلن `contracts.tools`
الملكية. يعلن `toolMetadata` دليل توافر منخفض التكلفة حتى يتمكن OpenClaw من
تجنب استيراد وقت تشغيل Plugin لمجرد أن يعيد مصنع أدواته `null`.

```json
{
  "providerAuthEnvVars": {
    "example": ["EXAMPLE_API_KEY"]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}
```

إذا لم تكن للأداة `toolMetadata`، يحافظ OpenClaw على السلوك الحالي ويحمّل
Plugin المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن
التي يعتمد مصنعها على المصادقة/الإعداد، يجب على مؤلفي Plugin إعلان
`toolMetadata` بدلًا من جعل النواة تستورد وقت التشغيل للسؤال.

## مرجع 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"` | يعلّم الاسم البديل كأمر شرطة مائلة في المحادثة بدلا من أمر CLI جذري. |
| `cliCommand` | لا       | `string`          | أمر CLI الجذري المرتبط الذي يُقترح لعمليات CLI، إذا كان موجودا.  |

## مرجع activation

استخدم `activation` عندما يستطيع Plugin التصريح بتكلفة منخفضة عن أحداث مستوى التحكم
التي يجب أن تُدرجه في خطة تفعيل/تحميل.

هذه الكتلة بيانات وصفية للمخطط، وليست واجهة API لدورة الحياة. إنها لا تسجل
سلوك وقت التشغيل، ولا تستبدل `register(...)`، ولا تَعِد بأن
كود Plugin قد نُفذ بالفعل. يستخدم مخطط التفعيل هذه الحقول
لتضييق plugins المرشحة قبل الرجوع إلى بيانات وصفية حالية لملكية البيان
مثل `providers`، و`channels`، و`commandAliases`، و`setup.providers`،
و`contracts.tools`، والخطافات.

فضّل أضيق بيانات وصفية تصف الملكية بالفعل. استخدم
`providers`، أو `channels`، أو `commandAliases`، أو واصفات الإعداد، أو `contracts`
عندما تعبّر هذه الحقول عن العلاقة. استخدم `activation` لتلميحات إضافية للمخطط
لا يمكن تمثيلها بحقول الملكية تلك.
استخدم `cliBackends` على المستوى الأعلى للأسماء البديلة لوقت تشغيل CLI مثل `claude-cli`،
أو `codex-cli`، أو `google-gemini-cli`؛ أما `activation.onAgentHarnesses` فهو فقط
لمعرفات أحزمة وكيل مضمّنة لا تملك حقل ملكية بالفعل.

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

يجب أن يضبط كل Plugin قيمة `activation.onStartup` عن قصد. اضبطها على `true`
فقط عندما يجب تشغيل Plugin أثناء بدء تشغيل Gateway. اضبطها على `false` عندما
يكون Plugin خاملا عند بدء التشغيل ويجب ألا يُحمّل إلا من محفزات أضيق.
لم يعد حذف `onStartup` يحمّل Plugin ضمنيا عند بدء التشغيل؛ استخدم بيانات وصفية
صريحة للتفعيل لبدء التشغيل، أو القناة، أو الإعداد، أو حزام الوكيل، أو الذاكرة، أو
محفزات تفعيل أضيق أخرى.

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

| الحقل              | مطلوب | النوع                                                 | ما يعنيه                                                                                                                                                                               |
| ------------------ | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onStartup`        | لا       | `boolean`                                            | تفعيل صريح عند بدء تشغيل Gateway. يجب أن يضبط كل Plugin هذا الحقل. تستورد `true` Plugin أثناء بدء التشغيل؛ وتبقيه `false` مؤجلا عن بدء التشغيل ما لم يتطلب محفز مطابق آخر التحميل. |
| `onProviders`      | لا       | `string[]`                                           | معرفات المزوّدين التي يجب أن تُدرج هذا Plugin في خطط التفعيل/التحميل.                                                                                                                      |
| `onAgentHarnesses` | لا       | `string[]`                                           | معرفات وقت تشغيل أحزمة الوكيل المضمّنة التي يجب أن تُدرج هذا Plugin في خطط التفعيل/التحميل. استخدم `cliBackends` على المستوى الأعلى للأسماء البديلة لخلفيات CLI.                                           |
| `onCommands`       | لا       | `string[]`                                           | معرفات الأوامر التي يجب أن تُدرج هذا Plugin في خطط التفعيل/التحميل.                                                                                                                       |
| `onChannels`       | لا       | `string[]`                                           | معرفات القنوات التي يجب أن تُدرج هذا Plugin في خطط التفعيل/التحميل.                                                                                                                       |
| `onRoutes`         | لا       | `string[]`                                           | أنواع المسارات التي يجب أن تُدرج هذا Plugin في خطط التفعيل/التحميل.                                                                                                                       |
| `onConfigPaths`    | لا       | `string[]`                                           | مسارات الإعداد النسبية إلى الجذر التي يجب أن تُدرج هذا Plugin في خطط بدء التشغيل/التحميل عندما يكون المسار موجودا وغير معطّل صراحة.                                                      |
| `onCapabilities`   | لا       | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات واسعة يستخدمها تخطيط التفعيل على مستوى التحكم. فضّل الحقول الأضيق عندما يكون ذلك ممكنا.                                                                                     |

المستهلكون المباشرون الحاليون:

- يستخدم تخطيط بدء تشغيل Gateway `activation.onStartup` للاستيراد الصريح عند بدء التشغيل
- يرجع تخطيط CLI المشغّل بالأوامر إلى
  `commandAliases[].cliCommand` أو `commandAliases[].name` القديمين
- يستخدم تخطيط بدء تشغيل وقت تشغيل الوكيل `activation.onAgentHarnesses` للأحزمة
  المضمّنة و`cliBackends[]` على المستوى الأعلى للأسماء البديلة لوقت تشغيل CLI
- يرجع تخطيط الإعداد/القناة المشغّل بالقنوات إلى ملكية `channels[]`
  القديمة عندما تكون البيانات الوصفية الصريحة لتفعيل القناة مفقودة
- يستخدم تخطيط Plugin عند بدء التشغيل `activation.onConfigPaths` لأسطح إعداد جذرية
  غير قنوات مثل كتلة `browser` في Plugin المتصفح المضمّن
- يرجع تخطيط الإعداد/وقت التشغيل المشغّل بالمزوّد إلى ملكية
  `providers[]` و`cliBackends[]` على المستوى الأعلى القديمتين عندما تكون البيانات الوصفية الصريحة
  لتفعيل المزوّد مفقودة

يمكن لتشخيصات المخطط التمييز بين تلميحات التفعيل الصريحة وبديل ملكية البيان.
على سبيل المثال، يعني `activation-command-hint` أن
`activation.onCommands` طابق، بينما يعني `manifest-command-alias` أن
المخطط استخدم ملكية `commandAliases` بدلا من ذلك. تسميات الأسباب هذه
لتشخيصات المضيف والاختبارات؛ ويجب على مؤلفي Plugin الاستمرار في التصريح بالبيانات الوصفية
التي تصف الملكية بأفضل شكل.

## مرجع qaRunners

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

```json
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}
```

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

## مرجع setup

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

```json
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

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

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

يتضمن OpenClaw أيضا `setup.providers[].envVars` في مصادقة المزوّد العامة وعمليات
البحث عن متغيرات البيئة. يظل `providerAuthEnvVars` مدعوما عبر محول توافق
أثناء نافذة الإيقاف التدريجي، لكن plugins غير المضمّنة التي لا تزال تستخدمه
تتلقى تشخيص بيان. يجب أن تضع plugins الجديدة بيانات وصفية لبيئة الإعداد/الحالة
على `setup.providers[].envVars`.

يمكن لـ OpenClaw أيضا اشتقاق خيارات إعداد بسيطة من `setup.providers[].authMethods`
عندما لا يكون إدخال إعداد متاحا، أو عندما يصرّح `setup.requiresRuntime: false`
بأن وقت تشغيل الإعداد غير ضروري. تظل إدخالات `providerAuthChoices` الصريحة
مفضلة للتسميات المخصصة، وأعلام CLI، ونطاق التهيئة الأولية، والبيانات الوصفية للمساعد.

اضبط `requiresRuntime: false` فقط عندما تكون تلك الواصفات كافية لسطح
الإعداد. يتعامل OpenClaw مع `false` الصريحة كعقد قائم على الواصفات فقط
ولن ينفذ `setup-api` أو `openclaw.setupEntry` لبحث الإعداد. إذا
كان Plugin قائم على الواصفات فقط لا يزال يشحن أحد إدخالات وقت تشغيل الإعداد هذه،
يبلغ OpenClaw عن تشخيص إضافي ويستمر في تجاهله. يبقي
حذف `requiresRuntime` سلوك الرجوع القديم كي لا تتعطل plugins الحالية التي أضافت
واصفات من دون العلم.

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

عندما ينفذ وقت تشغيل الإعداد، تبلغ تشخيصات سجل الإعداد عن انحراف الواصف
إذا سجل `setup-api` مزودا أو خلفية CLI لا تصرح بها واصفات البيان،
أو إذا لم يكن للواصف تسجيل وقت تشغيل مطابق. هذه التشخيصات إضافية ولا ترفض
plugins القديمة.

### مرجع setup.providers

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

`authEvidence` مخصص لعلامات بيانات الاعتماد المحلية المملوكة للمزوّد التي يمكن
التحقق منها دون تحميل كود وقت التشغيل. يجب أن تبقى هذه الفحوصات قليلة التكلفة ومحلية:
بلا استدعاءات شبكة، ولا قراءات من سلسلة المفاتيح أو مدير الأسرار، ولا أوامر shell، ولا
استطلاعات لواجهة API الخاصة بالمزوّد.

إدخالات الأدلة المدعومة:

| الحقل              | مطلوب | النوع      | ما يعنيه                                                                                                  |
| ------------------ | ----- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `type`             | نعم   | `string`   | حاليًا `local-file-with-env`.                                                                               |
| `fileEnvVar`       | لا    | `string`   | متغير بيئة يحتوي على مسار صريح لملف بيانات الاعتماد.                                                        |
| `fallbackPaths`    | لا    | `string[]` | مسارات ملفات بيانات اعتماد محلية تُفحص عندما يكون `fileEnvVar` غائبًا أو فارغًا. يدعم `${HOME}` و `${APPDATA}`. |
| `requiresAnyEnv`   | لا    | `string[]` | يجب أن يكون متغير بيئة واحد على الأقل من المتغيرات المدرجة غير فارغ قبل أن يكون الدليل صالحًا.              |
| `requiresAllEnv`   | لا    | `string[]` | يجب أن يكون كل متغير بيئة مدرج غير فارغ قبل أن يكون الدليل صالحًا.                                         |
| `credentialMarker` | نعم   | `string`   | علامة غير سرية تُعاد عندما يكون الدليل موجودًا.                                                            |
| `source`           | لا    | `string`   | تسمية مصدر موجهة للمستخدم لمخرجات المصادقة/الحالة.                                                        |

### حقول الإعداد

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

## مرجع uiHints

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

```json
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
```

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

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

## مرجع العقود

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

```json
{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

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

| الحقل                            | النوع      | ما يعنيه                                                         |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories`     | `string[]` | معرفات مصانع امتدادات خادم تطبيق Codex، حاليًا `codex-app-server`. |
| `agentToolResultMiddleware`      | `string[]` | معرفات وقت التشغيل التي قد يسجل Plugin مضمّن لها وسيط نتائج الأدوات. |
| `externalAuthProviders`          | `string[]` | معرفات المزوّدين التي يملك هذا Plugin خطاف ملف تعريف المصادقة الخارجية لها. |
| `speechProviders`                | `string[]` | معرفات مزوّدي الكلام التي يملكها هذا Plugin.                     |
| `realtimeTranscriptionProviders` | `string[]` | معرفات مزوّدي النسخ في الوقت الفعلي التي يملكها هذا Plugin.       |
| `realtimeVoiceProviders`         | `string[]` | معرفات مزوّدي الصوت في الوقت الفعلي التي يملكها هذا Plugin.       |
| `memoryEmbeddingProviders`       | `string[]` | معرفات مزوّدي تضمين الذاكرة التي يملكها هذا Plugin.               |
| `mediaUnderstandingProviders`    | `string[]` | معرفات مزوّدي فهم الوسائط التي يملكها هذا Plugin.                 |
| `imageGenerationProviders`       | `string[]` | معرفات مزوّدي توليد الصور التي يملكها هذا Plugin.                 |
| `videoGenerationProviders`       | `string[]` | معرفات مزوّدي توليد الفيديو التي يملكها هذا Plugin.               |
| `webFetchProviders`              | `string[]` | معرفات مزوّدي جلب الويب التي يملكها هذا Plugin.                   |
| `webSearchProviders`             | `string[]` | معرفات مزوّدي بحث الويب التي يملكها هذا Plugin.                   |
| `migrationProviders`             | `string[]` | معرفات مزوّدي الاستيراد التي يملكها هذا Plugin لـ `openclaw migrate`. |
| `tools`                          | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin.                        |

يُحتفظ بـ `contracts.embeddedExtensionFactories` لمصانع امتدادات خادم تطبيق Codex
المضمّنة فقط. يجب أن تعلن تحويلات نتائج الأدوات المضمّنة
`contracts.agentToolResultMiddleware` وأن تسجل باستخدام
`api.registerAgentToolResultMiddleware(...)` بدلًا من ذلك. لا يمكن لـ Plugins الخارجية
تسجيل وسيط نتائج الأدوات لأن هذا الحد الفاصل يمكنه إعادة كتابة مخرجات أدوات عالية الثقة
قبل أن يراها النموذج.

يجب أن تطابق تسجيلات وقت التشغيل `api.registerTool(...)` قيمة `contracts.tools`.
يستخدم اكتشاف الأدوات هذه القائمة لتحميل أوقات تشغيل Plugin التي يمكن أن تملك
الأدوات المطلوبة فقط.

يجب على Plugins المزوّدين التي تنفذ `resolveExternalAuthProfiles` إعلان
`contracts.externalAuthProviders`. تستمر Plugins التي لا تحتوي على الإعلان في العمل
عبر مسار توافق مهمل، لكن هذا المسار أبطأ وسيُزال بعد نافذة الترحيل.

يجب على مزوّدي تضمين الذاكرة المضمّنين إعلان
`contracts.memoryEmbeddingProviders` لكل معرف محوّل يعرضونه، بما في ذلك
المحوّلات المدمجة مثل `local`. تستخدم مسارات CLI المستقلة عقد البيان هذا
لتحميل Plugin المالك فقط قبل أن يسجل وقت تشغيل Gateway الكامل المزوّدين.

## مرجع mediaUnderstandingProviderMetadata

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

```json
{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}
```

يمكن أن يتضمن كل إدخال مزوّد ما يلي:

| الحقل                  | النوع                               | ما يعنيه                                                                |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `capabilities`         | `("image" \| "audio" \| "video")[]` | إمكانات الوسائط التي يعرضها هذا المزوّد.                                |
| `defaultModels`        | `Record<string, string>`            | افتراضيات ربط الإمكانية بالنموذج المستخدمة عندما لا تحدد الإعدادات نموذجًا. |
| `autoPriority`         | `Record<string, number>`            | الأرقام الأقل تُرتب أبكر للرجوع التلقائي إلى المزوّد المعتمد على بيانات الاعتماد. |
| `nativeDocumentInputs` | `"pdf"[]`                           | مدخلات المستندات الأصلية التي يدعمها المزوّد.                            |

## مرجع channelConfigs

استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات وصفية رخيصة للإعدادات
قبل تحميل وقت التشغيل. يمكن لاكتشاف إعداد/حالة القناة للقراءة فقط استخدام هذه البيانات
الوصفية مباشرة للقنوات الخارجية المهيأة عندما لا يتوفر إدخال إعداد، أو عندما يعلن
`setup.requiresRuntime: false` أن وقت تشغيل الإعداد غير ضروري.

`channelConfigs` هي بيانات وصفية في بيان Plugin، وليست قسم إعدادات مستخدم جديدًا
على المستوى الأعلى. ما يزال المستخدمون يهيئون مثيلات القنوات ضمن `channels.<channel-id>`.
يقرأ OpenClaw بيانات البيان الوصفية لتحديد أي Plugin يملك تلك القناة المهيأة
قبل تنفيذ كود وقت تشغيل Plugin.

بالنسبة إلى Plugin قناة، يصف `configSchema` و `channelConfigs` مسارين مختلفين:

- يتحقق `configSchema` من `plugins.entries.<plugin-id>.config`
- يتحقق `channelConfigs.<channel-id>.schema` من `channels.<channel-id>`

يجب على Plugins غير المضمّنة التي تعلن `channels[]` أن تعلن أيضًا إدخالات
`channelConfigs` مطابقة. بدونها، يستطيع OpenClaw still تحميل Plugin، لكن مخطط
إعدادات المسار البارد، والإعداد، وأسطح Control UI لا يمكنها معرفة شكل الخيارات
المملوكة للقناة حتى يُنفذ وقت تشغيل Plugin.

يمكن لـ `channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled` و
`nativeSkillsAutoEnabled` إعلان افتراضيات `auto` ثابتة لفحوصات إعدادات الأوامر
التي تعمل قبل تحميل وقت تشغيل القناة. يمكن للقنوات المضمّنة أيضًا نشر
الافتراضيات نفسها عبر `package.json#openclaw.channel.commands` إلى جانب
بيانات كتالوج القنوات الأخرى المملوكة للحزمة.

```json
{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

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

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

### استبدال Plugin قناة آخر

استخدم `preferOver` عندما يكون Plugin الخاص بك هو المالك المفضّل لمعرّف قناة يمكن أن
يوفّره Plugin آخر أيضًا. الحالات الشائعة هي معرّف Plugin أُعيدت تسميته، أو
Plugin مستقل يتجاوز Plugin مضمنًا، أو تفريعة مُصانة
تحافظ على معرّف القناة نفسه لتوافق الإعداد.

```json
{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}
```

عندما يُضبط `channels.chat`، يأخذ OpenClaw في الاعتبار كلًا من معرّف القناة
ومعرّف Plugin المفضّل. إذا كان Plugin الأقل أولوية قد اختير فقط لأنه
مضمن أو مفعّل افتراضيًا، فإن OpenClaw يعطّله في إعداد وقت التشغيل الفعّال
بحيث يملك Plugin واحد القناة وأدواتها. يظل اختيار المستخدم الصريح هو الفائز:
إذا فعّل المستخدم كلا الـ Plugins صراحةً، يحافظ OpenClaw على ذلك الاختيار
ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من تغيير مجموعة Plugins المطلوبة
بصمت.

أبقِ `preferOver` محصورًا بمعرّفات Plugin التي يمكنها فعلًا توفير القناة نفسها.
فهو ليس حقل أولوية عامًا ولا يعيد تسمية مفاتيح إعداد المستخدم.

## مرجع modelSupport

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

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

يطبّق OpenClaw هذا الترتيب للأسبقية:

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

الحقول:

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

## مرجع modelCatalog

استخدم `modelCatalog` عندما ينبغي لـ OpenClaw معرفة بيانات نموذج المزوّد الوصفية قبل
تحميل وقت تشغيل Plugin. هذا هو المصدر المملوك للـ manifest لصفوف الكتالوج
الثابتة، وأسماء المزوّد البديلة، وقواعد الإخفاء، ووضع الاكتشاف. يظل التحديث في وقت التشغيل
تابعًا لشيفرة وقت تشغيل المزوّد، لكن manifest يخبر النواة متى يكون وقت التشغيل
مطلوبًا.

```json
{
  "providers": ["openai"],
  "modelCatalog": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "input": ["text", "image"],
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 128000,
            "cost": {
              "input": 1.25,
              "output": 10,
              "cacheRead": 0.125
            },
            "status": "available",
            "tags": ["default"]
          }
        ]
      }
    },
    "aliases": {
      "azure-openai-responses": {
        "provider": "openai",
        "api": "azure-openai-responses"
      }
    },
    "suppressions": [
      {
        "provider": "azure-openai-responses",
        "model": "gpt-5.3-codex-spark",
        "reason": "not available on Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}
```

حقول المستوى الأعلى:

| الحقل          | النوع                                                     | ما يعنيه                                                                                               |
| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `providers`    | `Record<string, object>`                                 | صفوف الكتالوج لمعرّفات المزوّدين التي يملكها هذا Plugin. ينبغي أن تظهر المفاتيح أيضًا في `providers` على المستوى الأعلى.       |
| `aliases`      | `Record<string, object>`                                 | أسماء مزوّدين بديلة ينبغي أن تُحل إلى مزوّد مملوك لتخطيط الكتالوج أو الإخفاء.              |
| `suppressions` | `object[]`                                               | صفوف نماذج من مصدر آخر يخفيها هذا Plugin لسبب خاص بالمزوّد.                  |
| `discovery`    | `Record<string, "static" \| "refreshable" \| "runtime">` | ما إذا كان يمكن قراءة كتالوج المزوّد من بيانات manifest الوصفية، أو تحديثه في ذاكرة التخزين المؤقت، أو أنه يتطلب وقت التشغيل. |

تشارك `aliases` في البحث عن ملكية المزوّد لتخطيط كتالوج النماذج.
يجب أن تكون أهداف الأسماء البديلة مزوّدين على المستوى الأعلى مملوكين للـ Plugin نفسه. عندما تستخدم
قائمة مفلترة حسب المزوّد اسمًا بديلًا، يستطيع OpenClaw قراءة manifest المالك
وتطبيق تجاوزات API/عنوان URL الأساسي للاسم البديل دون تحميل وقت تشغيل المزوّد.
لا توسّع الأسماء البديلة قوائم الكتالوج غير المفلترة؛ فالقوائم الواسعة تُصدر صفوف
المزوّد القانوني المالك فقط.

تستبدل `suppressions` خطاف وقت تشغيل المزوّد القديم `suppressBuiltInModel`.
تُحترم إدخالات الإخفاء فقط عندما يكون المزوّد مملوكًا للـ Plugin أو
مصرّحًا به كمفتاح `modelCatalog.aliases` يستهدف مزوّدًا مملوكًا. لم تعد
خطافات الإخفاء في وقت التشغيل تُستدعى أثناء حل النموذج.

حقول المزوّد:

| الحقل     | النوع                     | ما يعنيه                                                     |
| --------- | ------------------------ | ----------------------------------------------------------------- |
| `baseUrl` | `string`                 | عنوان URL أساسي افتراضي اختياري للنماذج في كتالوج هذا المزوّد.    |
| `api`     | `ModelApi`               | محوّل API افتراضي اختياري للنماذج في كتالوج هذا المزوّد. |
| `headers` | `Record<string, string>` | ترويسات ثابتة اختيارية تنطبق على كتالوج هذا المزوّد.      |
| `models`  | `object[]`               | صفوف النماذج المطلوبة. تُتجاهل الصفوف التي لا تحتوي على `id`.            |

حقول النموذج:

| الحقل           | النوع                                                           | ما يعنيه                                                               |
| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `id`            | `string`                                                       | معرّف النموذج المحلي لدى المزوّد، دون بادئة `provider/`.                    |
| `name`          | `string`                                                       | اسم عرض اختياري.                                                      |
| `api`           | `ModelApi`                                                     | تجاوز API اختياري لكل نموذج.                                            |
| `baseUrl`       | `string`                                                       | تجاوز اختياري لعنوان URL الأساسي لكل نموذج.                                       |
| `headers`       | `Record<string, string>`                                       | ترويسات ثابتة اختيارية لكل نموذج.                                          |
| `input`         | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | الوسائط التي يقبلها النموذج.                                               |
| `reasoning`     | `boolean`                                                      | ما إذا كان النموذج يعرّض سلوك الاستدلال.                               |
| `contextWindow` | `number`                                                       | نافذة السياق الأصلية لدى المزوّد.                                             |
| `contextTokens` | `number`                                                       | حد سياق فعّال اختياري لوقت التشغيل عندما يختلف عن `contextWindow`. |
| `maxTokens`     | `number`                                                       | الحد الأقصى لرموز الإخراج عند معرفته.                                           |
| `cost`          | `object`                                                       | تسعير اختياري بالدولار الأمريكي لكل مليون رمز، بما في ذلك `tieredPricing` اختياري. |
| `compat`        | `object`                                                       | أعلام توافق اختيارية تطابق توافق إعداد نموذج OpenClaw.  |
| `status`        | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | حالة الإدراج. أخفِ فقط عندما يجب ألا يظهر الصف إطلاقًا.          |
| `statusReason`  | `string`                                                       | سبب اختياري يُعرض مع الحالة غير المتاحة.                            |
| `replaces`      | `string[]`                                                     | معرّفات نماذج محلية قديمة لدى المزوّد يحل هذا النموذج محلها.                       |
| `replacedBy`    | `string`                                                       | معرّف نموذج محلي لدى المزوّد بديل للصفوف المهملة.                    |
| `tags`          | `string[]`                                                     | وسوم مستقرة تستخدمها أدوات الاختيار والمرشحات.                                    |

حقول الإخفاء:

| الحقل                      | النوع       | ما يعنيه                                                                                             |
| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`   | معرّف المزوّد للصف العلوي المراد إخفاؤه. يجب أن يكون مملوكًا لهذا Plugin أو مصرّحًا به كاسم بديل مملوك. |
| `model`                    | `string`   | معرّف النموذج المحلي لدى المزوّد المراد إخفاؤه.                                                                      |
| `reason`                   | `string`   | رسالة اختيارية تُعرض عندما يُطلب الصف المخفي مباشرة.                                     |
| `when.baseUrlHosts`        | `string[]` | قائمة اختيارية بمضيفي عنوان URL الأساسي الفعّال للمزوّد المطلوبين قبل تطبيق الإخفاء.               |
| `when.providerConfigApiIn` | `string[]` | قائمة اختيارية بقيم `api` الدقيقة لإعداد المزوّد المطلوبة قبل تطبيق الإخفاء.              |

لا تضع البيانات الخاصة بوقت التشغيل فقط في `modelCatalog`. استخدم `static` فقط عندما تكون صفوف البيان مكتملة بما يكفي لكي تتخطى أسطح القوائم والاختيار المفلترة حسب المزوّد اكتشاف السجل/وقت التشغيل. استخدم `refreshable` عندما تكون صفوف البيان بذورًا أو مكمّلات مفيدة قابلة للإدراج، لكن يمكن لعملية تحديث/تخزين مؤقت أن تضيف المزيد من الصفوف لاحقًا؛ صفوف `refreshable` ليست مرجعية بذاتها. استخدم `runtime` عندما يجب على OpenClaw تحميل وقت تشغيل المزوّد لمعرفة القائمة.

## مرجع modelIdNormalization

استخدم `modelIdNormalization` لتنظيف معرّفات النماذج منخفض التكلفة والمملوك للمزوّد، والذي يجب أن يحدث قبل تحميل وقت تشغيل المزوّد. هذا يُبقي الأسماء المستعارة مثل أسماء النماذج القصيرة، ومعرّفات المزوّد المحلية القديمة، وقواعد بادئات الوكيل في بيان Plugin المالك بدلًا من جداول اختيار النماذج الأساسية.

```json
{
  "providers": ["anthropic", "openrouter"],
  "modelIdNormalization": {
    "providers": {
      "anthropic": {
        "aliases": {
          "sonnet-4.6": "claude-sonnet-4-6"
        }
      },
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  }
}
```

حقول المزوّد:

| الحقل                                | النوع                    | ما يعنيه                                                                                  |
| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- |
| `aliases`                            | `Record<string,string>` | أسماء مستعارة دقيقة لمعرّف النموذج، غير حساسة لحالة الأحرف. تُعاد القيم كما كُتبت.        |
| `stripPrefixes`                      | `string[]`              | بادئات تُزال قبل البحث عن الاسم المستعار، مفيدة لتكرار المزوّد/النموذج القديم.           |
| `prefixWhenBare`                     | `string`                | بادئة تُضاف عندما لا يحتوي معرّف النموذج المطبّع على `/` مسبقًا.                          |
| `prefixWhenBareAfterAliasStartsWith` | `object[]`              | قواعد شرطية لإضافة بادئة إلى المعرّف المجرّد بعد البحث عن الاسم المستعار، مفهرسة حسب `modelPrefix` و`prefix`. |

## مرجع providerEndpoints

استخدم `providerEndpoints` لتصنيف نقاط النهاية الذي يجب أن تعرفه سياسة الطلب العامة قبل تحميل وقت تشغيل المزوّد. لا يزال المركز يملك معنى كل `endpointClass`؛ وتمتلك بيانات Plugin الوصفية المضيف وبيانات عنوان URL الأساسي.

حقول نقطة النهاية:

| الحقل                          | النوع       | ما يعنيه                                                                                       |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- |
| `endpointClass`                | `string`   | فئة نقطة نهاية أساسية معروفة، مثل `openrouter` أو `moonshot-native` أو `google-vertex`.        |
| `hosts`                        | `string[]` | أسماء مضيفين دقيقة تُطابق فئة نقطة النهاية.                                                    |
| `hostSuffixes`                 | `string[]` | لواحق مضيفين تُطابق فئة نقطة النهاية. ابدأ بـ `.` للمطابقة حسب لاحقة النطاق فقط.              |
| `baseUrls`                     | `string[]` | عناوين HTTP(S) أساسية مطبّعة ودقيقة تُطابق فئة نقطة النهاية.                                  |
| `googleVertexRegion`           | `string`   | منطقة Google Vertex ثابتة للمضيفين العالميين المطابقين بدقة.                                  |
| `googleVertexRegionHostSuffix` | `string`   | لاحقة تُزال من المضيفين المطابقين لكشف بادئة منطقة Google Vertex.                              |

## مرجع providerRequest

استخدم `providerRequest` لبيانات وصفية منخفضة التكلفة لتوافق الطلبات تحتاجها سياسة الطلب العامة من دون تحميل وقت تشغيل المزوّد. أبقِ إعادة كتابة الحمولة الخاصة بالسلوك في خطافات وقت تشغيل المزوّد أو مساعدات عائلة المزوّد المشتركة.

```json
{
  "providers": ["vllm"],
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}
```

حقول المزوّد:

| الحقل                 | النوع         | ما يعنيه                                                                              |
| --------------------- | ------------ | -------------------------------------------------------------------------------------- |
| `family`              | `string`     | تسمية عائلة المزوّد المستخدمة في قرارات توافق الطلبات العامة والتشخيصات.             |
| `compatibilityFamily` | `"moonshot"` | حاوية توافق اختيارية لعائلة المزوّد لمساعدات الطلبات المشتركة.                       |
| `openAICompletions`   | `object`     | أعلام طلبات الإكمال المتوافقة مع OpenAI، وهي حاليًا `supportsStreamingUsage`.         |

## مرجع modelPricing

استخدم `modelPricing` عندما يحتاج مزوّد إلى سلوك تسعير في مستوى التحكم قبل تحميل وقت التشغيل. تقرأ ذاكرة التسعير المؤقتة في Gateway هذه البيانات الوصفية من دون استيراد شيفرة وقت تشغيل المزوّد.

```json
{
  "providers": ["ollama", "openrouter"],
  "modelPricing": {
    "providers": {
      "ollama": {
        "external": false
      },
      "openrouter": {
        "openRouter": {
          "passthroughProviderModel": true
        },
        "liteLLM": false
      }
    }
  }
}
```

حقول المزوّد:

| الحقل        | النوع              | ما يعنيه                                                                                               |
| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- |
| `external`   | `boolean`         | اضبطه على `false` للمزوّدين المحليين/ذاتيّي الاستضافة الذين يجب ألا يجلبوا أبدًا تسعير OpenRouter أو LiteLLM. |
| `openRouter` | `false \| object` | تعيين البحث عن تسعير OpenRouter. يعطّل `false` بحث OpenRouter لهذا المزوّد.                         |
| `liteLLM`    | `false \| object` | تعيين البحث عن تسعير LiteLLM. يعطّل `false` بحث LiteLLM لهذا المزوّد.                               |

حقول المصدر:

| الحقل                      | النوع               | ما يعنيه                                                                                                               |
| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`           | معرّف مزوّد الفهرس الخارجي عندما يختلف عن معرّف مزوّد OpenClaw، مثل `z-ai` لمزوّد `zai`.                            |
| `passthroughProviderModel` | `boolean`          | تعامل مع معرّفات النماذج التي تحتوي على شرطة مائلة كمراجع مزوّد/نموذج متداخلة، مفيد لمزوّدي الوكيل مثل OpenRouter. |
| `modelIdTransforms`        | `"version-dots"[]` | متغيرات إضافية لمعرّف نموذج الفهرس الخارجي. يحاول `version-dots` معرّفات إصدارات منقوطة مثل `claude-opus-4.6`.       |

### فهرس مزوّدي OpenClaw

فهرس مزوّدي OpenClaw هو بيانات وصفية تمهيدية مملوكة لـ OpenClaw للمزوّدين الذين قد لا تكون Plugins الخاصة بهم مثبّتة بعد. ليس جزءًا من بيان Plugin. تظل بيانات Plugin هي المرجع للمكوّنات المثبّتة. فهرس المزوّدين هو عقد الرجوع الداخلي الذي ستستهلكه مستقبلًا أسطح اختيار النماذج للمزوّدين القابلين للتثبيت وما قبل التثبيت عندما لا يكون Plugin المزوّد مثبتًا.

ترتيب مرجعية الفهرس:

1. إعدادات المستخدم.
2. بيان Plugin المثبّت `modelCatalog`.
3. ذاكرة فهرس النماذج المؤقتة من تحديث صريح.
4. صفوف معاينة فهرس مزوّدي OpenClaw.

يجب ألا يحتوي فهرس المزوّدين على أسرار، أو حالة تفعيل، أو خطافات وقت تشغيل، أو بيانات نماذج مباشرة خاصة بالحساب. تستخدم فهارس المعاينة الخاصة به شكل صف مزوّد `modelCatalog` نفسه مثل بيانات Plugin، لكنها يجب أن تبقى محدودة ببيانات العرض الوصفية المستقرة إلا إذا كانت حقول محوّل وقت التشغيل مثل `api` أو `baseUrl` أو التسعير أو أعلام التوافق محفوظة عمدًا بمحاذاة بيان Plugin المثبّت. يجب على المزوّدين الذين لديهم اكتشاف مباشر عبر `/models` كتابة الصفوف المحدّثة عبر مسار ذاكرة فهرس النماذج المؤقتة الصريح بدلًا من جعل الإدراج العادي أو الإعداد يستدعي واجهات API الخاصة بالمزوّدين.

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

مفاتيح الإمكانات القديمة في المستوى الأعلى مهملة. استخدم `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.bundle` و`openclaw.bundle.json` ليستا عقود Plugin في OpenClaw؛ يجب أن تستخدم Plugins الأصلية `openclaw.plugin.json` بالإضافة إلى حقول `package.json#openclaw` المدعومة أدناه.

أمثلة مهمة:

| الحقل                                                                                      | معناه                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions`                                                                      | يعلن نقاط دخول Plugin الأصلية. يجب أن يبقى داخل دليل حزمة Plugin.                                                                                                   |
| `openclaw.runtimeExtensions`                                                               | يعلن نقاط دخول وقت تشغيل JavaScript المبنية للحزم المثبتة. يجب أن يبقى داخل دليل حزمة Plugin.                                                                 |
| `openclaw.setupEntry`                                                                      | نقطة دخول خفيفة مخصصة للإعداد فقط، تُستخدم أثناء التهيئة الأولية، وبدء تشغيل القناة المؤجل، واكتشاف حالة القناة للقراءة فقط/SecretRef. يجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.runtimeSetupEntry`                                                               | يعلن نقطة دخول إعداد JavaScript المبنية للحزم المثبتة. يتطلب `setupEntry`، ويجب أن يكون موجودًا، ويجب أن يبقى داخل دليل حزمة Plugin.                         |
| `openclaw.channel`                                                                         | بيانات وصفية رخيصة لفهرس القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونص الاختيار.                                                                                                 |
| `openclaw.channel.commands`                                                                | بيانات وصفية ثابتة للأوامر الأصلية والمهارة الأصلية الافتراضية تلقائيًا، تُستخدم بواسطة واجهات التكوين والتدقيق وقائمة الأوامر قبل تحميل وقت تشغيل القناة.                                          |
| `openclaw.channel.configuredState`                                                         | بيانات وصفية خفيفة لمدقق حالة التكوين يمكنها الإجابة عن "هل يوجد بالفعل إعداد يعتمد على env فقط؟" دون تحميل وقت تشغيل القناة الكامل.                                         |
| `openclaw.channel.persistedAuthState`                                                      | بيانات وصفية خفيفة لمدقق المصادقة المستمرة يمكنها الإجابة عن "هل تم تسجيل الدخول إلى أي شيء بالفعل؟" دون تحميل وقت تشغيل القناة الكامل.                                               |
| `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات تثبيت/تحديث للـ Plugins المضمنة والمنشورة خارجيًا.                                                                                                                   |
| `openclaw.install.defaultChoice`                                                           | مسار التثبيت المفضل عندما تتوفر عدة مصادر تثبيت.                                                                                                                  |
| `openclaw.install.minHostVersion`                                                          | أدنى إصدار مدعوم من مضيف OpenClaw، باستخدام حد أدنى وفق semver مثل `>=2026.3.22` أو `>=2026.5.1-beta.1`.                                                                             |
| `openclaw.install.expectedIntegrity`                                                       | سلسلة تكامل npm dist المتوقعة مثل `sha512-...`؛ تتحقق مسارات التثبيت والتحديث من الأثرية التي تم جلبها مقابلها.                                                            |
| `openclaw.install.allowInvalidConfigRecovery`                                              | يسمح بمسار ضيق لاسترداد إعادة تثبيت Plugin مضمن عندما يكون التكوين غير صالح.                                                                                                       |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`                          | يسمح بتحميل واجهات القناة الخاصة بالإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل.                                                                                                 |

تحدد بيانات البيان الوصفية اختيارات المزوّد/القناة/الإعداد التي تظهر في
التهيئة الأولية قبل تحميل وقت التشغيل. يوضح `package.json#openclaw.install`
للتهيئة الأولية كيفية جلب ذلك الـ Plugin أو تمكينه عندما يختار المستخدم أحد تلك
الاختيارات. لا تنقل تلميحات التثبيت إلى `openclaw.plugin.json`.

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

يجب أن تستخدم بيانات التثبيت عند الطلب الرسمية `clawhubSpec` عندما يكون Plugin
منشورًا على ClawHub؛ تتعامل التهيئة الأولية مع ذلك كمصدر بعيد مفضل وتسجل
حقائق أثرية ClawHub بعد التثبيت. يظل `npmSpec` بديل التوافق
للحزم التي لم تنتقل إلى ClawHub بعد.

تثبيت إصدار npm الدقيق موجود بالفعل في `npmSpec`، على سبيل المثال
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. يجب أن تقرن إدخالات الفهرس
الخارجية الرسمية المواصفات الدقيقة مع `expectedIntegrity` بحيث تفشل مسارات التحديث
بشكل مغلق إذا لم تعد أثرية npm التي تم جلبها تطابق الإصدار المثبت.
لا تزال التهيئة الأولية التفاعلية تعرض مواصفات npm من السجل الموثوق، بما في ذلك
أسماء الحزم المجردة وdist-tags، للتوافق. يمكن لتشخيصات الفهرس
التمييز بين المصادر الدقيقة، والعائمة، والمثبتة بالتكامل، وناقصة التكامل، وغير المتطابقة في اسم الحزمة،
وذات الاختيار الافتراضي غير الصالح. كما تحذر عندما يكون
`expectedIntegrity` موجودًا لكن لا يوجد مصدر npm صالح يمكنه تثبيته.
عندما يكون `expectedIntegrity` موجودًا،
تفرضه مسارات التثبيت/التحديث؛ وعندما يُحذف، يُسجل حل السجل
دون تثبيت تكامل.

يجب أن توفر Plugins القنوات `openclaw.setupEntry` عندما تحتاج عمليات فحص الحالة أو قائمة القنوات
أو SecretRef إلى تحديد الحسابات المكونة دون تحميل وقت التشغيل الكامل.
يجب أن تعرض نقطة دخول الإعداد بيانات القناة الوصفية إضافة إلى محولات التكوين
والحالة والأسرار الآمنة للإعداد؛ أبقِ عملاء الشبكة، ومستمعي Gateway،
وأوقات تشغيل النقل في نقطة دخول الامتداد الرئيسية.

لا تتجاوز حقول نقاط دخول وقت التشغيل فحوصات حدود الحزمة لحقول نقاط دخول المصدر.
على سبيل المثال، لا يمكن لـ `openclaw.runtimeExtensions` جعل مسار
`openclaw.extensions` الهارب قابلًا للتحميل.

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

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

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

استخدمها عندما تحتاج مسارات الإعداد أو Doctor أو الحالة أو حضور القراءة فقط إلى مسبار مصادقة
رخيص بنعم/لا قبل تحميل Plugin القناة الكامل. حالة المصادقة المستمرة ليست
حالة قناة مكونة: لا تستخدم هذه البيانات الوصفية لتمكين Plugins تلقائيًا،
أو إصلاح تبعيات وقت التشغيل، أو تحديد ما إذا كان يجب تحميل وقت تشغيل قناة.
يجب أن يكون التصدير الهدف دالة صغيرة تقرأ الحالة المستمرة فقط؛
لا تمررها عبر برميل وقت تشغيل القناة الكامل.

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

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

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

## أسبقية الاكتشاف (معرفات Plugin المكررة)

يكتشف OpenClaw الـ Plugins من عدة جذور (مضمن، تثبيت عام، مساحة عمل، مسارات محددة صراحةً عبر التكوين). إذا اشترك اكتشافان في `id` نفسه، يُحتفظ فقط بالبيان ذي **الأسبقية الأعلى**؛ وتُسقط النسخ المكررة الأقل أسبقية بدلًا من تحميلها بجانبه.

الأسبقية، من الأعلى إلى الأدنى:

1. **محدد بالتكوين** — مسار مثبت صراحةً في `plugins.entries.<id>`
2. **مضمن** — Plugins التي تُشحن مع OpenClaw
3. **تثبيت عام** — Plugins المثبتة في جذر Plugins العام لـ OpenClaw
4. **مساحة العمل** — Plugins المكتشفة نسبةً إلى مساحة العمل الحالية

الآثار:

- لن تحجب نسخة متفرعة أو قديمة من Plugin مضمن موجودة في مساحة العمل البناء المضمن.
- لتجاوز Plugin مضمن فعليًا بآخر محلي، ثبته عبر `plugins.entries.<id>` كي يفوز بالأسبقية بدلًا من الاعتماد على اكتشاف مساحة العمل.
- تُسجل عمليات إسقاط النسخ المكررة حتى تتمكن تشخيصات Doctor وبدء التشغيل من الإشارة إلى النسخة المستبعدة.
- تُصاغ تجاوزات النسخ المكررة المحددة بالتكوين كتجاوزات صريحة في التشخيصات، لكنها تظل تحذر حتى تبقى التفرعات القديمة والحجب العرضي مرئية.

## متطلبات JSON Schema

- **يجب أن يشحن كل Plugin مخطط JSON Schema**، حتى لو لم يقبل أي تكوين.
- المخطط الفارغ مقبول (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`).
- تُتحقق المخططات عند وقت قراءة/كتابة التكوين، وليس عند وقت التشغيل.
- عند توسيع Plugin مضمن أو تفريعه بمفاتيح تكوين جديدة، حدّث `configSchema` في `openclaw.plugin.json` لذلك الـ Plugin في الوقت نفسه. مخططات Plugin المضمنة صارمة، لذا ستُرفض إضافة `plugins.entries.<id>.config.myNewKey` في تكوين المستخدم دون إضافة `myNewKey` إلى `configSchema.properties` قبل تحميل وقت تشغيل Plugin.

مثال على توسيع المخطط:

```json
{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "myNewKey": {
        "type": "string"
      }
    }
  }
}
```

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

- مفاتيح `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 بشكل منفصل؛ فالبيان مخصص فقط للاكتشاف + التحقق.
- تُحلَّل بيانات Plugins الأصلية باستخدام JSON5، لذلك تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير المقتبسة ما دامت القيمة النهائية لا تزال كائنًا.
- لا يقرأ محمّل البيان إلا حقول البيان الموثقة. تجنّب المفاتيح المخصصة في المستوى الأعلى.
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` كلها عندما لا يحتاجها Plugin.
- يجب أن يبقى `providerDiscoveryEntry` خفيفًا وألا يستورد شيفرة وقت تشغيل واسعة؛ استخدمه لبيانات وصفية ثابتة لفهرس المزوّدين أو واصفات اكتشاف ضيقة، وليس للتنفيذ وقت الطلب.
- تُحدَّد أنواع Plugin الحصرية عبر `plugins.slots.*`: ‏`kind: "memory"` عبر `plugins.slots.memory`، و`kind: "context-engine"` عبر `plugins.slots.contextEngine` (الافتراضي `legacy`).
- صرّح عن نوع Plugin الحصري في هذا البيان. أصبح `OpenClawPluginDefinition.kind` الخاص بمدخل وقت التشغيل مهمَلًا، ولا يبقى إلا كآلية توافق احتياطية لـ Plugins الأقدم.
- البيانات الوصفية لمتغيرات البيئة (`setup.providers[].envVars` و`providerAuthEnvVars` المهمَل و`channelEnvVars`) تعريفية فقط. لا تزال الحالة والتدقيق والتحقق من تسليم Cron وغيرها من الواجهات للقراءة فقط تطبّق سياسة ثقة Plugin والتفعيل الفعلي قبل التعامل مع متغير بيئة على أنه مهيّأ.
- لبيانات معالج الإعداد الوصفية وقت التشغيل التي تتطلب شيفرة مزوّد، راجع [خطافات وقت تشغيل المزوّد](/ar/plugins/architecture-internals#provider-runtime-hooks).
- إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح في مدير الحزم (على سبيل المثال، pnpm `allow-build-scripts` + `pnpm rebuild <package>`).

## ذات صلة

<CardGroup cols={3}>
  <Card title="بناء Plugins" href="/ar/plugins/building-plugins" icon="rocket">
    البدء باستخدام Plugins.
  </Card>
  <Card title="بنية Plugin" href="/ar/plugins/architecture" icon="diagram-project">
    البنية الداخلية ونموذج القدرات.
  </Card>
  <Card title="نظرة عامة على SDK" href="/ar/plugins/sdk-overview" icon="book">
    مرجع SDK الخاص بـ Plugin واستيرادات المسارات الفرعية.
  </Card>
</CardGroup>
