بيان 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، والقيم الافتراضية في settings.json لـ Claude، وقيم LSP الافتراضية لـ Claude، وحزم الخطافات المدعومة، عندما يتوافق التخطيط مع توقعات وقت تشغيل OpenClaw.

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

راجع Plugins للاطلاع على الدليل الكامل لنظام 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"      }    }  }}

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

مرجع catalog

يوفّر 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 المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن التي يعتمد مصنعها على المصادقة أو الإعدادات، ينبغي لمؤلفي الـ 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 قد نُفذت بالفعل. يستخدم مخطِّط التفعيل هذه الحقول لتضييق نطاق إضافات Plugin المرشحة قبل الرجوع إلى بيانات الملكية الوصفية الحالية في البيان، مثل 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 بدلًا منها. تسميات الأسباب هذه مخصصة لتشخيصات المضيف والاختبارات؛ وينبغي لمؤلفي Plugin الاستمرار في التصريح بالبيانات الوصفية التي تصف الملكية على أفضل وجه.

مرجع qaRunners

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

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

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

مرجع 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.

استخدم 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 الخاصة بالمزوّد.

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

حقول setup

مرجع uiHints

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

{  "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"],    "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. يستخدم اكتشاف الأدوات هذه القائمة لتحميل بيئات تشغيل الـ Plugins التي يمكنها امتلاك الأدوات المطلوبة فقط.

ينبغي للـ 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 الذي تحتاج إليه مساعدات النواة العامة من دون استيراد وقت تشغيل الـ 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، لكن مخطط إعدادات المسار البارد، والإعداد، وواجهات 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ين صراحةً (عبر 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": "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؛ بينما تملك بيانات الـ Plugin الوصفية للمضيف وعنوان URL الأساسي.

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

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

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

يجب ألا يحتوي فهرس المزوّدين على أسرار أو حالة التفعيل أو خطافات وقت التشغيل أو بيانات نماذج حية خاصة بحساب معيّن. تستخدم كتالوجات المعاينة فيه بنية صف مزوّد modelCatalog نفسها المستخدمة في بيانات Plugins، لكن ينبغي أن تظل مقتصرة على بيانات العرض الوصفية المستقرة، ما لم تُحاذَ عمدًا حقول مهايئ وقت التشغيل، مثل 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؛ ويجب على Plugins الأصلية استخدام openclaw.plugin.json إلى جانب حقول package.json#openclaw المدعومة أدناه.

أمثلة مهمة:

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

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

يُستخدم 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 من السجلات الموثوقة، بما في ذلك أسماء الحزم المجرّدة ووسوم التوزيع، لأغراض التوافق. يمكن لتشخيصات الفهرس التمييز بين المصادر الدقيقة والعائمة والمثبّتة بالتكامل والمفتقدة للتكامل وغير المتطابقة في اسم الحزمة وغير الصالحة في الاختيار الافتراضي. كما تحذّر عندما يكون expectedIntegrity موجودًا من دون مصدر npm صالح يمكن تثبيته عليه. عند وجود expectedIntegrity، تفرضه مسارات التثبيت/التحديث؛ وعند حذفه، يُسجّل تحليل السجل من دون تثبيت للتكامل.

يجب أن توفر ملحقات Plugin الخاصة بالقنوات 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"      }    }  }}

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

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

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

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

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

يكتشف OpenClaw ملحقات Plugin من ثلاثة جذور، تُفحص بهذا الترتيب: ملحقات Plugin المضمّنة التي تأتي مع 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. مضمّن — ملحقات Plugin التي تأتي مع OpenClaw
4. مساحة العمل — ملحقات Plugin المكتشفة نسبةً إلى مساحة العمل الحالية
5. أي مرشح مكتشف آخر

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

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

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

• يجب أن يوفّر كل 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.allow أو plugins.entries أو plugins.installs (أي Plugin مشار إليه لكن لا يمكن اكتشافه حاليًا)، فإن OpenClaw يخفض مستوى ذلك إلى تحذير بدلًا من ذلك.
• تُعد الإشارات إلى معرّفات Plugins غير معروفة في plugins.entries.<id> وplugins.allow وplugins.deny تحذيرات ("يُتجاهل إدخال إعدادات قديم") وليست أخطاء، كي لا تمنع الترقيات وPlugins المحذوفة أو المعاد تسميتها تشغيل Gateway.
• تُعد إشارة plugins.slots.memory إلى معرّف Plugin غير معروف خطأً، باستثناء Plugin الخارجي الرسمي المعروف memory-lancedb، إذ يصدر تحذيرًا بدلًا من ذلك.
• إذا كان Plugin مثبّتًا لكن بيانه أو مخططه تالف أو مفقود، يفشل التحقق من الصحة ويبلغ Doctor عن خطأ Plugin.
• إذا كانت إعدادات 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 يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح الخاصة بمدير الحزم (على سبيل المثال، allow-build-scripts في pnpm مع pnpm rebuild <package>).

ذو صلة