--- read_when: - أنت تبني Plugin لـ OpenClaw - تحتاج إلى إصدار مخطط تهيئة Plugin أو تصحيح أخطاء التحقق من صحة Plugin summary: متطلبات بيان Plugin + مخطط JSON (التحقق الصارم من التهيئة) title: ملف بيان Plugin x-i18n: generated_at: "2026-06-27T18:06:57Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 62f6684ab074e4f14ce5c833fe8c8c624a2750f80215bdeffd972e27dd6bfc9c source_path: plugins/manifest.md workflow: 16 --- هذه الصفحة مخصصة **لملف بيان Plugin الأصلي في OpenClaw** فقط. للاطلاع على تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles). تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة: - حزمة Codex: `.codex-plugin/plugin.json` - حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكونات Claude الافتراضي بدون ملف بيان - حزمة Cursor: `.cursor-plugin/plugin.json` يكتشف OpenClaw تخطيطات الحزم هذه تلقائياً أيضاً، لكنها لا تُتحقق مقابل مخطط `openclaw.plugin.json` الموضح هنا. بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حالياً بيانات تعريف الحزمة بالإضافة إلى جذور Skills المعلنة، وجذور أوامر Claude، وافتراضيات `settings.json` لحزمة Claude، وافتراضيات LSP لحزمة Claude، وحزم الخطافات المدعومة عندما يطابق التخطيط توقعات وقت تشغيل OpenClaw. يجب على كل Plugin أصلي في OpenClaw **أن يضم** ملف `openclaw.plugin.json` في **جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من صحة الإعدادات **من دون تنفيذ كود Plugin**. تُعامل ملفات البيان المفقودة أو غير الصالحة على أنها أخطاء Plugin وتمنع التحقق من صحة الإعدادات. راجع الدليل الكامل لنظام Plugin: [Plugins](/ar/tools/plugin). للاطلاع على نموذج الإمكانات الأصلي وإرشادات التوافق الخارجي الحالية: [نموذج الإمكانات](/ar/plugins/architecture#public-capability-model). ## ما الذي يفعله هذا الملف `openclaw.plugin.json` هو بيانات التعريف التي يقرأها OpenClaw **قبل أن يحمّل كود Plugin الخاص بك**. يجب أن يكون كل ما يلي خفيفاً بما يكفي لفحصه من دون تشغيل وقت تشغيل Plugin. **استخدمه من أجل:** - هوية Plugin، والتحقق من صحة الإعدادات، وتلميحات واجهة مستخدم الإعدادات - بيانات تعريف المصادقة، والإعداد الأولي، والتجهيز (الاسم المستعار، والتمكين التلقائي، ومتغيرات بيئة المزوّد، وخيارات المصادقة) - تلميحات التنشيط لأسطح مستوى التحكم - ملكية مختصرة لعائلة النماذج - لقطات ثابتة لملكية الإمكانات (`contracts`) - بيانات تعريف مشغّل ضمان الجودة التي يمكن لمضيف `openclaw qa` المشترك فحصها - بيانات تعريف الإعدادات الخاصة بالقناة المدمجة في أسطح الفهرس والتحقق **لا تستخدمه من أجل:** تسجيل سلوك وقت التشغيل، أو إعلان نقاط دخول الكود، أو بيانات تعريف تثبيت npm. مكان هذه الأمور هو كود Plugin و`package.json`. ## مثال بسيط ```json { "id": "voice-call", "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } } ``` ## مثال غني ```json { "id": "openrouter", "name": "OpenRouter", "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { "modelPrefixes": ["router-"] }, "modelIdNormalization": { "providers": { "openrouter": { "prefixWhenBare": "openrouter" } } }, "providerEndpoints": [ { "endpointClass": "openrouter", "hostSuffixes": ["openrouter.ai"] } ], "providerRequest": { "providers": { "openrouter": { "family": "openrouter" } } }, "cliBackends": ["openrouter-cli"], "syntheticAuthRefs": ["openrouter-cli"], "setup": { "providers": [ { "id": "openrouter", "envVars": ["OPENROUTER_API_KEY"] } ] }, "providerAuthAliases": { "openrouter-coding": "openrouter" }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, "providerAuthChoices": [ { "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", "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. | | `requiresPlugins` | لا | `string[]` | معرّفات Plugin التي يجب تثبيتها أيضًا حتى يكون لهذا الـ Plugin تأثير. يُبقي الاكتشاف الـ Plugin قابلًا للتحميل، لكنه يحذّر عند غياب أي 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` | بيانات تعريف خفيفة لعائلة الموفّر وتوافق الطلبات، تُستخدم بواسطة سياسة الطلبات العامة قبل تحميل وقت تشغيل الموفّر. | | `secretProviderIntegrations` | لا | `Record` | إعدادات مسبقة تصريحية لموفّر تنفيذ SecretRef يمكن لأسطح الإعداد أو التثبيت عرضها من دون ترميز تكاملات خاصة بالموفّر داخل النواة. | | `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[]` | واصفات خفيفة لمشغّلات ضمان الجودة تُستخدم بواسطة مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin. | | `contracts` | لا | `object` | لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والتضمينات، والكلام، والنسخ في الوقت الفعلي، والصوت في الوقت الفعلي، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات. | | `mediaUnderstandingProviderMetadata` | لا | `Record` | افتراضات خفيفة لفهم الوسائط لمعرّفات الموفّرين المعلنة في `contracts.mediaUnderstandingProviders`. | | `imageGenerationProviderMetadata` | لا | `Record` | بيانات تعريف خفيفة لمصادقة توليد الصور لمعرّفات الموفّرين المعلنة في `contracts.imageGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url. | | `videoGenerationProviderMetadata` | لا | `Record` | بيانات تعريف خفيفة لمصادقة توليد الفيديو لمعرّفات الموفّرين المعلنة في `contracts.videoGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url. | | `musicGenerationProviderMetadata` | لا | `Record` | بيانات تعريف خفيفة لمصادقة توليد الموسيقى لمعرّفات الموفّرين المعلنة في `contracts.musicGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url. | | `toolMetadata` | لا | `Record` | بيانات تعريف خفيفة للتوفر للأدوات المملوكة من Plugin والمعلنة في `contracts.tools`. استخدمها عندما ينبغي ألا تحمّل الأداة وقت التشغيل إلا عند وجود دليل على التهيئة أو البيئة أو المصادقة. | | `channelConfigs` | لا | `Record` | بيانات تعريف تهيئة القناة المملوكة من البيان، تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. | | `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبة إلى جذر Plugin. | | `name` | لا | `string` | اسم Plugin قابل للقراءة من قبل البشر. | | `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. | | `icon` | لا | `string` | عنوان URL لصورة HTTPS لبطاقات السوق/الفهرس. يقبل ClawHub أي عنوان URL صالح من نوع `https://` ويعود إلى أيقونة 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`. | | `referenceAudioInputs` | لا | `boolean` | خاص بتوليد الفيديو فقط. اضبطه على `true` عندما يقبل المزوّد أصولًا صوتية مرجعية؛ وإلا فسيخفي `video_generate` معلمات المرجع الصوتي. | يدعم كل إدخال `configSignals` ما يلي: | الحقل | مطلوب | النوع | معناه | | ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rootPath` | نعم | `string` | مسار نقطي إلى كائن التكوين المملوك لـ Plugin المراد فحصه، على سبيل المثال `plugins.entries.example.config`. | | `overlayPath` | لا | `string` | مسار نقطي داخل التكوين الجذر يجب أن يراكب كائنه الكائن الجذر قبل تقييم الإشارة. استخدم هذا للتكوين الخاص بإمكانات معيّنة مثل `image` أو `video` أو `music`. | | `overlayMapPath` | لا | `string` | مسار نقطي داخل التكوين الجذر يجب أن تراكب كل قيمة كائن فيه الكائن الجذر. استخدم هذا لخرائط الحسابات المسماة مثل `accounts`، حيث يجب أن يكون أي حساب مكوّن مؤهلًا. | | `required` | لا | `string[]` | مسارات نقطية داخل التكوين الفعّال يجب أن تحتوي على قيم مكوّنة. يجب ألا تكون السلاسل فارغة؛ ويجب ألا تكون الكائنات والمصفوفات فارغة. | | `requiredAny` | لا | `string[]` | مسارات نقطية داخل التكوين الفعّال يجب أن يحتوي واحد منها على الأقل على قيمة مكوّنة. | | `mode` | لا | `object` | حارس اختياري لوضع سلسلة نصية داخل التكوين الفعّال. استخدم هذا عندما تنطبق الإتاحة المعتمدة على التكوين فقط على وضع واحد. | يدعم كل حارس `mode` ما يلي: | الحقل | مطلوب | النوع | معناه | | ------------ | -------- | ---------- | ---------------------------------------------------------------------------------- | | `path` | لا | `string` | مسار نقطي داخل التكوين الفعّال. القيمة الافتراضية هي `mode`. | | `default` | لا | `string` | قيمة الوضع التي تُستخدم عندما يحذف التكوين المسار. | | `allowed` | لا | `string[]` | عند وجوده، تنجح الإشارة فقط عندما يكون الوضع الفعّال واحدًا من هذه القيم. | | `disallowed` | لا | `string[]` | عند وجوده، تفشل الإشارة عندما يكون الوضع الفعّال واحدًا من هذه القيم. | يدعم كل إدخال `authSignals` ما يلي: | الحقل | مطلوب | النوع | معناه | | ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | نعم | `string` | معرّف المزوّد الذي يجب التحقق منه في ملفات تعريف المصادقة المكوّنة. | | `providerBaseUrl` | لا | `object` | حارس اختياري يجعل الإشارة تُحتسب فقط عندما يستخدم المزوّد المكوّن المشار إليه عنوان URL أساسيًا مسموحًا. استخدم هذا عندما يكون اسم مصادقة مستعار صالحًا فقط لواجهات API معيّنة. | يدعم كل حارس `providerBaseUrl` ما يلي: | الحقل | مطلوب | النوع | معناه | | ----------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | نعم | `string` | معرّف تكوين المزوّد الذي يجب التحقق من `baseUrl` الخاص به. | | `defaultBaseUrl` | لا | `string` | عنوان URL الأساسي الذي يُفترض عندما يحذف تكوين المزوّد `baseUrl`. | | `allowedBaseUrls` | نعم | `string[]` | عناوين URL الأساسية المسموح بها لإشارة المصادقة هذه. تُتجاهل الإشارة عندما لا يطابق عنوان URL الأساسي المكوّن أو الافتراضي إحدى هذه القيم المطبّعة. | ## مرجع بيانات تعريف الأدوات يستخدم `toolMetadata` الأشكال نفسها لـ `configSignals` و`authSignals` كما في بيانات تعريف مزوّد التوليد، مع الفهرسة باسم الأداة. يصرّح `contracts.tools` بالملكية. يصرّح `toolMetadata` بدليل إتاحة منخفض التكلفة حتى يتمكن OpenClaw من تجنب استيراد وقت تشغيل Plugin فقط لكي يعيد مصنع أدواته `null`. ```json { "setup": { "providers": [ { "id": "example", "envVars": ["EXAMPLE_API_KEY"] } ] }, "contracts": { "tools": ["example_search"] }, "toolMetadata": { "example_search": { "authSignals": [ { "provider": "example" } ], "configSignals": [ { "rootPath": "plugins.entries.example.config", "overlayPath": "search", "required": ["apiKey"] } ] } } } ``` إذا لم تكن للأداة أي `toolMetadata`، يحافظ 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 `. | | `cliDescription` | لا | `string` | وصف يُستخدم في مساعدة CLI. | | `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation" \| "music-generation">` | أسطح الإعداد الأولي التي ينبغي أن يظهر فيها هذا الاختيار. إذا حُذفت، تكون القيمة الافتراضية `["text-inference"]`. | ## مرجع commandAliases استخدم `commandAliases` عندما يمتلك plugin اسم أمر وقت تشغيل قد يضعه المستخدمون بالخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw هذه البيانات الوصفية للتشخيص من دون استيراد كود وقت تشغيل plugin. ```json { "commandAliases": [ { "name": "dreaming", "kind": "runtime-slash", "cliCommand": "memory" } ] } ``` | الحقل | مطلوب | النوع | ما يعنيه | | ------------ | ----- | ----------------- | --------------------------------------------------------------------- | | `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا plugin. | | `kind` | لا | `"runtime-slash"` | يعلّم الاسم المستعار كأمر شرطة مائلة في الدردشة بدلًا من أمر CLI جذري. | | `cliCommand` | لا | `string` | أمر CLI جذري ذو صلة يمكن اقتراحه لعمليات CLI، إن وُجد. | ## مرجع activation استخدم `activation` عندما يستطيع plugin التصريح بتكلفة منخفضة عن أحداث مستوى التحكم التي يجب أن تُدرجه في خطة تفعيل/تحميل. هذه الكتلة بيانات وصفية للمخطِّط، وليست API دورة حياة. لا تسجّل سلوك وقت التشغيل، ولا تستبدل `register(...)`، ولا تعد بأن كود plugin قد نُفّذ بالفعل. يستخدم مخطِّط التفعيل هذه الحقول لتضييق plugins المرشحة قبل الرجوع إلى بيانات وصفية قائمة لملكية البيان مثل `providers` و`channels` و`commandAliases` و`setup.providers` و`contracts.tools` والخطافات. فضّل أضيق بيانات وصفية تصف الملكية بالفعل. استخدم `providers` أو `channels` أو `commandAliases` أو واصفات الإعداد أو `contracts` عندما تعبّر هذه الحقول عن العلاقة. استخدم `activation` لتلميحات مخطِّط إضافية لا يمكن تمثيلها بحقول الملكية تلك. استخدم `cliBackends` على المستوى الأعلى للأسماء المستعارة لوقت تشغيل CLI مثل `claude-cli` أو `my-cli` أو `google-gemini-cli`؛ أما `activation.onAgentHarnesses` فهو مخصص فقط لمعرّفات أدوات agent المضمّنة التي لا تملك حقل ملكية بالفعل. هذه الكتلة بيانات وصفية فقط. لا تسجّل سلوك وقت التشغيل، ولا تستبدل `register(...)` أو `setupEntry` أو نقاط إدخال وقت التشغيل/plugin الأخرى. يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل plugins أوسع، لذلك فإن غياب بيانات التفعيل غير الخاصة ببدء التشغيل عادة لا يكلّف إلا الأداء؛ ولا ينبغي أن يغيّر الصحة ما دامت بدائل ملكية البيان لا تزال موجودة. يجب على كل plugin تعيين `activation.onStartup` عمدًا. عيّنه إلى `true` فقط عندما يجب أن يعمل plugin أثناء بدء تشغيل Gateway. عيّنه إلى `false` عندما يكون plugin خاملًا عند بدء التشغيل ويجب تحميله فقط من محفزات أضيق. لم يعد حذف `onStartup` يؤدي إلى تحميل plugin ضمنيًا عند بدء التشغيل؛ استخدم بيانات تفعيل صريحة لبدء التشغيل أو القناة أو الإعدادات أو أداة agent أو الذاكرة أو محفزات تفعيل أضيق أخرى. ```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[]` | معرّفات وقت تشغيل أدوات agent المضمّنة التي يجب أن تُدرج هذا 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` القديمين - يستخدم تخطيط بدء تشغيل وقت تشغيل agent `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[]` | وسوم UI اختيارية. | | `advanced` | `boolean` | يعلّم الحقل على أنه متقدم. | | `sensitive` | `boolean` | يعلّم الحقل على أنه سري أو حساس. | | `placeholder` | `string` | نص عنصر نائب لإدخالات النماذج. | ## مرجع contracts استخدم `contracts` فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw قراءتها من دون استيراد وقت تشغيل Plugin. ```json { "contracts": { "agentToolResultMiddleware": ["openclaw", "codex"], "trustedToolPolicies": ["workflow-budget"], "externalAuthProviders": ["acme-ai"], "embeddingProviders": ["openai-compatible"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], "realtimeVoiceProviders": ["openai"], "memoryEmbeddingProviders": ["local"], "mediaUnderstandingProviders": ["openai"], "imageGenerationProviders": ["openai"], "videoGenerationProviders": ["qwen"], "webFetchProviders": ["firecrawl"], "webSearchProviders": ["gemini"], "migrationProviders": ["hermes"], "gatewayMethodDispatch": ["authenticated-request"], "tools": ["firecrawl_search", "firecrawl_scrape"] } } ``` كل قائمة اختيارية: | الحقل | النوع | معناه | | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `embeddedExtensionFactories` | `string[]` | معرّفات مصانع إضافات خادم تطبيق Codex، وحاليًا `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | معرّفات بيئة التشغيل التي قد يسجل هذا Plugin برمجيات وسيطة لنتائج الأدوات لها. | | `trustedToolPolicies` | `string[]` | معرّفات سياسات ما قبل الأداة الموثوقة المحلية للـ Plugin التي قد يسجلها Plugin مثبت. قد تسجل Plugins المضمنة السياسات دون هذا الحقل. | | `externalAuthProviders` | `string[]` | معرّفات المزوّدين الذين يملك هذا Plugin خطاف ملف تعريف المصادقة الخارجية الخاص بهم. | | `embeddingProviders` | `string[]` | معرّفات مزوّدي التضمين العامة التي يملكها هذا Plugin لاستخدام تضمين المتجهات القابل لإعادة الاستخدام، بما في ذلك الذاكرة. | | `speechProviders` | `string[]` | معرّفات مزوّدي الكلام التي يملكها هذا Plugin. | | `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ في الوقت الحقيقي التي يملكها هذا Plugin. | | `realtimeVoiceProviders` | `string[]` | معرّفات مزوّدي الصوت في الوقت الحقيقي التي يملكها هذا Plugin. | | `memoryEmbeddingProviders` | `string[]` | معرّفات مزوّدي التضمين الخاصة بالذاكرة التي يملكها هذا Plugin، وهي مهملة. | | `mediaUnderstandingProviders` | `string[]` | معرّفات مزوّدي فهم الوسائط التي يملكها هذا Plugin. | | `transcriptSourceProviders` | `string[]` | معرّفات مزوّدي مصادر النصوص المنسوخة التي يملكها هذا Plugin. | | `imageGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الصور التي يملكها هذا Plugin. | | `videoGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الفيديو التي يملكها هذا Plugin. | | `webFetchProviders` | `string[]` | معرّفات مزوّدي جلب الويب التي يملكها هذا Plugin. | | `webSearchProviders` | `string[]` | معرّفات مزوّدي البحث في الويب التي يملكها هذا Plugin. | | `migrationProviders` | `string[]` | معرّفات مزوّدي الاستيراد التي يملكها هذا Plugin من أجل `openclaw migrate`. | | `gatewayMethodDispatch` | `string[]` | استحقاق محجوز لمسارات HTTP الخاصة بـ Plugin المصادق عليها التي ترسل أساليب Gateway داخل العملية. | | `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin. | يُحتفظ بـ `contracts.embeddedExtensionFactories` لمصانع إضافات Codex المضمنة والمخصصة لخادم التطبيق فقط. يجب أن تعلن تحويلات نتائج الأدوات المضمنة `contracts.agentToolResultMiddleware` وأن تسجل باستخدام `api.registerAgentToolResultMiddleware(...)` بدلًا من ذلك. يمكن لـ Plugins المثبتة استخدام مسار البرمجيات الوسيطة نفسه فقط عند تفعيله صراحة، وفقط لبيئات التشغيل التي تعلنها في `contracts.agentToolResultMiddleware`. يجب أن تعلن Plugins المثبتة التي تحتاج إلى طبقة سياسة ما قبل الأداة الموثوقة من المضيف كل معرّف محلي مسجل في `contracts.trustedToolPolicies` وأن تُفعّل صراحة. تحافظ Plugins المضمنة على مسار السياسة الموثوقة الحالي، لكن تُرفض Plugins المثبتة ذات معرّفات السياسات غير المعلنة قبل التسجيل. تكون معرّفات السياسات محددة النطاق حسب Plugin المسجِّل، لذلك يمكن لـ Pluginين أن يعلنا ويسجلا معًا `workflow-budget`؛ ولا يجوز لـ Plugin واحد تسجيل المعرّف المحلي نفسه مرتين. يجب أن تطابق تسجيلات وقت التشغيل `api.registerTool(...)` مع `contracts.tools`. يستخدم اكتشاف الأدوات هذه القائمة لتحميل بيئات تشغيل Plugin التي يمكنها امتلاك الأدوات المطلوبة فقط. يجب أن تعلن Plugins المزوّدين التي تنفذ `resolveExternalAuthProfiles` `contracts.externalAuthProviders`؛ ويتم تجاهل خطافات المصادقة الخارجية غير المعلنة. يجب أن يعلن مزوّدو التضمين العامون `contracts.embeddingProviders` لكل محوّل مسجل باستخدام `api.registerEmbeddingProvider(...)`. استخدم العقد العام لتوليد المتجهات القابل لإعادة الاستخدام، بما في ذلك المزوّدون الذين تستخدمهم عملية البحث في الذاكرة. يُعد `contracts.memoryEmbeddingProviders` توافقًا خاصًا بالذاكرة ومهملاً، ويبقى فقط أثناء ترحيل المزوّدين الحاليين إلى مسار مزوّد التضمين العام. يقبل `contracts.gatewayMethodDispatch` حاليًا `"authenticated-request"`. إنه بوابة نظافة API لمسارات HTTP الأصلية الخاصة بـ Plugin التي ترسل عمدًا أساليب مستوى التحكم في Gateway داخل العملية، وليس صندوق حماية ضد Plugins أصلية خبيثة. استخدمه فقط للأسطح المضمنة/الخاصة بالمشغل المدققة بإحكام والتي تتطلب بالفعل مصادقة HTTP الخاصة بـ 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 Schema لـ `channels.`. مطلوب لكل إدخال إعداد قناة معلن. | | `uiHints` | `Record` | تسميات/عناصر نائبة/تلميحات حساسة اختيارية لواجهة المستخدم لقسم إعداد تلك القناة. | | `label` | `string` | تسمية القناة المدمجة في أسطح الاختيار والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. | | `description` | `string` | وصف قصير للقناة لأسطح الفحص والكتالوج. | | `commands` | `object` | افتراضيات تلقائية ثابتة للأوامر الأصلية وSkills الأصلية لفحوصات الإعداد قبل وقت التشغيل. | | `preferOver` | `string[]` | معرّفات Plugins قديمة أو ذات أولوية أدنى يجب أن تتفوق عليها هذه القناة في أسطح الاختيار. | ### استبدال Plugin قناة آخر استخدم `preferOver` عندما يكون Plugin الخاص بك هو المالك المفضل لمعرّف قناة يمكن أن يوفّره Plugin آخر أيضًا. الحالات الشائعة هي معرّف Plugin مُعاد تسميته، أو Plugin مستقل يحل محل Plugin مضمن، أو تفرع مُصان يبقي معرّف القناة نفسه لتوافق الإعدادات. ```json { "id": "acme-chat", "channels": ["chat"], "channelConfigs": { "chat": { "schema": { "type": "object", "additionalProperties": false, "properties": { "webhookUrl": { "type": "string" } } }, "preferOver": ["chat"] } } } ``` عندما يتم تكوين `channels.chat`، ينظر OpenClaw في كل من معرّف القناة ومعرّف Plugin المفضل. إذا كان Plugin ذو الأولوية الأدنى قد اختير فقط لأنه مضمن أو مفعّل افتراضيًا، فإن OpenClaw يعطله في إعدادات وقت التشغيل الفعالة بحيث يملك Plugin واحد القناة وأدواتها. لا يزال اختيار المستخدم الصريح هو الغالب: إذا فعّل المستخدم كلا Pluginين صراحة، فإن OpenClaw يحافظ على هذا الاختيار ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من تغيير مجموعة Plugins المطلوبة بصمت. أبقِ `preferOver` محدد النطاق إلى معرّفات Plugins التي يمكنها فعلًا توفير القناة نفسها. إنه ليس حقل أولوية عامًا ولا يعيد تسمية مفاتيح إعداد المستخدم. ## مرجع 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` الصريحة بيانات بيان `providers` الوصفية المالكة - تتفوّق `modelPatterns` على `modelPrefixes` - إذا تطابق Plugin غير مضمّن وPlugin مضمّن، يفوز Plugin غير المضمّن - يُتجاهل أي التباس متبقٍ إلى أن يحدد المستخدم أو الإعدادات مزوّدًا الحقول: | الحقل | النوع | معناه | | --------------- | ---------- | ------------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | بادئات تُطابق باستخدام `startsWith` مع معرّفات النماذج المختصرة. | | `modelPatterns` | `string[]` | مصادر تعبيرات نمطية تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف الشخصي. | تُصرَّف إدخالات `modelPatterns` عبر `compileSafeRegex`، الذي يرفض الأنماط التي تحتوي على تكرار متداخل (على سبيل المثال `(a+)+$`). تُتخطى الأنماط التي تفشل في فحص السلامة بصمت، تمامًا مثل التعبيرات النمطية غير الصالحة نحويًا. أبقِ الأنماط بسيطة وتجنب المحددات الكمية المتداخلة. ## مرجع modelCatalog استخدم `modelCatalog` عندما ينبغي لـ OpenClaw معرفة بيانات تعريف نماذج المزوّد قبل تحميل وقت تشغيل Plugin. هذا هو المصدر المملوك للبيان لصفوف الفهرس الثابتة، وأسماء المزوّدين البديلة، وقواعد الحجب، ووضع الاكتشاف. يظل التحديث وقت التشغيل من مسؤولية كود وقت تشغيل المزوّد، لكن البيان يخبر النواة متى يكون وقت التشغيل مطلوبًا. ```json { "providers": ["openai"], "modelCatalog": { "providers": { "openai": { "baseUrl": "https://api.openai.com/v1", "api": "openai-responses", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "input": ["text", "image"], "reasoning": true, "contextWindow": 256000, "maxTokens": 128000, "cost": { "input": 1.25, "output": 10, "cacheRead": 0.125 }, "status": "available", "tags": ["default"] } ] } }, "aliases": { "azure-openai-responses": { "provider": "openai", "api": "azure-openai-responses" } }, "suppressions": [ { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", "reason": "not available on Azure OpenAI Responses" } ], "discovery": { "openai": "static" } } } ``` حقول المستوى الأعلى: | الحقل | النوع | معناه | | ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `providers` | `Record` | صفوف الفهرس لمعرّفات المزوّدين التي يملكها هذا Plugin. ينبغي أن تظهر المفاتيح أيضًا في `providers` على المستوى الأعلى. | | `aliases` | `Record` | أسماء مزوّدين بديلة ينبغي حلّها إلى مزوّد مملوك لتخطيط الفهرس أو الحجب. | | `suppressions` | `object[]` | صفوف نماذج من مصدر آخر يحجبها هذا Plugin لسبب خاص بالمزوّد. | | `discovery` | `Record` | ما إذا كان يمكن قراءة فهرس المزوّد من بيانات البيان الوصفية، أو تحديثه في ذاكرة التخزين المؤقت، أو يتطلب وقت التشغيل. | | `runtimeAugment` | `boolean` | اضبطه على `true` فقط عندما يجب على وقت تشغيل المزوّد إلحاق صفوف فهرس بعد تخطيط البيان/الإعدادات. | تشارك `aliases` في البحث عن ملكية المزوّد لتخطيط فهرس النماذج. يجب أن تكون أهداف الأسماء البديلة مزوّدين على المستوى الأعلى يملكهم Plugin نفسه. عندما تستخدم قائمة مفلترة حسب المزوّد اسمًا بديلًا، يستطيع OpenClaw قراءة البيان المالك وتطبيق تجاوزات واجهة 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[]` | بادئات تُزال قبل البحث عن الاسم البديل، مفيدة لتكرار `provider/model` القديم. | | `prefixWhenBare` | `string` | بادئة تُضاف عندما لا يحتوي معرّف النموذج المُطبَّع مسبقًا على `/`. | | `prefixWhenBareAfterAliasStartsWith` | `object[]` | قواعد مشروطة لبادئة المعرّف المجرد بعد البحث عن الاسم البديل، مفهرسة حسب `modelPrefix` و`prefix`. | ## مرجع providerEndpoints استخدم `providerEndpoints` لتصنيف نقاط النهاية الذي يجب أن تعرفه سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد. لا تزال النواة تملك معنى كل `endpointClass`؛ وتملك بيانات Manifest الخاصة بـ 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`. | ## مرجع secretProviderIntegrations استخدم `secretProviderIntegrations` عندما يستطيع Plugin نشر إعداد مسبق قابل لإعادة الاستخدام لمزوّد SecretRef من نوع exec. يقرأ OpenClaw بيانات التعريف هذه قبل تحميل وقت تشغيل Plugin، ويخزّن ملكية Plugin في `secrets.providers..pluginIntegration`، ويترك حل الأسرار الفعلي إلى وقت تشغيل SecretRef. لا تُعرَض الإعدادات المسبقة إلا للـ plugins المضمّنة والـ plugins المثبّتة المكتشفة من جذور تثبيت plugins المُدارة، مثل تثبيتات git وClawHub. ```json { "secretProviderIntegrations": { "secret-store": { "providerAlias": "team-secrets", "displayName": "Team secrets", "source": "exec", "command": "${node}", "args": ["./bin/resolve-secrets.mjs"] } } } ``` مفتاح الخريطة هو معرّف التكامل. إذا حُذف `providerAlias`، يستخدم OpenClaw معرّف التكامل كاسم بديل لمزوّد SecretRef. يجب أن تطابق أسماء المزوّدين البديلة نمط اسم مزوّد SecretRef البديل العادي، مثل `team-secrets` أو `onepassword-work`. عندما يختار المشغّل الإعداد المسبق، يكتب OpenClaw مرجع مزوّد مثل: ```json { "secrets": { "providers": { "team-secrets": { "source": "exec", "pluginIntegration": { "pluginId": "acme-secrets", "integrationId": "secret-store" } } } } } ``` عند بدء التشغيل/إعادة التحميل، يحل OpenClaw ذلك المزوّد عبر تحميل بيانات تعريف بيان Plugin الحالية، والتحقق من أن Plugin المالك مثبّت ونشط، وتجسيد أمر exec من البيان. يؤدي تعطيل Plugin أو إزالته إلى إبطال المزوّد لـ SecretRefs النشطة. ما زال بإمكان المشغّلين الذين يريدون إعداد exec مستقلًا كتابة مزوّدي `command`/`args` يدويًا مباشرة. الإعدادات المسبقة ذات `source: "exec"` فقط مدعومة حاليًا. يجب أن يكون `command` هو `${node}`، ويجب أن يكون `args[0]` سكربت حل نسبيًا إلى جذر Plugin وبادئًا بـ `./`. يجسّده OpenClaw عند بدء التشغيل/إعادة التحميل إلى ملف Node التنفيذي الحالي ومسار السكربت المطلق داخل Plugin. خيارات Node مثل `--require` و`--import` و`--loader` و`--env-file` و`--eval` و`--print` ليست جزءًا من عقد الإعداد المسبق في البيان. يستطيع المشغّلون الذين يحتاجون أوامر غير Node إعداد مزوّدي exec يدويين مستقلين مباشرة. يشتق OpenClaw `trustedDirs` لإعدادات البيان المسبقة من جذر Plugin، ولإعدادات `${node}` المسبقة، من دليل ملف Node التنفيذي الحالي. يتم تجاهل `trustedDirs` المكتوبة في البيان. تمر خيارات مزوّد exec الأخرى مثل `timeoutMs` و`maxOutputBytes` و`jsonOnly` و`env` و`passEnv` و`allowInsecurePath` إلى إعداد مزوّد exec العادي في SecretRef. ## مرجع modelPricing استخدم `modelPricing` عندما يحتاج مزوّد إلى سلوك تسعير في مستوى التحكم قبل تحميل وقت التشغيل. يقرأ مخبأ تسعير Gateway بيانات التعريف هذه من دون استيراد كود وقت تشغيل المزوّد. ```json { "providers": ["ollama", "openrouter"], "modelPricing": { "providers": { "ollama": { "external": false }, "openrouter": { "openRouter": { "passthroughProviderModel": true }, "liteLLM": false } } } } ``` حقول المزوّد: | الحقل | النوع | ما يعنيه | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | | `external` | `boolean` | اضبطه على `false` للمزوّدين المحليين/ذاتيّي الاستضافة الذين يجب ألا يجلبوا أبدًا تسعير OpenRouter أو LiteLLM. | | `openRouter` | `false \| object` | ربط بحث تسعير OpenRouter. يعطّل `false` بحث OpenRouter لهذا المزوّد. | | `liteLLM` | `false \| object` | ربط بحث تسعير LiteLLM. يعطّل `false` بحث LiteLLM لهذا المزوّد. | حقول المصدر: | الحقل | النوع | ما يعنيه | | -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | معرّف مزوّد الفهرس الخارجي عندما يختلف عن معرّف مزوّد OpenClaw، مثل `z-ai` لمزوّد `zai`. | | `passthroughProviderModel` | `boolean` | عامل معرّفات النماذج التي تحتوي على شرطة مائلة كمراجع مزوّد/نموذج متداخلة، وهذا مفيد لمزوّدين وكيلين مثل OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | متغيرات إضافية لمعرّف نموذج الفهرس الخارجي. يحاول `version-dots` معرّفات الإصدارات المنقّطة مثل `claude-opus-4.6`. | ### فهرس مزوّدي OpenClaw فهرس مزوّدي OpenClaw هو بيانات تعريف معاينة مملوكة لـ OpenClaw للمزوّدين الذين قد لا تكون plugins الخاصة بهم مثبّتة بعد. وهو ليس جزءًا من بيان Plugin. تظل بيانات plugins هي سلطة الـ Plugin المثبّت. فهرس المزوّدين هو عقد الرجوع الداخلي الذي ستستهلكه أسطح مزوّدي التثبيت المستقبلية وأسطح اختيار النماذج قبل التثبيت عندما لا يكون 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.compat.pluginApi` | أدنى نطاق مطلوب لواجهة برمجة تطبيقات Plugin في OpenClaw لهذه الحزمة، باستخدام حد أدنى من semver مثل `>=2026.5.27`. | | `openclaw.install.expectedIntegrity` | سلسلة تكامل dist المتوقعة من npm مثل `sha512-...`؛ تتحقق مسارات التثبيت والتحديث من الأثر المجلب بمقارنتها بها. | | `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمن عندما يكون التكوين غير صالح. | | `openclaw.install.requiredPlatformPackages` | أسماء حزم npm البديلة التي يجب أن تتحقق عندما تطابق قيود منصة ملف القفل المضيف الحالي. | | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح بتحميل أسطح قناة وقت تشغيل الإعداد قبل الاستماع، ثم يؤجل Plugin القناة المكوّنة الكامل إلى ما بعد تفعيل ما بعد الاستماع. | تحدد بيانات البيان الوصفية خيارات المزود/القناة/الإعداد التي تظهر في الإعداد الأولي قبل تحميل وقت التشغيل. يخبر `package.json#openclaw.install` الإعداد الأولي بكيفية جلب Plugin هذا أو تمكينه عندما يختار المستخدم أحد تلك الخيارات. لا تنقل تلميحات التثبيت إلى `openclaw.plugin.json`. يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل البيانات الوصفية لمصادر Plugin غير المضمنة. تُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتخطى Plugins الخارجية على المضيفات الأقدم. يُفترض أن Plugins المصدر المضمنة متزامنة الإصدار مع نسخة المضيف المحلية. `openclaw.install.requiredPlatformPackages` مخصص لحزم npm التي تعرض ثنائيات أصلية مطلوبة عبر أسماء بديلة اختيارية خاصة بالمنصة. اسرد اسم حزمة npm المجرد لكل اسم بديل مدعوم للمنصة. أثناء تثبيت npm، يتحقق OpenClaw فقط من الاسم البديل المعلن الذي تطابق قيود ملف القفل لديه المضيف الحالي. إذا أبلغ npm عن النجاح لكنه أغفل ذلك الاسم البديل، يعيد OpenClaw المحاولة مرة واحدة بذاكرة تخزين مؤقت جديدة ويتراجع عن التثبيت إذا ظل الاسم البديل مفقودًا. يُفرض `openclaw.compat.pluginApi` أثناء تثبيت الحزمة لمصادر Plugin غير المضمنة. استخدمه لحد واجهة برمجة تطبيقات SDK/وقت تشغيل Plugin في OpenClaw الذي بُنيت الحزمة عليه. يمكن أن يكون أكثر صرامة من `minHostVersion` عندما تحتاج حزمة Plugin إلى واجهة برمجة تطبيقات أحدث لكنها لا تزال تحتفظ بتلميح تثبيت أدنى لمسارات أخرى. ترفع مزامنة إصدارات OpenClaw الرسمية حدود واجهة برمجة تطبيقات Plugin الرسمية الحالية إلى إصدار OpenClaw افتراضيًا، لكن إصدارات Plugin فقط يمكنها الاحتفاظ بحد أدنى أقل عندما تدعم الحزمة عمدًا مضيفات أقدم. لا تستخدم إصدار الحزمة وحده كعقد توافق. تظل `peerDependencies.openclaw` بيانات وصفية لحزمة npm؛ ويستخدم OpenClaw عقد `openclaw.compat.pluginApi` لاتخاذ قرارات توافق التثبيت. يجب أن تستخدم بيانات التثبيت عند الطلب الرسمية `clawhubSpec` عندما يكون Plugin منشورًا على ClawHub؛ يتعامل الإعداد الأولي مع ذلك كمصدر بعيد مفضل ويسجل حقائق أثر ClawHub بعد التثبيت. يظل `npmSpec` هو بديل التوافق للحزم التي لم تنتقل إلى ClawHub بعد. تثبيت إصدار npm الدقيق موجود بالفعل في `npmSpec`، على سبيل المثال `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. يجب أن تقرن إدخالات الفهرس الخارجية الرسمية المواصفات الدقيقة مع `expectedIntegrity` حتى تفشل مسارات التحديث بصورة مغلقة إذا لم يعد أثر npm المجلب يطابق الإصدار المثبت. لا يزال الإعداد الأولي التفاعلي يقدم مواصفات npm من السجل الموثوق، بما في ذلك أسماء الحزم المجردة و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" } } } } ``` استخدمه عندما تستطيع قناة الإجابة عن حالة التكوين من البيئة أو من مدخلات صغيرة أخرى لا تتطلب وقت التشغيل. إذا كان الفحص يحتاج إلى حل التكوين الكامل أو وقت تشغيل القناة الحقيقي، فأبق ذلك المنطق في خطاف Plugin `config.hasConfiguredState` بدلًا من ذلك. ## أسبقية الاكتشاف (معرّفات Plugin المكررة) يكتشف OpenClaw الـ Plugins من عدة جذور. لترتيب فحص نظام الملفات الخام، راجع [ترتيب فحص Plugin](/ar/gateway/configuration-reference#plugin-scan-order). إذا اشترك اكتشافان في `id` نفسه، فلن يُحتفظ إلا ببيان **الأعلى أسبقية**؛ وتُسقط النسخ المكررة الأقل أسبقية بدلًا من تحميلها بجانبه. الأسبقية، من الأعلى إلى الأدنى: 1. **محدد في التكوين** — مسار مثبت صراحةً في `plugins.entries.` 2. **مضمن** — Plugins تُشحن مع OpenClaw 3. **تثبيت عام** — Plugins مثبتة في جذر Plugin العام لـ 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.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة مصرّحًا به في بيان Plugin. - يجب أن تشير `plugins.entries.` و`plugins.allow` و`plugins.deny` و`plugins.slots.*` إلى معرّفات Plugins **قابلة للاكتشاف**. المعرّفات غير المعروفة هي **أخطاء**. - إذا كان Plugin مثبتًا لكن لديه بيان أو مخطط معطّل أو مفقود، يفشل التحقق ويبلّغ Doctor عن خطأ Plugin. - إذا كانت إعدادات Plugin موجودة لكن Plugin **معطّل**، تُحفظ الإعدادات ويظهر **تحذير** في Doctor + السجلات. راجع [مرجع الإعدادات](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل. ## ملاحظات - البيان **مطلوب لـ Plugins OpenClaw الأصلية**، بما في ذلك عمليات التحميل من نظام الملفات المحلي. لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالبيان مخصص فقط للاكتشاف + التحقق. - تُحلّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير المقتبسة ما دامت القيمة النهائية لا تزال كائنًا. - لا يقرأ محمّل البيان إلا حقول البيان الموثّقة. تجنّب المفاتيح المخصصة في المستوى الأعلى. - يمكن حذف `channels` و`providers` و`cliBackends` و`skills` كلها عندما لا يحتاج إليها Plugin. - يجب أن يبقى `providerCatalogEntry` خفيفًا وألا يستورد كود وقت تشغيل واسعًا؛ استخدمه لبيانات تعريف كتالوج المزوّد الثابتة أو واصفات الاكتشاف المحدودة، وليس للتنفيذ وقت الطلب. - تُحدّد أنواع Plugin الحصرية عبر `plugins.slots.*`: ‏`kind: "memory"` عبر `plugins.slots.memory`، و`kind: "context-engine"` عبر `plugins.slots.contextEngine` (الافتراضي `legacy`). - صرّح عن نوع Plugin الحصري في هذا البيان. تم إهمال `OpenClawPluginDefinition.kind` في مدخل وقت التشغيل ويبقى فقط كآلية احتياطية للتوافق مع Plugins الأقدم. - بيانات تعريف متغيرات البيئة (`setup.providers[].envVars`، و`providerAuthEnvVars` المهملة، و`channelEnvVars`) تصريحية فقط. لا تزال الحالة والتدقيق والتحقق من تسليم cron والأسطح الأخرى المخصصة للقراءة فقط تطبّق ثقة Plugin وسياسة التفعيل الفعلية قبل التعامل مع متغير بيئة على أنه مُعدّ. - بالنسبة إلى بيانات تعريف معالج الإعداد وقت التشغيل التي تتطلب كود المزوّد، راجع [خطافات وقت تشغيل المزوّد](/ar/plugins/architecture-internals#provider-runtime-hooks). - إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح في مدير الحزم (على سبيل المثال، pnpm `allow-build-scripts` + `pnpm rebuild `). ## ذات صلة البدء باستخدام Plugins. المعمارية الداخلية ونموذج القدرات. مرجع SDK الخاص بـ Plugin واستيرادات المسارات الفرعية.