​

Plugin manifest ‏(openclaw.plugin.json)

• Codex bundle: ‏.codex-plugin/plugin.json
• Claude bundle: ‏.claude-plugin/plugin.json أو تخطيط مكوّن Claude الافتراضي من دون manifest
• Cursor bundle: ‏.cursor-plugin/plugin.json

​

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

• هوية plugin
• التحقق من التكوين
• بيانات تعريف المصادقة والتهيئة الأولية التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل plugin
• بيانات تعريف الاسم المستعار والتمكين التلقائي التي يجب أن تُحل قبل تحميل وقت تشغيل plugin
• بيانات تعريف ملكية عائلة النماذج المختصرة التي يجب أن تفعّل plugin تلقائيًا قبل تحميل وقت التشغيل
• لقطات ملكية الإمكانات الثابتة المستخدمة في توصيلات التوافق المضمّنة وتغطية العقود
• بيانات تعريف تكوين خاصة بالقناة يجب دمجها في أسطح الفهرس والتحقق من دون تحميل وقت التشغيل
• تلميحات واجهة التكوين

• تسجيل سلوك وقت التشغيل
• الإعلان عن entrypoints الشيفرة
• بيانات تعريف npm install

​

مثال أدنى

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

​

مثال غني

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "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"
      }
    }
  }
}

​

مرجع الحقول العليا

​

مرجع providerAuthChoices

​

مرجع uiHints

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

​

مرجع contracts

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

مرجع channelConfigs

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

مرجع modelSupport

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

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

​

manifest مقابل package.json

• إذا كان يجب على OpenClaw معرفته قبل تحميل شيفرة plugin، فضعه في openclaw.plugin.json
• إذا كان يتعلق بالتغليف، أو ملفات الإدخال، أو سلوك npm install، فضعه في package.json

​

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

​

متطلبات JSON Schema

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

​

سلوك التحقق

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

​

ملاحظات

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

​

ذو صلة

• Building Plugins — البدء مع plugins
• Plugin Architecture — البنية الداخلية
• SDK Overview — مرجع Plugin SDK