بيان Plugin

تتناول هذه الصفحة بيان Plugin الأصلي لـ OpenClaw، openclaw.plugin.json. للاطلاع على تخطيطات الحزم المتوافقة (Codex وClaude وCursor)، راجع حزم Plugin.

تستخدم تنسيقات الحزم المتوافقة ملفات البيان الخاصة بها بدلًا من ذلك:

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

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

يجب أن يتضمن كل Plugin أصلي لـ OpenClaw الملف openclaw.plugin.json في جذر Plugin. يقرأه OpenClaw للتحقق من صحة الإعدادات من دون تنفيذ شيفرة Plugin. يؤدي البيان المفقود أو غير الصالح إلى حظر التحقق من صحة الإعدادات، ويُعامل بوصفه خطأً في Plugin.

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

وظيفة هذا الملف

يمثل openclaw.plugin.json بيانات وصفية يقرأها OpenClaw قبل تحميل شيفرة Plugin. يجب أن يكون فحص كل ما يتضمنه قليل التكلفة بما يكفي لعدم الحاجة إلى تشغيل وقت تنفيذ Plugin.

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

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

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

مثال بسيط

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

مثال شامل

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "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": "مفتاح API لـ OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "مفتاح API لـ OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "مفتاح API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

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

مرجع الكتالوج

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

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

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

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

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

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

يدعم كل إدخال من البيانات الوصفية ما يلي:

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

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

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

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

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

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

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

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

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

مرجع providerAuthChoices

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

عندما تكون appGuidedDiscovery صحيحة، يجب أن تعرض طريقة مصادقة المزوّد المطابقة appGuidedSetup.detect وappGuidedSetup.prepare. يجب أن يكون الاكتشاف للقراءة فقط: من دون تسجيل دخول أو جلب نموذج أو تنزيل أو كتابة إعدادات. تعيد مرحلة التحضير التحقق من النموذج المحدد بعينه وتُرجع مقترح إعدادات؛ ويختبر OpenClaw ذلك المقترح مباشرةً بمعزل عن غيره ولا يعتمده إلا بعد النجاح.

مرجع commandAliases

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

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

مرجع التنشيط

استخدم 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 فهو مخصص فقط لمعرّفات بيئات وكيل التشغيل المضمّنة التي لا تمتلك حقل ملكية بالفعل.

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

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

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

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

{  "qaRunners": [    {      "commandName": "matrix",      "description": "شغّل مسار ضمان الجودة المباشر لـ Matrix والمدعوم بـ Docker على خادم منزلي مؤقت"    }  ]}

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

مرجع الإعداد

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

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "بيانات اعتماد openai المحلية"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

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

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

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

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

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

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

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

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

مرجع setup.providers

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

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

حقول الإعداد

مرجع uiHints

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

{  "uiHints": {    "apiKey": {      "label": "مفتاح API",      "help": "يُستخدم لطلبات OpenRouter",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

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

مرجع العقود

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

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

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

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

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

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

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

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

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

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

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

مرجع configContracts

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

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

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

يدعم secretInputs ما يلي:

مرجع mediaUnderstandingProviderMetadata

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

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

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

مرجع channelConfigs

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

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

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

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

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

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

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "عنوان URL للخادم المنزلي",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "اتصال خادم Matrix المنزلي",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

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

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

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

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

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

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

مرجع modelSupport

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

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

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

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

الحقول:

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

مرجع modelCatalog

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

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

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

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

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

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

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

حقول الحجب:

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

مرجع modelIdNormalization

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

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

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

مرجع providerEndpoints

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

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

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

مرجع providerRequest

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

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

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

مرجع secretProviderIntegrations

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

{  "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 مرجع مزوّد مثل:

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

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

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

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

مرجع modelPricing

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

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

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

حقول المصدر:

فهرس مزوّدي OpenClaw

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

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

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

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

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

يرحّل openclaw doctor --fix مجموعة صغيرة ومغلقة من مفاتيح إمكانات البيان القديمة ذات المستوى الأعلى إلى contracts.*: ‏speechProviders وmediaUnderstandingProviders وimageGenerationProviders وtools. لم يعد أي من هذه المفاتيح (أو أي قائمة إمكانات أخرى) يُقرأ بوصفه حقل بيان ذي مستوى أعلى؛ لا يتعرّف التحميل المعتاد للبيان عليها إلا ضمن contracts.

البيان مقارنةً بـ package.json

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

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

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

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

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

أمثلة مهمة:

تحدد البيانات الوصفية للبيان خيارات المزوّد/القناة/الإعداد التي تظهر في الإعداد الأولي قبل تحميل وقت التشغيل. يوضح 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 غير المضمّنة. استخدمه لتحديد الحد الأدنى لـ API الخاص بـ SDK/وقت تشغيل plugin في OpenClaw الذي بُنيت الحزمة بالاستناد إليه. يمكن أن يكون أكثر تقييدًا من minHostVersion عندما تحتاج حزمة plugin إلى API أحدث مع الاحتفاظ بتلميح تثبيت أدنى لتدفقات أخرى. ترفع مزامنة إصدارات OpenClaw الرسمية افتراضيًا الحدود الدنيا الحالية لـ API في الـ plugins الرسمية إلى إصدار OpenClaw، لكن الإصدارات الخاصة بالـ plugin وحده يمكنها الاحتفاظ بحد أدنى أقل عندما تكون الحزمة مصممة لدعم مضيفين أقدم. لا تستخدم إصدار الحزمة وحده بوصفه عقد التوافق. يظل peerDependencies.openclaw من بيانات حزمة npm الوصفية؛ ويستخدم OpenClaw عقد openclaw.compat.pluginApi لاتخاذ قرارات توافق التثبيت.

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

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

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

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

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

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

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

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

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

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

استخدم env.allOf عندما يكون كل متغير مدرج مطلوبًا، وenv.anyOf عندما يكفي أي متغير واحد غير فارغ. إذا احتاج فحص صغير لا يعتمد على وقت التشغيل إلى أكثر من بيانات البيئة الوصفية، فاستخدم specifier مع exportName كما هو موضح لـ persistedAuthState؛ وعند وجود env، يستخدمه OpenClaw دون تحميل تلك الوحدة. إذا احتاج الفحص إلى حل الإعداد الكامل أو وقت تشغيل القناة الحقيقي، فاحتفظ بذلك المنطق في خطاف config.hasConfiguredState الخاص بالـ plugin بدلًا من ذلك.

أولوية الاكتشاف (معرّفات plugins المكررة)

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

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

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

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

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

متطلبات JSON Schema

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

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

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

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

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

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

ملاحظات

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

ذو صلة