بيان Plugin - OpenClaw

هذه الصفحة مخصّصة فقط لملف بيان 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)
بيانات تعريف مشغّل QA التي يمكن لمضيف 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"],
  "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`	معرّف Plugin القانوني. هذا هو المعرّف المستخدم في `plugins.entries.<id>`.
`configSchema`	نعم	`object`	JSON Schema مضمنة لإعدادات هذا الـ Plugin.
`enabledByDefault`	لا	`true`	يعلّم Plugin المضمّن على أنه مفعّل افتراضيًا. احذفه، أو اضبط أي قيمة غير `true`، لترك الـ Plugin معطّلًا افتراضيًا.
`enabledByDefaultOnPlatforms`	لا	`string[]`	يعلّم Plugin المضمّن على أنه مفعّل افتراضيًا فقط على منصات Node.js المدرجة، مثل `["darwin"]`. تظل الإعدادات الصريحة هي التي تسود.
`legacyPluginIds`	لا	`string[]`	معرّفات قديمة تُطبّع إلى معرّف Plugin القانوني هذا.
`autoEnableWhenConfiguredProviders`	لا	`string[]`	معرّفات المزوّدين التي ينبغي أن تفعّل هذا الـ Plugin تلقائيًا عندما تذكرها المصادقة أو الإعدادات أو مراجع النماذج.
`kind`	لا	`"memory"` \| `"context-engine"`	يصرّح بنوع Plugin حصري يستخدمه `plugins.slots.*`.
`channels`	لا	`string[]`	معرّفات القنوات التي يملكها هذا الـ Plugin. تُستخدم للاكتشاف والتحقق من الإعدادات.
`providers`	لا	`string[]`	معرّفات المزوّدين التي يملكها هذا الـ Plugin.
`providerCatalogEntry`	لا	`string`	مسار وحدة خفيف لفهرس المزوّدين، نسبي إلى جذر الـ Plugin، لبيانات تعريفية لفهرس المزوّدين ضمن نطاق البيان يمكن تحميلها من دون تفعيل وقت تشغيل الـ Plugin بالكامل.
`modelSupport`	لا	`object`	بيانات تعريفية مختصرة، يملكها البيان، لعائلة النماذج وتُستخدم لتحميل الـ Plugin تلقائيًا قبل وقت التشغيل.
`modelCatalog`	لا	`object`	بيانات تعريفية تصريحية لفهرس النماذج للمزوّدين الذين يملكهم هذا الـ Plugin. هذا هو عقد مستوى التحكم للقوائم المستقبلية للقراءة فقط، والإعداد الأولي، ومنتقيات النماذج، والأسماء المستعارة، والإخفاء من دون تحميل وقت تشغيل الـ Plugin.
`modelPricing`	لا	`object`	سياسة بحث أسعار خارجية يملكها المزوّد. استخدمها لاستثناء المزوّدين المحليين/ذاتيي الاستضافة من فهارس التسعير البعيدة أو ربط مراجع المزوّدين بمعرّفات فهارس OpenRouter/LiteLLM من دون ترميز معرّفات المزوّدين صراحة في النواة.
`modelIdNormalization`	لا	`object`	تنظيف الأسماء المستعارة/البادئات لمعرّفات النماذج الذي يملكه المزوّد ويجب تشغيله قبل تحميل وقت تشغيل المزوّد.
`providerEndpoints`	لا	`object[]`	بيانات تعريفية يملكها البيان للمضيف/baseUrl الخاص بنقاط النهاية لمسارات المزوّدين التي يجب أن تصنّفها النواة قبل تحميل وقت تشغيل المزوّد.
`providerRequest`	لا	`object`	بيانات تعريفية خفيفة لعائلة المزوّد وتوافق الطلبات تستخدمها سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد.
`cliBackends`	لا	`string[]`	معرّفات خلفيات الاستدلال في CLI التي يملكها هذا الـ Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع الإعدادات الصريحة.
`syntheticAuthRefs`	لا	`string[]`	مراجع المزوّد أو خلفية CLI التي ينبغي فحص خطاف المصادقة الاصطناعي المملوك للـ Plugin الخاص بها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل.
`nonSecretAuthMarkers`	لا	`string[]`	قيم مفاتيح API نائبة يملكها Plugin مضمّن وتمثّل حالة اعتماد محلية أو OAuth أو محيطية غير سرية.
`commandAliases`	لا	`object[]`	أسماء الأوامر التي يملكها هذا الـ Plugin وينبغي أن تنتج تشخيصات إعدادات وCLI واعية بالـ Plugin قبل تحميل وقت التشغيل.
`providerAuthEnvVars`	لا	`Record<string, string[]>`	بيانات تعريفية قديمة للتوافق لمتغيرات البيئة الخاصة بمصادقة/حالة المزوّد. فضّل `setup.providers[].envVars` للـ Plugins الجديدة؛ لا يزال OpenClaw يقرأ هذا أثناء نافذة الإهمال.
`providerAuthAliases`	لا	`Record<string, string>`	معرّفات المزوّدين التي ينبغي أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، مثل مزوّد برمجة يشارك مفتاح API وملفات تعريف المصادقة الخاصة بالمزوّد الأساسي.
`channelEnvVars`	لا	`Record<string, string[]>`	بيانات تعريفية خفيفة لمتغيرات بيئة القناة يمكن أن يفحصها OpenClaw من دون تحميل كود الـ Plugin. استخدم هذا لإعداد القنوات المدفوع بمتغيرات البيئة أو أسطح المصادقة التي ينبغي أن تراها مساعدات بدء التشغيل/الإعدادات العامة.
`providerAuthChoices`	لا	`object[]`	بيانات تعريفية خفيفة لاختيارات المصادقة لمنتقيات الإعداد الأولي، وحلّ المزوّد المفضّل، وتوصيل أعلام CLI البسيط.
`activation`	لا	`object`	بيانات تعريفية خفيفة لمخطط التفعيل لبدء التشغيل، والمزوّدين، والأوامر، والقنوات، والمسارات، والتحميل المشغّل بالقدرات. بيانات تعريفية فقط؛ يظل وقت تشغيل الـ Plugin مالكًا للسلوك الفعلي.
`setup`	لا	`object`	واصفات إعداد/إعداد أولي خفيفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل الـ Plugin.
`qaRunners`	لا	`object[]`	واصفات خفيفة لمشغلات QA يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin.
`contracts`	لا	`object`	لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات.
`mediaUnderstandingProviderMetadata`	لا	`Record<string, object>`	افتراضيات خفيفة لفهم الوسائط لمعرّفات المزوّدين المصرّح بها في `contracts.mediaUnderstandingProviders`.
`imageGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريفية خفيفة لمصادقة توليد الصور لمعرّفات المزوّدين المصرّح بها في `contracts.imageGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي.
`videoGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريفية خفيفة لمصادقة توليد الفيديو لمعرّفات المزوّدين المصرّح بها في `contracts.videoGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي.
`musicGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريفية خفيفة لمصادقة توليد الموسيقى لمعرّفات المزوّدين المصرّح بها في `contracts.musicGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة المملوكة للمزوّد وحواجز عنوان URL الأساسي.
`toolMetadata`	لا	`Record<string, object>`	بيانات تعريفية خفيفة للتوافر للأدوات المملوكة للـ Plugin والمصرّح بها في `contracts.tools`. استخدمها عندما لا ينبغي للأداة تحميل وقت التشغيل إلا إذا وُجدت أدلة من الإعدادات أو البيئة أو المصادقة.
`channelConfigs`	لا	`Record<string, object>`	بيانات تعريفية لإعدادات القناة يملكها البيان وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل.
`skills`	لا	`string[]`	أدلة Skills المراد تحميلها، نسبيًا إلى جذر الـ Plugin.
`name`	لا	`string`	اسم Plugin قابل للقراءة البشرية.
`description`	لا	`string`	ملخص قصير يُعرض في واجهات Plugin.
`version`	لا	`string`	إصدار Plugin لأغراض معلوماتية.
`uiHints`	لا	`Record<string, object>`	تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول التكوين.

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

تصف حقول بيانات تعريف مزوّدات التوليد إشارات المصادقة الثابتة للمزوّدات المعلنة في قائمة 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"]
          }
        }
      ]
    }
  }
}

يدعم كل إدخال بيانات تعريف ما يلي:

الحقل	مطلوب	النوع	ما يعنيه
`aliases`	لا	`string[]`	معرّفات مزوّد إضافية يجب اعتبارها أسماء مستعارة ثابتة للمصادقة لمزوّد التوليد.
`authProviders`	لا	`string[]`	معرّفات المزوّدات التي يجب اعتبار ملفات تعريف المصادقة المكوّنة لها مصادقةً لمزوّد التوليد هذا.
`configSignals`	لا	`object[]`	إشارات إتاحة منخفضة التكلفة ومعتمدة على الإعدادات فقط للمزوّدات المحلية أو ذاتية الاستضافة التي يمكن تكوينها دون ملفات تعريف مصادقة أو متغيرات بيئة.
`authSignals`	لا	`object[]`	إشارات مصادقة صريحة. عند وجودها، تستبدل مجموعة الإشارات الافتراضية من معرّف المزوّد و`aliases` و`authProviders`.

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

الحقل	مطلوب	النوع	ما يعنيه
`rootPath`	نعم	`string`	مسار بالنقاط إلى كائن الإعدادات المملوك لـ Plugin لفحصه، على سبيل المثال `plugins.entries.example.config`.
`overlayPath`	لا	`string`	مسار بالنقاط داخل إعدادات الجذر إلى الكائن الذي يجب أن يركّب فوق كائن الجذر قبل تقييم الإشارة. استخدم هذا للإعدادات الخاصة بالإمكانات مثل `image` أو `video` أو `music`.
`required`	لا	`string[]`	مسارات بالنقاط داخل الإعدادات الفعالة يجب أن تحتوي على قيم مكوّنة. يجب أن تكون السلاسل غير فارغة؛ ويجب ألا تكون الكائنات والمصفوفات فارغة.
`requiredAny`	لا	`string[]`	مسارات بالنقاط داخل الإعدادات الفعالة حيث يجب أن يحتوي واحد منها على الأقل على قيمة مكوّنة.
`mode`	لا	`object`	حارس وضع نصي اختياري داخل الإعدادات الفعالة. استخدم هذا عندما تنطبق الإتاحة المعتمدة على الإعدادات فقط على وضع واحد.

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

الحقل	مطلوب	النوع	ما يعنيه
`path`	لا	`string`	مسار بالنقاط داخل الإعدادات الفعالة. تكون القيمة الافتراضية `mode`.
`default`	لا	`string`	قيمة الوضع التي تُستخدم عندما تحذف الإعدادات المسار.
`allowed`	لا	`string[]`	إذا وُجد، تمرّ الإشارة فقط عندما يكون الوضع الفعال واحدًا من هذه القيم.
`disallowed`	لا	`string[]`	إذا وُجد، تفشل الإشارة عندما يكون الوضع الفعال واحدًا من هذه القيم.

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

الحقل	مطلوب	النوع	ما يعنيه
`provider`	نعم	`string`	معرّف المزوّد المطلوب التحقق منه في ملفات تعريف المصادقة المكوّنة.
`providerBaseUrl`	لا	`object`	حارس اختياري يجعل الإشارة تُحتسب فقط عندما يستخدم المزوّد المكوّن المشار إليه عنوان URL أساسيًا مسموحًا. استخدم هذا عندما يكون اسم مستعار للمصادقة صالحًا فقط لواجهات API معينة.

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

الحقل	مطلوب	النوع	ما يعنيه
`provider`	نعم	`string`	معرّف إعدادات المزوّد الذي يجب التحقق من `baseUrl` الخاص به.
`defaultBaseUrl`	لا	`string`	عنوان URL الأساسي الذي يُفترض عندما تحذف إعدادات المزوّد `baseUrl`.
`allowedBaseUrls`	نعم	`string[]`	عناوين URL الأساسية المسموح بها لإشارة المصادقة هذه. تُتجاهل الإشارة عندما لا يطابق عنوان URL الأساسي المكوّن أو الافتراضي إحدى هذه القيم المعيّرة.

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

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

{
  "providerAuthEnvVars": {
    "example": ["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 المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن التي يعتمد مصنعها على المصادقة/الإعدادات، يجب على مؤلفي Plugins إعلان toolMetadata بدلًا من جعل النواة تستورد وقت التشغيل للسؤال.

مرجع 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 عندما يمتلك Plugin اسم أمر وقت تشغيل قد يضعه المستخدمون عن طريق الخطأ في plugins.allow أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw هذه البيانات الوصفية للتشخيصات دون استيراد كود وقت تشغيل Plugin.

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

الحقل	مطلوب	النوع	ما يعنيه
`name`	نعم	`string`	اسم الأمر الذي ينتمي إلى هذا Plugin.
`kind`	لا	`"runtime-slash"`	يحدد الاسم المستعار كأمر شرطة مائلة في الدردشة بدلا من أمر CLI جذري.
`cliCommand`	لا	`string`	أمر CLI الجذري المرتبط لاقتراحه لعمليات CLI، إن وجد.

مرجع activation

استخدم activation عندما يستطيع Plugin التصريح بتكلفة منخفضة عن أحداث مستوى التحكم التي ينبغي أن تضمه إلى خطة تفعيل/تحميل. هذه الكتلة بيانات وصفية للمخطط، وليست واجهة API لدورة الحياة. لا تسجل سلوك وقت التشغيل، ولا تستبدل register(...)، ولا تعد بأن كود Plugin قد تم تنفيذه بالفعل. يستخدم مخطط التفعيل هذه الحقول لتضييق Plugins المرشحة قبل الرجوع إلى بيانات ملكية البيان الحالية مثل providers وchannels وcommandAliases وsetup.providers وcontracts.tools والخطافات. فضّل أضيق بيانات وصفية تصف الملكية بالفعل. استخدم providers أو channels أو commandAliases أو واصفات الإعداد أو contracts عندما تعبر تلك الحقول عن العلاقة. استخدم activation لتلميحات مخطط إضافية لا يمكن تمثيلها بواسطة حقول الملكية تلك. استخدم cliBackends في المستوى الأعلى للأسماء المستعارة لوقت تشغيل CLI مثل claude-cli أو codex-cli أو google-gemini-cli؛ أما activation.onAgentHarnesses فهو مخصص فقط لمعرفات حاضنات الوكلاء المضمنة التي لا تملك حقل ملكية بالفعل. هذه الكتلة بيانات وصفية فقط. لا تسجل سلوك وقت التشغيل، ولا تستبدل register(...) أو setupEntry أو نقاط دخول وقت التشغيل/Plugin الأخرى. يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugins على نطاق أوسع، لذلك عادة لا يكلف غياب بيانات وصفية لتفعيل غير بدء التشغيل سوى الأداء؛ ولا ينبغي أن يغير الصحة ما دامت بدائل ملكية البيان الاحتياطية موجودة. ينبغي لكل 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"]
  }
}

الحقل	مطلوب	النوع	ما يعنيه
`onStartup`	لا	`boolean`	تفعيل صريح عند بدء تشغيل Gateway. ينبغي لكل Plugin ضبط هذا. يستورد `true` Plugin أثناء بدء التشغيل؛ ويبقيه `false` كسولا عند بدء التشغيل ما لم يتطلب مشغل مطابق آخر التحميل.
`onProviders`	لا	`string[]`	معرفات المزوّدين التي ينبغي أن تضم هذا Plugin إلى خطط التفعيل/التحميل.
`onAgentHarnesses`	لا	`string[]`	معرفات وقت تشغيل حاضنات الوكلاء المضمنة التي ينبغي أن تضم هذا Plugin إلى خطط التفعيل/التحميل. استخدم `cliBackends` في المستوى الأعلى للأسماء المستعارة لخلفيات CLI.
`onCommands`	لا	`string[]`	معرفات الأوامر التي ينبغي أن تضم هذا Plugin إلى خطط التفعيل/التحميل.
`onChannels`	لا	`string[]`	معرفات القنوات التي ينبغي أن تضم هذا Plugin إلى خطط التفعيل/التحميل.
`onRoutes`	لا	`string[]`	أنواع المسارات التي ينبغي أن تضم هذا Plugin إلى خطط التفعيل/التحميل.
`onConfigPaths`	لا	`string[]`	مسارات إعدادات نسبية إلى الجذر ينبغي أن تضم هذا Plugin إلى خطط بدء التشغيل/التحميل عندما يكون المسار موجودا وغير معطل صراحة.
`onCapabilities`	لا	`Array<"provider" \| "channel" \| "tool" \| "hook">`	تلميحات قدرات واسعة يستخدمها تخطيط التفعيل في مستوى التحكم. فضّل الحقول الأضيق عندما يكون ذلك ممكنا.

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

يستخدم تخطيط بدء تشغيل Gateway activation.onStartup للاستيراد الصريح عند بدء التشغيل
يرجع تخطيط CLI المشغّل بالأوامر إلى commandAliases[].cliCommand أو commandAliases[].name القديمين
يستخدم تخطيط بدء تشغيل وقت تشغيل الوكيل activation.onAgentHarnesses للحاضنات المضمنة وcliBackends[] في المستوى الأعلى للأسماء المستعارة لوقت تشغيل CLI
يرجع تخطيط الإعداد/القناة المشغّل بالقناة إلى ملكية channels[] القديمة عندما تكون البيانات الوصفية الصريحة لتفعيل القناة مفقودة
يستخدم تخطيط Plugin عند بدء التشغيل activation.onConfigPaths لأسطح إعدادات جذرية غير قنوية مثل كتلة browser في Plugin المتصفح المضمّن
يرجع تخطيط الإعداد/وقت التشغيل المشغّل بالمزوّد إلى ملكية providers[] وcliBackends[] في المستوى الأعلى القديمتين عندما تكون البيانات الوصفية الصريحة لتفعيل المزوّد مفقودة

يمكن لتشخيصات المخطط التمييز بين تلميحات التفعيل الصريحة وبين الرجوع الاحتياطي لملكية البيان. على سبيل المثال، يعني activation-command-hint أن activation.onCommands قد طابق، بينما يعني manifest-command-alias أن المخطط استخدم ملكية commandAliases بدلا من ذلك. تسميات الأسباب هذه مخصصة لتشخيصات المضيف والاختبارات؛ ينبغي لمؤلفي Plugins الاستمرار في التصريح بالبيانات الوصفية التي تصف الملكية بأفضل شكل.

مرجع qaRunners

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

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

الحقل	مطلوب	النوع	ما يعنيه
`commandName`	نعم	`string`	الأمر الفرعي المثبت تحت `openclaw qa`، على سبيل المثال `matrix`.
`description`	لا	`string`	نص مساعدة احتياطي يستخدم عندما يحتاج المضيف المشترك إلى أمر بديل.

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

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

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

الحقل	مطلوب	النوع	ما يعنيه
`type`	نعم	`string`	حاليًا `local-file-with-env`.
`fileEnvVar`	لا	`string`	متغير بيئة يحتوي على مسار ملف اعتماد صريح.
`fallbackPaths`	لا	`string[]`	مسارات ملفات اعتماد محلية تُفحص عند غياب `fileEnvVar` أو كونه فارغًا. يدعم `${HOME}` و`${APPDATA}`.
`requiresAnyEnv`	لا	`string[]`	يجب أن يكون واحد على الأقل من متغيرات البيئة المدرجة غير فارغ قبل أن يكون الدليل صالحًا.
`requiresAllEnv`	لا	`string[]`	يجب أن يكون كل متغير بيئة مدرج غير فارغ قبل أن يكون الدليل صالحًا.
`credentialMarker`	نعم	`string`	علامة غير سرية تُعاد عند وجود الدليل.
`source`	لا	`string`	تسمية مصدر موجهة للمستخدم لمخرجات المصادقة/الحالة.

حقول setup

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

مرجع uiHints

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

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

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

الحقل	النوع	ما يعنيه
`label`	`string`	تسمية الحقل الموجهة للمستخدم.
`help`	`string`	نص مساعدة قصير.
`tags`	`string[]`	وسوم واجهة مستخدم اختيارية.
`advanced`	`boolean`	يعلّم الحقل على أنه متقدم.
`sensitive`	`boolean`	يعلّم الحقل على أنه سري أو حساس.
`placeholder`	`string`	نص العنصر النائب لمدخلات النماذج.

مرجع contracts

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

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

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

الحقل	النوع	ما يعنيه
`embeddedExtensionFactories`	`string[]`	معرّفات مصانع امتدادات خادم تطبيقات Codex، حاليًا `codex-app-server`.
`agentToolResultMiddleware`	`string[]`	معرّفات وقت التشغيل التي قد يسجل Plugin مضمّن وسيط نتائج أدوات لها.
`externalAuthProviders`	`string[]`	معرّفات المزوّدين التي يملك هذا Plugin خطاف ملف تعريف المصادقة الخارجي الخاص بها.
`speechProviders`	`string[]`	معرّفات مزوّدي الكلام التي يملكها هذا Plugin.
`realtimeTranscriptionProviders`	`string[]`	معرّفات مزوّدي النسخ الفوري التي يملكها هذا Plugin.
`realtimeVoiceProviders`	`string[]`	معرّفات مزوّدي الصوت الفوري التي يملكها هذا Plugin.
`memoryEmbeddingProviders`	`string[]`	معرّفات مزوّدي تضمين الذاكرة التي يملكها هذا Plugin.
`mediaUnderstandingProviders`	`string[]`	معرّفات مزوّدي فهم الوسائط التي يملكها هذا Plugin.
`imageGenerationProviders`	`string[]`	معرّفات مزوّدي توليد الصور التي يملكها هذا Plugin.
`videoGenerationProviders`	`string[]`	معرّفات مزوّدي توليد الفيديو التي يملكها هذا Plugin.
`webFetchProviders`	`string[]`	معرّفات مزوّدي جلب الويب التي يملكها هذا Plugin.
`webSearchProviders`	`string[]`	معرّفات مزوّدي بحث الويب التي يملكها هذا Plugin.
`migrationProviders`	`string[]`	معرّفات مزوّدي الاستيراد التي يملكها هذا Plugin لـ `openclaw migrate`.
`tools`	`string[]`	أسماء أدوات الوكيل التي يملكها هذا Plugin.

يُحتفظ بـ contracts.embeddedExtensionFactories لمصانع امتدادات خادم تطبيقات Codex المضمّنة فقط. يجب أن تعلن تحويلات نتائج الأدوات المضمّنة contracts.agentToolResultMiddleware وأن تسجل باستخدام api.registerAgentToolResultMiddleware(...) بدلًا من ذلك. لا يمكن لـ Plugins الخارجية تسجيل وسيط نتائج الأدوات لأن الحد الفاصل يمكنه إعادة كتابة مخرجات الأدوات عالية الثقة قبل أن يراها النموذج. يجب أن تطابق تسجيلات وقت التشغيل api.registerTool(...) قيمة contracts.tools. يستخدم اكتشاف الأدوات هذه القائمة لتحميل أوقات تشغيل Plugins فقط التي يمكن أن تملك الأدوات المطلوبة. يجب على Plugins المزوّدين التي تنفذ resolveExternalAuthProfiles أن تعلن contracts.externalAuthProviders. لا تزال Plugins التي لا تحتوي على الإعلان تمر عبر مسار توافق احتياطي مهجور، لكن هذا المسار أبطأ وسيُزال بعد نافذة الترحيل. يجب أن يعلن مزوّدو تضمين الذاكرة المضمّنون contracts.memoryEmbeddingProviders لكل معرّف محوّل يعرِضونه، بما في ذلك المحوّلات المدمجة مثل local. تستخدم مسارات CLI المستقلة عقد البيان هذا لتحميل Plugin المالك فقط قبل أن يكون وقت تشغيل 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"]
    }
  }
}

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

الحقل	النوع	ما يعنيه
`capabilities`	`("image" \| "audio" \| "video")[]`	قدرات الوسائط التي يعرِضها هذا المزوّد.
`defaultModels`	`Record<string, string>`	افتراضيات القدرة إلى النموذج المستخدمة عندما لا تحدد الإعدادات نموذجًا.
`autoPriority`	`Record<string, number>`	الأرقام الأصغر تُرتّب أولًا للاحتياطي التلقائي للمزوّد المستند إلى الاعتمادات.
`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"]
    }
  }
}

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

الحقل	النوع	ما يعنيه
`schema`	`object`	مخطط JSON لـ `channels.<id>`. مطلوب لكل إدخال مُعلَن لإعدادات القناة.
`uiHints`	`Record<string, object>`	تسميات/عناصر نائبة/تلميحات حساسة اختيارية لواجهة المستخدم لقسم إعدادات تلك القناة.
`label`	`string`	تسمية القناة التي تُدمج في واجهات الاختيار والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة.
`description`	`string`	وصف قصير للقناة لواجهات الفحص والكتالوج.
`commands`	`object`	أوامر أصلية ثابتة وافتراضات تلقائية أصلية لـ Skills لفحوصات الإعدادات قبل وقت التشغيل.
`preferOver`	`string[]`	معرّفات Plugin قديمة أو أقل أولوية يجب أن تتقدم عليها هذه القناة في واجهات الاختيار.

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

مرجع 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 الصريحة تستخدم بيانات manifest الوصفية الخاصة بـ providers المالك
تتقدم modelPatterns على modelPrefixes
إذا تطابق Plugin غير مضمّن وPlugin مضمّن، يفوز الـ Plugin غير المضمّن
يُتجاهل أي غموض متبقٍ إلى أن يحدد المستخدم أو الإعدادات مزوّدًا

الحقول:

الحقل	النوع	ما يعنيه
`modelPrefixes`	`string[]`	بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة.
`modelPatterns`	`string[]`	مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف الشخصي.

مرجع modelCatalog

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

{
  "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"
    }
  }
}

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

الحقل	النوع	ما يعنيه
`providers`	`Record<string, object>`	صفوف الكتالوج لمعرّفات المزوّدين التي يملكها هذا الـ Plugin. يجب أن تظهر المفاتيح أيضًا في `providers` ذات المستوى الأعلى.
`aliases`	`Record<string, object>`	أسماء مستعارة للمزوّدين يجب أن تتحول إلى مزوّد مملوك لأغراض الكتالوج أو تخطيط الإخفاء.
`suppressions`	`object[]`	صفوف نماذج من مصدر آخر يخفيها هذا الـ Plugin لسبب خاص بالمزوّد.
`discovery`	`Record<string, "static" \| "refreshable" \| "runtime">`	ما إذا كان يمكن قراءة كتالوج المزوّد من بيانات manifest الوصفية، أو تحديثه في ذاكرة التخزين المؤقت، أو يتطلب وقت التشغيل.

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

الحقل	النوع	ما يعنيه
`baseUrl`	`string`	عنوان URL أساسي افتراضي اختياري للنماذج في كتالوج هذا المزوّد.
`api`	`ModelApi`	محوّل API افتراضي اختياري للنماذج في كتالوج هذا المزوّد.
`headers`	`Record<string, string>`	ترويسات ثابتة اختيارية تنطبق على كتالوج هذا المزوّد.
`models`	`object[]`	صفوف النماذج المطلوبة. يتم تجاهل الصفوف التي لا تحتوي على `id`.

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

الحقل	النوع	ما يعنيه
`id`	`string`	معرّف النموذج المحلي لدى المزوّد، بدون بادئة `provider/`.
`name`	`string`	اسم عرض اختياري.
`api`	`ModelApi`	تجاوز اختياري للـ API على مستوى النموذج.
`baseUrl`	`string`	تجاوز اختياري لعنوان URL الأساسي على مستوى النموذج.
`headers`	`Record<string, string>`	ترويسات ثابتة اختيارية على مستوى النموذج.
`input`	`Array<"text" \| "image" \| "document" \| "audio" \| "video">`	الصيغ التي يقبلها النموذج.
`reasoning`	`boolean`	ما إذا كان النموذج يعرض سلوك الاستدلال.
`contextWindow`	`number`	نافذة السياق الأصلية للمزوّد.
`contextTokens`	`number`	حد سياق فعلي اختياري في وقت التشغيل عندما يختلف عن `contextWindow`.
`maxTokens`	`number`	الحد الأقصى لرموز الإخراج عندما يكون معروفًا.
`cost`	`object`	تسعير اختياري بالدولار الأمريكي لكل مليون رمز، بما في ذلك `tieredPricing` الاختياري.
`compat`	`object`	علامات توافق اختيارية تطابق توافق إعدادات نماذج OpenClaw.
`status`	`"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"`	حالة الإدراج. أخفِ الصف فقط عندما يجب ألا يظهر إطلاقًا.
`statusReason`	`string`	سبب اختياري يظهر مع الحالة غير المتاحة.
`replaces`	`string[]`	معرّفات نماذج محلية أقدم لدى المزوّد يحل هذا النموذج محلها.
`replacedBy`	`string`	معرّف النموذج المحلي البديل لدى المزوّد للصفوف المهملة.
`tags`	`string[]`	وسوم مستقرة تستخدمها واجهات الاختيار والمرشحات.

حقول الإخفاء:

الحقل	النوع	ما يعنيه
`provider`	`string`	معرّف المزوّد للصف الوارد من المصدر الأعلى لإخفائه. يجب أن يكون مملوكًا لهذا الـ Plugin أو مُعلنًا كاسم مستعار مملوك.
`model`	`string`	معرّف النموذج المحلي لدى المزوّد المراد إخفاؤه.
`reason`	`string`	رسالة اختيارية تظهر عندما يُطلب الصف المخفي مباشرة.
`when.baseUrlHosts`	`string[]`	قائمة اختيارية بمضيفي عنوان URL الأساسي الفعلي للمزوّد المطلوبة قبل تطبيق الإخفاء.
`when.providerConfigApiIn`	`string[]`	قائمة اختيارية بقيم `api` الدقيقة في إعدادات المزوّد المطلوبة قبل تطبيق الإخفاء.

لا تضع البيانات الخاصة بوقت التشغيل فقط في 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"
      }
    }
  }
}

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

الحقل	النوع	ما يعنيه
`aliases`	`Record<string,string>`	أسماء بديلة دقيقة لمعرف النموذج، غير حساسة لحالة الأحرف. تُعاد القيم كما كُتبت.
`stripPrefixes`	`string[]`	بادئات تُزال قبل البحث عن الاسم البديل، وهي مفيدة لتكرار المزوّد/النموذج القديم.
`prefixWhenBare`	`string`	بادئة تُضاف عندما لا يحتوي معرف النموذج المطبّع مسبقًا على `/`.
`prefixWhenBareAfterAliasStartsWith`	`object[]`	قواعد شرطية لبادئة المعرف المجرد بعد البحث عن الاسم البديل، مفهرسة حسب `modelPrefix` و`prefix`.

مرجع providerEndpoints

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

الحقل	النوع	ما يعنيه
`endpointClass`	`string`	فئة نقطة نهاية معروفة في النواة، مثل `openrouter` أو `moonshot-native` أو `google-vertex`.
`hosts`	`string[]`	أسماء مضيفين دقيقة تُعيَّن إلى فئة نقطة النهاية.
`hostSuffixes`	`string[]`	لواحق مضيفين تُعيَّن إلى فئة نقطة النهاية. ابدأ بـ `.` للمطابقة على لاحقة النطاق فقط.
`baseUrls`	`string[]`	عناوين URL أساسية HTTP(S) مطبّعة ودقيقة تُعيَّن إلى فئة نقطة النهاية.
`googleVertexRegion`	`string`	منطقة Google Vertex ثابتة للمضيفين العالميين الدقيقين.
`googleVertexRegionHostSuffix`	`string`	لاحقة تُزال من المضيفين المطابقين لكشف بادئة منطقة Google Vertex.

مرجع providerRequest

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

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

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

الحقل	النوع	ما يعنيه
`family`	`string`	تسمية عائلة المزوّد المستخدمة في قرارات توافق الطلبات العامة والتشخيصات.
`compatibilityFamily`	`"moonshot"`	حاوية توافق اختيارية لعائلة المزوّد لمساعدات الطلبات المشتركة.
`openAICompletions`	`object`	أعلام طلبات الإكمال المتوافقة مع OpenAI، حاليًا `supportsStreamingUsage`.

مرجع modelPricing

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

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

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

الحقل	النوع	ما يعنيه
`external`	`boolean`	اضبطه على `false` للمزوّدين المحليين/ذاتيي الاستضافة الذين يجب ألا يجلبوا تسعير OpenRouter أو LiteLLM أبدًا.
`openRouter`	`false \| object`	تعيين بحث تسعير OpenRouter. يعطّل `false` بحث OpenRouter لهذا المزوّد.
`liteLLM`	`false \| object`	تعيين بحث تسعير LiteLLM. يعطّل `false` بحث LiteLLM لهذا المزوّد.

حقول المصدر:

الحقل	النوع	ما يعنيه
`provider`	`string`	معرف مزوّد الكتالوج الخارجي عندما يختلف عن معرف مزوّد OpenClaw، مثل `z-ai` لمزوّد `zai`.
`passthroughProviderModel`	`boolean`	تعامل مع معرفات النماذج التي تحتوي على شرطة مائلة كمراجع مزوّد/نموذج متداخلة، وهو مفيد لمزوّدي الوكيل مثل OpenRouter.
`modelIdTransforms`	`"version-dots"[]`	تنويعات إضافية لمعرف نموذج الكتالوج الخارجي. يحاول `version-dots` معرفات إصدارات منقوطة مثل `claude-opus-4.6`.

فهرس مزوّدي OpenClaw

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

إعدادات المستخدم.
بيان Plugin المثبت modelCatalog.
ذاكرة التخزين المؤقت لكتالوج النماذج من تحديث صريح.
صفوف معاينة فهرس مزوّدي 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.json`	الاكتشاف، والتحقق من الإعدادات، وبيانات تعريف خيار المصادقة، وتلميحات واجهة المستخدم التي يجب أن توجد قبل تشغيل كود Plugin
`package.json`	بيانات npm التعريفية، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، أو حواجز التثبيت، أو الإعداد، أو بيانات تعريف الكتالوج

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

إذا كان يجب على 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 المدعومة أدناه. أمثلة مهمة:

الحقل	معناه
`openclaw.extensions`	يعلن عن نقاط دخول Plugin الأصلية. يجب أن تبقى داخل دليل حزمة Plugin.
`openclaw.runtimeExtensions`	يعلن عن نقاط دخول وقت تشغيل JavaScript المبنية للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin.
`openclaw.setupEntry`	نقطة دخول خفيفة للإعداد فقط تُستخدم أثناء التهيئة، وبدء تشغيل القناة المؤجل، واكتشاف حالة القناة للقراءة فقط/SecretRef. يجب أن تبقى داخل دليل حزمة Plugin.
`openclaw.runtimeSetupEntry`	يعلن عن نقطة دخول إعداد JavaScript المبنية للحزم المثبتة. يتطلب `setupEntry`، ويجب أن يكون موجودًا، ويجب أن يبقى داخل دليل حزمة Plugin.
`openclaw.channel`	بيانات وصفية منخفضة التكلفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، والأسماء البديلة، ونص الاختيار.
`openclaw.channel.commands`	بيانات وصفية ثابتة للأوامر الأصلية وبيانات وصفية افتراضية تلقائية للمهارات الأصلية تُستخدم بواسطة أسطح التكوين والتدقيق وقائمة الأوامر قبل تحميل وقت تشغيل القناة.
`openclaw.channel.configuredState`	بيانات وصفية خفيفة لفاحص حالة التكوين يمكنها الإجابة عن “هل يوجد إعداد يعتمد على البيئة فقط بالفعل؟” دون تحميل وقت تشغيل القناة الكامل.
`openclaw.channel.persistedAuthState`	بيانات وصفية خفيفة لفاحص المصادقة المستمرة يمكنها الإجابة عن “هل يوجد أي شيء مسجل الدخول بالفعل؟” دون تحميل وقت تشغيل القناة الكامل.
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	تلميحات التثبيت/التحديث للـ plugins المضمنة والمنشورة خارجيًا.
`openclaw.install.defaultChoice`	مسار التثبيت المفضل عندما تتوفر عدة مصادر تثبيت.
`openclaw.install.minHostVersion`	الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد أدنى وفق semver مثل `>=2026.3.22` أو `>=2026.5.1-beta.1`.
`openclaw.install.expectedIntegrity`	سلسلة تكامل npm dist المتوقعة مثل `sha512-...`؛ تتحقق تدفقات التثبيت والتحديث من الأثرية المجلبة مقابلها.
`openclaw.install.allowInvalidConfigRecovery`	يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمن عندما يكون التكوين غير صالح.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	يتيح تحميل أسطح القناة الخاصة بالإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل.

تحدد بيانات manifest الوصفية خيارات المزوّد/القناة/الإعداد التي تظهر في التهيئة قبل تحميل وقت التشغيل. يخبر package.json#openclaw.install التهيئة بكيفية جلب ذلك Plugin أو تمكينه عندما يختار المستخدم أحد تلك الخيارات. لا تنقل تلميحات التثبيت إلى openclaw.plugin.json. يُفرض openclaw.install.minHostVersion أثناء التثبيت وتحميل سجل manifest لمصادر Plugin غير المضمنة. تُرفض القيم غير الصالحة؛ أما القيم الأحدث لكن الصالحة فتتجاوز plugins الخارجية على المضيفات الأقدم. يُفترض أن plugins المصدر المضمنة متوافقة الإصدار مع نسخة المضيف المحلية. يجب أن تستخدم البيانات الوصفية الرسمية للتثبيت عند الطلب 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"
      }
    }
  }
}

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

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

يكتشف OpenClaw plugins من عدة جذور (مضمن، تثبيت عام، مساحة عمل، مسارات محددة صراحة في التكوين). إذا اشترك اكتشافان في id نفسه، فلا يُحتفظ إلا بالـ manifest الأعلى أسبقية؛ وتُسقط التكرارات الأقل أسبقية بدلًا من تحميلها بجانبه. الأسبقية، من الأعلى إلى الأدنى:

محدد في التكوين — مسار مثبت صراحة في plugins.entries.<id>
مضمن — plugins المشحونة مع OpenClaw
تثبيت عام — plugins المثبتة في جذر plugins العام لـ OpenClaw
مساحة العمل — 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.* غير المعروفة هي أخطاء، ما لم يكن معرّف القناة معلنًا بواسطة manifest Plugin.
يجب أن تشير plugins.entries.<id> وplugins.allow وplugins.deny وplugins.slots.* إلى معرّفات Plugin قابلة للاكتشاف. المعرّفات غير المعروفة هي أخطاء.
إذا كان Plugin مثبتًا لكن لديه manifest أو مخطط معطوب أو مفقود، يفشل التحقق ويبلغ Doctor عن خطأ Plugin.
إذا كان تكوين Plugin موجودًا لكن Plugin معطل، فيُحتفظ بالتكوين ويظهر تحذير في Doctor + السجلات.

راجع مرجع التكوين للاطلاع على مخطط plugins.* الكامل.

ملاحظات

البيان مطلوب لـ plugins OpenClaw الأصلية، بما في ذلك التحميلات من نظام الملفات المحلي. ما يزال وقت التشغيل يحمّل وحدة plugin بشكل منفصل؛ أما البيان فهو للاكتشاف + التحقق فقط.
تُحلّل بيانات البيانات الأصلية باستخدام JSON5، لذلك تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير المقتبسة ما دامت القيمة النهائية ما تزال كائنًا.
لا يقرأ محمّل البيان إلا حقول البيان الموثّقة. تجنّب المفاتيح المخصصة في المستوى الأعلى.
يمكن إغفال channels وproviders وcliBackends وskills كلها عندما لا يحتاجها plugin.
يجب أن يبقى providerCatalogEntry خفيفًا، وينبغي ألا يستورد شيفرة وقت تشغيل واسعة؛ استخدمه لبيانات تعريف كتالوج المزوّد الثابتة أو واصفات الاكتشاف المحدودة، لا للتنفيذ وقت الطلب. providerDiscoveryEntry هي التسمية القديمة وما تزال تعمل مع plugins الحالية.
تُختار أنواع plugins الحصرية عبر 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>).

Building plugins

بدء استخدام plugins.

Plugin architecture

البنية الداخلية ونموذج القدرات.

SDK overview

مرجع SDK الخاص بـ Plugin واستيرادات المسارات الفرعية.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

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

​مثال أدنى

​مثال غني

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

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

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

​مرجع providerAuthChoices

​مرجع commandAliases

​مرجع activation

​مرجع qaRunners

​مرجع setup

​مرجع setup.providers

​حقول setup

​مرجع uiHints

​مرجع contracts

​مرجع mediaUnderstandingProviderMetadata

​مرجع channelConfigs

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

​مرجع modelSupport

​مرجع modelCatalog

​مرجع modelIdNormalization

​مرجع providerEndpoints

​مرجع providerRequest

​مرجع modelPricing

​فهرس مزوّدي OpenClaw

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

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

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

​متطلبات JSON Schema

​سلوك التحقق

​ملاحظات

​ذات صلة

Building plugins

Plugin architecture

SDK overview

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

مثال أدنى

مثال غني

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

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

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

مرجع providerAuthChoices

مرجع commandAliases

مرجع activation

مرجع qaRunners

مرجع setup

مرجع setup.providers

حقول setup

مرجع uiHints

مرجع contracts

مرجع mediaUnderstandingProviderMetadata

مرجع channelConfigs

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

مرجع modelSupport

مرجع modelCatalog

مرجع modelIdNormalization

مرجع providerEndpoints

مرجع providerRequest

مرجع modelPricing

فهرس مزوّدي OpenClaw

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

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

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

متطلبات JSON Schema

سلوك التحقق

ملاحظات

ذات صلة