ملف بيان Plugin

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

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

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

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

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

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

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

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

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

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

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

• هوية Plugin، والتحقق من صحة الإعدادات، وتلميحات واجهة مستخدم الإعدادات
• بيانات تعريف المصادقة، والإعداد الأولي، والتجهيز (الاسم المستعار، والتمكين التلقائي، ومتغيرات بيئة المزوّد، وخيارات المصادقة)
• تلميحات التنشيط لأسطح مستوى التحكم
• ملكية مختصرة لعائلة النماذج
• لقطات ثابتة لملكية الإمكانات (contracts)
• بيانات تعريف مشغّل ضمان الجودة التي يمكن لمضيف 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": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

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

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

تصف حقول بيانات تعريف مزوّد التوليد إشارات المصادقة الثابتة للمزوّدين المصرّح عنهم في قائمة 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، يحافظ OpenClaw على السلوك الحالي ويحمّل Plugin المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن التي يعتمد مصنعها على المصادقة/التكوين، يجب على مؤلفي Plugin التصريح عن toolMetadata بدلًا من جعل النواة تستورد وقت التشغيل للسؤال.

مرجع providerAuthChoices

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

مرجع commandAliases

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

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

مرجع 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 أو الذاكرة أو محفزات تفعيل أضيق أخرى.

{  "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 القديمين
• يستخدم تخطيط بدء تشغيل وقت تشغيل 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.

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

مرجع setup

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

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

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

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

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

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

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

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

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

مرجع setup.providers

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

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

حقول setup

مرجع uiHints

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

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

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

مرجع contracts

استخدم 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"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "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 المسجِّل، لذلك يمكن لـ 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.

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

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

مرجع channelConfigs

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

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

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

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

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

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

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

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

استبدال 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ين صراحة، فإن OpenClaw يحافظ على هذا الاختيار ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من تغيير مجموعة Plugins المطلوبة بصمت.

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

مرجع modelSupport

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

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

يطبّق OpenClaw ترتيب الأولوية هذا:

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

الحقول:

تُصرَّف إدخالات 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": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

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

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

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

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

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

حقول الحجب:

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

مرجع modelIdNormalization

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

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

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

مرجع providerEndpoints

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

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

مرجع providerRequest

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

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

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

مرجع secretProviderIntegrations

استخدم secretProviderIntegrations عندما يستطيع Plugin نشر إعداد مسبق قابل لإعادة الاستخدام لمزوّد SecretRef من نوع exec. يقرأ OpenClaw بيانات التعريف هذه قبل تحميل وقت تشغيل Plugin، ويخزّن ملكية Plugin في secrets.providers.<alias>.pluginIntegration، ويترك حل الأسرار الفعلي إلى وقت تشغيل SecretRef. لا تُعرَض الإعدادات المسبقة إلا للـ plugins المضمّنة والـ plugins المثبّتة المكتشفة من جذور تثبيت plugins المُدارة، مثل تثبيتات 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 المالك مثبّت ونشط، وتجسيد أمر 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 بيانات التعريف هذه من دون استيراد كود وقت تشغيل المزوّد.

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

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

حقول المصدر:

فهرس مزوّدي 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، فضعه في 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 المدعومة أدناه.

أمثلة مهمة:

تحدد بيانات البيان الوصفية خيارات المزود/القناة/الإعداد التي تظهر في الإعداد الأولي قبل تحميل وقت التشغيل. يخبر 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.<id> قديم لذلك Plugin المضمن نفسه. لا تزال أخطاء التكوين غير ذات الصلة تمنع التثبيت وتوجه المشغلين إلى openclaw doctor --fix.

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

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

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

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

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

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

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

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

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

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

الآثار:

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

متطلبات JSON Schema

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

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

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

سلوك التحقق

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

راجع مرجع الإعدادات للاطلاع على مخطط 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 وسياسة التفعيل الفعلية قبل التعامل مع متغير بيئة على أنه مُعدّ.
• بالنسبة إلى بيانات تعريف معالج الإعداد وقت التشغيل التي تتطلب كود المزوّد، راجع خطافات وقت تشغيل المزوّد.
• إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح في مدير الحزم (على سبيل المثال، pnpm allow-build-scripts + pnpm rebuild <package>).

ذات صلة