---
read_when:
    - أنت تعمل على تصحيح أخطاء تثبيت حزم Plugin
    - أنت تغيّر سلوك بدء تشغيل Plugin أو الفحص أو التثبيت عبر مدير الحزم
    - أنت تدير عمليات تثبيت OpenClaw المجمّعة أو بيانات تعريف Plugin المضمّنة
sidebarTitle: Dependencies
summary: كيفية تثبيت OpenClaw لحزم Plugin وحل تبعيات Plugin
title: حل تبعيات Plugin
x-i18n:
    generated_at: "2026-07-12T06:16:12Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: ae24a82568e275399cb7b68729d2805956792852612f84d6918850305f0eb243
    source_path: plugins/dependency-resolution.md
    workflow: 16
---

يتعامل OpenClaw مع تبعيات Plugin أثناء التثبيت/التحديث فقط. ولا يشغّل التحميل في وقت التشغيل مدير حزم مطلقًا، ولا يصلح شجرة تبعيات، ولا يعدّل دليل حزمة OpenClaw.

## تقسيم المسؤوليات

تمتلك حزم Plugin رسم تبعياتها:

- توجد تبعيات وقت التشغيل في `dependencies` أو `optionalDependencies` الخاصة بحزمة Plugin.
- تكون استيرادات SDK/النواة تبعيات نظيرة أو استيرادات مقدَّمة من OpenClaw.
- تجلب إضافات التطوير المحلية تبعياتها المثبّتة مسبقًا.
- تُثبَّت إضافات npm وgit في جذور حزم مملوكة لـ OpenClaw.

يمتلك OpenClaw دورة حياة Plugin فقط:

- اكتشاف مصدر Plugin.
- تثبيت الحزمة أو تحديثها عند طلب ذلك صراحةً.
- تسجيل بيانات التثبيت الوصفية.
- تحميل نقطة دخول Plugin.
- الإخفاق مع خطأ قابل للتنفيذ عند فقدان التبعيات.

## جذور التثبيت

يستخدم OpenClaw جذورًا ثابتة لكل مصدر:

- تُثبَّت حزم npm في مشاريع منفصلة لكل Plugin ضمن
  `~/.openclaw/npm/projects/<encoded-package>`.
- تُستنسخ حزم git ضمن `~/.openclaw/git`.
- تُنسخ تثبيتات المصدر المحلي/المسار/الأرشيف أو يُشار إليها من دون إصلاح التبعيات.

تُشغَّل تثبيتات npm في جذر المشروع الخاص بكل Plugin باستخدام:

```bash
cd ~/.openclaw/npm/projects/<encoded-package>
npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund
```

يستخدم `openclaw plugins install npm-pack:<path.tgz>` جذر مشروع npm نفسه الخاص بكل Plugin لملف tarball محلي من npm-pack: يقرأ OpenClaw بيانات npm الوصفية لملف tarball، ويضيفه إلى المشروع المُدار كتبعية `file:` منسوخة، ويشغّل تثبيت npm المعتاد أعلاه، ثم يتحقق من بيانات ملف القفل المثبّت الوصفية قبل الوثوق بـ Plugin. يوجد هذا المسار لإثبات قبول الحزمة والنسخة المرشحة للإصدار، حيث ينبغي أن تتصرف أداة الحزمة المحلية مثل أداة السجل التي تحاكيها.

استخدم `npm-pack:` عند اختبار حزم Plugin الرسمية أو الخارجية قبل النشر. يفيد تثبيت أرشيف أو مسار خام في تصحيح الأخطاء محليًا، لكنه لا يثبت مسار التبعيات نفسه الخاص بحزمة npm أو ClawHub مثبّتة. يثبت `npm-pack:` بنية تثبيت الحزمة المُدارة؛ لكنه لا يثبت بمفرده أن Plugin محتوى رسمي مرتبط بالفهرس.

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

إذا أخفق Plugin في وقت التشغيل بسبب استيراد مفقود، فأصلح بيان الحزمة بدلًا من إصلاح المشروع المُدار يدويًا. تنتمي استيرادات وقت التشغيل إلى `dependencies` أو `optionalDependencies` الخاصة بحزمة Plugin؛ ولا تُثبَّت `devDependencies` لمشاريع وقت التشغيل المُدارة. يمكن أن يزيل تنفيذ `npm install` محليًا داخل `~/.openclaw/npm/projects/<encoded-package>` عائقًا أمام تشخيص مؤقت، لكنه ليس إثباتًا لقبول الحزمة لأن التثبيت أو التحديث التالي يعيد إنشاء المشروع من بيانات الحزمة الوصفية.

قد يرفع npm التبعيات المتعدية إلى `node_modules` الخاص بمشروع كل Plugin بجوار حزمة Plugin. يفحص OpenClaw جذر المشروع المُدار قبل الوثوق بالتثبيت، ويزيل ذلك المشروع عند إلغاء التثبيت، لذلك تظل تبعيات وقت التشغيل المرفوعة داخل حدود التنظيف الخاصة بذلك Plugin.

يمكن لحزم Plugin المنشورة على npm تضمين `npm-shrinkwrap.json`؛ ويستخدم npm ملف القفل القابل للنشر هذا أثناء التثبيت، ويدعمه جذر مشروع npm المُدار في OpenClaw عبر مسار التثبيت المعتاد. يجب أن تتضمن حزم Plugin القابلة للنشر والمملوكة لـ OpenClaw ملف shrinkwrap محليًا للحزمة ومولّدًا من رسم التبعيات المنشور لتلك الحزمة:

```bash
pnpm deps:shrinkwrap:generate
pnpm deps:shrinkwrap:check
```

يزيل المولّد `devDependencies` الخاصة بـ Plugin، ويطبّق سياسة تجاوز مساحة العمل، ويكتب `extensions/<id>/npm-shrinkwrap.json` لكل Plugin يحتوي على `openclaw.release.publishToNpm: true`. يمكن لحزم Plugin التابعة لجهات خارجية أيضًا تضمين ملف shrinkwrap؛ ولا يشترط OpenClaw وجوده لحزم المجتمع، لكن npm يلتزم به عند وجوده.

قبل اعتبار حزمة محلية إثباتًا لنسخة مرشحة للإصدار، افحص ملف tarball الذي سيُثبَّت:

```bash
npm pack --pack-destination /tmp
tar -xOf /tmp/<plugin-package>.tgz package/package.json
tar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'
```

بالنسبة إلى تغييرات التبعيات، تحقق أيضًا من قدرة تثبيت إنتاجي على حل حزم وقت التشغيل من دون تبعيات التطوير:

```bash
tmpdir=$(mktemp -d)
(
  cd "$tmpdir"
  npm init -y >/dev/null
  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz
)
rm -rf "$tmpdir"
```

يمكن أيضًا لحزم npm الخاصة بـ Plugin والمملوكة لـ OpenClaw أن تُنشر باستخدام `bundledDependencies` صريحة. يضع مسار نشر npm قائمة أسماء تبعيات وقت التشغيل كطبقة فوقية، ويزيل بيانات مساحة العمل المخصصة للتطوير فقط من البيان المنشور، ويشغّل تثبيت npm من دون نصوص برمجية لتبعيات وقت التشغيل المحلية للحزمة، ثم يحزم ملف tarball الخاص بـ Plugin أو ينشره مع تضمين ملفات تلك التبعيات. تلغي الحزم كثيفة الاعتماد على المكونات الأصلية (Codex وACPX وCopilot وllama.cpp وmemory-lancedb وTlon) ذلك باستخدام `openclaw.release.bundleRuntimeDependencies: false`؛ وتظل تشحن ملف shrinkwrap، لكن npm يحل تبعيات وقت التشغيل أثناء التثبيت بدلًا من تضمين كل ملف ثنائي لكل منصة في ملف tarball الخاص بـ Plugin. لا تجمع حزمة `openclaw` الجذرية شجرة تبعياتها الكاملة.

تعلن الإضافات التي تستورد `openclaw/plugin-sdk/*` عن `openclaw` كتبعية نظيرة. لا يسمح OpenClaw لـ npm بتثبيت نسخة منفصلة من حزمة المضيف من السجل داخل مشروع مُدار، لأن حزمة مضيف قديمة يمكن أن تؤثر في حل npm للتبعيات النظيرة داخل ذلك Plugin. تتخطى تثبيتات npm المُدارة حل npm للتبعيات النظيرة وتجسيدها، ويعيد OpenClaw فرض روابط `node_modules/openclaw` المحلية الخاصة بـ Plugin للحزم المثبّتة التي تعلن عن تبعية المضيف النظيرة، بعد التثبيت أو التحديث.

تستنسخ تثبيتات git المستودع أو تحدّثه، ثم تشغّل:

```bash
npm install --omit=dev --ignore-scripts --no-audit --no-fund
```

بعد ذلك يُحمَّل Plugin المثبّت من دليل تلك الحزمة، لذلك يعمل حل `node_modules` المحلي للحزمة والأبوي بالطريقة نفسها التي يعمل بها في حزمة Node عادية.

## الإضافات المحلية

الإضافات المحلية هي أدلة يتحكم فيها المطور. لا يشغّل OpenClaw مطلقًا `npm install` أو `pnpm install` أو إصلاح التبعيات لها؛ فإذا كانت لـ Plugin محلية تبعيات، فثبّتها داخل تلك الإضافة قبل تحميلها.

تُحمَّل إضافات TypeScript المحلية التابعة لجهات خارجية عبر Jiti كمسار طوارئ. وتُحمَّل إضافات JavaScript المحزّمة والإضافات الداخلية المضمّنة عبر import/require الأصليين بدلًا من ذلك.

## بدء التشغيل وإعادة التحميل

لا يثبّت بدء تشغيل Gateway وإعادة تحميل الإعدادات تبعيات Plugin مطلقًا. فهما يقرآن سجلات تثبيت Plugin، ويحسبان نقطة الدخول، ويحمّلانها.

يؤدي فقدان تبعية في وقت التشغيل إلى إخفاق تحميل Plugin مع خطأ يوجّه المشغّل إلى إصلاح صريح:

```bash
openclaw plugins update <id>
openclaw plugins install <source>
openclaw doctor --fix
```

ينظف `doctor --fix` حالة التبعيات القديمة التي أنشأها OpenClaw، ويمكنه استعادة الإضافات القابلة للتنزيل والمفقودة من سجلات التثبيت المحلية عندما تظل الإعدادات تشير إليها. لا يصلح Doctor تبعيات Plugin محلية مثبّتة بالفعل.

## الإضافات المضمّنة

تأتي الإضافات المضمّنة خفيفة الوزن والضرورية للنواة كجزء من OpenClaw. وينبغي إما ألا تحمل شجرة كبيرة من تبعيات وقت التشغيل، أو أن تنتقل إلى حزمة قابلة للتنزيل على ClawHub/npm.

للاطلاع على القائمة المولّدة الحالية للإضافات التي تأتي ضمن الحزمة الأساسية، أو تُثبَّت خارجيًا، أو تظل متاحة كمصدر فقط، راجع
[مخزون Plugin](/ar/plugins/plugin-inventory).

يجب ألا تطلب بيانات الإضافات المضمّنة تجهيز التبعيات. ينبغي تحزيم وظائف Plugin الكبيرة أو الاختيارية كإضافة عادية وتثبيتها عبر مسار npm/git/ClawHub نفسه المستخدم لإضافات الجهات الخارجية.

في نسخ المصدر، يتعامل OpenClaw مع المستودع بوصفه مستودعًا أحاديًا لـ pnpm. بعد `pnpm install`، تُحمَّل الإضافات المضمّنة من `extensions/<id>` كي تتوفر تبعيات مساحة العمل المحلية للحزمة وتُلتقط التعديلات مباشرةً. يقتصر تطوير نسخة المصدر على pnpm؛ ولا يجهّز تنفيذ `npm install` العادي في جذر المستودع تبعيات Plugin المضمّنة.

| بنية التثبيت                    | موقع Plugin المضمّن               | مالك التبعيات                                                     |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw`        | شجرة وقت التشغيل المبنية داخل الحزمة | حزمة OpenClaw ومسارات تثبيت/تحديث/Doctor الصريحة لـ Plugin     |
| نسخة git مع `pnpm install` | حزم مساحة العمل `extensions/<id>`  | مساحة عمل pnpm، بما في ذلك التبعيات الخاصة بكل حزمة Plugin |
| `openclaw plugins install ...`   | جذر مشروع npm/git/ClawHub المُدار  | مسار تثبيت/تحديث Plugin                                       |

## تنظيف المكوّنات القديمة

أنشأت إصدارات OpenClaw الأقدم جذور تبعيات للإضافات المضمّنة عند بدء التشغيل أو أثناء إصلاح Doctor. يزيل التنظيف الحالي في Doctor تلك الأدلة والروابط الرمزية القديمة باستخدام `--fix`، بما في ذلك جذور `plugin-runtime-deps` القديمة، والروابط الرمزية العامة لحزم بادئة Node التي تشير إلى أهداف `plugin-runtime-deps` المشذّبة، وبيانات `.openclaw-runtime-deps*`، و`node_modules` المولّدة للإضافات، وأدلة مراحل التثبيت، ومخازن pnpm المحلية للحزم. كما تزيل مرحلة ما بعد التثبيت للحزمة تلك الروابط الرمزية العامة قبل تشذيب الجذور القديمة المستهدفة، كي لا تترك الترقيات استيرادات حزم ESM معلّقة.

استخدمت تثبيتات npm الأقدم أيضًا جذرًا مشتركًا في `~/.openclaw/npm/node_modules`. ولا تزال مسارات التثبيت والتحديث وإلغاء التثبيت وDoctor الحالية تتعرف على ذلك الجذر المسطّح القديم لأغراض الاستعادة والتنظيف فقط. أما تثبيتات npm الجديدة فتنشئ جذور مشاريع منفصلة لكل Plugin بدلًا منه.
