Plugins

بيان Plugin

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

للاطلاع على تخطيطات الحِزم المتوافقة، راجع حِزم Plugin.

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

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

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

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

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

راجع دليل نظام Plugin الكامل: Plugins. لنموذج الإمكانات الأصلي وإرشادات التوافق الخارجي الحالية: نموذج الإمكانات.

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

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

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

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

لا تستخدمه من أجل: تسجيل سلوك وقت التشغيل، أو إعلان نقاط دخول الكود، أو بيانات تثبيت npm. هذه تنتمي إلى كود Plugin الخاص بك وpackage.json.

مثال أدنى

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

مثال غني

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

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

الحقل	مطلوب	النوع	ما يعنيه
`id`	نعم	`string`	معرّف Plugin القانوني. هذا هو المعرّف المستخدم في `plugins.entries.<id>`.
`configSchema`	نعم	`object`	مخطط JSON مضمّن لإعدادات هذا الـ Plugin.
`enabledByDefault`	لا	`true`	يضع علامة على Plugin مضمّن بأنه مفعّل افتراضيًا. احذفه، أو اضبط أي قيمة غير `true`، لإبقاء الـ Plugin معطّلًا افتراضيًا.
`enabledByDefaultOnPlatforms`	لا	`string[]`	يضع علامة على Plugin مضمّن بأنه مفعّل افتراضيًا على منصات Node.js المدرجة فقط، مثل `["darwin"]`. تظل الإعدادات الصريحة هي صاحبة الأولوية.
`legacyPluginIds`	لا	`string[]`	معرّفات قديمة تُطبّع إلى معرّف Plugin القانوني هذا.
`autoEnableWhenConfiguredProviders`	لا	`string[]`	معرّفات المزوّدين التي ينبغي أن تفعّل هذا الـ Plugin تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النماذج.
`kind`	لا	`"memory"` \| `"context-engine"`	يعلن نوع Plugin حصريًا مستخدمًا بواسطة `plugins.slots.*`.
`channels`	لا	`string[]`	معرّفات القنوات المملوكة لهذا الـ Plugin. تُستخدم للاكتشاف والتحقق من الإعدادات.
`providers`	لا	`string[]`	معرّفات المزوّدين المملوكة لهذا الـ Plugin.
`providerDiscoveryEntry`	لا	`string`	مسار وحدة خفيف لاكتشاف المزوّد، نسبي إلى جذر الـ Plugin، لبيانات تعريف كتالوج المزوّدين المحصورة في البيان والتي يمكن تحميلها من دون تفعيل وقت تشغيل الـ Plugin الكامل.
`modelSupport`	لا	`object`	اختصار مملوك للبيان لبيانات تعريف عائلة النماذج، يُستخدم لتحميل الـ Plugin تلقائيًا قبل وقت التشغيل.
`modelCatalog`	لا	`object`	بيانات تعريف تعريفية لكتالوج النماذج للمزوّدين المملوكين لهذا الـ Plugin. هذا هو عقد مستوى التحكم للإدراج المستقبلي للقراءة فقط، والتهيئة، ومحددات النماذج، والأسماء البديلة، والكبت من دون تحميل وقت تشغيل الـ Plugin.
`modelPricing`	لا	`object`	سياسة بحث عن الأسعار الخارجية مملوكة للمزوّد. استخدمها لاستثناء المزوّدين المحليين/المستضافين ذاتيًا من كتالوجات الأسعار البعيدة أو ربط مراجع المزوّدين بمعرّفات كتالوج OpenRouter/LiteLLM من دون ترميز معرّفات المزوّدين في النواة.
`modelIdNormalization`	لا	`object`	تنظيف للأسماء البديلة/البادئات لمعرّفات النماذج مملوك للمزوّد، ويجب تشغيله قبل تحميل وقت تشغيل المزوّد.
`providerEndpoints`	لا	`object[]`	بيانات تعريف لنقاط نهاية المضيف/baseUrl مملوكة للبيان لمسارات المزوّد التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل المزوّد.
`providerRequest`	لا	`object`	بيانات تعريف خفيفة لعائلة المزوّد وتوافق الطلبات، تُستخدم بواسطة سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد.
`cliBackends`	لا	`string[]`	معرّفات خلفيات الاستدلال الخاصة بـ CLI والمملوكة لهذا الـ Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع إعدادات صريحة.
`syntheticAuthRefs`	لا	`string[]`	مراجع المزوّد أو خلفية CLI التي ينبغي فحص خطاف المصادقة الاصطناعي المملوك للـ Plugin الخاص بها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل.
`nonSecretAuthMarkers`	لا	`string[]`	قيم مفاتيح API نائبة مملوكة لـ Plugin مضمّن وتمثل حالة اعتماد محلية غير سرية أو OAuth أو محيطة.
`commandAliases`	لا	`object[]`	أسماء أوامر مملوكة لهذا الـ Plugin، وينبغي أن تنتج تشخيصات إعدادات وCLI مدركة للـ Plugin قبل تحميل وقت التشغيل.
`providerAuthEnvVars`	لا	`Record<string, string[]>`	بيانات تعريف متغيرات بيئة توافقية مهملة للبحث عن مصادقة/حالة المزوّد. فضّل `setup.providers[].envVars` للـ Plugins الجديدة؛ لا يزال OpenClaw يقرأ هذا أثناء نافذة الإهمال.
`providerAuthAliases`	لا	`Record<string, string>`	معرّفات مزوّدين ينبغي أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، مثل مزوّد برمجة يشارك مفتاح API الخاص بالمزوّد الأساسي وملفات تعريف المصادقة.
`channelEnvVars`	لا	`Record<string, string[]>`	بيانات تعريف خفيفة لمتغيرات بيئة القناة يستطيع OpenClaw فحصها من دون تحميل كود الـ Plugin. استخدم هذا لإعداد القنوات المدفوع بالبيئة أو أسطح المصادقة التي ينبغي أن تراها مساعدات بدء التشغيل/الإعدادات العامة.
`providerAuthChoices`	لا	`object[]`	بيانات تعريف خفيفة لاختيارات المصادقة لمحددات التهيئة، وحل المزوّد المفضل، وتوصيل أعلام CLI البسيط.
`activation`	لا	`object`	بيانات تعريف خفيفة لمخطط التفعيل لبدء التشغيل، والمزوّد، والأمر، والقناة، والمسار، والتحميل الناتج عن القدرات. بيانات تعريف فقط؛ يظل وقت تشغيل الـ Plugin مالكًا للسلوك الفعلي.
`setup`	لا	`object`	واصفات خفيفة للإعداد/التهيئة تستطيع أسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل الـ Plugin.
`qaRunners`	لا	`object[]`	واصفات خفيفة لمشغلات ضمان الجودة يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin.
`contracts`	لا	`object`	لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات.
`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.
`version`	لا	`string`	إصدار Plugin لأغراض معلوماتية.
`uiHints`	لا	`Record<string, object>`	تسميات واجهة المستخدم والنصوص النائبة وتلميحات الحساسية لحقول الإعدادات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرجع providerAuthChoices

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

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

مرجع commandAliases

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

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

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

مرجع التفعيل

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

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

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

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

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

{
  "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 بدلاً من ذلك. تسميات الأسباب هذه مخصصة لتشخيصات المضيف والاختبارات؛ وينبغي لمؤلفي Plugins الاستمرار في التصريح بالبيانات الوصفية التي تصف الملكية بأفضل شكل.

مرجع مشغلات ضمان الجودة

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

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

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

مرجع الإعداد

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

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

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

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

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

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

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

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

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

مرجع setup.providers

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

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

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

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

حقول الإعداد

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

مرجع uiHints

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

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

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

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

مرجع contracts

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

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

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

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

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

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

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

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

مرجع mediaUnderstandingProviderMetadata

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

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

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

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

مرجع channelConfigs

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

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

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

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

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

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

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

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

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

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

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

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

مرجع modelSupport

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

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

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

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

الحقول:

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

مرجع modelCatalog

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

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

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

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

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

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

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

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

حقول الحجب:

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

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

مرجع modelIdNormalization

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

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

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

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

مرجع providerEndpoints

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

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

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

مرجع providerRequest

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

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

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

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

مرجع modelPricing

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

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

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

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

حقول المصدر:

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

فهرس مزوّدي OpenClaw

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

ترتيب صلاحية الكتالوج:

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

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

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

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

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

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

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

إذا لم تكن متأكدًا من مكان انتماء جزء من البيانات، فاستخدم هذه القاعدة:

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

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

تعيش بعض بيانات Plugin قبل وقت التشغيل عمدًا في package.json تحت كتلة openclaw بدلًا من openclaw.plugin.json. ليست openclaw.bundle وopenclaw.bundle.json عقود Plugin في OpenClaw؛ يجب على plugins الأصلية استخدام openclaw.plugin.json بالإضافة إلى حقول package.json#openclaw المدعومة أدناه.

أمثلة مهمة:

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

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

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

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

تثبيت إصدار npm الدقيق موجود بالفعل في npmSpec، على سبيل المثال "npmSpec": "@wecom/[email protected]". يجب أن تقرن إدخالات الفهرس الخارجية الرسمية المواصفات الدقيقة مع expectedIntegrity حتى تفشل تدفقات التحديث بإغلاق آمن إذا لم يعد أثر npm الذي تم جلبه يطابق الإصدار المثبت. ما زالت التهيئة التفاعلية تعرض مواصفات npm من السجل الموثوق، بما في ذلك أسماء الحزم المجردة ووسوم التوزيع، من أجل التوافق. يمكن لتشخيصات الفهرس تمييز المصادر الدقيقة، والعائمة، والمثبتة بالتكامل، وناقصة التكامل، وغير المتطابقة في اسم الحزمة، وذات الاختيار الافتراضي غير الصالح. كما تحذر عندما يكون expectedIntegrity موجودًا لكن لا يوجد مصدر npm صالح يمكنه تثبيته. عند وجود expectedIntegrity، تفرضه تدفقات التثبيت/التحديث؛ وعند حذفه، يُسجل حل السجل دون تثبيت تكامل.

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

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

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

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

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

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

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

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

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

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

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

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

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

الآثار:

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

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

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

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

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

سلوك التحقق

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

راجع مرجع الإعدادات للاطلاع على مخطط plugins.* الكامل.

ملاحظات

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

بيان Plugin

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

مثال أدنى

مثال غني

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

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

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

مرجع providerAuthChoices

مرجع commandAliases

مرجع التفعيل

مرجع مشغلات ضمان الجودة

مرجع الإعداد

مرجع setup.providers

حقول الإعداد

مرجع uiHints

مرجع contracts

مرجع mediaUnderstandingProviderMetadata

مرجع channelConfigs

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

مرجع modelSupport

مرجع modelCatalog

مرجع modelIdNormalization

مرجع providerEndpoints

مرجع providerRequest

مرجع modelPricing

فهرس مزوّدي OpenClaw

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

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

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

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

سلوك التحقق

ملاحظات

ذات صلة

Ask OpenClaw

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

# مثال أدنى

# مثال غني

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

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

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

# مرجع providerAuthChoices

# مرجع commandAliases

# مرجع التفعيل

# مرجع مشغلات ضمان الجودة

# مرجع الإعداد

# مرجع setup.providers

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

# مرجع uiHints

# مرجع contracts

# مرجع mediaUnderstandingProviderMetadata

# مرجع channelConfigs

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

# مرجع modelSupport

# مرجع modelCatalog

# مرجع modelIdNormalization

# مرجع providerEndpoints

# مرجع providerRequest

# مرجع modelPricing

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

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

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

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

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

# سلوك التحقق

# ملاحظات

# ذات صلة

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

مثال أدنى

مثال غني

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

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

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

مرجع providerAuthChoices

مرجع commandAliases

مرجع التفعيل

مرجع مشغلات ضمان الجودة

مرجع الإعداد

مرجع setup.providers

حقول الإعداد

مرجع uiHints

مرجع contracts

مرجع mediaUnderstandingProviderMetadata

مرجع channelConfigs

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

مرجع modelSupport

مرجع modelCatalog

مرجع modelIdNormalization

مرجع providerEndpoints

مرجع providerRequest

مرجع modelPricing

فهرس مزوّدي OpenClaw

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

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

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

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

سلوك التحقق

ملاحظات

ذات صلة