--- read_when: - أنت تستكشف أخطاء تثبيت حزم Plugin وإصلاحها - أنت تغيّر سلوك بدء تشغيل Plugin أو doctor أو تثبيت مدير الحزم - أنت تتولى صيانة تثبيتات OpenClaw المعبأة أو ملفات بيان Plugin المضمّنة sidebarTitle: Dependencies summary: كيف يثبّت OpenClaw حزم Plugin ويحلّ تبعيات Plugin title: حل اعتماديات Plugin x-i18n: generated_at: "2026-05-10T19:50:29Z" model: gpt-5.5 provider: openai source_hash: eb9637f46f273de976ff9203d23558d8bb51922b347871bc71917ef61d3c04a3 source_path: plugins/dependency-resolution.md workflow: 16 --- يُبقي OpenClaw عمل تبعيات Plugin في وقت التثبيت/التحديث. لا يقوم التحميل في وقت التشغيل بتشغيل مديري الحزم، أو إصلاح أشجار التبعيات، أو تعديل دليل حزمة OpenClaw. ## تقسيم المسؤوليات تمتلك حزم Plugin رسم بياني التبعيات الخاص بها: - توجد تبعيات وقت التشغيل في `dependencies` أو `optionalDependencies` الخاصة بحزمة Plugin - تكون استيرادات SDK/النواة تبعيات نظيرة أو استيرادات يوفرها OpenClaw - تجلب Plugins التطوير المحلية تبعياتها المثبتة مسبقا الخاصة بها - تثبت Plugins من npm وgit في جذور حزم مملوكة لـ OpenClaw يمتلك OpenClaw دورة حياة Plugin فقط: - اكتشاف مصدر Plugin - تثبيت الحزمة أو تحديثها عند الطلب الصريح - تسجيل بيانات تعريف التثبيت - تحميل نقطة دخول Plugin - الفشل مع خطأ قابل للتنفيذ عند فقدان التبعيات ## جذور التثبيت يستخدم OpenClaw جذورا ثابتة لكل مصدر: - تثبت حزم npm تحت `~/.openclaw/npm` - تستنسخ حزم git تحت `~/.openclaw/git` - تنسخ تثبيتات local/path/archive أو يشار إليها من دون إصلاح التبعيات تعمل تثبيتات npm في جذر npm باستخدام: ```bash cd ~/.openclaw/npm npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund ``` يستخدم `openclaw plugins install npm-pack:` جذر npm المدار نفسه لكرة tar محلية من npm-pack. يقرأ OpenClaw بيانات تعريف npm الخاصة بكرة tar، ويضيفها إلى الجذر المدار كتبعية `file:` منسوخة، ويشغل تثبيت npm العادي، ثم يتحقق من بيانات تعريف lockfile المثبتة قبل الوثوق بـ Plugin. هذا مخصص لإثبات قبول الحزمة ومرشح الإصدار حيث ينبغي أن يتصرف أثر الحزمة المحلي مثل أثر السجل الذي يحاكيه. قد يرفع npm التبعيات الانتقالية إلى `~/.openclaw/npm/node_modules` بجانب حزمة Plugin. يفحص OpenClaw جذر npm المدار قبل الوثوق بالتثبيت ويستخدم npm لإزالة الحزم المدارة بواسطة npm أثناء إلغاء التثبيت، لذلك تبقى تبعيات وقت التشغيل المرفوعة داخل حدود التنظيف المدارة. تعلن Plugins التي تستورد `openclaw/plugin-sdk/*` عن `openclaw` كتبعية نظيرة. لا يسمح OpenClaw لـ npm بتثبيت نسخة سجل منفصلة من حزمة المضيف في الجذر المدار، لأن حزم المضيف القديمة يمكن أن تؤثر في حل تبعيات npm النظيرة أثناء تثبيت Plugins اللاحقة. تتخطى تثبيتات npm المدارة حل/تجسيد تبعيات npm النظيرة للجذر المشترك ويعيد OpenClaw تأكيد روابط `node_modules/openclaw` المحلية لـ Plugin للحزم المثبتة التي تعلن عن نظير المضيف بعد التثبيت أو التحديث أو إلغاء التثبيت. تستنسخ تثبيتات git المستودع أو تحدثه، ثم تشغل: ```bash npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` ثم يحمل Plugin المثبت من دليل تلك الحزمة، لذلك يعمل حل `node_modules` المحلي للحزمة والأب بالطريقة نفسها التي يعمل بها لحزمة Node عادية. ## Plugins المحلية تعامل Plugins المحلية كدلائل يتحكم بها المطور. لا يقوم OpenClaw بتشغيل `npm install` أو `pnpm install` أو إصلاح التبعيات لها. إذا كان لدى Plugin محلي تبعيات، فثبتها في ذلك Plugin قبل تحميله. يمكن لـ Plugins TypeScript المحلية التابعة لجهات خارجية استخدام مسار Jiti الطارئ. تحمل Plugins JavaScript المحزمة وPlugins الداخلية المضمنة عبر import/require الأصلي بدلا من Jiti. ## بدء التشغيل وإعادة التحميل لا يثبت بدء تشغيل Gateway وإعادة تحميل الإعدادات تبعيات Plugin أبدا. يقرآن سجلات تثبيت Plugin، ويحسبان نقطة الدخول، ويحملانها. إذا كانت تبعية مفقودة في وقت التشغيل، يفشل Plugin في التحميل وينبغي أن يوجه الخطأ المشغل إلى إصلاح صريح: ```bash openclaw plugins update openclaw plugins install openclaw doctor --fix ``` يمكن لـ `doctor --fix` تنظيف حالة التبعيات القديمة التي أنشأها OpenClaw واسترداد Plugins القابلة للتنزيل المفقودة من سجلات التثبيت المحلية عندما تشير الإعدادات إليها. لا يصلح doctor تبعيات Plugin محلي مثبت مسبقا. ## Plugins المضمنة تشحن Plugins المضمنة الخفيفة والحرجة للنواة كجزء من OpenClaw. ينبغي ألا تكون لها شجرة تبعيات وقت تشغيل ثقيلة، أو أن تنقل إلى حزمة قابلة للتنزيل على ClawHub/npm. للاطلاع على القائمة الحالية المولدة لـ Plugins التي تشحن في حزمة النواة، أو تثبت خارجيا، أو تبقى مصدرية فقط، راجع [مخزون Plugin](/ar/plugins/plugin-inventory). يجب ألا تطلب بيانات تعريف Plugins المضمنة تجهيز التبعيات. ينبغي تحزيم وظائف Plugin الكبيرة أو الاختيارية كـ Plugin عادي وتثبيتها عبر مسار npm/git/ClawHub نفسه مثل Plugins التابعة لجهات خارجية. في نسخ المصدر، يعامل OpenClaw المستودع كمستودع pnpm أحادي. بعد `pnpm install`، تحمل Plugins المضمنة من `extensions/` بحيث تكون تبعيات مساحة العمل المحلية للحزمة متاحة وتلتقط التعديلات مباشرة. تطوير نسخة المصدر مخصص لـ pnpm فقط؛ لا يعد `npm install` العادي في جذر المستودع طريقة مدعومة لتحضير تبعيات Plugin المضمنة. | شكل التثبيت | موقع Plugin المضمن | مالك التبعية | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | | `npm install -g openclaw` | شجرة وقت تشغيل مبنية داخل الحزمة | حزمة OpenClaw وتدفقات تثبيت/تحديث/doctor الصريحة لـ Plugin | | نسخة git مع `pnpm install` | حزم مساحة عمل `extensions/` | مساحة عمل pnpm، بما في ذلك التبعيات الخاصة بكل حزمة Plugin | | `openclaw plugins install ...` | جذر Plugin مدار من npm/git/ClawHub | تدفق تثبيت/تحديث Plugin | ## تنظيف القديم أنشأت إصدارات OpenClaw الأقدم جذور تبعيات Plugins المضمنة عند بدء التشغيل أو أثناء إصلاح doctor. يزيل تنظيف doctor الحالي تلك الأدلة والروابط الرمزية القديمة عند استخدام `--fix`، بما في ذلك جذور `plugin-runtime-deps` القديمة، وروابط حزم بادئة Node العامة التي تشير إلى أهداف `plugin-runtime-deps` المشذبة، وبيانات تعريف `.openclaw-runtime-deps*`، و`node_modules` المولدة لـ Plugin، وأدلة مرحلة التثبيت، ومخازن pnpm المحلية للحزمة. يزيل postinstall المحزم أيضا تلك الروابط الرمزية العامة قبل تشذيب جذور الأهداف القديمة حتى لا تترك الترقيات استيرادات حزم ESM متدلية. هذه المسارات ليست سوى بقايا قديمة. يجب ألا تنشئها التثبيتات الجديدة.