الانتقال إلى المحتوى الرئيسي

​
بيان المكون الإضافي (openclaw.plugin.json)

هذه الصفحة مخصصة لـ بيان المكون الإضافي الأصلي في OpenClaw فقط. للاطلاع على تخطيطات الحزم المتوافقة، راجع حزم المكونات الإضافية. تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة:
  • حزمة 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، والقيم الافتراضية لـ Claude bundle LSP، وحزم hooks المدعومة عندما يطابق التخطيط توقعات وقت تشغيل OpenClaw. يجب على كل مكون إضافي أصلي في OpenClaw أن يتضمن ملف openclaw.plugin.json في جذر المكون الإضافي. يستخدم OpenClaw هذا البيان للتحقق من صحة التكوين من دون تنفيذ كود المكون الإضافي. تُعامل البيانات المفقودة أو غير الصالحة على أنها أخطاء في المكون الإضافي وتمنع التحقق من صحة التكوين. راجع الدليل الكامل لنظام المكونات الإضافية: المكونات الإضافية. وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية: نموذج القدرات.

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

openclaw.plugin.json هو البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل كود المكون الإضافي الخاص بك. استخدمه من أجل:
  • هوية المكون الإضافي
  • التحقق من صحة التكوين
  • بيانات التعريف الخاصة بالمصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل المكون الإضافي
  • تلميحات تفعيل منخفضة التكلفة يمكن لأسطح control-plane فحصها قبل تحميل وقت التشغيل
  • واصفات إعداد منخفضة التكلفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل تحميل وقت التشغيل
  • بيانات تعريف الأسماء المستعارة والتمكين التلقائي التي يجب حلها قبل تحميل وقت تشغيل المكون الإضافي
  • بيانات تعريف مختصرة لملكية عائلة النماذج ينبغي أن تفعّل المكون الإضافي تلقائيًا قبل تحميل وقت التشغيل
  • لقطات ثابتة لملكية القدرات تُستخدم في ربط التوافق المضمّن وتغطية العقود
  • بيانات تعريف تكوين خاصة بالقنوات ينبغي دمجها في أسطح الفهرسة والتحقق من دون تحميل وقت التشغيل
  • تلميحات واجهة المستخدم للتكوين
لا تستخدمه من أجل:
  • تسجيل سلوك وقت التشغيل
  • تعريف نقاط دخول الكود
  • بيانات تعريف تثبيت npm
هذه تنتمي إلى كود المكون الإضافي الخاص بك و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-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["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"
      }
    }
  }
}

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

الحقلمطلوبالنوعما الذي يعنيه
idنعمstringالمعرّف الأساسي للمكون الإضافي. هذا هو المعرّف المستخدم في plugins.entries.<id>.
configSchemaنعمobjectمخطط JSON مضمن لتكوين هذا المكون الإضافي.
enabledByDefaultلاtrueيحدد مكونًا إضافيًا مضمّنًا على أنه مفعّل افتراضيًا. احذف هذا الحقل، أو عيّن أي قيمة غير true، لترك المكون الإضافي معطلًا افتراضيًا.
legacyPluginIdsلاstring[]معرّفات قديمة تُطبَّع إلى هذا المعرّف الأساسي للمكون الإضافي.
autoEnableWhenConfiguredProvidersلاstring[]معرّفات الموفرين التي يجب أن تفعّل هذا المكون الإضافي تلقائيًا عندما تشير المصادقة أو التكوين أو مراجع النماذج إليها.
kindلا"memory" | "context-engine"يعلن نوع مكون إضافي حصريًا يُستخدم بواسطة plugins.slots.*.
channelsلاstring[]معرّفات القنوات المملوكة لهذا المكون الإضافي. تُستخدم للاكتشاف والتحقق من صحة التكوين.
providersلاstring[]معرّفات الموفرين المملوكة لهذا المكون الإضافي.
modelSupportلاobjectبيانات تعريف مختصرة مملوكة للبيان لعائلة النماذج، وتُستخدم لتحميل المكون الإضافي تلقائيًا قبل وقت التشغيل.
cliBackendsلاstring[]معرّفات الواجهات الخلفية للاستدلال في CLI المملوكة لهذا المكون الإضافي. تُستخدم للتفعيل التلقائي عند بدء التشغيل انطلاقًا من مراجع التكوين الصريحة.
commandAliasesلاobject[]أسماء الأوامر المملوكة لهذا المكون الإضافي والتي ينبغي أن تُنتج تشخيصات واعية بالمكون الإضافي للتكوين وCLI قبل تحميل وقت التشغيل.
providerAuthEnvVarsلاRecord<string, string[]>بيانات تعريف منخفضة التكلفة لمتغيرات البيئة الخاصة بمصادقة الموفر، ويمكن لـ OpenClaw فحصها من دون تحميل كود المكون الإضافي.
providerAuthAliasesلاRecord<string, string>معرّفات موفرين يجب أن تعيد استخدام معرّف موفر آخر للبحث عن المصادقة، مثل موفر برمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة الخاصة بالموفر الأساسي.
channelEnvVarsلاRecord<string, string[]>بيانات تعريف منخفضة التكلفة لمتغيرات بيئة القنوات، ويمكن لـ OpenClaw فحصها من دون تحميل كود المكون الإضافي. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على متغيرات البيئة والتي ينبغي أن تراها أدوات البدء/التكوين العامة.
providerAuthChoicesلاobject[]بيانات تعريف منخفضة التكلفة لخيارات المصادقة لمحددات الإعداد الأولي، وحل الموفر المفضل، وربط أعلام CLI البسيط.
activationلاobjectتلميحات تفعيل منخفضة التكلفة للتحميل المُحفَّز بواسطة الموفر أو الأمر أو القناة أو المسار أو القدرة. بيانات تعريف فقط؛ لا يزال وقت تشغيل المكون الإضافي يملك السلوك الفعلي.
setupلاobjectواصفات إعداد/تهيئة أولية منخفضة التكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل المكون الإضافي.
contractsلاobjectلقطة ثابتة للقدرات المضمّنة من أجل speech، وrealtime transcription، وrealtime voice، وmedia-understanding، وimage-generation، وmusic-generation، وvideo-generation، وweb-fetch، وweb search، وملكية الأدوات.
channelConfigsلاRecord<string, object>بيانات تعريف تكوين القنوات المملوكة للبيان والمُدمجة في أسطح الاكتشاف والتحقق من الصحة قبل تحميل وقت التشغيل.
skillsلاstring[]أدلة Skills التي سيتم تحميلها، نسبةً إلى جذر المكون الإضافي.
nameلاstringاسم مقروء بشريًا للمكون الإضافي.
descriptionلاstringملخص قصير يظهر في أسطح المكونات الإضافية.
versionلاstringإصدار معلوماتي للمكون الإضافي.
uiHintsلاRecord<string, object>تسميات واجهة المستخدم والعناصر النائبة وتلميحات الحساسية لحقول التكوين.

​
مرجع providerAuthChoices

يصف كل إدخال في providerAuthChoices خيارًا واحدًا للإعداد الأولي أو المصادقة. يقرأ OpenClaw هذا قبل تحميل وقت تشغيل الموفر.
الحقلمطلوبالنوعما الذي يعنيه
providerنعمstringمعرّف الموفر الذي ينتمي إليه هذا الخيار.
methodنعمstringمعرّف أسلوب المصادقة الذي سيتم التوجيه إليه.
choiceIdنعمstringمعرّف ثابت لخيار المصادقة يُستخدم بواسطة تدفقات الإعداد الأولي وCLI.
choiceLabelلاstringتسمية موجهة للمستخدم. إذا حُذفت، يعود OpenClaw إلى choiceId.
choiceHintلاstringنص مساعد قصير للمحدد.
assistantPriorityلاnumberتُرتَّب القيم الأقل أولًا في المحددات التفاعلية التي يقودها المساعد.
assistantVisibilityلا"visible" | "manual-only"يُخفي الخيار من محددات المساعد مع الاستمرار في السماح بالاختيار اليدوي عبر CLI.
deprecatedChoiceIdsلاstring[]معرّفات خيارات قديمة ينبغي أن تعيد توجيه المستخدمين إلى هذا الخيار البديل.
groupIdلاstringمعرّف مجموعة اختياري لتجميع الخيارات المرتبطة.
groupLabelلاstringتسمية موجهة للمستخدم لتلك المجموعة.
groupHintلاstringنص مساعد قصير للمجموعة.
optionKeyلاstringمفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد.
cliFlagلاstringاسم علم CLI، مثل --openrouter-api-key.
cliOptionلاstringصيغة خيار CLI الكاملة، مثل --openrouter-api-key <key>.
cliDescriptionلاstringالوصف المستخدم في تعليمات CLI.
onboardingScopesلاArray<"text-inference" | "image-generation">أسطح الإعداد الأولي التي ينبغي أن يظهر فيها هذا الخيار. إذا حُذفت، فالقيمة الافتراضية هي ["text-inference"].

​
مرجع commandAliases

استخدم commandAliases عندما يملك المكون الإضافي اسم أمر وقت تشغيل قد يضعه المستخدمون عن طريق الخطأ في plugins.allow أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل المكون الإضافي. 
{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}
الحقلمطلوبالنوعما الذي يعنيه
nameنعمstringاسم الأمر الذي ينتمي إلى هذا المكون الإضافي.
kindلا"runtime-slash"يحدد الاسم المستعار على أنه أمر slash في الدردشة بدلًا من أمر CLI جذري.
cliCommandلاstringأمر CLI جذري ذي صلة يُقترح لعمليات CLI، إذا كان موجودًا.

​
مرجع activation

استخدم activation عندما يمكن للمكون الإضافي أن يعلن بتكلفة منخفضة عن أحداث control-plane التي ينبغي أن تفعّله لاحقًا. هذه الكتلة هي بيانات تعريف فقط. وهي لا تسجل سلوك وقت التشغيل، ولا تحل محل register(...) أو setupEntry أو نقاط دخول وقت التشغيل/المكون الإضافي الأخرى. 
{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}
الحقلمطلوبالنوعما الذي يعنيه
onProvidersلاstring[]معرّفات الموفرين التي ينبغي أن تفعّل هذا المكون الإضافي عند طلبها.
onCommandsلاstring[]معرّفات الأوامر التي ينبغي أن تفعّل هذا المكون الإضافي.
onChannelsلاstring[]معرّفات القنوات التي ينبغي أن تفعّل هذا المكون الإضافي.
onRoutesلاstring[]أنواع المسارات التي ينبغي أن تفعّل هذا المكون الإضافي.
onCapabilitiesلاArray<"provider" | "channel" | "tool" | "hook">تلميحات قدرات عامة تُستخدم في تخطيط التفعيل ضمن control-plane.

​
مرجع setup

استخدم setup عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات تعريف منخفضة التكلفة مملوكة للمكون الإضافي قبل تحميل وقت التشغيل. 
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
يبقى cliBackends على المستوى الأعلى صالحًا ويستمر في وصف الواجهات الخلفية للاستدلال في CLI. أما setup.cliBackends فهو سطح الواصفات الخاص بالإعداد من أجل تدفقات control-plane/الإعداد التي ينبغي أن تظل بيانات تعريف فقط.

​
مرجع setup.providers

الحقلمطلوبالنوعما الذي يعنيه
idنعمstringمعرّف الموفر الذي يُعرَض أثناء الإعداد أو التهيئة الأولية.
authMethodsلاstring[]معرّفات أساليب الإعداد/المصادقة التي يدعمها هذا الموفر من دون تحميل وقت التشغيل الكامل.
envVarsلاstring[]متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل المكون الإضافي.

​
حقول setup

الحقلمطلوبالنوعما الذي يعنيه
providersلاobject[]واصفات إعداد الموفر المعروضة أثناء الإعداد والتهيئة الأولية.
cliBackendsلاstring[]معرّفات الواجهات الخلفية المتاحة وقت الإعداد من دون تفعيل وقت التشغيل الكامل.
configMigrationsلاstring[]معرّفات ترحيل التكوين المملوكة لسطح إعداد هذا المكون الإضافي.
requiresRuntimeلاbooleanما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ وقت تشغيل المكون الإضافي بعد البحث عن الواصفات.

​
مرجع uiHints

uiHints هو خريطة من أسماء حقول التكوين إلى تلميحات عرض صغيرة. 
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
يمكن أن يتضمن كل تلميح حقل ما يلي:
الحقلالنوعما الذي يعنيه
labelstringتسمية الحقل الموجهة للمستخدم.
helpstringنص مساعد قصير.
tagsstring[]وسوم واجهة مستخدم اختيارية.
advancedbooleanيحدد الحقل على أنه متقدم.
sensitivebooleanيحدد الحقل على أنه سري أو حساس.
placeholderstringنص العنصر النائب لمدخلات النماذج.

​
مرجع contracts

استخدم contracts فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw قراءتها من دون استيراد وقت تشغيل المكون الإضافي. 
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
كل قائمة اختيارية:
الحقلالنوعما الذي يعنيه
speechProvidersstring[]معرّفات موفري speech التي يملكها هذا المكون الإضافي.
realtimeTranscriptionProvidersstring[]معرّفات موفري realtime transcription التي يملكها هذا المكون الإضافي.
realtimeVoiceProvidersstring[]معرّفات موفري realtime voice التي يملكها هذا المكون الإضافي.
mediaUnderstandingProvidersstring[]معرّفات موفري media-understanding التي يملكها هذا المكون الإضافي.
imageGenerationProvidersstring[]معرّفات موفري image-generation التي يملكها هذا المكون الإضافي.
videoGenerationProvidersstring[]معرّفات موفري video-generation التي يملكها هذا المكون الإضافي.
webFetchProvidersstring[]معرّفات موفري web-fetch التي يملكها هذا المكون الإضافي.
webSearchProvidersstring[]معرّفات موفري web search التي يملكها هذا المكون الإضافي.
toolsstring[]أسماء أدوات الوكيل التي يملكها هذا المكون الإضافي من أجل فحوصات العقد المضمّنة.

​
مرجع channelConfigs

استخدم channelConfigs عندما يحتاج مكون إضافي للقنوات إلى بيانات تعريف تكوين منخفضة التكلفة قبل تحميل وقت التشغيل. 
{
  "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",
      "preferOver": ["matrix-legacy"]
    }
  }
}
يمكن أن يتضمن كل إدخال قناة:
الحقلالنوعما الذي يعنيه
schemaobjectمخطط JSON لـ channels.<id>. وهو مطلوب لكل إدخال تكوين قناة مُعلن.
uiHintsRecord<string, object>تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لذلك القسم من تكوين القناة.
labelstringتسمية القناة المدمجة في أسطح المحدد والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة.
descriptionstringوصف قصير للقناة لأسطح الفحص والفهرس.
preferOverstring[]معرّفات مكونات إضافية قديمة أو أقل أولوية ينبغي أن تتفوق عليها هذه القناة في أسطح الاختيار.

​
مرجع modelSupport

استخدم modelSupport عندما ينبغي لـ OpenClaw أن يستنتج مكون الموفر الإضافي الخاص بك من معرّفات النماذج المختصرة مثل gpt-5.4 أو claude-sonnet-4.6 قبل تحميل وقت تشغيل المكون الإضافي. 
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
يطبق OpenClaw ترتيب الأولوية التالي:
  • تستخدم مراجع provider/model الصريحة بيانات تعريف providers المملوكة في البيان
  • تتفوق modelPatterns على modelPrefixes
  • إذا طابق كل من مكون إضافي غير مضمّن ومكون إضافي مضمّن، فإن المكون الإضافي غير المضمّن يفوز
  • يُتجاهل أي غموض متبقٍ حتى يحدد المستخدم أو التكوين موفرًا
الحقول:
الحقلالنوعما الذي يعنيه
modelPrefixesstring[]بادئات تُطابق باستخدام startsWith مع معرّفات النماذج المختصرة.
modelPatternsstring[]مصادر Regex تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة ملف التعريف.
مفاتيح القدرات القديمة ذات المستوى الأعلى أصبحت مهملة. استخدم openclaw doctor --fix من أجل نقل speechProviders وrealtimeTranscriptionProviders، وrealtimeVoiceProviders وmediaUnderstandingProviders، وimageGenerationProviders وvideoGenerationProviders، وwebFetchProviders وwebSearchProviders إلى contracts؛ إذ لم يعد تحميل البيان العادي يتعامل مع تلك الحقول ذات المستوى الأعلى على أنها ملكية قدرات.

​
البيان مقابل package.json

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

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

توجد بعض بيانات تعريف المكونات الإضافية قبل وقت التشغيل عمدًا في package.json ضمن كتلة openclaw بدلًا من openclaw.plugin.json. أمثلة مهمة:
الحقلما الذي يعنيه
openclaw.extensionsيعرّف نقاط دخول المكونات الإضافية الأصلية.
openclaw.setupEntryنقطة دخول خفيفة مخصصة للإعداد فقط تُستخدم أثناء التهيئة الأولية وبدء تشغيل القنوات المؤجل.
openclaw.channelبيانات تعريف خفيفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار.
openclaw.channel.configuredStateبيانات تعريف خفيفة لفاحص حالة التكوين يمكنها الإجابة عن سؤال “هل يوجد إعداد يعتمد على env فقط بالفعل؟” من دون تحميل وقت تشغيل القناة الكامل.
openclaw.channel.persistedAuthStateبيانات تعريف خفيفة لفاحص المصادقة المحفوظة يمكنها الإجابة عن سؤال “هل يوجد أي تسجيل دخول بالفعل؟” من دون تحميل وقت تشغيل القناة الكامل.
openclaw.install.npmSpec / openclaw.install.localPathتلميحات التثبيت/التحديث للمكونات الإضافية المضمّنة والمنشورة خارجيًا.
openclaw.install.defaultChoiceمسار التثبيت المفضل عند توفر عدة مصادر تثبيت.
openclaw.install.minHostVersionالحد الأدنى المدعوم من إصدار مضيف OpenClaw، باستخدام حد أدنى semver مثل >=2026.3.22.
openclaw.install.allowInvalidConfigRecoveryيسمح بمسار استرداد ضيق لإعادة تثبيت المكونات الإضافية المضمّنة عندما يكون التكوين غير صالح.
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListenيتيح تحميل أسطح القنوات المخصصة للإعداد فقط قبل المكون الإضافي الكامل للقناة أثناء بدء التشغيل.
يُفرض openclaw.install.minHostVersion أثناء التثبيت وتحميل سجل البيان. تُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتجاوز المكون الإضافي على المضيفين الأقدم. إن openclaw.install.allowInvalidConfigRecovery ضيق النطاق عمدًا. فهو لا يجعل التكوينات المعطوبة التعسفية قابلة للتثبيت. في الوقت الحالي، لا يسمح إلا لتدفقات التثبيت بالتعافي من حالات فشل معينة قديمة لترقية المكونات الإضافية المضمّنة، مثل مسار مكون إضافي مضمّن مفقود أو إدخال channels.<id> قديم لذلك المكون الإضافي المضمّن نفسه. وما تزال أخطاء التكوين غير المرتبطة تمنع التثبيت وتوجه المشغلين إلى openclaw doctor --fix. إن openclaw.channel.persistedAuthState هو بيانات تعريف الحزمة لوحدة فاحص صغيرة: 
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
استخدمه عندما تحتاج تدفقات الإعداد أو doctor أو حالة التكوين إلى تحقق رخيص بنعم/لا من المصادقة قبل تحميل المكون الإضافي الكامل للقناة. يجب أن يكون التصدير الهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ لا توجهه عبر شريط وقت تشغيل القناة الكامل. يتبع openclaw.channel.configuredState البنية نفسها من أجل فحوصات حالة التكوين الرخيصة المعتمدة على env فقط: 
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
استخدمه عندما تتمكن قناة من الإجابة عن حالة التكوين من env أو من مدخلات صغيرة أخرى غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل التكوين الكامل أو إلى وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في hook config.hasConfiguredState الخاص بالمكون الإضافي بدلًا من ذلك.

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

  • يجب على كل مكون إضافي أن يتضمن مخطط JSON، حتى إذا كان لا يقبل أي تكوين.
  • يُقبل مخطط فارغ (على سبيل المثال، { "type": "object", "additionalProperties": false }).
  • يتم التحقق من المخططات عند قراءة/كتابة التكوين، وليس أثناء وقت التشغيل.

​
سلوك التحقق

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

​
ملاحظات

  • البيان مطلوب للمكونات الإضافية الأصلية في OpenClaw، بما في ذلك التحميلات المحلية من نظام الملفات.
  • ما يزال وقت التشغيل يحمّل وحدة المكون الإضافي بشكل منفصل؛ البيان مخصص فقط للاكتشاف + التحقق.
  • تُحلَّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير الموضوعة بين علامتي اقتباس طالما أن القيمة النهائية لا تزال كائنًا.
  • لا يقرأ محمّل البيان إلا حقول البيان الموثقة. تجنب إضافة مفاتيح مخصصة ذات مستوى أعلى هنا.
  • providerAuthEnvVars هو مسار البيانات الوصفية الرخيص لفحوصات المصادقة، والتحقق من علامات env، وأسُطح مصادقة الموفر المشابهة التي يجب ألا تشغّل وقت تشغيل المكون الإضافي لمجرد فحص أسماء env.
  • يسمح providerAuthAliases لمتغيرات الموفر بإعادة استخدام متغيرات البيئة الخاصة بمصادقة موفر آخر، وملفات تعريف المصادقة، والمصادقة المستندة إلى التكوين، وخيار الإعداد الأولي لمفتاح API من دون ترميز ثابت لهذه العلاقة في النواة.
  • channelEnvVars هو مسار البيانات الوصفية الرخيص للرجوع إلى shell-env، ومطالبات الإعداد، وأسُطح القنوات المشابهة التي يجب ألا تشغّل وقت تشغيل المكون الإضافي لمجرد فحص أسماء env.
  • providerAuthChoices هو مسار البيانات الوصفية الرخيص لمحددات خيارات المصادقة، وحل --auth-choice، وربط الموفر المفضل، وتسجيل أعلام CLI البسيطة في الإعداد الأولي قبل تحميل وقت تشغيل الموفر. أما بالنسبة إلى بيانات تعريف المعالج التفاعلي في وقت التشغيل التي تتطلب كود الموفر، فراجع hooks وقت تشغيل الموفر.
  • تُختار أنواع المكونات الإضافية الحصرية عبر plugins.slots.*.
    • يُختار kind: "memory" بواسطة plugins.slots.memory.
    • يُختار kind: "context-engine" بواسطة plugins.slots.contextEngine (الافتراضي: legacy المدمج).
  • يمكن حذف channels وproviders وcliBackends وskills عندما لا يحتاجها المكون الإضافي.
  • إذا كان المكون الإضافي يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات قائمة سماح لمدير الحزم (على سبيل المثال، pnpm allow-build-scripts
    • pnpm rebuild <package>).

​
ذو صلة