---
read_when:
    - در حال اشکال‌زدایی نصب بسته‌های Plugin هستید
    - شما در حال تغییر رفتار راه‌اندازی Plugin، doctor، یا نصب توسط مدیر بسته هستید
    - شما در حال نگه‌داری از نصب‌های بسته‌بندی‌شده OpenClaw یا مانیفست‌های Plugin همراه هستید
sidebarTitle: Dependencies
summary: نحوهٔ نصب بسته‌های Plugin توسط OpenClaw و حل وابستگی‌های Plugin
title: حل وابستگی‌های Plugin
x-i18n:
    generated_at: "2026-05-02T11:55:17Z"
    model: gpt-5.5
    provider: openai
    source_hash: c9476529ad1d44ed1b17caca628c58acfbb1d8c73393f58fa7d3d76944a71aea
    source_path: plugins/dependency-resolution.md
    workflow: 16
---

# حل وابستگی‌های Plugin

OpenClaw کار مربوط به وابستگی‌های Plugin را در زمان نصب/به‌روزرسانی نگه می‌دارد. بارگذاری زمان اجرا
مدیرهای بسته را اجرا نمی‌کند، درخت‌های وابستگی را ترمیم نمی‌کند، یا دایرکتوری بسته
OpenClaw را تغییر نمی‌دهد.

## تفکیک مسئولیت

بسته‌های Plugin مالک گراف وابستگی خود هستند:

- وابستگی‌های زمان اجرا در `dependencies` یا `optionalDependencies` بسته Plugin قرار می‌گیرند
- ایمپورت‌های SDK/هسته، peer هستند یا ایمپورت‌های فراهم‌شده توسط OpenClaw
- Pluginهای توسعه محلی، وابستگی‌های ازپیش‌نصب‌شده خودشان را همراه دارند
- Pluginهای npm و git در ریشه‌های بسته متعلق به OpenClaw نصب می‌شوند

OpenClaw فقط مالک چرخه عمر Plugin است:

- کشف منبع Plugin
- نصب یا به‌روزرسانی بسته هنگام درخواست صریح
- ثبت فراداده نصب
- بارگذاری نقطه ورود Plugin
- شکست با خطای قابل اقدام وقتی وابستگی‌ها موجود نیستند

## ریشه‌های نصب

OpenClaw از ریشه‌های پایدار به‌ازای هر منبع استفاده می‌کند:

- بسته‌های npm زیر `~/.openclaw/npm` نصب می‌شوند
- بسته‌های git زیر `~/.openclaw/git` clone می‌شوند
- نصب‌های محلی/مسیر/آرشیو بدون ترمیم وابستگی کپی یا ارجاع داده می‌شوند

نصب‌های npm در ریشه npm با این دستور اجرا می‌شوند:

```bash
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```

npm ممکن است وابستگی‌های گذرای Plugin را کنار بسته Plugin به
`~/.openclaw/npm/node_modules` hoist کند. OpenClaw پیش از اعتماد به نصب، ریشه npm مدیریت‌شده را اسکن می‌کند
و هنگام حذف نصب، از npm برای حذف بسته‌های مدیریت‌شده توسط npm استفاده می‌کند، بنابراین وابستگی‌های
زمان اجرای hoistشده داخل مرز پاک‌سازی مدیریت‌شده باقی می‌مانند.

نصب‌های git مخزن را clone یا refresh می‌کنند، سپس اجرا می‌کنند:

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

سپس Plugin نصب‌شده از همان دایرکتوری بسته بارگذاری می‌شود، بنابراین حل‌وفصل
`node_modules` محلیِ بسته و والد همان‌طور کار می‌کند که برای یک بسته معمولی
Node کار می‌کند.

## Pluginهای محلی

Pluginهای محلی به‌عنوان دایرکتوری‌های تحت کنترل توسعه‌دهنده در نظر گرفته می‌شوند. OpenClaw برای آن‌ها
`npm install`، `pnpm install`، یا ترمیم وابستگی اجرا نمی‌کند. اگر یک Plugin محلی
وابستگی دارد، پیش از بارگذاری آن، وابستگی‌ها را در همان Plugin نصب کنید.

Pluginهای محلی TypeScript شخص ثالث می‌توانند از مسیر اضطراری Jiti استفاده کنند. Pluginهای
JavaScript بسته‌بندی‌شده و Pluginهای داخلی همراه، به‌جای Jiti از طریق
import/require بومی بارگذاری می‌شوند.

## راه‌اندازی و بارگذاری مجدد

راه‌اندازی Gateway و بارگذاری مجدد پیکربندی هرگز وابستگی‌های Plugin را نصب نمی‌کنند. آن‌ها
رکوردهای نصب Plugin را می‌خوانند، نقطه ورود را محاسبه می‌کنند، و آن را بارگذاری می‌کنند.

اگر یک وابستگی در زمان اجرا موجود نباشد، Plugin بارگذاری نمی‌شود و خطا
باید اپراتور را به یک اصلاح صریح راهنمایی کند:

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

`doctor --fix` می‌تواند وضعیت وابستگی قدیمی تولیدشده توسط OpenClaw را پاک‌سازی کند و
Pluginهای قابل‌دانلود پیکربندی‌شده‌ای را که در رکوردهای نصب محلی وجود ندارند نصب کند.
این دستور وابستگی‌های یک Plugin محلیِ ازپیش‌نصب‌شده را ترمیم نمی‌کند.

## Pluginهای همراه

Pluginهای سبک و حیاتی برای هسته، به‌عنوان بخشی از OpenClaw منتشر می‌شوند.
آن‌ها یا نباید درخت وابستگی زمان اجرای سنگینی داشته باشند، یا باید به یک
بسته قابل‌دانلود در ClawHub/npm منتقل شوند.

برای فهرست تولیدشده فعلی Pluginهایی که در بسته هسته منتشر می‌شوند، بیرونی نصب می‌شوند،
یا فقط در سورس باقی می‌مانند، [موجودی Plugin](/fa/plugins/plugin-inventory) را ببینید.

manifestهای Plugin همراه نباید staging وابستگی درخواست کنند. قابلیت‌های بزرگ یا اختیاری
Plugin باید به‌عنوان یک Plugin معمولی بسته‌بندی شوند و از طریق همان مسیر
npm/git/ClawHub مانند Pluginهای شخص ثالث نصب شوند.

در checkoutهای سورس، OpenClaw مخزن را به‌عنوان یک monorepo مبتنی بر pnpm در نظر می‌گیرد. پس از
`pnpm install`، Pluginهای همراه از `extensions/<id>` بارگذاری می‌شوند تا وابستگی‌های
workspace محلی بسته در دسترس باشند و ویرایش‌ها مستقیماً اعمال شوند. توسعه در checkout سورس
فقط با pnpm پشتیبانی می‌شود؛ اجرای ساده `npm install` در ریشه مخزن
روش پشتیبانی‌شده‌ای برای آماده‌سازی وابستگی‌های Plugin همراه نیست.

| شکل نصب                         | محل Plugin همراه                     | مالک وابستگی                                                        |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw`        | درخت زمان اجرای ساخته‌شده داخل بسته | بسته OpenClaw و جریان‌های صریح نصب/به‌روزرسانی/doctor برای Plugin   |
| checkout از Git به‌همراه `pnpm install` | بسته‌های workspace در `extensions/<id>` | workspace مبتنی بر pnpm، شامل وابستگی‌های خود هر بسته Plugin        |
| `openclaw plugins install ...`   | ریشه Plugin مدیریت‌شده npm/git/ClawHub | جریان نصب/به‌روزرسانی Plugin                                       |

## پاک‌سازی قدیمی

نسخه‌های قدیمی‌تر OpenClaw در زمان راه‌اندازی یا هنگام ترمیم doctor، ریشه‌های وابستگی
Plugin همراه تولید می‌کردند. پاک‌سازی فعلی doctor وقتی از `--fix` استفاده شود،
آن دایرکتوری‌ها و symlinkهای کهنه را حذف می‌کند، از جمله ریشه‌های قدیمی
`plugin-runtime-deps`، manifestهای `.openclaw-runtime-deps*`، `node_modules`های Plugin تولیدشده،
دایرکتوری‌های مرحله نصب، و storeهای pnpm محلیِ بسته.

این مسیرها فقط بقایای قدیمی هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند.
