ملف بيان Plugin

هذه الصفحة مخصصة لملف بيان Plugin الأصلي في OpenClaw فقط. للاطلاع على تخطيطات الحزم المتوافقة، راجع حزم Plugin. تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة:

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

يكتشف OpenClaw تخطيطات الحزم هذه تلقائياً أيضاً، لكنها لا تُتحقق مقابل مخطط openclaw.plugin.json الموضح هنا. بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حالياً بيانات تعريف الحزمة بالإضافة إلى جذور Skills المعلنة، وجذور أوامر Claude، وافتراضيات settings.json لحزمة Claude، وافتراضيات LSP لحزمة Claude، وحزم الخطافات المدعومة عندما يطابق التخطيط توقعات وقت تشغيل OpenClaw. يجب على كل Plugin أصلي في OpenClaw أن يضم ملف openclaw.plugin.json في جذر Plugin. يستخدم OpenClaw هذا البيان للتحقق من صحة الإعدادات من دون تنفيذ كود Plugin. تُعامل ملفات البيان المفقودة أو غير الصالحة على أنها أخطاء Plugin وتمنع التحقق من صحة الإعدادات. راجع الدليل الكامل لنظام Plugin: Plugins. للاطلاع على نموذج الإمكانات الأصلي وإرشادات التوافق الخارجي الحالية: نموذج الإمكانات.

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

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

هوية Plugin، والتحقق من صحة الإعدادات، وتلميحات واجهة مستخدم الإعدادات
بيانات تعريف المصادقة، والإعداد الأولي، والتجهيز (الاسم المستعار، والتمكين التلقائي، ومتغيرات بيئة المزوّد، وخيارات المصادقة)
تلميحات التنشيط لأسطح مستوى التحكم
ملكية مختصرة لعائلة النماذج
لقطات ثابتة لملكية الإمكانات (contracts)
بيانات تعريف مشغّل ضمان الجودة التي يمكن لمضيف openclaw qa المشترك فحصها
بيانات تعريف الإعدادات الخاصة بالقناة المدمجة في أسطح الفهرس والتحقق

لا تستخدمه من أجل: تسجيل سلوك وقت التشغيل، أو إعلان نقاط دخول الكود، أو بيانات تعريف تثبيت npm. مكان هذه الأمور هو كود Plugin وpackage.json.

مثال بسيط

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

مثال غني

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["OPENROUTER_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

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

الحقل	مطلوب	النوع	المعنى
`id`	نعم	`string`	معرّف Plugin القانوني. هذا هو المعرّف المستخدم في `plugins.entries.<id>`.
`configSchema`	نعم	`object`	JSON Schema مضمّن لإعدادات هذا الـ Plugin.
`requiresPlugins`	لا	`string[]`	معرّفات Plugin التي يجب تثبيتها أيضًا حتى يكون لهذا الـ Plugin تأثير. يُبقي الاكتشاف الـ Plugin قابلًا للتحميل، لكنه يحذّر عند غياب أي 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`	بيانات تعريف خفيفة لعائلة الموفّر وتوافق الطلبات، تُستخدم بواسطة سياسة الطلبات العامة قبل تحميل وقت تشغيل الموفّر.
`secretProviderIntegrations`	لا	`Record<string, object>`	إعدادات مسبقة تصريحية لموفّر تنفيذ SecretRef يمكن لأسطح الإعداد أو التثبيت عرضها من دون ترميز تكاملات خاصة بالموفّر داخل النواة.
`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[]`	واصفات خفيفة لمشغّلات ضمان الجودة تُستخدم بواسطة مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل الـ Plugin.
`contracts`	لا	`object`	لقطة ثابتة لملكية القدرات لخطافات المصادقة الخارجية، والتضمينات، والكلام، والنسخ في الوقت الفعلي، والصوت في الوقت الفعلي، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، وبحث الويب، وملكية الأدوات.
`mediaUnderstandingProviderMetadata`	لا	`Record<string, object>`	افتراضات خفيفة لفهم الوسائط لمعرّفات الموفّرين المعلنة في `contracts.mediaUnderstandingProviders`.
`imageGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريف خفيفة لمصادقة توليد الصور لمعرّفات الموفّرين المعلنة في `contracts.imageGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url.
`videoGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريف خفيفة لمصادقة توليد الفيديو لمعرّفات الموفّرين المعلنة في `contracts.videoGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url.
`musicGenerationProviderMetadata`	لا	`Record<string, object>`	بيانات تعريف خفيفة لمصادقة توليد الموسيقى لمعرّفات الموفّرين المعلنة في `contracts.musicGenerationProviders`، بما في ذلك الأسماء المستعارة للمصادقة التي يملكها الموفّر وحواجز base-url.
`toolMetadata`	لا	`Record<string, object>`	بيانات تعريف خفيفة للتوفر للأدوات المملوكة من Plugin والمعلنة في `contracts.tools`. استخدمها عندما ينبغي ألا تحمّل الأداة وقت التشغيل إلا عند وجود دليل على التهيئة أو البيئة أو المصادقة.
`channelConfigs`	لا	`Record<string, object>`	بيانات تعريف تهيئة القناة المملوكة من البيان، تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل.
`skills`	لا	`string[]`	أدلة Skills المطلوب تحميلها، نسبة إلى جذر Plugin.
`name`	لا	`string`	اسم Plugin قابل للقراءة من قبل البشر.
`description`	لا	`string`	ملخص قصير يظهر في أسطح Plugin.
`icon`	لا	`string`	عنوان URL لصورة HTTPS لبطاقات السوق/الفهرس. يقبل ClawHub أي عنوان URL صالح من نوع `https://` ويعود إلى أيقونة 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`.
`referenceAudioInputs`	لا	`boolean`	خاص بتوليد الفيديو فقط. اضبطه على `true` عندما يقبل المزوّد أصولًا صوتية مرجعية؛ وإلا فسيخفي `video_generate` معلمات المرجع الصوتي.

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

الحقل	مطلوب	النوع	معناه
`rootPath`	نعم	`string`	مسار نقطي إلى كائن التكوين المملوك لـ Plugin المراد فحصه، على سبيل المثال `plugins.entries.example.config`.
`overlayPath`	لا	`string`	مسار نقطي داخل التكوين الجذر يجب أن يراكب كائنه الكائن الجذر قبل تقييم الإشارة. استخدم هذا للتكوين الخاص بإمكانات معيّنة مثل `image` أو `video` أو `music`.
`overlayMapPath`	لا	`string`	مسار نقطي داخل التكوين الجذر يجب أن تراكب كل قيمة كائن فيه الكائن الجذر. استخدم هذا لخرائط الحسابات المسماة مثل `accounts`، حيث يجب أن يكون أي حساب مكوّن مؤهلًا.
`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.

{
  "setup": {
    "providers": [
      {
        "id": "example",
        "envVars": ["EXAMPLE_API_KEY"]
      }
    ]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}

إذا لم تكن للأداة أي toolMetadata، يحافظ OpenClaw على السلوك الحالي ويحمّل Plugin المالك عندما يطابق عقد الأداة السياسة. بالنسبة إلى أدوات المسار الساخن التي يعتمد مصنعها على المصادقة/التكوين، يجب على مؤلفي Plugin التصريح عن toolMetadata بدلًا من جعل النواة تستورد وقت التشغيل للسؤال.

مرجع providerAuthChoices

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

الحقل	مطلوب	النوع	ما يعنيه
`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" \| "music-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 أو my-cli أو google-gemini-cli؛ أما activation.onAgentHarnesses فهو مخصص فقط لمعرّفات أدوات agent المضمّنة التي لا تملك حقل ملكية بالفعل. هذه الكتلة بيانات وصفية فقط. لا تسجّل سلوك وقت التشغيل، ولا تستبدل register(...) أو setupEntry أو نقاط إدخال وقت التشغيل/plugin الأخرى. يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل plugins أوسع، لذلك فإن غياب بيانات التفعيل غير الخاصة ببدء التشغيل عادة لا يكلّف إلا الأداء؛ ولا ينبغي أن يغيّر الصحة ما دامت بدائل ملكية البيان لا تزال موجودة. يجب على كل plugin تعيين activation.onStartup عمدًا. عيّنه إلى true فقط عندما يجب أن يعمل plugin أثناء بدء تشغيل Gateway. عيّنه إلى false عندما يكون plugin خاملًا عند بدء التشغيل ويجب تحميله فقط من محفزات أضيق. لم يعد حذف onStartup يؤدي إلى تحميل plugin ضمنيًا عند بدء التشغيل؛ استخدم بيانات تفعيل صريحة لبدء التشغيل أو القناة أو الإعدادات أو أداة agent أو الذاكرة أو محفزات تفعيل أضيق أخرى.

{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}

الحقل	مطلوب	النوع	ما يعنيه
`onStartup`	لا	`boolean`	تفعيل صريح عند بدء تشغيل Gateway. يجب على كل plugin تعيين هذا. تؤدي `true` إلى استيراد plugin أثناء بدء التشغيل؛ وتُبقيه `false` كسولًا عند بدء التشغيل ما لم يتطلب محفز مطابق آخر التحميل.
`onProviders`	لا	`string[]`	معرّفات المزوّدين التي يجب أن تُدرج هذا plugin في خطط التفعيل/التحميل.
`onAgentHarnesses`	لا	`string[]`	معرّفات وقت تشغيل أدوات agent المضمّنة التي يجب أن تُدرج هذا 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 القديمين
يستخدم تخطيط بدء تشغيل وقت تشغيل agent activation.onAgentHarnesses من أجل الأدوات المضمّنة وcliBackends[] على المستوى الأعلى للأسماء المستعارة لوقت تشغيل CLI
يتراجع تخطيط الإعداد/القناة المحفَّز بالقنوات إلى ملكية channels[] القديمة عندما تكون بيانات تفعيل القناة الصريحة مفقودة
يستخدم تخطيط plugin عند بدء التشغيل activation.onConfigPaths لأسطح إعدادات الجذر غير القنوية مثل كتلة browser الخاصة بplugin المتصفح المضمّن
يتراجع تخطيط الإعداد/وقت التشغيل المحفَّز بالمزوّد إلى ملكية providers[] وcliBackends[] على المستوى الأعلى القديمتين عندما تكون بيانات تفعيل المزوّد الصريحة مفقودة

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

مرجع qaRunners

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

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

الحقل	مطلوب	النوع	معناه
`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[]`	وسوم UI اختيارية.
`advanced`	`boolean`	يعلّم الحقل على أنه متقدم.
`sensitive`	`boolean`	يعلّم الحقل على أنه سري أو حساس.
`placeholder`	`string`	نص عنصر نائب لإدخالات النماذج.

مرجع contracts

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

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

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

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

يُحتفظ بـ contracts.embeddedExtensionFactories لمصانع إضافات Codex المضمنة والمخصصة لخادم التطبيق فقط. يجب أن تعلن تحويلات نتائج الأدوات المضمنة contracts.agentToolResultMiddleware وأن تسجل باستخدام api.registerAgentToolResultMiddleware(...) بدلًا من ذلك. يمكن لـ Plugins المثبتة استخدام مسار البرمجيات الوسيطة نفسه فقط عند تفعيله صراحة، وفقط لبيئات التشغيل التي تعلنها في contracts.agentToolResultMiddleware. يجب أن تعلن Plugins المثبتة التي تحتاج إلى طبقة سياسة ما قبل الأداة الموثوقة من المضيف كل معرّف محلي مسجل في contracts.trustedToolPolicies وأن تُفعّل صراحة. تحافظ Plugins المضمنة على مسار السياسة الموثوقة الحالي، لكن تُرفض Plugins المثبتة ذات معرّفات السياسات غير المعلنة قبل التسجيل. تكون معرّفات السياسات محددة النطاق حسب Plugin المسجِّل، لذلك يمكن لـ Pluginين أن يعلنا ويسجلا معًا workflow-budget؛ ولا يجوز لـ Plugin واحد تسجيل المعرّف المحلي نفسه مرتين. يجب أن تطابق تسجيلات وقت التشغيل api.registerTool(...) مع contracts.tools. يستخدم اكتشاف الأدوات هذه القائمة لتحميل بيئات تشغيل Plugin التي يمكنها امتلاك الأدوات المطلوبة فقط. يجب أن تعلن Plugins المزوّدين التي تنفذ resolveExternalAuthProfiles contracts.externalAuthProviders؛ ويتم تجاهل خطافات المصادقة الخارجية غير المعلنة. يجب أن يعلن مزوّدو التضمين العامون contracts.embeddingProviders لكل محوّل مسجل باستخدام api.registerEmbeddingProvider(...). استخدم العقد العام لتوليد المتجهات القابل لإعادة الاستخدام، بما في ذلك المزوّدون الذين تستخدمهم عملية البحث في الذاكرة. يُعد contracts.memoryEmbeddingProviders توافقًا خاصًا بالذاكرة ومهملاً، ويبقى فقط أثناء ترحيل المزوّدين الحاليين إلى مسار مزوّد التضمين العام. يقبل contracts.gatewayMethodDispatch حاليًا "authenticated-request". إنه بوابة نظافة API لمسارات HTTP الأصلية الخاصة بـ Plugin التي ترسل عمدًا أساليب مستوى التحكم في Gateway داخل العملية، وليس صندوق حماية ضد Plugins أصلية خبيثة. استخدمه فقط للأسطح المضمنة/الخاصة بالمشغل المدققة بإحكام والتي تتطلب بالفعل مصادقة HTTP الخاصة بـ Gateway.

مرجع mediaUnderstandingProviderMetadata

استخدم mediaUnderstandingProviderMetadata عندما يكون لدى مزوّد فهم الوسائط نماذج افتراضية، أو أولوية احتياطية للمصادقة التلقائية، أو دعم مستندات أصلي تحتاجه مساعدات النواة العامة قبل تحميل وقت التشغيل. يجب أيضًا إعلان المفاتيح في contracts.mediaUnderstandingProviders.

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

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

الحقل	النوع	معناه
`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 Schema لـ `channels.<id>`. مطلوب لكل إدخال إعداد قناة معلن.
`uiHints`	`Record<string, object>`	تسميات/عناصر نائبة/تلميحات حساسة اختيارية لواجهة المستخدم لقسم إعداد تلك القناة.
`label`	`string`	تسمية القناة المدمجة في أسطح الاختيار والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة.
`description`	`string`	وصف قصير للقناة لأسطح الفحص والكتالوج.
`commands`	`object`	افتراضيات تلقائية ثابتة للأوامر الأصلية وSkills الأصلية لفحوصات الإعداد قبل وقت التشغيل.
`preferOver`	`string[]`	معرّفات Plugins قديمة أو ذات أولوية أدنى يجب أن تتفوق عليها هذه القناة في أسطح الاختيار.

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

استخدم preferOver عندما يكون Plugin الخاص بك هو المالك المفضل لمعرّف قناة يمكن أن يوفّره Plugin آخر أيضًا. الحالات الشائعة هي معرّف Plugin مُعاد تسميته، أو Plugin مستقل يحل محل Plugin مضمن، أو تفرع مُصان يبقي معرّف القناة نفسه لتوافق الإعدادات.

{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}

عندما يتم تكوين channels.chat، ينظر OpenClaw في كل من معرّف القناة ومعرّف Plugin المفضل. إذا كان Plugin ذو الأولوية الأدنى قد اختير فقط لأنه مضمن أو مفعّل افتراضيًا، فإن OpenClaw يعطله في إعدادات وقت التشغيل الفعالة بحيث يملك Plugin واحد القناة وأدواتها. لا يزال اختيار المستخدم الصريح هو الغالب: إذا فعّل المستخدم كلا Pluginين صراحة، فإن OpenClaw يحافظ على هذا الاختيار ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من تغيير مجموعة Plugins المطلوبة بصمت. أبقِ preferOver محدد النطاق إلى معرّفات Plugins التي يمكنها فعلًا توفير القناة نفسها. إنه ليس حقل أولوية عامًا ولا يعيد تسمية مفاتيح إعداد المستخدم.

مرجع modelSupport

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

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

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

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

الحقول:

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

تُصرَّف إدخالات modelPatterns عبر compileSafeRegex، الذي يرفض الأنماط التي تحتوي على تكرار متداخل (على سبيل المثال (a+)+$). تُتخطى الأنماط التي تفشل في فحص السلامة بصمت، تمامًا مثل التعبيرات النمطية غير الصالحة نحويًا. أبقِ الأنماط بسيطة وتجنب المحددات الكمية المتداخلة.

مرجع modelCatalog

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

{
  "providers": ["openai"],
  "modelCatalog": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "input": ["text", "image"],
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 128000,
            "cost": {
              "input": 1.25,
              "output": 10,
              "cacheRead": 0.125
            },
            "status": "available",
            "tags": ["default"]
          }
        ]
      }
    },
    "aliases": {
      "azure-openai-responses": {
        "provider": "openai",
        "api": "azure-openai-responses"
      }
    },
    "suppressions": [
      {
        "provider": "azure-openai-responses",
        "model": "gpt-5.3-codex-spark",
        "reason": "not available on Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}

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

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

تشارك aliases في البحث عن ملكية المزوّد لتخطيط فهرس النماذج. يجب أن تكون أهداف الأسماء البديلة مزوّدين على المستوى الأعلى يملكهم Plugin نفسه. عندما تستخدم قائمة مفلترة حسب المزوّد اسمًا بديلًا، يستطيع OpenClaw قراءة البيان المالك وتطبيق تجاوزات واجهة 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[]`	بادئات تُزال قبل البحث عن الاسم البديل، مفيدة لتكرار `provider/model` القديم.
`prefixWhenBare`	`string`	بادئة تُضاف عندما لا يحتوي معرّف النموذج المُطبَّع مسبقًا على `/`.
`prefixWhenBareAfterAliasStartsWith`	`object[]`	قواعد مشروطة لبادئة المعرّف المجرد بعد البحث عن الاسم البديل، مفهرسة حسب `modelPrefix` و`prefix`.

مرجع providerEndpoints

استخدم providerEndpoints لتصنيف نقاط النهاية الذي يجب أن تعرفه سياسة الطلبات العامة قبل تحميل وقت تشغيل المزوّد. لا تزال النواة تملك معنى كل endpointClass؛ وتملك بيانات Manifest الخاصة بـ 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`.

مرجع secretProviderIntegrations

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

{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}

مفتاح الخريطة هو معرّف التكامل. إذا حُذف providerAlias، يستخدم OpenClaw معرّف التكامل كاسم بديل لمزوّد SecretRef. يجب أن تطابق أسماء المزوّدين البديلة نمط اسم مزوّد SecretRef البديل العادي، مثل team-secrets أو onepassword-work. عندما يختار المشغّل الإعداد المسبق، يكتب OpenClaw مرجع مزوّد مثل:

{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}

عند بدء التشغيل/إعادة التحميل، يحل OpenClaw ذلك المزوّد عبر تحميل بيانات تعريف بيان Plugin الحالية، والتحقق من أن Plugin المالك مثبّت ونشط، وتجسيد أمر exec من البيان. يؤدي تعطيل Plugin أو إزالته إلى إبطال المزوّد لـ SecretRefs النشطة. ما زال بإمكان المشغّلين الذين يريدون إعداد exec مستقلًا كتابة مزوّدي command/args يدويًا مباشرة. الإعدادات المسبقة ذات source: "exec" فقط مدعومة حاليًا. يجب أن يكون command هو ${node}، ويجب أن يكون args[0] سكربت حل نسبيًا إلى جذر Plugin وبادئًا بـ ./. يجسّده OpenClaw عند بدء التشغيل/إعادة التحميل إلى ملف Node التنفيذي الحالي ومسار السكربت المطلق داخل Plugin. خيارات Node مثل --require و--import و--loader و--env-file و--eval و--print ليست جزءًا من عقد الإعداد المسبق في البيان. يستطيع المشغّلون الذين يحتاجون أوامر غير Node إعداد مزوّدي exec يدويين مستقلين مباشرة. يشتق OpenClaw trustedDirs لإعدادات البيان المسبقة من جذر Plugin، ولإعدادات ${node} المسبقة، من دليل ملف Node التنفيذي الحالي. يتم تجاهل trustedDirs المكتوبة في البيان. تمر خيارات مزوّد exec الأخرى مثل timeoutMs وmaxOutputBytes وjsonOnly وenv وpassEnv وallowInsecurePath إلى إعداد مزوّد exec العادي في SecretRef.

مرجع modelPricing

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

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

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

الحقل	النوع	ما يعنيه
`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 المزوّد مثبّتًا. ترتيب سلطة الفهرس:

إعدادات المستخدم.
بيان 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.compat.pluginApi`	أدنى نطاق مطلوب لواجهة برمجة تطبيقات Plugin في OpenClaw لهذه الحزمة، باستخدام حد أدنى من semver مثل `>=2026.5.27`.
`openclaw.install.expectedIntegrity`	سلسلة تكامل dist المتوقعة من npm مثل `sha512-...`؛ تتحقق مسارات التثبيت والتحديث من الأثر المجلب بمقارنتها بها.
`openclaw.install.allowInvalidConfigRecovery`	يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمن عندما يكون التكوين غير صالح.
`openclaw.install.requiredPlatformPackages`	أسماء حزم npm البديلة التي يجب أن تتحقق عندما تطابق قيود منصة ملف القفل المضيف الحالي.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	يسمح بتحميل أسطح قناة وقت تشغيل الإعداد قبل الاستماع، ثم يؤجل Plugin القناة المكوّنة الكامل إلى ما بعد تفعيل ما بعد الاستماع.

تحدد بيانات البيان الوصفية خيارات المزود/القناة/الإعداد التي تظهر في الإعداد الأولي قبل تحميل وقت التشغيل. يخبر package.json#openclaw.install الإعداد الأولي بكيفية جلب Plugin هذا أو تمكينه عندما يختار المستخدم أحد تلك الخيارات. لا تنقل تلميحات التثبيت إلى openclaw.plugin.json. يُفرض openclaw.install.minHostVersion أثناء التثبيت وتحميل سجل البيانات الوصفية لمصادر Plugin غير المضمنة. تُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتخطى Plugins الخارجية على المضيفات الأقدم. يُفترض أن Plugins المصدر المضمنة متزامنة الإصدار مع نسخة المضيف المحلية. openclaw.install.requiredPlatformPackages مخصص لحزم npm التي تعرض ثنائيات أصلية مطلوبة عبر أسماء بديلة اختيارية خاصة بالمنصة. اسرد اسم حزمة npm المجرد لكل اسم بديل مدعوم للمنصة. أثناء تثبيت npm، يتحقق OpenClaw فقط من الاسم البديل المعلن الذي تطابق قيود ملف القفل لديه المضيف الحالي. إذا أبلغ npm عن النجاح لكنه أغفل ذلك الاسم البديل، يعيد OpenClaw المحاولة مرة واحدة بذاكرة تخزين مؤقت جديدة ويتراجع عن التثبيت إذا ظل الاسم البديل مفقودًا. يُفرض openclaw.compat.pluginApi أثناء تثبيت الحزمة لمصادر Plugin غير المضمنة. استخدمه لحد واجهة برمجة تطبيقات SDK/وقت تشغيل Plugin في OpenClaw الذي بُنيت الحزمة عليه. يمكن أن يكون أكثر صرامة من minHostVersion عندما تحتاج حزمة Plugin إلى واجهة برمجة تطبيقات أحدث لكنها لا تزال تحتفظ بتلميح تثبيت أدنى لمسارات أخرى. ترفع مزامنة إصدارات OpenClaw الرسمية حدود واجهة برمجة تطبيقات Plugin الرسمية الحالية إلى إصدار OpenClaw افتراضيًا، لكن إصدارات Plugin فقط يمكنها الاحتفاظ بحد أدنى أقل عندما تدعم الحزمة عمدًا مضيفات أقدم. لا تستخدم إصدار الحزمة وحده كعقد توافق. تظل peerDependencies.openclaw بيانات وصفية لحزمة npm؛ ويستخدم OpenClaw عقد openclaw.compat.pluginApi لاتخاذ قرارات توافق التثبيت. يجب أن تستخدم بيانات التثبيت عند الطلب الرسمية clawhubSpec عندما يكون Plugin منشورًا على ClawHub؛ يتعامل الإعداد الأولي مع ذلك كمصدر بعيد مفضل ويسجل حقائق أثر ClawHub بعد التثبيت. يظل npmSpec هو بديل التوافق للحزم التي لم تنتقل إلى ClawHub بعد. تثبيت إصدار npm الدقيق موجود بالفعل في npmSpec، على سبيل المثال "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". يجب أن تقرن إدخالات الفهرس الخارجية الرسمية المواصفات الدقيقة مع expectedIntegrity حتى تفشل مسارات التحديث بصورة مغلقة إذا لم يعد أثر npm المجلب يطابق الإصدار المثبت. لا يزال الإعداد الأولي التفاعلي يقدم مواصفات npm من السجل الموثوق، بما في ذلك أسماء الحزم المجردة وdist-tags، من أجل التوافق. يمكن لتشخيصات الفهرس أن تميز بين المصادر الدقيقة، والعائمة، والمثبتة بالتكامل، وناقصة التكامل، وعدم تطابق اسم الحزمة، وخيار افتراضي غير صالح. كما تحذر عندما يكون expectedIntegrity موجودًا لكن لا يوجد مصدر npm صالح يمكنه تثبيته. عندما يكون expectedIntegrity موجودًا، تفرضه مسارات التثبيت/التحديث؛ وعندما يُحذف، يُسجل حل السجل دون تثبيت تكامل. يجب أن توفر Plugins القنوات openclaw.setupEntry عندما تحتاج فحوصات الحالة أو قائمة القنوات أو SecretRef إلى تحديد الحسابات المكوّنة دون تحميل وقت التشغيل الكامل. يجب أن تعرض نقطة دخول الإعداد بيانات القناة الوصفية مع محولات تكوين وحالة وأسرار آمنة للإعداد؛ أبق عملاء الشبكة، ومستمعي Gateway، وأوقات تشغيل النقل في نقطة دخول الامتداد الرئيسية. لا تتجاوز حقول نقطة دخول وقت التشغيل فحوصات حدود الحزمة لحقول نقطة دخول المصدر. على سبيل المثال، لا يمكن لـ openclaw.runtimeExtensions جعل مسار openclaw.extensions الهارب قابلًا للتحميل. openclaw.install.allowInvalidConfigRecovery ضيق عمدًا. لا يجعل التكوينات المعطلة عشوائيًا قابلة للتثبيت. حاليًا، لا يسمح إلا لمسارات التثبيت بالاسترداد من حالات فشل محددة وقديمة لترقية Plugin مضمن، مثل مسار Plugin مضمن مفقود أو إدخال channels.<id> قديم لذلك Plugin المضمن نفسه. لا تزال أخطاء التكوين غير ذات الصلة تمنع التثبيت وتوجه المشغلين إلى openclaw doctor --fix. openclaw.channel.persistedAuthState بيانات وصفية للحزمة من أجل وحدة مدقق صغيرة جدًا:

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

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

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

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

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

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

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

راجع مرجع الإعدادات للاطلاع على مخطط plugins.* الكامل.

ملاحظات

البيان مطلوب لـ Plugins OpenClaw الأصلية، بما في ذلك عمليات التحميل من نظام الملفات المحلي. لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالبيان مخصص فقط للاكتشاف + التحقق.
تُحلّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة والمفاتيح غير المقتبسة ما دامت القيمة النهائية لا تزال كائنًا.
لا يقرأ محمّل البيان إلا حقول البيان الموثّقة. تجنّب المفاتيح المخصصة في المستوى الأعلى.
يمكن حذف channels وproviders وcliBackends وskills كلها عندما لا يحتاج إليها Plugin.
يجب أن يبقى providerCatalogEntry خفيفًا وألا يستورد كود وقت تشغيل واسعًا؛ استخدمه لبيانات تعريف كتالوج المزوّد الثابتة أو واصفات الاكتشاف المحدودة، وليس للتنفيذ وقت الطلب.
تُحدّد أنواع Plugin الحصرية عبر plugins.slots.*: ‏kind: "memory" عبر plugins.slots.memory، وkind: "context-engine" عبر plugins.slots.contextEngine (الافتراضي legacy).
صرّح عن نوع Plugin الحصري في هذا البيان. تم إهمال OpenClawPluginDefinition.kind في مدخل وقت التشغيل ويبقى فقط كآلية احتياطية للتوافق مع Plugins الأقدم.
بيانات تعريف متغيرات البيئة (setup.providers[].envVars، وproviderAuthEnvVars المهملة، وchannelEnvVars) تصريحية فقط. لا تزال الحالة والتدقيق والتحقق من تسليم cron والأسطح الأخرى المخصصة للقراءة فقط تطبّق ثقة Plugin وسياسة التفعيل الفعلية قبل التعامل مع متغير بيئة على أنه مُعدّ.
بالنسبة إلى بيانات تعريف معالج الإعداد وقت التشغيل التي تتطلب كود المزوّد، راجع خطافات وقت تشغيل المزوّد.
إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي متطلبات لقائمة السماح في مدير الحزم (على سبيل المثال، pnpm allow-build-scripts + pnpm rebuild <package>).

بناء Plugins

البدء باستخدام Plugins.

معمارية Plugin

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

نظرة عامة على SDK

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

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

​مثال بسيط

​مثال غني

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

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

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

​مرجع providerAuthChoices

​مرجع commandAliases

​مرجع activation

​مرجع qaRunners

​مرجع setup

​مرجع setup.providers

​حقول setup

​مرجع uiHints

​مرجع contracts

​مرجع mediaUnderstandingProviderMetadata

​مرجع channelConfigs

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

​مرجع modelSupport

​مرجع modelCatalog

​مرجع modelIdNormalization

​مرجع providerEndpoints

​مرجع providerRequest

​مرجع secretProviderIntegrations

​مرجع modelPricing

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

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

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

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

​متطلبات JSON Schema

​سلوك التحقق

​ملاحظات

​ذات صلة

بناء Plugins

معمارية Plugin

نظرة عامة على SDK

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

مثال بسيط

مثال غني

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

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

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

مرجع providerAuthChoices

مرجع commandAliases

مرجع activation

مرجع qaRunners

مرجع setup

مرجع setup.providers

حقول setup

مرجع uiHints

مرجع contracts

مرجع mediaUnderstandingProviderMetadata

مرجع channelConfigs

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

مرجع modelSupport

مرجع modelCatalog

مرجع modelIdNormalization

مرجع providerEndpoints

مرجع providerRequest

مرجع secretProviderIntegrations

مرجع modelPricing

فهرس مزوّدي OpenClaw

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

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

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

متطلبات JSON Schema

سلوك التحقق

ملاحظات

ذات صلة