--- read_when: - أنت تبني Plugin لـ OpenClaw - تحتاج إلى إصدار مخطط تهيئة Plugin أو تصحيح أخطاء التحقق من Plugin summary: متطلبات بيان Plugin + مخطط JSON (التحقق الصارم من صحة التكوين) title: بيان Plugin x-i18n: generated_at: "2026-05-10T19:50:53Z" model: gpt-5.5 provider: openai source_hash: 27129a118083d41fc631282cbef37b1b8e36c31343026bd9def5d521ff7fddef source_path: plugins/manifest.md workflow: 16 --- هذه الصفحة مخصّصة فقط لملف بيان Plugin الأصلي في OpenClaw. للاطلاع على تخطيطات الحِزم المتوافقة، راجع [حِزم Plugin](/ar/plugins/bundles). تستخدم تنسيقات الحِزم المتوافقة ملفات بيان مختلفة: - حزمة Codex: `.codex-plugin/plugin.json` - حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي بدون بيان - حزمة Cursor: `.cursor-plugin/plugin.json` يكتشف OpenClaw تخطيطات الحِزم هذه تلقائياً أيضاً، لكنها لا تُتحقَّق منها وفق مخطط `openclaw.plugin.json` الموضّح هنا. بالنسبة إلى الحِزم المتوافقة، يقرأ OpenClaw حالياً بيانات تعريف الحزمة إضافةً إلى جذور Skills المعلنة، وجذور أوامر Claude، وافتراضات `settings.json` لحزمة Claude، وافتراضات LSP لحزمة Claude، وحِزم الخطافات المدعومة عندما يطابق التخطيط توقعات وقت تشغيل OpenClaw. يجب أن يوفّر كل Plugin أصلي في OpenClaw ملف `openclaw.plugin.json` في **جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من الإعدادات **بدون تنفيذ كود Plugin**. تُعامل البيانات المفقودة أو غير الصالحة على أنها أخطاء في Plugin وتمنع التحقق من الإعدادات. راجع الدليل الكامل لنظام Plugin: [Plugins](/ar/tools/plugin). لنموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية: [نموذج القدرات](/ar/plugins/architecture#public-capability-model). ## ما الذي يفعله هذا الملف `openclaw.plugin.json` هو بيانات التعريف التي يقرؤها OpenClaw **قبل تحميل كود Plugin الخاص بك**. يجب أن يكون كل ما يلي خفيفاً بما يكفي لفحصه بدون تشغيل وقت تشغيل Plugin. **استخدمه من أجل:** - هوية Plugin، والتحقق من الإعدادات، وتلميحات واجهة إعدادات المستخدم - بيانات تعريف المصادقة، والتهيئة الأولية، والإعداد (الاسم البديل، والتفعيل التلقائي، ومتغيرات بيئة المزوّد، وخيارات المصادقة) - تلميحات التفعيل لأسطح مستوى التحكم - ملكية مختصرة لعائلة النماذج - لقطات ثابتة لملكية القدرات (`contracts`) - بيانات تعريف مشغّل QA التي يمكن لمضيف `openclaw qa` المشترك فحصها - بيانات تعريف إعدادات خاصة بالقناة تُدمَج في أسطح الفهرس والتحقق **لا تستخدمه من أجل:** تسجيل سلوك وقت التشغيل، أو إعلان نقاط دخول الكود، أو بيانات تعريف تثبيت npm. هذه تنتمي إلى كود Plugin و`package.json`. ## مثال أدنى ```json { "id": "voice-call", "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } } ``` ## مثال غني ```json { "id": "openrouter", "name": "OpenRouter", "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { "modelPrefixes": ["router-"] }, "modelIdNormalization": { "providers": { "openrouter": { "prefixWhenBare": "openrouter" } } }, "providerEndpoints": [ { "endpointClass": "openrouter", "hostSuffixes": ["openrouter.ai"] } ], "providerRequest": { "providers": { "openrouter": { "family": "openrouter" } } }, "cliBackends": ["openrouter-cli"], "syntheticAuthRefs": ["openrouter-cli"], "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, "providerAuthAliases": { "openrouter-coding": "openrouter" }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, "providerAuthChoices": [ { "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", "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.`. | | `configSchema` | نعم | `object` | JSON Schema مضمنة لإعدادات هذا الـ 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. | | `providerCatalogEntry` | لا | `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` | بيانات تعريفية قديمة للتوافق لمتغيرات البيئة الخاصة بمصادقة/حالة المزوّد. فضّل `setup.providers[].envVars` للـ Plugins الجديدة؛ لا يزال OpenClaw يقرأ هذا أثناء نافذة الإهمال. | | `providerAuthAliases` | لا | `Record` | معرّفات المزوّدين التي ينبغي أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، مثل مزوّد برمجة يشارك مفتاح API وملفات تعريف المصادقة الخاصة بالمزوّد الأساسي. | | `channelEnvVars` | لا | `Record` | بيانات تعريفية خفيفة لمتغيرات بيئة القناة يمكن أن يفحصها OpenClaw من دون تحميل كود الـ Plugin. استخدم هذا لإعداد القنوات المدفوع بمتغيرات البيئة أو أسطح المصادقة التي ينبغي أن تراها مساعدات بدء التشغيل/الإعدادات العامة. | | `providerAuthChoices` | لا | `object[]` | بيانات تعريفية خفيفة لاختيارات المصادقة لمنتقيات الإعداد الأولي، وحلّ المزوّد المفضّل، وتوصيل أعلام CLI البسيط. | | `activation` | لا | `object` | بيانات تعريفية خفيفة لمخطط التفعيل لبدء التشغيل، والمزوّدين، والأوامر، والقنوات، والمسارات، والتحميل المشغّل بالقدرات. بيانات تعريفية فقط؛ يظل وقت تشغيل الـ Plugin مالكًا للسلوك الفعلي. | | `setup` | لا | `object` | واصفات إعداد/إعداد أولي خفيفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل الـ Plugin. | | `qaRunners` | لا | `object[]` | واصفات خفيفة لمشغلات QA يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin. | | `contracts` | لا | `object` | لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات. | | `mediaUnderstandingProviderMetadata` | لا | `Record` | افتراضيات خفيفة لفهم الوسائط لمعرّفات المزوّدين المصرّح بها في `contracts.mediaUnderstandingProviders`. | | `imageGenerationProviderMetadata` | لا | `Record` | بيانات تعريفية خفيفة لمصادقة توليد الصور لمعرّفات المزوّدين المصرّح بها في `contracts.imageGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي. | | `videoGenerationProviderMetadata` | لا | `Record` | بيانات تعريفية خفيفة لمصادقة توليد الفيديو لمعرّفات المزوّدين المصرّح بها في `contracts.videoGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي. | | `musicGenerationProviderMetadata` | لا | `Record` | بيانات تعريفية خفيفة لمصادقة توليد الموسيقى لمعرّفات المزوّدين المصرّح بها في `contracts.musicGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي. | | `toolMetadata` | لا | `Record` | بيانات تعريفية خفيفة للتوافر للأدوات المملوكة للـ Plugin والمصرّح بها في `contracts.tools`. استخدمها عندما لا ينبغي للأداة تحميل وقت التشغيل إلا إذا وُجدت أدلة من الإعدادات أو البيئة أو المصادقة. | | `channelConfigs` | لا | `Record` | بيانات تعريفية لإعدادات القناة يملكها البيان وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. | | `skills` | لا | `string[]` | أدلة Skills المراد تحميلها، نسبيًا إلى جذر الـ Plugin. | | `name` | لا | `string` | اسم Plugin قابل للقراءة البشرية. | | `description` | لا | `string` | ملخص قصير يُعرض في واجهات Plugin. | | `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. | | `uiHints` | لا | `Record` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول التكوين. | ## مرجع بيانات تعريف مزوّدات التوليد تصف حقول بيانات تعريف مزوّدات التوليد إشارات المصادقة الثابتة للمزوّدات المعلنة في قائمة `contracts.*GenerationProviders` المطابقة. يقرأ OpenClaw هذه الحقول قبل تحميل وقت تشغيل المزوّد حتى تتمكن أدوات النواة من تحديد ما إذا كان مزوّد التوليد متاحًا دون استيراد كل Plugin مزوّد. استخدم هذه الحقول فقط للحقائق التصريحية منخفضة التكلفة. تبقى آليات النقل، وتحويلات الطلبات، وتحديث الرموز، والتحقق من بيانات الاعتماد، وسلوك التوليد الفعلي في وقت تشغيل Plugin. ```json { "contracts": { "imageGenerationProviders": ["example-image"] }, "imageGenerationProviderMetadata": { "example-image": { "aliases": ["example-image-oauth"], "authProviders": ["example-image"], "configSignals": [ { "rootPath": "plugins.entries.example-image.config", "overlayPath": "image", "mode": { "path": "mode", "default": "local", "allowed": ["local"] }, "requiredAny": ["workflow", "workflowPath"], "required": ["promptNodeId"] } ], "authSignals": [ { "provider": "example-image" }, { "provider": "example-image-oauth", "providerBaseUrl": { "provider": "example-image", "defaultBaseUrl": "https://api.example.com/v1", "allowedBaseUrls": ["https://api.example.com/v1"] } } ] } } } ``` يدعم كل إدخال بيانات تعريف ما يلي: | الحقل | مطلوب | النوع | ما يعنيه | | --------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `aliases` | لا | `string[]` | معرّفات مزوّد إضافية يجب اعتبارها أسماء مستعارة ثابتة للمصادقة لمزوّد التوليد. | | `authProviders` | لا | `string[]` | معرّفات المزوّدات التي يجب اعتبار ملفات تعريف المصادقة المكوّنة لها مصادقةً لمزوّد التوليد هذا. | | `configSignals` | لا | `object[]` | إشارات إتاحة منخفضة التكلفة ومعتمدة على الإعدادات فقط للمزوّدات المحلية أو ذاتية الاستضافة التي يمكن تكوينها دون ملفات تعريف مصادقة أو متغيرات بيئة. | | `authSignals` | لا | `object[]` | إشارات مصادقة صريحة. عند وجودها، تستبدل مجموعة الإشارات الافتراضية من معرّف المزوّد و`aliases` و`authProviders`. | يدعم كل إدخال `configSignals` ما يلي: | الحقل | مطلوب | النوع | ما يعنيه | | ------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rootPath` | نعم | `string` | مسار بالنقاط إلى كائن الإعدادات المملوك لـ Plugin لفحصه، على سبيل المثال `plugins.entries.example.config`. | | `overlayPath` | لا | `string` | مسار بالنقاط داخل إعدادات الجذر إلى الكائن الذي يجب أن يركّب فوق كائن الجذر قبل تقييم الإشارة. استخدم هذا للإعدادات الخاصة بالإمكانات مثل `image` أو `video` أو `music`. | | `required` | لا | `string[]` | مسارات بالنقاط داخل الإعدادات الفعالة يجب أن تحتوي على قيم مكوّنة. يجب أن تكون السلاسل غير فارغة؛ ويجب ألا تكون الكائنات والمصفوفات فارغة. | | `requiredAny` | لا | `string[]` | مسارات بالنقاط داخل الإعدادات الفعالة حيث يجب أن يحتوي واحد منها على الأقل على قيمة مكوّنة. | | `mode` | لا | `object` | حارس وضع نصي اختياري داخل الإعدادات الفعالة. استخدم هذا عندما تنطبق الإتاحة المعتمدة على الإعدادات فقط على وضع واحد. | يدعم كل حارس `mode` ما يلي: | الحقل | مطلوب | النوع | ما يعنيه | | ------------ | -------- | ---------- | ---------------------------------------------------------------------------------- | | `path` | لا | `string` | مسار بالنقاط داخل الإعدادات الفعالة. تكون القيمة الافتراضية `mode`. | | `default` | لا | `string` | قيمة الوضع التي تُستخدم عندما تحذف الإعدادات المسار. | | `allowed` | لا | `string[]` | إذا وُجد، تمرّ الإشارة فقط عندما يكون الوضع الفعال واحدًا من هذه القيم. | | `disallowed` | لا | `string[]` | إذا وُجد، تفشل الإشارة عندما يكون الوضع الفعال واحدًا من هذه القيم. | يدعم كل إدخال `authSignals` ما يلي: | الحقل | مطلوب | النوع | ما يعنيه | | ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | نعم | `string` | معرّف المزوّد المطلوب التحقق منه في ملفات تعريف المصادقة المكوّنة. | | `providerBaseUrl` | لا | `object` | حارس اختياري يجعل الإشارة تُحتسب فقط عندما يستخدم المزوّد المكوّن المشار إليه عنوان URL أساسيًا مسموحًا. استخدم هذا عندما يكون اسم مستعار للمصادقة صالحًا فقط لواجهات API معينة. | يدعم كل حارس `providerBaseUrl` ما يلي: | الحقل | مطلوب | النوع | ما يعنيه | | ----------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | نعم | `string` | معرّف إعدادات المزوّد الذي يجب التحقق من `baseUrl` الخاص به. | | `defaultBaseUrl` | لا | `string` | عنوان URL الأساسي الذي يُفترض عندما تحذف إعدادات المزوّد `baseUrl`. | | `allowedBaseUrls` | نعم | `string[]` | عناوين URL الأساسية المسموح بها لإشارة المصادقة هذه. تُتجاهل الإشارة عندما لا يطابق عنوان URL الأساسي المكوّن أو الافتراضي إحدى هذه القيم المعيّرة. | ## مرجع بيانات تعريف الأدوات تستخدم `toolMetadata` الأشكال نفسها لـ `configSignals` و`authSignals` مثل بيانات تعريف مزوّدات التوليد، مع الفهرسة باسم الأداة. تعلن `contracts.tools` الملكية. تعلن `toolMetadata` دليل إتاحة منخفض التكلفة حتى يتمكن OpenClaw من تجنب استيراد وقت تشغيل Plugin لمجرد أن يعيد مصنع الأدوات الخاص به `null`. ```json { "providerAuthEnvVars": { "example": ["EXAMPLE_API_KEY"] }, "contracts": { "tools": ["example_search"] }, "toolMetadata": { "example_search": { "authSignals": [ { "provider": "example" } ], "configSignals": [ { "rootPath": "plugins.entries.example.config", "overlayPath": "search", "required": ["apiKey"] } ] } } } ``` إذا لم تكن للأداة `toolMetadata`، يحافظ OpenClaw على السلوك الحالي ويحمّل Plugin المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن التي يعتمد مصنعها على المصادقة/الإعدادات، يجب على مؤلفي Plugins إعلان `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 `. | | `cliDescription` | لا | `string` | الوصف المستخدم في مساعدة CLI. | | `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح التهيئة التي يجب أن يظهر فيها هذا الخيار. إذا حُذف، تكون قيمته الافتراضية `["text-inference"]`. | ## مرجع commandAliases استخدم `commandAliases` عندما يمتلك Plugin اسم أمر وقت تشغيل قد يضعه المستخدمون عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw هذه البيانات الوصفية للتشخيصات دون استيراد كود وقت تشغيل Plugin. ```json { "commandAliases": [ { "name": "dreaming", "kind": "runtime-slash", "cliCommand": "memory" } ] } ``` | الحقل | مطلوب | النوع | ما يعنيه | | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. | | `kind` | لا | `"runtime-slash"` | يحدد الاسم المستعار كأمر شرطة مائلة في الدردشة بدلا من أمر CLI جذري. | | `cliCommand` | لا | `string` | أمر CLI الجذري المرتبط لاقتراحه لعمليات CLI، إن وجد. | ## مرجع activation استخدم `activation` عندما يستطيع Plugin التصريح بتكلفة منخفضة عن أحداث مستوى التحكم التي ينبغي أن تضمه إلى خطة تفعيل/تحميل. هذه الكتلة بيانات وصفية للمخطط، وليست واجهة API لدورة الحياة. لا تسجل سلوك وقت التشغيل، ولا تستبدل `register(...)`، ولا تعد بأن كود Plugin قد تم تنفيذه بالفعل. يستخدم مخطط التفعيل هذه الحقول لتضييق Plugins المرشحة قبل الرجوع إلى بيانات ملكية البيان الحالية مثل `providers` و`channels` و`commandAliases` و`setup.providers` و`contracts.tools` والخطافات. فضّل أضيق بيانات وصفية تصف الملكية بالفعل. استخدم `providers` أو `channels` أو `commandAliases` أو واصفات الإعداد أو `contracts` عندما تعبر تلك الحقول عن العلاقة. استخدم `activation` لتلميحات مخطط إضافية لا يمكن تمثيلها بواسطة حقول الملكية تلك. استخدم `cliBackends` في المستوى الأعلى للأسماء المستعارة لوقت تشغيل CLI مثل `claude-cli` أو `codex-cli` أو `google-gemini-cli`؛ أما `activation.onAgentHarnesses` فهو مخصص فقط لمعرفات حاضنات الوكلاء المضمنة التي لا تملك حقل ملكية بالفعل. هذه الكتلة بيانات وصفية فقط. لا تسجل سلوك وقت التشغيل، ولا تستبدل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى. يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugins على نطاق أوسع، لذلك عادة لا يكلف غياب بيانات وصفية لتفعيل غير بدء التشغيل سوى الأداء؛ ولا ينبغي أن يغير الصحة ما دامت بدائل ملكية البيان الاحتياطية موجودة. ينبغي لكل 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` بدلا من ذلك. تسميات الأسباب هذه مخصصة لتشخيصات المضيف والاختبارات؛ ينبغي لمؤلفي Plugins الاستمرار في التصريح بالبيانات الوصفية التي تصف الملكية بأفضل شكل. ## مرجع qaRunners استخدم `qaRunners` عندما يساهم Plugin بواحد أو أكثر من مشغلات النقل تحت الجذر المشترك `openclaw qa`. أبق هذه البيانات الوصفية منخفضة التكلفة وثابتة؛ فما يزال وقت تشغيل Plugin يمتلك تسجيل CLI الفعلي عبر سطح خفيف `runtime-api.ts` يصدر `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } ``` | الحقل | مطلوب | النوع | ما يعنيه | | ------------- | -------- | -------- | ------------------------------------------------------------------ | | `commandName` | نعم | `string` | الأمر الفرعي المثبت تحت `openclaw qa`، على سبيل المثال `matrix`. | | `description` | لا | `string` | نص مساعدة احتياطي يستخدم عندما يحتاج المضيف المشترك إلى أمر بديل. | ## مرجع setup استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات وصفية منخفضة التكلفة مملوكة لـ Plugin قبل تحميل وقت التشغيل. ```json { "setup": { "providers": [ { "id": "openai", "authMethods": ["api-key"], "envVars": ["OPENAI_API_KEY"], "authEvidence": [ { "type": "local-file-with-env", "fileEnvVar": "OPENAI_CREDENTIALS_FILE", "requiresAllEnv": ["OPENAI_PROJECT"], "credentialMarker": "openai-local-credentials", "source": "openai local credentials" } ] } ], "cliBackends": ["openai-cli"], "configMigrations": ["legacy-openai-auth"], "requiresRuntime": false } } ``` يبقى `cliBackends` في المستوى الأعلى صالحا ويستمر في وصف خلفيات استدلال CLI. أما `setup.cliBackends` فهو سطح الواصف الخاص بالإعداد لتدفقات مستوى التحكم/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط. عند وجود `setup.providers` و`setup.cliBackends`، يكونان سطح البحث المفضل الذي يبدأ بالواصفات لاكتشاف الإعداد. إذا كان الواصف يضيق فقط Plugin المرشح وما زال الإعداد يحتاج إلى خطافات وقت إعداد أكثر ثراء، فاضبط `requiresRuntime: true` وأبق `setup-api` في مكانه باعتباره مسار التنفيذ الاحتياطي. يتضمن OpenClaw أيضا `setup.providers[].envVars` في عمليات البحث العامة عن مصادقة المزوّد ومتغيرات البيئة. يظل `providerAuthEnvVars` مدعوما عبر محول توافق أثناء نافذة الإهمال، لكن Plugins غير المضمنة التي ما زالت تستخدمه تتلقى تشخيص بيان. ينبغي أن تضع Plugins الجديدة بيانات تعريف بيئة الإعداد/الحالة على `setup.providers[].envVars`. يمكن لـ OpenClaw أيضا اشتقاق اختيارات إعداد بسيطة من `setup.providers[].authMethods` عندما لا يكون إدخال إعداد متاحا، أو عندما يصرح `setup.requiresRuntime: false` بأن وقت تشغيل الإعداد غير ضروري. تظل إدخالات `providerAuthChoices` الصريحة مفضلة للتسميات المخصصة، وأعلام CLI، ونطاق التهيئة الأولية، وبيانات المساعد الوصفية. اضبط `requiresRuntime: false` فقط عندما تكون تلك الواصفات كافية لسطح الإعداد. يتعامل OpenClaw مع `false` الصريح كعقد يعتمد على الواصفات فقط ولن ينفذ `setup-api` أو `openclaw.setupEntry` لبحث الإعداد. إذا كان Plugin يعتمد على الواصفات فقط وما زال يشحن أحد إدخالات وقت تشغيل الإعداد تلك، يبلغ OpenClaw عن تشخيص إضافي ويواصل تجاهله. يحافظ حذف `requiresRuntime` على سلوك الرجوع الاحتياطي القديم حتى لا تتعطل Plugins الحالية التي أضافت واصفات دون العلم. نظرا لأن بحث الإعداد يمكنه تنفيذ كود `setup-api` مملوك لـ Plugin، يجب أن تظل قيم `setup.providers[].id` و`setup.cliBackends[]` المعيارية فريدة عبر Plugins المكتشفة. تفشل الملكية الغامضة بشكل مغلق بدلا من اختيار فائز من ترتيب الاكتشاف. عندما ينفذ وقت تشغيل الإعداد، تبلغ تشخيصات سجل الإعداد عن انجراف الواصفات إذا سجل `setup-api` مزودا أو خلفية CLI لا تصرح بها واصفات البيان، أو إذا لم يكن للواصف تسجيل وقت تشغيل مطابق. هذه التشخيصات إضافية ولا ترفض Plugins القديمة. ### مرجع setup.providers | الحقل | مطلوب | النوع | ما يعنيه | | -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ | | `id` | نعم | `string` | معرف المزوّد المعروض أثناء الإعداد أو التهيئة الأولية. أبق المعرفات المعيارية فريدة عالميا. | | `authMethods` | لا | `string[]` | معرفات طريقة الإعداد/المصادقة التي يدعمها هذا المزوّد دون تحميل وقت التشغيل الكامل. | | `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة فحصها قبل تحميل وقت تشغيل Plugin. | | `authEvidence` | لا | `object[]` | فحوصات أدلة مصادقة محلية منخفضة التكلفة للمزوّدين الذين يستطيعون المصادقة عبر علامات غير سرية. | `authEvidence` مخصّص لعلامات الاعتماد المحلية المملوكة للمزوّدين، والتي يمكن التحقق منها دون تحميل كود وقت التشغيل. يجب أن تبقى هذه الفحوصات خفيفة ومحلية: لا استدعاءات شبكة، ولا قراءات من سلسلة المفاتيح أو مدير الأسرار، ولا أوامر shell، ولا استقصاءات API للمزوّد. إدخالات الأدلة المدعومة: | الحقل | مطلوب | النوع | ما يعنيه | | ------------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `type` | نعم | `string` | حاليًا `local-file-with-env`. | | `fileEnvVar` | لا | `string` | متغير بيئة يحتوي على مسار ملف اعتماد صريح. | | `fallbackPaths` | لا | `string[]` | مسارات ملفات اعتماد محلية تُفحص عند غياب `fileEnvVar` أو كونه فارغًا. يدعم `${HOME}` و`${APPDATA}`. | | `requiresAnyEnv` | لا | `string[]` | يجب أن يكون واحد على الأقل من متغيرات البيئة المدرجة غير فارغ قبل أن يكون الدليل صالحًا. | | `requiresAllEnv` | لا | `string[]` | يجب أن يكون كل متغير بيئة مدرج غير فارغ قبل أن يكون الدليل صالحًا. | | `credentialMarker` | نعم | `string` | علامة غير سرية تُعاد عند وجود الدليل. | | `source` | لا | `string` | تسمية مصدر موجهة للمستخدم لمخرجات المصادقة/الحالة. | ### حقول setup | الحقل | مطلوب | النوع | ما يعنيه | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | | `providers` | لا | `object[]` | واصفات إعداد المزوّدين المعروضة أثناء الإعداد والتوجيه الأولي. | | `cliBackends` | لا | `string[]` | معرّفات الخلفيات في وقت الإعداد المستخدمة للبحث عن الإعداد بالواصف أولًا. أبقِ المعرّفات المطبّعة فريدة عالميًا. | | `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات التي يملكها سطح إعداد هذا Plugin. | | `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث بالواصف. | ## مرجع uiHints `uiHints` هو تعيين من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة. ```json { "uiHints": { "apiKey": { "label": "API key", "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } } } ``` يمكن أن يتضمن كل تلميح حقل: | الحقل | النوع | ما يعنيه | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | تسمية الحقل الموجهة للمستخدم. | | `help` | `string` | نص مساعدة قصير. | | `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. | | `advanced` | `boolean` | يعلّم الحقل على أنه متقدم. | | `sensitive` | `boolean` | يعلّم الحقل على أنه سري أو حساس. | | `placeholder` | `string` | نص العنصر النائب لمدخلات النماذج. | ## مرجع contracts استخدم `contracts` فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw قراءتها دون استيراد وقت تشغيل Plugin. ```json { "contracts": { "agentToolResultMiddleware": ["pi", "codex"], "externalAuthProviders": ["acme-ai"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], "realtimeVoiceProviders": ["openai"], "memoryEmbeddingProviders": ["local"], "mediaUnderstandingProviders": ["openai", "openai-codex"], "imageGenerationProviders": ["openai"], "videoGenerationProviders": ["qwen"], "webFetchProviders": ["firecrawl"], "webSearchProviders": ["gemini"], "migrationProviders": ["hermes"], "tools": ["firecrawl_search", "firecrawl_scrape"] } } ``` كل قائمة اختيارية: | الحقل | النوع | ما يعنيه | | -------------------------------- | ---------- | --------------------------------------------------------------------- | | `embeddedExtensionFactories` | `string[]` | معرّفات مصانع امتدادات خادم تطبيقات Codex، حاليًا `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | معرّفات وقت التشغيل التي قد يسجل Plugin مضمّن وسيط نتائج أدوات لها. | | `externalAuthProviders` | `string[]` | معرّفات المزوّدين التي يملك هذا Plugin خطاف ملف تعريف المصادقة الخارجي الخاص بها. | | `speechProviders` | `string[]` | معرّفات مزوّدي الكلام التي يملكها هذا Plugin. | | `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ الفوري التي يملكها هذا Plugin. | | `realtimeVoiceProviders` | `string[]` | معرّفات مزوّدي الصوت الفوري التي يملكها هذا Plugin. | | `memoryEmbeddingProviders` | `string[]` | معرّفات مزوّدي تضمين الذاكرة التي يملكها هذا Plugin. | | `mediaUnderstandingProviders` | `string[]` | معرّفات مزوّدي فهم الوسائط التي يملكها هذا Plugin. | | `imageGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الصور التي يملكها هذا Plugin. | | `videoGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الفيديو التي يملكها هذا Plugin. | | `webFetchProviders` | `string[]` | معرّفات مزوّدي جلب الويب التي يملكها هذا Plugin. | | `webSearchProviders` | `string[]` | معرّفات مزوّدي بحث الويب التي يملكها هذا Plugin. | | `migrationProviders` | `string[]` | معرّفات مزوّدي الاستيراد التي يملكها هذا Plugin لـ `openclaw migrate`. | | `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin. | يُحتفظ بـ `contracts.embeddedExtensionFactories` لمصانع امتدادات خادم تطبيقات Codex المضمّنة فقط. يجب أن تعلن تحويلات نتائج الأدوات المضمّنة `contracts.agentToolResultMiddleware` وأن تسجل باستخدام `api.registerAgentToolResultMiddleware(...)` بدلًا من ذلك. لا يمكن لـ Plugins الخارجية تسجيل وسيط نتائج الأدوات لأن الحد الفاصل يمكنه إعادة كتابة مخرجات الأدوات عالية الثقة قبل أن يراها النموذج. يجب أن تطابق تسجيلات وقت التشغيل `api.registerTool(...)` قيمة `contracts.tools`. يستخدم اكتشاف الأدوات هذه القائمة لتحميل أوقات تشغيل Plugins فقط التي يمكن أن تملك الأدوات المطلوبة. يجب على Plugins المزوّدين التي تنفذ `resolveExternalAuthProfiles` أن تعلن `contracts.externalAuthProviders`. لا تزال Plugins التي لا تحتوي على الإعلان تمر عبر مسار توافق احتياطي مهجور، لكن هذا المسار أبطأ وسيُزال بعد نافذة الترحيل. يجب أن يعلن مزوّدو تضمين الذاكرة المضمّنون `contracts.memoryEmbeddingProviders` لكل معرّف محوّل يعرِضونه، بما في ذلك المحوّلات المدمجة مثل `local`. تستخدم مسارات CLI المستقلة عقد البيان هذا لتحميل Plugin المالك فقط قبل أن يكون وقت تشغيل Gateway الكامل قد سجّل المزوّدين. ## مرجع mediaUnderstandingProviderMetadata استخدم `mediaUnderstandingProviderMetadata` عندما يكون لدى مزوّد فهم وسائط نماذج افتراضية، أو أولوية احتياطية للمصادقة التلقائية، أو دعم مستندات أصلي تحتاج إليه مساعدات النواة العامة قبل تحميل وقت التشغيل. يجب أيضًا إعلان المفاتيح في `contracts.mediaUnderstandingProviders`. ```json { "contracts": { "mediaUnderstandingProviders": ["example"] }, "mediaUnderstandingProviderMetadata": { "example": { "capabilities": ["image", "audio"], "defaultModels": { "image": "example-vision-latest", "audio": "example-transcribe-latest" }, "autoPriority": { "image": 40 }, "nativeDocumentInputs": ["pdf"] } } } ``` يمكن أن يتضمن كل إدخال مزوّد: | الحقل | النوع | ما يعنيه | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | | `capabilities` | `("image" \| "audio" \| "video")[]` | قدرات الوسائط التي يعرِضها هذا المزوّد. | | `defaultModels` | `Record` | افتراضيات القدرة إلى النموذج المستخدمة عندما لا تحدد الإعدادات نموذجًا. | | `autoPriority` | `Record` | الأرقام الأصغر تُرتّب أولًا للاحتياطي التلقائي للمزوّد المستند إلى الاعتمادات. | | `nativeDocumentInputs` | `"pdf"[]` | مدخلات المستندات الأصلية التي يدعمها المزوّد. | ## مرجع channelConfigs استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات تعريف إعدادات خفيفة قبل تحميل وقت التشغيل. يمكن لاكتشاف إعداد/حالة القناة للقراءة فقط استخدام بيانات التعريف هذه مباشرة للقنوات الخارجية المضبوطة عندما لا يتوفر إدخال إعداد، أو عندما يعلن `setup.requiresRuntime: false` أن وقت تشغيل الإعداد غير ضروري. `channelConfigs` هي بيانات تعريف بيان Plugin، وليست قسم إعدادات مستخدم جديدًا من المستوى الأعلى. لا يزال المستخدمون يضبطون نُسخ القنوات ضمن `channels.`. يقرأ OpenClaw بيانات تعريف البيان ليقرر أي Plugin يملك تلك القناة المضبوطة قبل تنفيذ كود وقت تشغيل Plugin. بالنسبة إلى Plugin قناة، يصف `configSchema` و`channelConfigs` مسارين مختلفين: - يتحقق `configSchema` من `plugins.entries..config` - يتحقق `channelConfigs..schema` من `channels.` يجب على Plugins غير المضمّنة التي تعلن `channels[]` أن تعلن أيضًا إدخالات `channelConfigs` المطابقة. بدونها، لا يزال بإمكان OpenClaw تحميل Plugin، لكن مخطط إعدادات المسار البارد، والإعداد، وأسطح Control UI لا يمكنها معرفة شكل الخيار المملوك للقناة حتى ينفذ وقت تشغيل Plugin. يمكن لـ `channelConfigs..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.`. مطلوب لكل إدخال مُعلَن لإعدادات القناة. | | `uiHints` | `Record` | تسميات/عناصر نائبة/تلميحات حساسة اختيارية لواجهة المستخدم لقسم إعدادات تلك القناة. | | `label` | `string` | تسمية القناة التي تُدمج في واجهات الاختيار والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. | | `description` | `string` | وصف قصير للقناة لواجهات الفحص والكتالوج. | | `commands` | `object` | أوامر أصلية ثابتة وافتراضات تلقائية أصلية لـ Skills لفحوصات الإعدادات قبل وقت التشغيل. | | `preferOver` | `string[]` | معرّفات Plugin قديمة أو أقل أولوية يجب أن تتقدم عليها هذه القناة في واجهات الاختيار. | ### استبدال Plugin قناة آخر استخدم `preferOver` عندما يكون Plugin الخاص بك هو المالك المفضّل لمعرّف قناة يمكن أن يوفره Plugin آخر أيضًا. الحالات الشائعة هي معرّف Plugin أُعيدت تسميته، أو Plugin مستقل يحل محل Plugin مضمّن، أو تفرع تتم صيانته ويحتفظ بمعرّف القناة نفسه لتوافق الإعدادات. ```json { "id": "acme-chat", "channels": ["chat"], "channelConfigs": { "chat": { "schema": { "type": "object", "additionalProperties": false, "properties": { "webhookUrl": { "type": "string" } } }, "preferOver": ["chat"] } } } ``` عندما يتم إعداد `channels.chat`، يأخذ OpenClaw في الحسبان كلًا من معرّف القناة ومعرّف Plugin المفضّل. إذا كان Plugin الأقل أولوية قد اختير فقط لأنه مضمّن أو مفعّل افتراضيًا، فإن OpenClaw يعطّله في إعدادات وقت التشغيل الفعلية بحيث يمتلك Plugin واحد القناة وأدواتها. يظل اختيار المستخدم الصريح هو الحاسم: إذا فعّل المستخدم كلا الـ Pluginين صراحةً، فإن OpenClaw يحافظ على ذلك الاختيار ويبلغ عن تشخيصات القنوات/الأدوات المكررة بدلًا من تغيير مجموعة الـ Plugin المطلوبة بصمت. أبقِ `preferOver` محصورًا في معرّفات Plugin التي يمكنها فعلًا توفير القناة نفسها. فهو ليس حقل أولوية عامًا ولا يعيد تسمية مفاتيح إعدادات المستخدم. ## مرجع modelSupport استخدم `modelSupport` عندما يجب أن يستنتج OpenClaw Plugin المزوّد لديك من معرّفات نماذج مختصرة مثل `gpt-5.5` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل Plugin. ```json { "modelSupport": { "modelPrefixes": ["gpt-", "o1", "o3", "o4"], "modelPatterns": ["^computer-use-preview"] } } ``` يطبّق OpenClaw ترتيب الأسبقية هذا: - مراجع `provider/model` الصريحة تستخدم بيانات manifest الوصفية الخاصة بـ `providers` المالك - تتقدم `modelPatterns` على `modelPrefixes` - إذا تطابق Plugin غير مضمّن وPlugin مضمّن، يفوز الـ Plugin غير المضمّن - يُتجاهل أي غموض متبقٍ إلى أن يحدد المستخدم أو الإعدادات مزوّدًا الحقول: | الحقل | النوع | ما يعنيه | | --------------- | ---------- | ------------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة. | | `modelPatterns` | `string[]` | مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف الشخصي. | ## مرجع modelCatalog استخدم `modelCatalog` عندما يجب أن يعرف OpenClaw بيانات نماذج المزوّد الوصفية قبل تحميل وقت تشغيل Plugin. هذا هو المصدر المملوك للـ manifest لصفوف الكتالوج الثابتة والأسماء المستعارة للمزوّدين وقواعد الإخفاء ووضع الاكتشاف. لا يزال التحديث في وقت التشغيل ينتمي إلى كود وقت تشغيل المزوّد، لكن الـ manifest يخبر النواة متى يكون وقت التشغيل مطلوبًا. ```json { "providers": ["openai"], "modelCatalog": { "providers": { "openai": { "baseUrl": "https://api.openai.com/v1", "api": "openai-responses", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "input": ["text", "image"], "reasoning": true, "contextWindow": 256000, "maxTokens": 128000, "cost": { "input": 1.25, "output": 10, "cacheRead": 0.125 }, "status": "available", "tags": ["default"] } ] } }, "aliases": { "azure-openai-responses": { "provider": "openai", "api": "azure-openai-responses" } }, "suppressions": [ { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", "reason": "not available on Azure OpenAI Responses" } ], "discovery": { "openai": "static" } } } ``` حقول المستوى الأعلى: | الحقل | النوع | ما يعنيه | | -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `providers` | `Record` | صفوف الكتالوج لمعرّفات المزوّدين التي يملكها هذا الـ Plugin. يجب أن تظهر المفاتيح أيضًا في `providers` ذات المستوى الأعلى. | | `aliases` | `Record` | أسماء مستعارة للمزوّدين يجب أن تتحول إلى مزوّد مملوك لأغراض الكتالوج أو تخطيط الإخفاء. | | `suppressions` | `object[]` | صفوف نماذج من مصدر آخر يخفيها هذا الـ Plugin لسبب خاص بالمزوّد. | | `discovery` | `Record` | ما إذا كان يمكن قراءة كتالوج المزوّد من بيانات manifest الوصفية، أو تحديثه في ذاكرة التخزين المؤقت، أو يتطلب وقت التشغيل. | تشارك `aliases` في بحث ملكية المزوّد لتخطيط كتالوج النماذج. يجب أن تكون أهداف الأسماء المستعارة مزوّدين من المستوى الأعلى يملكهم الـ Plugin نفسه. عندما تستخدم قائمة مفلترة حسب المزوّد اسمًا مستعارًا، يستطيع OpenClaw قراءة الـ manifest المالك وتطبيق تجاوزات API/عنوان URL الأساسي للاسم المستعار دون تحميل وقت تشغيل المزوّد. لا توسّع الأسماء المستعارة قوائم الكتالوج غير المفلترة؛ فالقوائم العامة تصدر صفوف المزوّد القانوني المالك فقط. تستبدل `suppressions` خطاف وقت تشغيل المزوّد القديم `suppressBuiltInModel`. لا تُحترم إدخالات الإخفاء إلا عندما يكون المزوّد مملوكًا للـ Plugin أو مُعلنًا كمفتاح `modelCatalog.aliases` يستهدف مزوّدًا مملوكًا. لم تعد خطافات الإخفاء في وقت التشغيل تُستدعى أثناء حل النماذج. حقول المزوّد: | الحقل | النوع | ما يعنيه | | --------- | ------------------------ | ----------------------------------------------------------------- | | `baseUrl` | `string` | عنوان URL أساسي افتراضي اختياري للنماذج في كتالوج هذا المزوّد. | | `api` | `ModelApi` | محوّل API افتراضي اختياري للنماذج في كتالوج هذا المزوّد. | | `headers` | `Record` | ترويسات ثابتة اختيارية تنطبق على كتالوج هذا المزوّد. | | `models` | `object[]` | صفوف النماذج المطلوبة. يتم تجاهل الصفوف التي لا تحتوي على `id`. | حقول النموذج: | الحقل | النوع | ما يعنيه | | --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | | `id` | `string` | معرّف النموذج المحلي لدى المزوّد، بدون بادئة `provider/`. | | `name` | `string` | اسم عرض اختياري. | | `api` | `ModelApi` | تجاوز اختياري للـ API على مستوى النموذج. | | `baseUrl` | `string` | تجاوز اختياري لعنوان URL الأساسي على مستوى النموذج. | | `headers` | `Record` | ترويسات ثابتة اختيارية على مستوى النموذج. | | `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` عندما تكون صفوف البيان بذورًا أو إضافات قابلة للإدراج ومفيدة، لكن يمكن للتحديث/التخزين المؤقت إضافة صفوف أكثر لاحقًا؛ الصفوف القابلة للتحديث ليست مرجعية بحد ذاتها. استخدم `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` | أسماء بديلة دقيقة لمعرف النموذج، غير حساسة لحالة الأحرف. تُعاد القيم كما كُتبت. | | `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` لبيانات تعريف توافق الطلبات منخفضة التكلفة التي تحتاجها سياسة الطلبات العامة دون تحميل وقت تشغيل المزوّد. أبقِ إعادة كتابة الحمولة الخاصة بالسلوك في خطافات وقت تشغيل المزوّد أو مساعدات عائلة المزوّد المشتركة. ```json { "providers": ["vllm"], "providerRequest": { "providers": { "vllm": { "family": "vllm", "openAICompletions": { "supportsStreamingUsage": true } } } } } ``` حقول المزوّد: | الحقل | النوع | ما يعنيه | | --------------------- | ------------ | ------------------------------------------------------------------------------ | | `family` | `string` | تسمية عائلة المزوّد المستخدمة في قرارات توافق الطلبات العامة والتشخيصات. | | `compatibilityFamily` | `"moonshot"` | حاوية توافق اختيارية لعائلة المزوّد لمساعدات الطلبات المشتركة. | | `openAICompletions` | `object` | أعلام طلبات الإكمال المتوافقة مع OpenAI، حاليًا `supportsStreamingUsage`. | ## مرجع modelPricing استخدم `modelPricing` عندما يحتاج مزوّد إلى سلوك تسعير مستوى التحكم قبل تحميل وقت التشغيل. تقرأ ذاكرة التخزين المؤقت للتسعير في Gateway بيانات التعريف هذه دون استيراد كود وقت تشغيل المزوّد. ```json { "providers": ["ollama", "openrouter"], "modelPricing": { "providers": { "ollama": { "external": false }, "openrouter": { "openRouter": { "passthroughProviderModel": true }, "liteLLM": false } } } } ``` حقول المزوّد: | الحقل | النوع | ما يعنيه | | ------------ | ----------------- | ------------------------------------------------------------------------------------------------ | | `external` | `boolean` | اضبطه على `false` للمزوّدين المحليين/ذاتيي الاستضافة الذين يجب ألا يجلبوا تسعير OpenRouter أو LiteLLM أبدًا. | | `openRouter` | `false \| object` | تعيين بحث تسعير OpenRouter. يعطّل `false` بحث OpenRouter لهذا المزوّد. | | `liteLLM` | `false \| object` | تعيين بحث تسعير LiteLLM. يعطّل `false` بحث LiteLLM لهذا المزوّد. | حقول المصدر: | الحقل | النوع | ما يعنيه | | -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | معرف مزوّد الكتالوج الخارجي عندما يختلف عن معرف مزوّد OpenClaw، مثل `z-ai` لمزوّد `zai`. | | `passthroughProviderModel` | `boolean` | تعامل مع معرفات النماذج التي تحتوي على شرطة مائلة كمراجع مزوّد/نموذج متداخلة، وهو مفيد لمزوّدي الوكيل مثل OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | تنويعات إضافية لمعرف نموذج الكتالوج الخارجي. يحاول `version-dots` معرفات إصدارات منقوطة مثل `claude-opus-4.6`. | ### فهرس مزوّدي OpenClaw فهرس مزوّدي OpenClaw هو بيانات تعريف معاينة مملوكة لـ OpenClaw للمزوّدين الذين قد لا تكون Plugins الخاصة بهم مثبتة بعد. ليس جزءًا من بيان Plugin. تظل بيانات Plugins هي المرجع للمكوّن الإضافي المثبت. فهرس المزوّدين هو عقد الاحتياط الداخلي الذي ستستهلكه مستقبلًا أسطح اختيار النماذج لمزوّدي التثبيت وما قبل التثبيت عندما لا يكون Plugin المزوّد مثبتًا. ترتيب مرجعية الكتالوج: 1. إعدادات المستخدم. 2. بيان Plugin المثبت `modelCatalog`. 3. ذاكرة التخزين المؤقت لكتالوج النماذج من تحديث صريح. 4. صفوف معاينة فهرس مزوّدي OpenClaw. يجب ألا يحتوي فهرس المزوّدين على أسرار، أو حالة تمكين، أو خطافات وقت تشغيل، أو بيانات نماذج مباشرة خاصة بحساب. تستخدم كتالوجات المعاينة الخاصة به نفس شكل صف مزوّد `modelCatalog` مثل بيانات Plugins، لكن يجب أن تظل محدودة ببيانات تعريف العرض المستقرة، ما لم تُبقَ حقول محوّل وقت التشغيل مثل `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 dist المتوقعة مثل `sha512-...`؛ تتحقق تدفقات التثبيت والتحديث من الأثرية المجلبة مقابلها. | | `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمن عندما يكون التكوين غير صالح. | | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يتيح تحميل أسطح القناة الخاصة بالإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل. | تحدد بيانات manifest الوصفية خيارات المزوّد/القناة/الإعداد التي تظهر في التهيئة قبل تحميل وقت التشغيل. يخبر `package.json#openclaw.install` التهيئة بكيفية جلب ذلك Plugin أو تمكينه عندما يختار المستخدم أحد تلك الخيارات. لا تنقل تلميحات التثبيت إلى `openclaw.plugin.json`. يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل manifest لمصادر Plugin غير المضمنة. تُرفض القيم غير الصالحة؛ أما القيم الأحدث لكن الصالحة فتتجاوز plugins الخارجية على المضيفات الأقدم. يُفترض أن plugins المصدر المضمنة متوافقة الإصدار مع نسخة المضيف المحلية. يجب أن تستخدم البيانات الوصفية الرسمية للتثبيت عند الطلب `clawhubSpec` عندما يكون Plugin منشورًا على ClawHub؛ تتعامل التهيئة مع ذلك بوصفه المصدر البعيد المفضل وتسجل حقائق أثرية ClawHub بعد التثبيت. يبقى `npmSpec` احتياطي التوافق للحزم التي لم تنتقل إلى ClawHub بعد. يوجد تثبيت إصدار npm الدقيق بالفعل في `npmSpec`، على سبيل المثال `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. يجب أن تقرن إدخالات الفهرس الخارجي الرسمية المواصفات الدقيقة بـ `expectedIntegrity` لكي تفشل تدفقات التحديث بإغلاق آمن إذا لم تعد أثرية npm المجلبة تطابق الإصدار المثبت. لا تزال التهيئة التفاعلية تعرض مواصفات npm الموثوقة من السجل، بما في ذلك أسماء الحزم المجردة وdist-tags، من أجل التوافق. تستطيع تشخيصات الفهرس تمييز المصادر الدقيقة، والعائمة، والمثبتة بالتكامل، وناقصة التكامل، وغير المطابقة لاسم الحزمة، وذات الاختيار الافتراضي غير الصالح. كما تحذر عندما يكون `expectedIntegrity` موجودًا لكن لا يوجد مصدر npm صالح يمكنه تثبيته. عندما يكون `expectedIntegrity` موجودًا، تفرضه تدفقات التثبيت/التحديث؛ وعندما يُحذف، يُسجل حل السجل دون تثبيت تكامل. يجب أن توفر plugins القنوات `openclaw.setupEntry` عندما تحتاج عمليات فحص الحالة، أو قائمة القنوات، أو SecretRef إلى تحديد الحسابات المكونة دون تحميل وقت التشغيل الكامل. يجب أن تعرض نقطة دخول الإعداد بيانات القناة الوصفية إضافة إلى مهايئات التكوين والحالة والأسرار الآمنة للإعداد؛ أبقِ عملاء الشبكة، ومستمعي Gateway، وأوقات تشغيل النقل في نقطة دخول الإضافة الرئيسية. لا تتجاوز حقول نقاط دخول وقت التشغيل فحوص حدود الحزمة لحقول نقاط دخول المصدر. على سبيل المثال، لا يستطيع `openclaw.runtimeExtensions` جعل مسار `openclaw.extensions` الهارب قابلاً للتحميل. `openclaw.install.allowInvalidConfigRecovery` ضيق عن قصد. لا يجعل التكوينات المعطوبة عشوائيًا قابلة للتثبيت. حاليًا لا يسمح إلا لتدفقات التثبيت بالتعافي من إخفاقات ترقية محددة وقديمة في Plugin مضمن، مثل مسار Plugin مضمن مفقود أو إدخال `channels.` قديم لذلك Plugin المضمن نفسه. لا تزال أخطاء التكوين غير ذات الصلة تمنع التثبيت وتوجه المشغلين إلى `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` هي بيانات وصفية للحزمة من أجل وحدة فاحص صغيرة: ```json { "openclaw": { "channel": { "id": "whatsapp", "persistedAuthState": { "specifier": "./auth-presence", "exportName": "hasAnyWhatsAppAuth" } } } } ``` استخدمها عندما تحتاج تدفقات الإعداد، أو doctor، أو الحالة، أو الحضور للقراءة فقط إلى فحص مصادقة رخيص بنعم/لا قبل تحميل Plugin القناة الكامل. حالة المصادقة المستمرة ليست حالة قناة مكونة: لا تستخدم هذه البيانات الوصفية لتمكين plugins تلقائيًا، أو إصلاح تبعيات وقت التشغيل، أو تحديد ما إذا كان يجب تحميل وقت تشغيل قناة. يجب أن يكون التصدير الهدف دالة صغيرة تقرأ الحالة المستمرة فقط؛ لا تمررها عبر برميل وقت تشغيل القناة الكامل. يتبع `openclaw.channel.configuredState` الشكل نفسه للفحوصات الرخيصة المكونة من البيئة فقط: ```json { "openclaw": { "channel": { "id": "telegram", "configuredState": { "specifier": "./configured-state", "exportName": "hasTelegramConfiguredState" } } } } ``` استخدمها عندما تستطيع قناة الإجابة عن حالة التكوين من البيئة أو من مدخلات صغيرة أخرى غير وقت التشغيل. إذا كان الفحص يحتاج إلى حل التكوين الكامل أو وقت تشغيل القناة الحقيقي، فأبقِ ذلك المنطق في hook `config.hasConfiguredState` الخاص بالـ Plugin بدلًا من ذلك. ## أسبقية الاكتشاف (معرّفات Plugin المكررة) يكتشف OpenClaw plugins من عدة جذور (مضمن، تثبيت عام، مساحة عمل، مسارات محددة صراحة في التكوين). إذا اشترك اكتشافان في `id` نفسه، فلا يُحتفظ إلا بالـ manifest **الأعلى أسبقية**؛ وتُسقط التكرارات الأقل أسبقية بدلًا من تحميلها بجانبه. الأسبقية، من الأعلى إلى الأدنى: 1. **محدد في التكوين** — مسار مثبت صراحة في `plugins.entries.` 2. **مضمن** — plugins المشحونة مع OpenClaw 3. **تثبيت عام** — plugins المثبتة في جذر plugins العام لـ OpenClaw 4. **مساحة العمل** — plugins المكتشفة بالنسبة إلى مساحة العمل الحالية الآثار: - لن تحجب نسخة متفرعة أو قديمة من Plugin مضمن موجودة في مساحة العمل البناء المضمن. - لتجاوز Plugin مضمن فعليًا بآخر محلي، ثبته عبر `plugins.entries.` لكي يفوز بالأسبقية بدلًا من الاعتماد على اكتشاف مساحة العمل. - تُسجل عمليات إسقاط التكرارات لكي يستطيع Doctor وتشخيصات بدء التشغيل الإشارة إلى النسخة المهملة. - تُصاغ تجاوزات التكرارات المحددة في التكوين كتجاوزات صريحة في التشخيصات، لكنها لا تزال تحذر لكي تبقى التفرعات القديمة والحجب العرضي مرئية. ## متطلبات JSON Schema - **يجب أن يشحن كل Plugin مع JSON Schema**، حتى لو لم يقبل أي تكوين. - المخطط الفارغ مقبول (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`). - تُتحقق المخططات عند قراءة/كتابة التكوين، وليس في وقت التشغيل. - عند توسيع Plugin مضمن أو تفريعه بمفاتيح تكوين جديدة، حدّث `configSchema` في `openclaw.plugin.json` لذلك Plugin في الوقت نفسه. مخططات plugins المضمنة صارمة، لذا فإن إضافة `plugins.entries..config.myNewKey` في تكوين المستخدم دون إضافة `myNewKey` إلى `configSchema.properties` سيُرفض قبل تحميل وقت تشغيل Plugin. مثال على توسيع المخطط: ```json { "configSchema": { "type": "object", "additionalProperties": false, "properties": { "myNewKey": { "type": "string" } } } } ``` ## سلوك التحقق - مفاتيح `channels.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة معلنًا بواسطة manifest Plugin. - يجب أن تشير `plugins.entries.` و`plugins.allow` و`plugins.deny` و`plugins.slots.*` إلى معرّفات Plugin **قابلة للاكتشاف**. المعرّفات غير المعروفة هي **أخطاء**. - إذا كان Plugin مثبتًا لكن لديه manifest أو مخطط معطوب أو مفقود، يفشل التحقق ويبلغ Doctor عن خطأ Plugin. - إذا كان تكوين Plugin موجودًا لكن Plugin **معطل**، فيُحتفظ بالتكوين ويظهر **تحذير** في Doctor + السجلات. راجع [مرجع التكوين](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل. ## ملاحظات - البيان **مطلوب لـ plugins OpenClaw الأصلية**، بما في ذلك التحميلات من نظام الملفات المحلي. ما يزال وقت التشغيل يحمّل وحدة plugin بشكل منفصل؛ أما البيان فهو للاكتشاف + التحقق فقط. - تُحلّل بيانات البيانات الأصلية باستخدام JSON5، لذلك تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير المقتبسة ما دامت القيمة النهائية ما تزال كائنًا. - لا يقرأ محمّل البيان إلا حقول البيان الموثّقة. تجنّب المفاتيح المخصصة في المستوى الأعلى. - يمكن إغفال `channels` و`providers` و`cliBackends` و`skills` كلها عندما لا يحتاجها plugin. - يجب أن يبقى `providerCatalogEntry` خفيفًا، وينبغي ألا يستورد شيفرة وقت تشغيل واسعة؛ استخدمه لبيانات تعريف كتالوج المزوّد الثابتة أو واصفات الاكتشاف المحدودة، لا للتنفيذ وقت الطلب. `providerDiscoveryEntry` هي التسمية القديمة وما تزال تعمل مع plugins الحالية. - تُختار أنواع plugins الحصرية عبر `plugins.slots.*`: `kind: "memory"` عبر `plugins.slots.memory`، و`kind: "context-engine"` عبر `plugins.slots.contextEngine` (القيمة الافتراضية `legacy`). - صرّح عن نوع plugin الحصري في هذا البيان. `OpenClawPluginDefinition.kind` في مدخل وقت التشغيل مهمل، ويبقى فقط كآلية توافق احتياطية لـ plugins الأقدم. - بيانات تعريف متغيرات البيئة (`setup.providers[].envVars` و`providerAuthEnvVars` المهمل و`channelEnvVars`) تصريحية فقط. ما تزال أسطح الحالة والتدقيق والتحقق من تسليم cron وغيرها من الأسطح للقراءة فقط تطبّق سياسة ثقة plugin والتفعيل الفعلي قبل التعامل مع متغير بيئة على أنه مكوَّن. - لبيانات تعريف معالج وقت التشغيل التي تتطلب شيفرة المزوّد، راجع [خطافات وقت تشغيل المزوّد](/ar/plugins/architecture-internals#provider-runtime-hooks). - إذا كان plugin لديك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح الخاصة بمدير الحزم (على سبيل المثال، pnpm `allow-build-scripts` + `pnpm rebuild `). ## ذات صلة بدء استخدام plugins. البنية الداخلية ونموذج القدرات. مرجع SDK الخاص بـ Plugin واستيرادات المسارات الفرعية.