إنشاء Provider Plugins
يأخذك هذا الدليل خطوة بخطوة عبر إنشاء plugin لموفر نماذج تضيف موفر نماذج (LLM) إلى OpenClaw. وبنهاية الدليل سيكون لديك موفر يحتوي على كتالوج نماذج، ومصادقة بمفتاح API، وتحليل ديناميكي للنماذج.إذا لم تكن قد أنشأت أي plugin لـ OpenClaw من قبل، فاقرأ
البدء أولًا للتعرّف على البنية الأساسية
للحزمة وإعداد manifest.
الشرح خطوة بخطوة
الحزمة وmanifest
providerAuthEnvVars حتى يتمكن OpenClaw من اكتشاف
بيانات الاعتماد من دون تحميل وقت تشغيل plugin الخاصة بك. أضف
providerAuthAliases عندما ينبغي لمتغير من الموفر أن يعيد استخدام مصادقة
معرّف موفر آخر. الحقل modelSupport اختياري، ويتيح لـ OpenClaw تحميل
provider plugin الخاصة بك تلقائيًا من معرّفات نماذج مختصرة مثل acme-large
قبل وجود خطافات وقت التشغيل. إذا نشرت الموفر على ClawHub، فإن حقول
openclaw.compat وopenclaw.build هذه مطلوبة في package.json.تسجيل الموفر
يحتاج الموفر الأدنى إلى هذا موفر يعمل بالفعل. يمكن للمستخدمين الآن تنفيذ
يعيد إذا كان تدفق المصادقة لديك يحتاج أيضًا إلى تصحيح
id وlabel وauth وcatalog:index.ts
openclaw onboard --acme-ai-api-key <key> واختيار
acme-ai/acme-large كنموذج لهم.إذا كان الموفر المصدر يستخدم رموز تحكم تختلف عن OpenClaw، فأضف
تحويلًا نصيًا صغيرًا ثنائي الاتجاه بدلًا من استبدال مسار البث:input كتابة مطالبة النظام النهائية ومحتوى الرسالة النصية قبل
النقل. ويعيد output كتابة دلتا نص المساعد والنص النهائي قبل أن يحلل
OpenClaw علامات التحكم الخاصة به أو قبل التسليم عبر القنوات.بالنسبة إلى الموفرين المضمّنين الذين يسجلون موفرًا نصيًا واحدًا فقط مع
مصادقة بمفتاح API بالإضافة إلى وقت تشغيل واحد مدعوم بكتالوج، ففضّل
المساعد الأضيق defineSingleProviderPluginEntry(...):models.providers.* والأسماء المستعارة والنموذج الافتراضي للوكيل أثناء
onboard، فاستخدم مساعدات preset الجاهزة من
openclaw/plugin-sdk/provider-onboard. أضيق هذه المساعدات هي
createDefaultModelPresetAppliers(...)،
وcreateDefaultModelsPresetAppliers(...)، و
createModelCatalogPresetAppliers(...).عندما تدعم نقطة النهاية الأصلية للموفر كتل الاستخدام المتدفقة على نقل
openai-completions العادي، ففضّل مساعدات الكتالوج المشتركة في
openclaw/plugin-sdk/provider-catalog-shared بدلًا من كتابة عمليات تحقق
خاصة بمعرّف الموفر. يقوم
supportsNativeStreamingUsageCompat(...) و
applyProviderNativeStreamingUsageCompat(...) باكتشاف الدعم من خريطة
إمكانات نقطة النهاية، بحيث تتمكن نقاط النهاية الأصلية على نمط
Moonshot/DashScope من الاشتراك حتى عندما تستخدم plugin معرّف موفر مخصصًا.إضافة تحليل ديناميكي للنماذج
إذا كان موفرك يقبل معرّفات نماذج عشوائية (مثل proxy أو router)،
فأضف إذا كان التحليل يتطلب استدعاءً شبكيًا، فاستخدم
resolveDynamicModel:prepareDynamicModel
للإحماء غير المتزامن — ويتم تشغيل resolveDynamicModel مرة أخرى بعد
اكتماله.إضافة خطافات وقت التشغيل (عند الحاجة)
تحتاج معظم الموفرات فقط إلى عائلات إعادة التشغيل المتاحة حاليًا:
أمثلة مضمّنة فعلية:
أمثلة مضمّنة فعلية:
catalog وresolveDynamicModel. أضف
الخطافات تدريجيًا بحسب ما يتطلبه موفرك.تغطي أدوات البناء المساعدة المشتركة الآن أكثر عائلات إعادة التشغيل/
توافق الأدوات شيوعًا، لذلك لا تحتاج plugins عادةً إلى توصيل كل خطاف
يدويًا واحدًا تلو الآخر:| العائلة | ما الذي تقوم بتوصيله |
|---|---|
openai-compatible | سياسة إعادة تشغيل مشتركة بنمط OpenAI لوسائط النقل المتوافقة مع OpenAI، بما في ذلك تنظيف tool-call-id، وإصلاحات ترتيب المساعد أولًا، والتحقق العام من أدوار Gemini حيث يحتاجه النقل |
anthropic-by-model | سياسة إعادة تشغيل مدركة لـ Claude تُختار بواسطة modelId، بحيث لا تحصل وسائط نقل رسائل Anthropic على تنظيف كتل الاستدلال الخاصة بـ Claude إلا عندما يكون النموذج المحلل فعليًا معرّف Claude |
google-gemini | سياسة إعادة تشغيل Gemini الأصلية بالإضافة إلى تنظيف إعادة تشغيل bootstrap ووضع مخرجات الاستدلال الموسومة |
passthrough-gemini | تنظيف thought-signature لنماذج Gemini التي تعمل عبر وسائط نقل proxy متوافقة مع OpenAI؛ ولا يفعّل التحقق الأصلي من إعادة تشغيل Gemini أو إعادة كتابة bootstrap |
hybrid-anthropic-openai | سياسة هجينة للموفرين الذين يخلطون بين أسطح نماذج رسائل Anthropic والأسطح المتوافقة مع OpenAI داخل plugin واحدة؛ ويظل إسقاط كتل الاستدلال الاختياري الخاصة بـ Claude محصورًا بجانب Anthropic |
googleوgoogle-gemini-cli: google-geminiopenrouterوkilocodeوopencodeوopencode-go: passthrough-geminiamazon-bedrockوanthropic-vertex: anthropic-by-modelminimax: hybrid-anthropic-openaimoonshotوollamaوxaiوzai: openai-compatible
| العائلة | ما الذي تقوم بتوصيله |
|---|---|
google-thinking | تطبيع حمولة الاستدلال في Gemini على مسار البث المشترك |
kilocode-thinking | غلاف استدلال Kilo على مسار بث proxy المشترك، مع تخطي kilo/auto ومعرّفات استدلال proxy غير المدعومة لحقن الاستدلال |
moonshot-thinking | تعيين حمولة الاستدلال الأصلية الثنائية في Moonshot انطلاقًا من الإعدادات ومستوى /think |
minimax-fast-mode | إعادة كتابة نموذج MiniMax في الوضع السريع على مسار البث المشترك |
openai-responses-defaults | أغلفة OpenAI/Codex Responses الأصلية المشتركة: رؤوس الإسناد، و/fast/serviceTier، ودرجة إسهاب النص، والبحث الأصلي على الويب في Codex، وتشكيل حمولة توافق الاستدلال، وإدارة السياق في Responses |
openrouter-thinking | غلاف استدلال OpenRouter لمسارات proxy، مع التعامل مركزيًا مع تخطي النماذج غير المدعومة/auto |
tool-stream-default-on | غلاف tool_stream مفعّل افتراضيًا لموفرين مثل Z.AI الذين يريدون بث الأدوات ما لم يتم تعطيله صراحةً |
googleوgoogle-gemini-cli: google-thinkingkilocode: kilocode-thinkingmoonshot: moonshot-thinkingminimaxوminimax-portal: minimax-fast-modeopenaiوopenai-codex: openai-responses-defaultsopenrouter: openrouter-thinkingzai: tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared أيضًا تعداد
عائلات إعادة التشغيل بالإضافة إلى المساعدات المشتركة التي تُبنى منها هذه
العائلات. وتشمل التصديرات العامة الشائعة:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- أدوات بناء إعادة التشغيل المشتركة مثل
buildOpenAICompatibleReplayPolicy(...)، وbuildAnthropicReplayPolicyForModel(...)، وbuildGoogleGeminiReplayPolicy(...)، وbuildHybridAnthropicOrOpenAIReplayPolicy(...) - مساعدات إعادة تشغيل Gemini مثل
sanitizeGoogleGeminiReplayHistory(...)وresolveTaggedReasoningOutputMode() - مساعدات نقطة النهاية/النموذج مثل
resolveProviderEndpoint(...)، وnormalizeProviderId(...)، وnormalizeGooglePreviewModelId(...)، وnormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream أداة بناء العائلة
العامة ومساعدات الأغلفة العامة التي تعيد هذه العائلات استخدامها. وتشمل
التصديرات العامة الشائعة:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- أغلفة OpenAI/Codex المشتركة مثل
createOpenAIAttributionHeadersWrapper(...)، وcreateOpenAIFastModeWrapper(...)، وcreateOpenAIServiceTierWrapper(...)، وcreateOpenAIResponsesContextManagementWrapper(...)، وcreateCodexNativeWebSearchWrapper(...) - أغلفة proxy/الموفر المشتركة مثل
createOpenRouterWrapper(...)، وcreateToolStreamWrapper(...)، وcreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider
الدوال wrapAnthropicProviderStream وresolveAnthropicBetas،
وresolveAnthropicFastMode، وresolveAnthropicServiceTier،
وأدوات بناء أغلفة Anthropic منخفضة المستوى من نقطة الفصل العامة api.ts /
contract-api.ts. وتبقى هذه المساعدات خاصة بـ Anthropic لأنها
ترمّز أيضًا معالجة Claude OAuth beta وبوابات context1m.تحتفظ موفرات مضمّنة أخرى أيضًا بأغلفة خاصة بالنقل محليًا عندما لا يكون
السلوك قابلاً للمشاركة بشكل نظيف بين العائلات. المثال الحالي: تحتفظ
plugin xAI المضمّنة بتشكيل xAI Responses الأصلية داخل
wrapStreamFn الخاصة بها، بما في ذلك إعادة كتابة الأسماء المستعارة لـ /fast،
وtool_stream الافتراضي، وتنظيف الأدوات الصارمة غير المدعومة، وإزالة
حمولة الاستدلال الخاصة بـ xAI.يوفّر openclaw/plugin-sdk/provider-tools حاليًا عائلة مشتركة
واحدة لمخططات الأدوات، إلى جانب مساعدات المخطط/التوافق المشتركة:- توثّق
ProviderToolCompatFamilyجرد العائلات المشتركة المتاح اليوم. - تقوم
buildProviderToolCompatFamilyHooks("gemini")بتوصيل تنظيف مخطط Gemini والتشخيصات للموفرين الذين يحتاجون إلى مخططات أدوات آمنة لـ Gemini. - تمثل
normalizeGeminiToolSchemas(...)وinspectGeminiToolSchemas(...)مساعدات مخطط Gemini العامة الأساسية. - تعيد
resolveXaiModelCompatPatch()تصحيح التوافق المضمّن لـ xAI:toolSchemaProfile: "xai"، والكلمات المفتاحية غير المدعومة في المخطط، ودعمweb_searchالأصلي، وفك ترميز وسائط استدعاء الأدوات من HTML entity. - تطبق
applyXaiModelCompat(model)تصحيح توافق xAI نفسه على نموذج محلول قبل أن يصل إلى المنفّذ.
normalizeResolvedModel و
contributeResolvedModelCompat للحفاظ على امتلاك الموفر لبيانات
التوافق الوصفية هذه بدلًا من ترميز قواعد xAI داخل core.ويدعم نمط جذر الحزمة نفسه أيضًا موفرات مضمّنة أخرى:@openclaw/openai-provider: يصدّرapi.tsأدوات بناء الموفر، ومساعدات النموذج الافتراضي، وأدوات بناء موفرات realtime@openclaw/openrouter-provider: يصدّرapi.tsأداة بناء الموفر بالإضافة إلى مساعدات onboarding/الإعدادات
- تبادل الرموز
- رؤوس مخصصة
- هوية النقل الأصلية
- الاستخدام والفوترة
بالنسبة إلى الموفرين الذين يحتاجون إلى تبادل رمز قبل كل استدعاء استدلال:
جميع خطافات الموفر المتاحة
جميع خطافات الموفر المتاحة
يستدعي OpenClaw الخطافات بهذا الترتيب. معظم الموفرين يستخدمون 2-3 فقط:
ملاحظات حول الرجوع الاحتياطي في وقت التشغيل:
| # | الخطاف | متى يُستخدم |
|---|---|---|
| 1 | catalog | كتالوج النماذج أو القيم الافتراضية لـ base URL |
| 2 | applyConfigDefaults | القيم الافتراضية العامة المملوكة للموفر أثناء materialization للإعدادات |
| 3 | normalizeModelId | تنظيف الأسماء المستعارة القديمة/التجريبية لمعرّف النموذج قبل البحث |
| 4 | normalizeTransport | تنظيف api / baseUrl لعائلة الموفر قبل تجميع النموذج العام |
| 5 | normalizeConfig | تطبيع إعدادات models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | إعادة كتابة توافق الاستخدام الأصلي المتدفق لموفري الإعدادات |
| 7 | resolveConfigApiKey | تحليل مصادقة env-marker المملوك للموفر |
| 8 | resolveSyntheticAuth | مصادقة اصطناعية محلية/مستضافة ذاتيًا أو معتمدة على الإعدادات |
| 9 | shouldDeferSyntheticProfileAuth | خفض أولوية العناصر النائبة الاصطناعية المخزنة للملف الشخصي خلف مصادقة env/config |
| 10 | resolveDynamicModel | قبول معرّفات نماذج عشوائية من المصدر |
| 11 | prepareDynamicModel | جلب بيانات وصفية غير متزامن قبل التحليل |
| 12 | normalizeResolvedModel | إعادة كتابة النقل قبل المنفّذ |
-
يتحقق
normalizeConfigمن الموفر المطابق أولًا، ثم من provider plugins الأخرى القادرة على الخطافات إلى أن تغيّر إحداها الإعدادات فعلًا. وإذا لم تعِد أي خطافات موفر كتابة إدخال إعدادات مدعومًا من عائلة Google، فسيستمر تطبيق مطبّع إعدادات Google المضمّن. -
تستخدم
resolveConfigApiKeyخطاف الموفر عندما يكون مكشوفًا. كما أن المسار المضمّنamazon-bedrockيملك هنا أيضًا محلل AWS env-marker مضمّنًا، رغم أن مصادقة وقت تشغيل Bedrock نفسها ما تزال تستخدم سلسلة AWS SDK الافتراضية. | 13 |contributeResolvedModelCompat| أعلام التوافق لنماذج المورّد خلف نقل متوافق آخر | | 14 |capabilities| حقيبة إمكانات ثابتة قديمة؛ للتوافق فقط | | 15 |normalizeToolSchemas| تنظيف مخطط الأدوات المملوك للموفر قبل التسجيل | | 16 |inspectToolSchemas| تشخيصات مخطط الأدوات المملوكة للموفر | | 17 |resolveReasoningOutputMode| عقد مخرجات الاستدلال الموسوم مقابل الأصلي | | 18 |prepareExtraParams| معاملات الطلب الافتراضية | | 19 |createStreamFn| نقل StreamFn مخصص بالكامل | | 20 |wrapStreamFn| أغلفة رؤوس/جسم مخصصة على مسار البث العادي | | 21 |resolveTransportTurnState| رؤوس/بيانات وصفية أصلية لكل دورة | | 22 |resolveWebSocketSessionPolicy| رؤوس جلسات WS الأصلية/فترة التهدئة | | 23 |formatApiKey| شكل رمز وقت تشغيل مخصص | | 24 |refreshOAuth| تحديث OAuth مخصص | | 25 |buildAuthDoctorHint| إرشادات إصلاح المصادقة | | 26 |matchesContextOverflowError| كشف تجاوز السعة السياقية المملوك للموفر | | 27 |classifyFailoverReason| تصنيف مملوك للموفر لحدّ المعدل/الحمل الزائد | | 28 |isCacheTtlEligible| بوابة TTL لذاكرة prompt المؤقتة | | 29 |buildMissingAuthMessage| تلميح مخصص لغياب المصادقة | | 30 |suppressBuiltInModel| إخفاء الصفوف المصدرية القديمة | | 31 |augmentModelCatalog| صفوف اصطناعية للتوافق المستقبلي | | 32 |isBinaryThinking| تشغيل/إيقاف الاستدلال الثنائي | | 33 |supportsXHighThinking| دعم الاستدلالxhigh| | 34 |resolveDefaultThinkingLevel| سياسة/thinkالافتراضية | | 35 |isModernModelRef| مطابقة النماذج المباشرة/اختبارات smoke | | 36 |prepareRuntimeAuth| تبادل الرمز قبل الاستدلال | | 37 |resolveUsageAuth| تحليل بيانات اعتماد الاستخدام المخصص | | 38 |fetchUsageSnapshot| نقطة نهاية استخدام مخصصة | | 39 |createEmbeddingProvider| مُكيّف embeddings مملوك للموفر للذاكرة/البحث | | 40 |buildReplayPolicy| سياسة مخصصة لإعادة تشغيل/ضغط السجل النصي | | 41 |sanitizeReplayHistory| إعادة كتابة مملوكة للموفر لسجل إعادة التشغيل بعد التنظيف العام | | 42 |validateReplayTurns| تحقق صارم من أدوار إعادة التشغيل قبل المنفّذ المضمّن | | 43 |onModelSelected| استدعاء بعد الاختيار (مثلًا telemetry) | ملاحظة حول ضبط prompt:- تسمح
resolveSystemPromptContributionللموفر بحقن إرشادات مطالبة نظام مدركة لذاكرة التخزين المؤقت لعائلة نماذج. فضّلها علىbefore_prompt_buildعندما يكون السلوك تابعًا لعائلة موفر/نموذج واحدة ويجب أن يحافظ على التقسيم المستقر/الديناميكي لذاكرة التخزين المؤقت.
- تسمح
إضافة إمكانات إضافية (اختياري)
يمكن لـ provider plugin تسجيل موفر للكلام، والنسخ الفوري، والصوت الفوري،
وفهم الوسائط، وتوليد الصور، وتوليد الفيديو، وجلب الويب،
والبحث على الويب إلى جانب الاستدلال النصي:يصنّف OpenClaw هذا على أنه plugin ذات إمكانات هجينة. وهذا هو
النمط الموصى به لـ plugins الخاصة بالشركات (plugin واحدة لكل مورّد). راجع
الداخليات: ملكية الإمكانات.بالنسبة إلى توليد الفيديو، فضّل بنية الإمكانات المدركة للأوضاع كما هو موضح أعلاه:
generate وimageToVideo وvideoToVideo. إن الحقول
التجميعية المسطحة مثل maxInputImages وmaxInputVideos وmaxDurationSeconds
لا تكفي للإعلان بوضوح عن دعم أوضاع التحويل أو الأوضاع المعطّلة.ينبغي لموفري توليد الموسيقى اتباع النمط نفسه:
generate للتوليد المعتمد على المطالبة فقط وedit للتوليد
المعتمد على الصور المرجعية. إن الحقول التجميعية المسطحة مثل maxInputImages،
وsupportsLyrics، وsupportsFormat لا تكفي للإعلان عن دعم
التعديل؛ إذ إن كتل generate / edit الصريحة هي العقد المتوقع.النشر إلى ClawHub
يتم نشر Provider Plugins بالطريقة نفسها مثل أي plugin خارجية أخرى للشفرة:clawhub package publish.
بنية الملفات
مرجع ترتيب الكتالوج
يتحكمcatalog.order في وقت دمج كتالوجك مقارنةً بالموفرين
المضمّنين:
| الترتيب | متى | حالة الاستخدام |
|---|---|---|
simple | المرور الأول | الموفّرون العاديون المعتمدون على مفتاح API |
profile | بعد simple | الموفّرون المقيّدون بملفات تعريف المصادقة |
paired | بعد profile | توليف عدة إدخالات مترابطة |
late | المرور الأخير | تجاوز الموفّرين الحاليين (يفوز عند التعارض) |
الخطوات التالية
- Channel Plugins — إذا كانت plugin الخاصة بك توفّر قناة أيضًا
- SDK Runtime — مساعدات
api.runtime(TTS، والبحث، والوكيل الفرعي) - نظرة عامة على SDK — المرجع الكامل للاستيراد عبر المسارات الفرعية
- داخليات Plugin — تفاصيل الخطافات والأمثلة المضمّنة