---
read_when:
    - أنت تبني Plugin لـ OpenClaw
    - تحتاج إلى إصدار مخطط إعدادات Plugin أو تصحيح أخطاء التحقق من صحة Plugin
summary: متطلبات بيان Plugin ومخطط JSON (تحقق صارم من صحة الإعدادات)
title: بيان Plugin
x-i18n:
    generated_at: "2026-07-12T06:16:34Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: cd4ab5b10108585abb9a83a416b129e6f6351023016064b5d64b66aeabd04b2f
    source_path: plugins/manifest.md
    workflow: 16
---

تغطي هذه الصفحة **بيان Plugin الأصلي لـ OpenClaw**، وهو `openclaw.plugin.json`. للاطلاع على تخطيطات الحزم المتوافقة (Codex وClaude وCursor)، راجع [حزم 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.

راجع [Plugins](/ar/tools/plugin) للاطلاع على الدليل الكامل لنظام Plugins، و[نموذج الإمكانات](/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"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["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.                                                                                                                                                                                                                               |
| `requiresPlugins`                    | لا       | `string[]`                   | معرّفات Plugins التي يجب تثبيتها أيضًا لكي يكون لهذا الـ Plugin تأثير. تُبقي عملية الاكتشاف الـ Plugin قابلًا للتحميل، لكنها تُصدر تحذيرًا عند غياب أي Plugin مطلوب.                                                                                                               |
| `enabledByDefault`                   | لا       | `true`                       | يضع علامة على Plugin مضمّن باعتباره مفعّلًا افتراضيًا. احذفه، أو عيّن أي قيمة غير `true`، لترك الـ Plugin معطّلًا افتراضيًا.                                                                                                                                               |
| `enabledByDefaultOnPlatforms`        | لا       | `string[]`                   | يضع علامة على Plugin مضمّن باعتباره مفعّلًا افتراضيًا فقط على منصات Node.js المدرجة، مثل `["darwin"]`. تظل للإعدادات الصريحة الأولوية.                                                                                                                                   |
| `legacyPluginIds`                    | لا       | `string[]`                   | المعرّفات القديمة التي تُطبَّع إلى المعرّف القياسي لهذا الـ Plugin.                                                                                                                                                                                                                     |
| `autoEnableWhenConfiguredProviders`  | لا       | `string[]`                   | معرّفات المزوّدين التي ينبغي أن تفعّل هذا الـ Plugin تلقائيًا عندما تشير إليها مراجع المصادقة أو الإعدادات أو النماذج.                                                                                                                                                                            |
| `kind`                               | لا       | `PluginKind \| PluginKind[]` | يعلن عن نوع حصري واحد أو أكثر من أنواع Plugins ‏(`"memory"`، و`"context-engine"`) المستخدمة بواسطة `plugins.slots.*`. يعلن الـ Plugin الذي يملك كلتا الفتحتين عن كلا النوعين في مصفوفة واحدة.                                                                                                    |
| `channels`                           | لا       | `string[]`                   | معرّفات القنوات التي يملكها هذا الـ Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات.                                                                                                                                                                                                |
| `providers`                          | لا       | `string[]`                   | معرّفات المزوّدين التي يملكها هذا الـ Plugin.                                                                                                                                                                                                                                         |
| `providerCatalogEntry`               | لا       | `string`                     | مسار وحدة خفيف لكتالوج المزوّد، نسبةً إلى جذر الـ Plugin، لبيانات تعريف كتالوج المزوّد ضمن نطاق البيان، والتي يمكن تحميلها دون تفعيل وقت تشغيل الـ Plugin الكامل.                                                                                        |
| `modelSupport`                       | لا       | `object`                     | بيانات تعريف مختصرة لعائلة النماذج، يملكها البيان، وتُستخدم لتحميل الـ Plugin تلقائيًا قبل وقت التشغيل.                                                                                                                                                                                |
| `modelCatalog`                       | لا       | `object`                     | بيانات تعريف تصريحية لكتالوج النماذج للمزوّدين الذين يملكهم هذا الـ Plugin. هذا هو عقد مستوى التحكم للإدراج المستقبلي للقراءة فقط، والإعداد الأولي، ومنتقيات النماذج، والأسماء البديلة، والحجب دون تحميل وقت تشغيل الـ Plugin.                                                |
| `modelPricing`                       | لا       | `object`                     | سياسة البحث عن الأسعار الخارجية التي يملكها المزوّد. استخدمها لاستثناء المزوّدين المحليين أو المستضافين ذاتيًا من كتالوجات الأسعار البعيدة، أو لربط مراجع المزوّد بمعرّفات كتالوج OpenRouter/LiteLLM دون ترميز معرّفات المزوّدين داخل النواة.                                                    |
| `modelIdNormalization`               | لا       | `object`                     | تنظيف الأسماء البديلة أو البادئات لمعرّفات النماذج، الذي يملكه المزوّد ويجب تنفيذه قبل تحميل وقت تشغيل المزوّد.                                                                                                                                                                                  |
| `providerEndpoints`                  | لا       | `object[]`                   | بيانات تعريف المضيف أو `baseUrl` لنقاط النهاية، التي يملكها البيان، لمسارات المزوّد التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل المزوّد.                                                                                                                                                   |
| `providerRequest`                    | لا       | `object`                     | بيانات تعريف خفيفة لعائلة المزوّد وتوافق الطلبات، تستخدمها سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد.                                                                                                                                                     |
| `secretProviderIntegrations`         | لا       | `Record<string, object>`     | إعدادات مسبقة تصريحية لمزوّدي تنفيذ SecretRef، يمكن لواجهات الإعداد أو التثبيت عرضها دون ترميز تكاملات خاصة بالمزوّد داخل النواة.                                                                                                                            |
| `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 يقرأ هذه البيانات خلال فترة الإهمال.                                                                                        |
| `providerUsageAuthEnvVars`           | لا       | `Record<string, string[]>`   | بيانات اعتماد المزوّد الخاصة بالاستخدام أو الفوترة فقط. يستخدم OpenClaw هذه الأسماء لاكتشاف الاستخدام وتنقية الأسرار، ولكن لا يستخدمها أبدًا لمصادقة الاستدلال.                                                                                                                                  |
| `providerAuthAliases`                | لا       | `Record<string, string>`     | معرّفات المزوّدين التي ينبغي أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، مثل مزوّد برمجة يشارك مفتاح API وملفات تعريف المصادقة الخاصة بالمزوّد الأساسي.                                                                                                                 |
| `channelEnvVars`                     | لا       | `Record<string, string[]>`   | بيانات تعريف خفيفة لمتغيرات بيئة القناة يستطيع OpenClaw فحصها دون تحميل رمز الـ Plugin. استخدمها لإعداد القنوات المعتمد على متغيرات البيئة، أو لواجهات المصادقة التي ينبغي أن تراها مساعدات بدء التشغيل أو الإعدادات العامة.                                                                                   |
| `providerAuthChoices`                | لا       | `object[]`                   | بيانات تعريف خفيفة لخيارات المصادقة لاستخدامها في منتقيات الإعداد الأولي، وحلّ المزوّد المفضّل، والربط البسيط لعلامات CLI.                                                                                                                                                              |
| `activation`                         | لا       | `object`                     | بيانات تعريف خفيفة لمخطط التفعيل من أجل التحميل المحفَّز ببدء التشغيل أو المزوّد أو الأمر أو القناة أو المسار أو الإمكانية. هي بيانات تعريف فقط؛ ويظل وقت تشغيل الـ Plugin مالكًا للسلوك الفعلي.                                                                                              |
| `setup`                              | لا       | `object`                     | واصفات خفيفة للإعداد أو الإعداد الأولي يمكن لواجهات الاكتشاف والإعداد فحصها دون تحميل وقت تشغيل الـ Plugin.                                                                                                                                                           |
| `qaRunners`                          | لا       | `object[]`                   | واصفات خفيفة لمشغّلات ضمان الجودة يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin.                                                                                                                                                                             |
| `contracts`                          | لا       | `object`                     | لقطة ثابتة لملكية الإمكانات لخطافات المصادقة الخارجية، والتضمينات، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور والفيديو والموسيقى، وجلب الويب، والبحث في الويب، ومزوّدي العمال، واستخراج محتوى المستندات والويب، وملكية الأدوات. |
| `configContracts`                    | لا       | `object`                     | سلوك الإعدادات الذي يملكه البيان وتستهلكه مساعدات النواة العامة: اكتشاف العلامات الخطرة، وأهداف ترحيل SecretRef، وتضييق مسارات الإعدادات القديمة. راجع [مرجع configContracts](#configcontracts-reference).                                                     |
| `mediaUnderstandingProviderMetadata` | لا       | `Record<string, object>`     | إعدادات افتراضية منخفضة التكلفة لفهم الوسائط لمعرّفات المزوّدين المعلنة في `contracts.mediaUnderstandingProviders`.                                                                                                                                                                   |
| `imageGenerationProviderMetadata`    | لا       | `Record<string, object>`     | بيانات وصفية منخفضة التكلفة لمصادقة توليد الصور لمعرّفات المزوّدين المعلنة في `contracts.imageGenerationProviders`، بما في ذلك الأسماء البديلة للمصادقة التي يملكها المزوّد وقيود عنوان URL الأساسي.                                                                                                         |
| `videoGenerationProviderMetadata`    | لا       | `Record<string, object>`     | بيانات وصفية منخفضة التكلفة لمصادقة توليد الفيديو لمعرّفات المزوّدين المعلنة في `contracts.videoGenerationProviders`، بما في ذلك الأسماء البديلة للمصادقة التي يملكها المزوّد وقيود عنوان URL الأساسي.                                                                                                         |
| `musicGenerationProviderMetadata`    | لا       | `Record<string, object>`     | بيانات وصفية منخفضة التكلفة لمصادقة توليد الموسيقى لمعرّفات المزوّدين المعلنة في `contracts.musicGenerationProviders`، بما في ذلك الأسماء البديلة للمصادقة التي يملكها المزوّد وقيود عنوان URL الأساسي.                                                                                                         |
| `toolMetadata`                       | لا       | `Record<string, object>`     | بيانات وصفية منخفضة التكلفة لإتاحة الأدوات المملوكة للـ Plugin والمعلنة في `contracts.tools`. استخدمها عندما ينبغي ألا تحمّل الأداة بيئة التشغيل ما لم تتوفر أدلة من الإعدادات أو متغيرات البيئة أو المصادقة.                                                                                                  |
| `channelConfigs`                     | لا       | `Record<string, object>`     | بيانات وصفية لإعدادات القنوات يملكها ملف البيان، وتُدمج في واجهات الاكتشاف والتحقق قبل تحميل بيئة التشغيل.                                                                                                                                                                 |
| `skills`                             | لا       | `string[]`                   | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر الـ Plugin.                                                                                                                                                                                                                    |
| `name`                               | لا       | `string`                     | اسم الـ Plugin القابل للقراءة.                                                                                                                                                                                                                                                |
| `description`                        | لا       | `string`                     | ملخص قصير يظهر في واجهات الـ Plugin.                                                                                                                                                                                                                                    |
| `catalog`                            | لا       | `object`                     | تلميحات عرض اختيارية لواجهات كتالوج الـ Plugin. لا تثبّت هذه البيانات الوصفية أي Plugin أو تفعّله أو تمنحه الثقة.                                                                                                                                               |
| `icon`                               | لا       | `string`                     | عنوان URL لصورة عبر HTTPS لبطاقات السوق أو الكتالوج. يقبل ClawHub أي عنوان URL صالح يبدأ بـ `https://`، ويستخدم أيقونة الـ Plugin الافتراضية عند حذف هذا الحقل أو إذا كانت قيمته غير صالحة.                                                                                                         |
| `version`                            | لا       | `string`                     | إصدار الـ Plugin لأغراض معلوماتية.                                                                                                                                                                                                                                              |
| `uiHints`                            | لا       | `Record<string, object>`     | تسميات واجهة المستخدم، والنصوص النائبة، وتلميحات الحساسية لحقول الإعدادات.                                                                                                                                                                                                          |

## مرجع `catalog`

يوفّر `catalog` تلميحات عرض اختيارية لمتصفحات الـ Plugin. قد تتجاهل المضيفات هذه التلميحات. وهي لا تثبّت الـ Plugin أو تفعّله مطلقًا، ولا تغيّر سلوكه في وقت التشغيل أو مستوى الثقة به.

```json
{
  "catalog": {
    "featured": true,
    "order": 10
  }
}
```

| الحقل      | النوع      | معناه                                                              |
| ---------- | --------- | -------------------------------------------------------------------------- |
| `featured` | `boolean` | ما إذا كان ينبغي لواجهات الكتالوج إبراز هذا الـ Plugin.                       |
| `order`    | `number`  | تلميح عرض تصاعدي بين الـ Plugins المنتقاة؛ تظهر القيم الأقل في موضع أسبق. |

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

تصف حقول البيانات الوصفية لمزوّد التوليد إشارات المصادقة الثابتة للمزوّدين المعلنين في قائمة `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`.                     |
| `referenceAudioInputs` | لا       | `boolean`  | لتوليد الفيديو فقط. اضبطه على `true` عندما يقبل المزوّد أصولًا صوتية مرجعية؛ وإلا فإن `video_generate` يخفي معاملات المراجع الصوتية. |

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

| الحقل            | مطلوب | النوع       | معناه                                                                                                                                                                             |
| ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rootPath`       | نعم      | `string`   | مسار نقطي إلى كائن الإعدادات المملوك للـ Plugin لفحصه، مثل `plugins.entries.example.config`.                                                                                      |
| `overlayPath`    | لا       | `string`   | مسار نقطي داخل الإعدادات الجذرية، ينبغي أن يُسقِط كائنه قيمه فوق الكائن الجذري قبل تقييم الإشارة. استخدمه للإعدادات الخاصة بقدرة معيّنة، مثل `image` أو `video` أو `music`.   |
| `overlayMapPath` | لا       | `string`   | مسار نقطي داخل الإعدادات الجذرية، ينبغي أن يُسقِط كل كائن من قيمه فوق الكائن الجذري. استخدمه لخرائط الحسابات المسماة مثل `accounts`، حيث ينبغي أن يكون أي حساب مضبوط مؤهّلًا. |
| `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
{
  "setup": {
    "providers": [
      {
        "id": "example",
        "envVars": ["EXAMPLE_API_KEY"]
      }
    ]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}
```

تقبل إدخالات `toolMetadata` أيضًا `optional` (يضع علامة على أن الأداة غير مطلوبة لتفعيل الـ Plugin) و`replaySafe` (يضع علامة على أن تكرار تنفيذ الأداة آمن بعد دورة نموذج غير مكتملة)، بالإضافة إلى حقول `configSignals`/`authSignals` المشتركة أعلاه.

إذا لم يكن للأداة `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`                                                               | نص مساعد قصير للمجموعة.                                                                              |
| `onboardingFeatured`  | لا    | `boolean`                                                              | يُظهر هذه المجموعة في فئة الخيارات المميزة بأداة اختيار الإعداد الأولي التفاعلية، قبل إدخال "المزيد...". |
| `optionKey`           | لا    | `string`                                                               | مفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد.                                        |
| `cliFlag`             | لا    | `string`                                                               | اسم علم CLI، مثل `--openrouter-api-key`.                                                            |
| `cliOption`           | لا    | `string`                                                               | الصيغة الكاملة لخيار CLI، مثل `--openrouter-api-key <key>`.                                        |
| `cliDescription`      | لا    | `string`                                                               | الوصف المستخدم في مساعدة CLI.                                                                       |
| `onboardingScopes`    | لا    | `Array<"text-inference" \| "image-generation" \| "music-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 قد نُفذت بالفعل. يستخدم مخطِّط التفعيل هذه الحقول لتضييق نطاق إضافات Plugin المرشحة قبل الرجوع إلى بيانات الملكية الوصفية الحالية في البيان، مثل `providers` و`channels` و`commandAliases` و`setup.providers` و`contracts.tools` والخطافات.

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

ينبغي لكل 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` المطابقة. يتيح `adapterFactory` اختياري
النقل لسيناريوهات ضمان الجودة المشتركة دون تغيير مشغّل الأمر المسجّل.

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

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

يجب أن يطابق معرّف `adapterFactory` القيمة `commandName`. لا تُصدّر تسجيلات
لأوامر غير موجودة في البيان.

## مرجع 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`.

استخدم `providerUsageAuthEnvVars` عندما يجب أن تفعّل بيانات اعتماد للفوترة أو على مستوى المؤسسة الدالة `resolveUsageAuth` من دون أن تصبح بيانات اعتماد للاستدلال. تنضم هذه الأسماء إلى حظر ملفات dotenv لمساحة العمل، وإزالتها من العمليات الفرعية لـ ACP، وتصفية الأسرار في بيئة العزل، والتنقيح الشامل للأسرار. ويظل وقت تشغيل المزوّد يقرأ القيمة ويصنّفها داخل `resolveUsageAuth`.

يمكن لـ 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` لعلامات بيانات الاعتماد المحلية المملوكة للمزوّد التي يمكن التحقق منها من دون تحميل شيفرة وقت التشغيل. يجب أن تظل هذه الفحوص منخفضة التكلفة ومحلية: بلا استدعاءات شبكة، ولا قراءات من سلسلة المفاتيح أو مدير الأسرار، ولا أوامر صدفة، ولا عمليات فحص لواجهة API الخاصة بالمزوّد.

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

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

### حقول setup

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

## مرجع uiHints

`uiHints` خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة. يمكن للمفاتيح استخدام النقاط لحقول الإعدادات المتداخلة، لكن لا يجوز أن يكون أي مقطع من المسار `__proto__` أو `constructor` أو `prototype`؛ يرفض الإعداد هذه الأسماء.

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

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

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

## مرجع contracts

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

```json
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "musicGenerationProviders": ["stability-audio"],
    "documentExtractors": ["example-docs"],
    "webContentExtractors": ["firecrawl"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "workerProviders": ["example-worker"],
    "usageProviders": ["acme-ai"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

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

| الحقل                            | النوع       | ما يعنيه                                                                                                                        |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `embeddedExtensionFactories`     | `string[]` | معرّفات مصانع امتدادات خادم تطبيق Codex، وحاليًا `codex-app-server`.                                                                |
| `agentToolResultMiddleware`      | `string[]` | معرّفات بيئات التشغيل التي يجوز لهذا الـ Plugin تسجيل برمجيات وسيطة لنتائج الأدوات لها.                                                                     |
| `trustedToolPolicies`            | `string[]` | معرّفات سياسات ما قبل الأداة الموثوقة والمحلية للـ Plugin التي يجوز لـ Plugin مثبّت تسجيلها. يجوز للـ Plugins المضمّنة تسجيل السياسات من دون هذا الحقل. |
| `externalAuthProviders`          | `string[]` | معرّفات المزوّدين الذين يمتلك هذا الـ Plugin خطاف ملفات تعريف المصادقة الخارجية الخاص بهم.                                                                      |
| `embeddingProviders`             | `string[]` | معرّفات مزوّدي التضمين العامين الذين يمتلكهم هذا الـ Plugin لاستخدامات تضمين المتجهات القابلة لإعادة الاستخدام، بما في ذلك الذاكرة.                                 |
| `speechProviders`                | `string[]` | معرّفات مزوّدي الكلام الذين يمتلكهم هذا الـ Plugin.                                                                                                |
| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ في الوقت الفعلي الذين يمتلكهم هذا الـ Plugin.                                                                                |
| `realtimeVoiceProviders`         | `string[]` | معرّفات مزوّدي الصوت في الوقت الفعلي الذين يمتلكهم هذا الـ Plugin.                                                                                        |
| `memoryEmbeddingProviders`       | `string[]` | معرّفات مزوّدي التضمين الخاصة بالذاكرة والمهملة التي يمتلكها هذا الـ Plugin.                                                                  |
| `mediaUnderstandingProviders`    | `string[]` | معرّفات مزوّدي فهم الوسائط الذين يمتلكهم هذا الـ Plugin.                                                                                   |
| `transcriptSourceProviders`      | `string[]` | معرّفات مزوّدي مصادر النصوص المنسوخة الذين يمتلكهم هذا الـ Plugin.                                                                                     |
| `documentExtractors`             | `string[]` | معرّفات مزوّدي استخراج المستندات (مثل PDF) الذين يمتلكهم هذا الـ Plugin.                                                                  |
| `imageGenerationProviders`       | `string[]` | معرّفات مزوّدي توليد الصور الذين يمتلكهم هذا الـ Plugin.                                                                                      |
| `videoGenerationProviders`       | `string[]` | معرّفات مزوّدي توليد الفيديو الذين يمتلكهم هذا الـ Plugin.                                                                                      |
| `musicGenerationProviders`       | `string[]` | معرّفات مزوّدي توليد الموسيقى الذين يمتلكهم هذا الـ Plugin.                                                                                      |
| `webContentExtractors`           | `string[]` | معرّفات مزوّدي استخراج محتوى صفحات الويب الذين يمتلكهم هذا الـ Plugin.                                                                           |
| `webFetchProviders`              | `string[]` | معرّفات مزوّدي جلب محتوى الويب الذين يمتلكهم هذا الـ Plugin.                                                                                             |
| `webSearchProviders`             | `string[]` | معرّفات مزوّدي البحث في الويب الذين يمتلكهم هذا الـ Plugin.                                                                                            |
| `workerProviders`                | `string[]` | معرّفات مزوّدي عمال السحابة الذين يمتلكهم هذا الـ Plugin للتزويد وإدارة دورة حياة عقود الإيجار المدعومة بملفات التعريف.                                      |
| `usageProviders`                 | `string[]` | معرّفات المزوّدين الذين يمتلك هذا الـ Plugin خطافات مصادقة الاستخدام ولقطات الاستخدام الخاصة بهم.                                                             |
| `migrationProviders`             | `string[]` | معرّفات مزوّدي الاستيراد الذين يمتلكهم هذا الـ Plugin للأمر `openclaw migrate`.                                                                         |
| `gatewayMethodDispatch`          | `string[]` | استحقاق محجوز لمسارات HTTP الموثّقة الخاصة بالـ Plugin التي توجّه أساليب Gateway داخل العملية.                                  |
| `tools`                          | `string[]` | أسماء أدوات الوكيل التي يمتلكها هذا الـ Plugin.                                                                                                   |

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

يجب على الـ Plugins المثبّتة التي تحتاج إلى طبقة سياسة ما قبل الأداة الموثوقة من المضيف أن تصرّح عن كل معرّف محلي مسجّل في `contracts.trustedToolPolicies` وأن تكون مُمكّنة صراحةً. تحتفظ الـ Plugins المضمّنة بمسار السياسة الموثوقة الحالي، لكن تُرفض الـ Plugins المثبّتة ذات معرّفات السياسات غير المصرّح بها قبل التسجيل. يقتصر نطاق معرّفات السياسات على الـ Plugin الذي يسجّلها، لذلك يجوز لاثنين من الـ Plugins التصريح عن `workflow-budget` وتسجيله؛ ولا يجوز لـ Plugin واحد تسجيل المعرّف المحلي نفسه مرتين.

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

ينبغي للـ Plugins المزوّدة التي تنفّذ `resolveExternalAuthProfiles` التصريح بـ `contracts.externalAuthProviders`؛ وتُتجاهل خطافات المصادقة الخارجية غير المصرّح بها.

ينبغي للـ Plugins المزوّدة التي تنفّذ كلًا من `resolveUsageAuth` و`fetchUsageSnapshot` التصريح عن كل معرّف مزوّد مكتشف تلقائيًا في `contracts.usageProviders`. يقرأ اكتشاف الاستخدام هذا العقد قبل تحميل شيفرة وقت التشغيل، ثم يتحقق من الخطافين كليهما بعد تحميل المالكين المصرّح بهم فقط.

ينبغي لمزوّدي التضمين العام التصريح بـ `contracts.embeddingProviders` لكل مهايئ مسجّل باستخدام `api.registerEmbeddingProvider(...)`. استخدم العقد العام لتوليد المتجهات القابل لإعادة الاستخدام، بما في ذلك المزوّدون الذين يستهلكهم بحث الذاكرة. إن `contracts.memoryEmbeddingProviders` توافق مهمل خاص بالذاكرة، ولا يبقى إلا أثناء ترحيل المزوّدين الحاليين إلى واجهة مزوّد التضمين العامة.

يجب على مزوّدي العمال التصريح عن كل معرّف `api.registerWorkerProvider(...)` في `contracts.workerProviders`. يحتفظ النواة بالنية الدائمة قبل استدعاء `provision`؛ ويتحقق المزوّدون من إعداداتهم قبل التخصيص الخارجي، ويجب أن تعتمد الاستدعاءات المتكررة ذات معرّف العملية نفسه عقد الإيجار نفسه. يحتفظ النواة أيضًا بلقطة الإعدادات المتحقق منها ويمررها مع `leaseId` إلى `inspect({ leaseId, profile })` و`destroy({ leaseId, profile })`، بما في ذلك بعد تغيير ملف التعريف المسمّى أو إزالته. عملية التدمير متكررة التنفيذ بأمان، ويُرجع الفحص اتحاد الحالات المغلق `active` / `destroyed` / `unknown`، ولا يُشار إلى مادة مفتاح SSH الخاص إلا من خلال `SecretRef`. يجب أن تتضمن نقاط نهاية SSH المزوّدة أيضًا `hostKey` عامًا من مخرجات تزويد موثوقة بالصيغة `algorithm base64` تمامًا، من دون اسم مضيف أو تعليق، لكي تتمكن النواة من تثبيت هوية المضيف قبل الاتصال. يجوز للمزوّدين الذين ينشئون مراجع هوية ديناميكية تنفيذ `resolveSshIdentity({ leaseId, profile, keyRef })` المرجعي؛ أما المزوّدون الذين لا ينفّذونه فيستخدمون محلّل الأسرار العام في النواة. تؤدي الحالة المرجعية `unknown` إلى جعل سجل محلي نشط يتيمًا؛ وبعد طلب تدمير محفوظ، تؤكد اكتمال الإزالة.

يقبل `contracts.gatewayMethodDispatch` حاليًا `"authenticated-request"`. وهو بوابة لضبط نظافة API لمسارات HTTP الأصلية للـ Plugin التي توجّه عمدًا أساليب مستوى تحكم Gateway داخل العملية، وليس بيئة عزل ضد الـ Plugins الأصلية الخبيثة. استخدمه فقط لأسطح مضمّنة أو تشغيلية خضعت لمراجعة دقيقة وتتطلب مسبقًا مصادقة HTTP الخاصة بـ Gateway. يظل المسار المستحق قابلًا للوصول عندما يكون قبول العمل الجذري في Gateway مغلقًا، فقط إذا صرّح أيضًا بـ `auth: "gateway"` و`gatewayRuntimeScopeSurface: "trusted-operator"` الخاص بالمسار؛ وتبقى المسارات النظيرة العادية من الـ Plugin نفسه خلف حدود القبول. يُبقي ذلك حالة التعليق والاستئناف قابلتين للوصول من دون منح الـ Plugin بأكمله تجاوزًا للقبول. أبقِ التحليل وتشكيل الاستجابة محدودين خارج التوجيه؛ ويجب أن يمر العمل الجوهري أو المعدِّل عبر توجيه أساليب Gateway، الذي يمتلك إنفاذ القبول والنطاق.

## مرجع configContracts

استخدم `configContracts` لسلوك الإعدادات المملوك لبيان الـ Plugin الذي تحتاج إليه مساعدات النواة العامة من دون استيراد وقت تشغيل الـ Plugin: اكتشاف العلامات الخطرة، وأهداف ترحيل `SecretRef`، وتضييق مسارات الإعدادات القديمة.

```json
{
  "configContracts": {
    "compatibilityMigrationPaths": ["legacyProvider"],
    "compatibilityRuntimePaths": ["legacyProvider.webhook"],
    "dangerousFlags": [
      {
        "path": "accounts.*.allowUnverifiedSenders",
        "equals": true
      }
    ],
    "secretInputs": {
      "bundledDefaultEnabled": false,
      "paths": [
        {
          "path": "apiKey",
          "expected": "string"
        }
      ]
    }
  }
}
```

| الحقل                         | مطلوب | النوع       | ما يعنيه                                                                                                                                                                                                                          |
| ----------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compatibilityMigrationPaths` | لا       | `string[]` | مسارات إعدادات نسبية إلى الجذر تشير إلى احتمال انطباق عمليات ترحيل التوافق في وقت إعداد هذا الـ Plugin. يتيح ذلك لقراءات إعدادات وقت التشغيل العامة تخطي جميع أسطح إعداد الـ Plugin عندما لا تشير الإعدادات إليه مطلقًا.                 |
| `compatibilityRuntimePaths`   | لا       | `string[]` | مسارات توافق نسبية إلى الجذر يمكن لهذا الـ Plugin خدمتها في وقت التشغيل قبل تنشيط شيفرة الـ Plugin بالكامل. استخدم هذا للأسطح القديمة التي ينبغي أن تضيّق مجموعات المرشحين المضمّنة من دون استيراد وقت تشغيل كل Plugin متوافق. |
| `dangerousFlags`              | لا       | `object[]` | قيم إعدادات حرفية ينبغي للأمر `openclaw doctor` الإبلاغ عنها بوصفها غير آمنة أو خطرة عند تمكينها. انظر أدناه.                                                                                                                                   |
| `secretInputs`                | لا       | `object`   | مسارات إعدادات ضمن `plugins.entries.<id>.config` ينبغي لسجل أهداف ترحيل/تدقيق `SecretRef` معاملتها كسلاسل ذات هيئة أسرار. انظر أدناه.                                                                                  |

يدعم كل إدخال في `dangerousFlags` ما يلي:

| الحقل    | مطلوب | النوع                                  | ما يعنيه                                                                                                       |
| -------- | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `path`   | نعم      | `string`                              | مسار إعدادات مفصول بنقاط بالنسبة إلى `plugins.entries.<id>.config`. يدعم أحرف البدل `*` لمقاطع الخرائط/المصفوفات. |
| `equals` | نعم      | `string \| number \| boolean \| null` | القيمة الحرفية الدقيقة التي تميّز قيمة الإعدادات هذه بأنها خطرة.                                                            |

يدعم `secretInputs` ما يلي:

| الحقل                    | مطلوب | النوع      | ما يعنيه                                                                                                                                                                                                                       |
| ------------------------ | ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bundledDefaultEnabled` | لا    | `boolean`  | يتجاوز التمكين الافتراضي للـ Plugin المضمّن عند تحديد ما إذا كان سطح SecretRef هذا نشطًا. استخدمه عندما يكون الـ Plugin مضمّنًا، لكن يجب أن يظل السطح غير نشط حتى يُمكَّن صراحةً في الإعدادات. |
| `paths`                 | نعم   | `object[]` | مسارات إعدادات على هيئة أسرار، يحتوي كل منها على `path` (مفصول بنقاط، ونسبي إلى `plugins.entries.<id>.config`، ويدعم محارف البدل `*`) و`expected` اختياري (لا يدعم حاليًا سوى `"string"`). |

## مرجع 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"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}
```

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

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

## مرجع 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 تحميل الـ 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[]`               | معرّفات Plugins القديمة أو الأقل أولوية التي ينبغي لهذه القناة أن تتفوق عليها في واجهات الاختيار.           |

### استبدال 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 واحد القناة وأدواتها. يظل اختيار المستخدم الصريح هو الغالب: إذا مكّن المستخدم كلا الـ Pluginين صراحةً (عبر `plugins.allow` أو إعداد فعلي في `plugins.entries`)، يحافظ OpenClaw على ذلك الاختيار ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من تغيير مجموعة الـ Plugins المطلوبة بصمت.

اجعل نطاق `preferOver` مقتصرًا على معرّفات Plugins التي يمكنها فعلًا توفير القناة نفسها. فهو ليس حقل أولوية عامًا، ولا يعيد تسمية مفاتيح إعدادات المستخدم.

## مرجع modelSupport

استخدم `modelSupport` عندما ينبغي لـ OpenClaw استنتاج Plugin المزوّد الخاص بك من معرّفات نماذج مختصرة مثل `gpt-5.6-sol` أو `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[]` | مصادر تعبيرات نمطية تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة ملف التعريف.             |

تُجمّع إدخالات `modelPatterns` عبر `compileSafeRegex`، الذي يرفض الأنماط المحتوية على تكرار متداخل (مثل `(a+)+$`). تُتخطى الأنماط التي تفشل في فحص السلامة بصمت، كما هو الحال مع التعبيرات النمطية غير الصالحة نحويًا. اجعل الأنماط بسيطة وتجنب محددات التكرار المتداخلة.

## مرجع modelCatalog

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

```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">` | ما إذا كان يمكن قراءة كتالوج المزوّد من بيانات البيان الوصفية، أو تحديثه في ذاكرة التخزين المؤقت، أو كان يتطلب وقت التشغيل. |
| `runtimeAugment` | `boolean`                                                | يُضبط على `true` فقط عندما يجب أن يضيف وقت تشغيل المزوّد صفوف الكتالوج بعد تخطيط البيان/الإعداد.                            |

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

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

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

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

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

| الحقل               | النوع                                                           | معناه                                                                                       |
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `id`                | `string`                                                        | معرّف النموذج المحلي لدى المزوّد، من دون البادئة `provider/`.                              |
| `name`              | `string`                                                        | اسم عرض اختياري.                                                                            |
| `api`               | `ModelApi`                                                      | تجاوز اختياري لواجهة API لكل نموذج.                                                        |
| `baseUrl`           | `string`                                                        | تجاوز اختياري لعنوان URL الأساسي لكل نموذج.                                                |
| `headers`           | `Record<string, string>`                                        | ترويسات ثابتة اختيارية لكل نموذج.                                                           |
| `input`             | `Array<"text" \| "image" \| "document">`                        | الأنماط التي يقبلها النموذج. تُحذف القيم الأخرى بصمت.                                      |
| `reasoning`         | `boolean`                                                       | ما إذا كان النموذج يوفّر سلوك الاستدلال.                                                    |
| `contextWindow`     | `number`                                                        | نافذة السياق الأصلية لدى المزوّد.                                                           |
| `contextTokens`     | `number`                                                        | حد سياق فعّال اختياري في وقت التشغيل عندما يختلف عن `contextWindow`.                       |
| `maxTokens`         | `number`                                                        | الحد الأقصى لرموز الإخراج عندما يكون معروفًا.                                               |
| `thinkingLevelMap`  | `Record<string, string \| null>`                                | تجاوزات اختيارية لمعرّف النموذج أو المعامل لكل مستوى تفكير.                                |
| `cost`              | `object`                                                        | تسعير اختياري بالدولار الأمريكي لكل مليون رمز، بما في ذلك `tieredPricing` الاختياري.       |
| `compat`            | `object`                                                        | علامات توافق اختيارية تطابق توافق إعداد نموذج OpenClaw.                                    |
| `mediaInput`        | `object`                                                        | إعداد إدخال اختياري لكل نمط، ويقتصر حاليًا على الصور.                                      |
| `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` عندما تكون صفوف البيان بذورًا أو إضافات مفيدة قابلة للإدراج، لكن يمكن لعملية تحديث/ذاكرة تخزين مؤقت إضافة المزيد من الصفوف لاحقًا؛ ولا تكون الصفوف القابلة للتحديث مرجعية بمفردها. استخدم `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 الأساسي.

تُستبعد Plugins المزوّدين الخارجية رسميًا من توزيعة النواة، ولذلك تظل بياناتها غير مرئية حتى تثبيتها. يجب أيضًا نسخ `providerEndpoints` الخاصة بها في `scripts/lib/official-external-provider-catalog.json` حتى يستمر تصنيف نقاط النهاية في العمل دون الـ Plugin؛ ويفرض اختبار عقد هذا التطابق.

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

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

## مرجع providerRequest

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

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

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

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

## مرجع secretProviderIntegrations

استخدم `secretProviderIntegrations` عندما يتمكن Plugin من نشر إعداد مسبق قابل لإعادة الاستخدام لمزوّد تنفيذ SecretRef. يقرأ OpenClaw بيانات التعريف هذه قبل تحميل وقت تشغيل Plugin، ويخزّن ملكية Plugin في `secrets.providers.<alias>.pluginIntegration`، ويترك الحل الفعلي للأسرار لوقت تشغيل SecretRef. لا تُعرض الإعدادات المسبقة إلا لإضافات Plugins المضمّنة وإضافات Plugins المثبّتة والمكتشفة من جذور تثبيت Plugins المُدارة، مثل عمليات التثبيت من git وClawHub.

```json
{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}
```

مفتاح الخريطة هو معرّف التكامل. إذا حُذف `providerAlias`، يستخدم OpenClaw معرّف التكامل اسمًا مستعارًا لمزوّد SecretRef. يجب أن تتطابق الأسماء المستعارة للمزوّدين مع نمط الاسم المستعار المعتاد لمزوّد SecretRef، مثل `team-secrets` أو `onepassword-work`.

عندما يختار المشغّل الإعداد المسبق، يكتب OpenClaw مرجع مزوّد مثل:

```json
{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}
```

عند بدء التشغيل أو إعادة التحميل، يحلّ OpenClaw هذا المزوّد عبر تحميل بيانات تعريف بيان Plugin الحالية، والتحقق من أن Plugin المالك مثبّت ونشط، وإنشاء أمر التنفيذ من البيان. يؤدي تعطيل Plugin أو إزالته إلى إبطال المزوّد لمراجع SecretRefs النشطة. ولا يزال بإمكان المشغّلين الذين يريدون إعداد تنفيذ مستقل كتابة مزوّدات `command`/`args` اليدوية مباشرةً.

لا تُدعم حاليًا سوى الإعدادات المسبقة ذات `source: "exec"`. يجب أن تكون قيمة `command` هي `${node}`، ويجب أن تكون `args[0]` نصًا برمجيًا للحل يبدأ بـ `./` ويكون مساره نسبيًا إلى جذر Plugin. ينشئه OpenClaw عند بدء التشغيل أو إعادة التحميل باستخدام ملف Node التنفيذي الحالي والمسار المطلق للنص البرمجي داخل Plugin. خيارات Node مثل `--require` و`--import` و`--loader` و`--env-file` و`--eval` و`--print` ليست جزءًا من عقد الإعداد المسبق للبيان. ويمكن للمشغّلين الذين يحتاجون إلى أوامر غير Node إعداد مزوّدات تنفيذ يدوية مستقلة مباشرةً.

يشتق OpenClaw قيمة `trustedDirs` للإعدادات المسبقة للبيان من جذر Plugin، وبالنسبة إلى إعدادات `${node}` المسبقة، من دليل ملف Node التنفيذي الحالي. تُتجاهل قيم `trustedDirs` المؤلّفة داخل البيان. تمر خيارات مزوّد التنفيذ الأخرى، مثل `timeoutMs` و`noOutputTimeoutMs` و`maxOutputBytes` و`jsonOnly` و`env` و`passEnv` و`allowInsecurePath`، إلى إعداد مزوّد تنفيذ SecretRef المعتاد.

## مرجع 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. تظل بيانات Plugins هي المرجع المعتمد لإضافات Plugins المثبّتة. يمثّل فهرس المزوّدين عقد الرجوع الداخلي الذي ستستهلكه مستقبلًا واجهات المزوّدين القابلين للتثبيت ومنتقي النماذج قبل التثبيت عندما لا يكون Plugin الخاص بالمزوّد مثبّتًا.

ترتيب مرجعية الكتالوج:

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

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

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

ينقل `openclaw doctor --fix` مجموعة صغيرة ومغلقة من مفاتيح إمكانات البيان العليا القديمة إلى `contracts.*`: وهي `speechProviders` و`mediaUnderstandingProviders` و`imageGenerationProviders` و`tools`. لم يعد أي من هذه المفاتيح، ولا أي قائمة إمكانات أخرى، يُقرأ كحقل علوي في البيان؛ ولا يتعرّف تحميل البيان المعتاد عليها إلا ضمن `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`                                                         | بيانات وصفية خفيفة لأداة فحص حالة الإعداد يمكنها الإجابة عن السؤال «هل يوجد بالفعل إعداد يعتمد على متغيرات البيئة فقط؟» من دون تحميل وقت تشغيل القناة الكامل.                                         |
| `openclaw.channel.persistedAuthState`                                                      | بيانات وصفية خفيفة لأداة فحص المصادقة المحفوظة يمكنها الإجابة عن السؤال «هل سُجّل الدخول إلى أي شيء بالفعل؟» من دون تحميل وقت تشغيل القناة الكامل.                                               |
| `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث لملحقات Plugin المضمّنة والمنشورة خارجيًا.                                                                                                                   |
| `openclaw.install.defaultChoice`                                                           | مسار التثبيت المفضّل عند توفر عدة مصادر للتثبيت.                                                                                                                  |
| `openclaw.install.minHostVersion`                                                          | أدنى إصدار مضيف مدعوم من OpenClaw، باستخدام حد أدنى وفق الإصدار الدلالي مثل `>=2026.3.22` أو `>=2026.5.1-beta.1`.                                                                             |
| `openclaw.compat.pluginApi`                                                                | أدنى نطاق مطلوب لواجهة برمجة تطبيقات Plugin في OpenClaw لهذه الحزمة، باستخدام حد أدنى وفق الإصدار الدلالي مثل `>=2026.5.27`.                                                                                 |
| `openclaw.install.expectedIntegrity`                                                       | سلسلة تكامل توزيعة npm المتوقعة مثل `sha512-...`؛ تتحقق مسارات التثبيت والتحديث من العنصر المُجلَب بمقارنتها بها.                                                            |
| `openclaw.install.allowInvalidConfigRecovery`                                              | يسمح بمسار ضيق لاسترداد إعادة تثبيت Plugin مضمّن عندما يكون الإعداد غير صالح.                                                                                                       |
| `openclaw.install.requiredPlatformPackages`                                                | أسماء بديلة لحزم npm يجب أن تصبح متاحة عندما تطابق قيود المنصة في ملف القفل المضيف الحالي.                                                                           |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`                          | يتيح تحميل واجهات قناة وقت تشغيل الإعداد قبل بدء الاستماع، ثم يؤجل Plugin القناة المُعدّ بالكامل حتى التنشيط بعد بدء الاستماع.                                                 |

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

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

يُستخدم `openclaw.install.requiredPlatformPackages` لحزم npm التي توفر ملفات ثنائية أصلية مطلوبة من خلال أسماء بديلة اختيارية خاصة بالمنصة. أدرج اسم حزمة npm المجرّد لكل اسم بديل لمنصة مدعومة. أثناء تثبيت npm، يتحقق OpenClaw فقط من الاسم البديل المعلن الذي تطابق قيود ملف القفل الخاصة به المضيف الحالي. إذا أبلغ npm عن النجاح لكنه أغفل ذلك الاسم البديل، يعيد OpenClaw المحاولة مرة واحدة باستخدام ذاكرة تخزين مؤقت جديدة، ويتراجع عن التثبيت إذا ظل الاسم البديل مفقودًا.

يُفرض `openclaw.compat.pluginApi` أثناء تثبيت الحزم لمصادر Plugin غير المضمّنة. استخدمه لتحديد الحد الأدنى لواجهة برمجة تطبيقات SDK/وقت تشغيل Plugin في OpenClaw التي بُنيت الحزمة وفقها. يمكن أن يكون أكثر صرامة من `minHostVersion` عندما تحتاج حزمة Plugin إلى واجهة برمجة تطبيقات أحدث مع احتفاظها بتلميح تثبيت أدنى لمسارات أخرى. ترفع مزامنة إصدارات OpenClaw الرسمية افتراضيًا الحدود الدنيا الحالية لواجهات برمجة تطبيقات Plugin الرسمية إلى إصدار OpenClaw، لكن الإصدارات الخاصة بملحقات Plugin وحدها يمكنها الاحتفاظ بحد أدنى أقل عندما تدعم الحزمة عمدًا مضيفات أقدم. لا تستخدم إصدار الحزمة وحده بوصفه عقد التوافق. تظل `peerDependencies.openclaw` بيانات وصفية لحزمة npm؛ ويستخدم OpenClaw عقد `openclaw.compat.pluginApi` لاتخاذ قرارات توافق التثبيت.

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

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

يجب أن توفر ملحقات Plugin الخاصة بالقنوات `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"
      }
    }
  }
}
```

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

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

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

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

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

يكتشف OpenClaw ملحقات Plugin من ثلاثة جذور، تُفحص بهذا الترتيب: ملحقات Plugin المضمّنة التي تأتي مع OpenClaw، وجذر التثبيت العام (`~/.openclaw/extensions`)، وجذر مساحة العمل الحالية (`<workspace>/.openclaw/extensions`)، بالإضافة إلى أي إدخالات صريحة في `plugins.load.paths`.

إذا تشارك اكتشافان في `id` نفسه، فلا يُحتفظ إلا بالبيان ذي **الأسبقية الأعلى**؛ وتُسقط النسخ المكررة ذات الأسبقية الأدنى بدلًا من تحميلها بجانبه. ترتيب الأسبقية، من الأعلى إلى الأدنى:

1. **محدد عبر الإعداد** — مسار مثبّت صراحةً في `plugins.entries.<id>`
2. **تثبيت عام يطابق سجل تثبيت متتبَّعًا** — Plugin مثبّت عبر `openclaw plugin install`/`openclaw plugin update` يتعرّف عليه تتبع التثبيت في OpenClaw للمعرّف نفسه، حتى عندما يكون المعرّف تابعًا أيضًا لـ Plugin مضمّن
3. **مضمّن** — ملحقات Plugin التي تأتي مع OpenClaw
4. **مساحة العمل** — ملحقات Plugin المكتشفة نسبةً إلى مساحة العمل الحالية
5. أي مرشح مكتشف آخر

الآثار المترتبة:

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

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

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

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

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

## سلوك التحقق من الصحة

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

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

## ملاحظات

- البيان **مطلوب لPlugins الأصلية في OpenClaw**، بما في ذلك التحميل من نظام الملفات المحلي. لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالبيان مخصص للاكتشاف والتحقق من الصحة فقط.
- تُحلّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير الموضوعة بين علامتي اقتباس، ما دامت القيمة النهائية كائنًا.
- لا يقرأ محمّل البيان سوى حقول البيان الموثقة. تجنّب المفاتيح المخصصة في المستوى الأعلى.
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` جميعها عندما لا يحتاج إليها Plugin.
- يجب أن يظل `providerCatalogEntry` خفيفًا وألا يستورد شيفرة واسعة لوقت التشغيل؛ استخدمه لبيانات تعريف كتالوج المزوّد الثابتة أو واصفات الاكتشاف محدودة النطاق، وليس للتنفيذ وقت الطلب.
- تُحدّد أنواع Plugins الحصرية عبر `plugins.slots.*`: النوع `kind: "memory"` عبر `plugins.slots.memory` (الافتراضي `memory-core`)، والنوع `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 يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح الخاصة بمدير الحزم (على سبيل المثال، `allow-build-scripts` في pnpm مع `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>