حل وابستگی‌های 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 با این دستور اجرا می‌شوند:

npm install --prefix ~/.openclaw/npm <spec> --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

openclaw plugins install npm-pack:<path.tgz> از همان ریشهٔ npm مدیریت‌شده برای یک tarball محلی npm-pack استفاده می‌کند. OpenClaw فرادادهٔ npm داخل tarball را می‌خواند، آن را به‌عنوان یک وابستگی کپی‌شدهٔ file: به ریشهٔ مدیریت‌شده اضافه می‌کند، نصب معمول npm را اجرا می‌کند، و سپس پیش از اعتماد به Plugin، فرادادهٔ lockfile نصب‌شده را تأیید می‌کند. این برای پذیرش بسته و اثبات نسخهٔ نامزد انتشار در نظر گرفته شده است، جایی که یک مصنوعهٔ pack محلی باید مانند مصنوعهٔ registry که شبیه‌سازی می‌کند رفتار کند.

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

Pluginهایی که openclaw/plugin-sdk/* را import می‌کنند، openclaw را به‌عنوان وابستگی peer اعلام می‌کنند. OpenClaw اجازه نمی‌دهد npm یک کپی registry جداگانه از بستهٔ میزبان را در ریشهٔ مدیریت‌شده نصب کند، چون بسته‌های میزبان قدیمی می‌توانند در نصب‌های بعدی Plugin بر حل‌وفصل peer در npm اثر بگذارند. نصب‌های npm مدیریت‌شده از حل‌وفصل/مادی‌سازی peer توسط npm برای ریشهٔ مشترک صرف‌نظر می‌کنند و OpenClaw پس از نصب، به‌روزرسانی، یا حذف نصب، پیوندهای Plugin-محلی node_modules/openclaw را برای بسته‌های نصب‌شده‌ای که peer میزبان را اعلام می‌کنند دوباره برقرار می‌کند.

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

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 بارگذاری نمی‌شود و خطا باید اپراتور را به یک اصلاح صریح هدایت کند:

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

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

# Pluginهای همراه

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

برای فهرست تولیدشدهٔ فعلی Pluginهایی که در بستهٔ هسته ارسال می‌شوند، به‌صورت خارجی نصب می‌شوند، یا فقط در سورس باقی می‌مانند، موجودی Plugin را ببینید.

manifestهای Plugin همراه نباید درخواست مرحله‌بندی وابستگی کنند. قابلیت‌های بزرگ یا اختیاری 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 ریشه‌های وابستگی Plugin همراه را هنگام راه‌اندازی یا در طول ترمیم doctor تولید می‌کردند. پاک‌سازی فعلی doctor هنگام استفاده از --fix آن دایرکتوری‌ها و symlinkهای قدیمی را حذف می‌کند، از جمله ریشه‌های قدیمی plugin-runtime-deps، symlinkهای بستهٔ سراسری با prefix مربوط به Node که به مقصدهای هرس‌شدهٔ plugin-runtime-deps اشاره می‌کنند، manifestهای .openclaw-runtime-deps*، node_modules تولیدشدهٔ Plugin، دایرکتوری‌های مرحلهٔ نصب، و storeهای pnpm محلیِ بسته. postinstall بسته‌بندی‌شده نیز پیش از هرس ریشه‌های مقصد قدیمی، آن symlinkهای سراسری را حذف می‌کند تا ارتقاها importهای بستهٔ ESM آویزان باقی نگذارند.

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