رفع وابستگی‌های Plugin

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

تفکیک مسئولیت‌ها

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

• وابستگی‌های زمان اجرا در dependencies یا optionalDependencies بستهٔ Plugin قرار می‌گیرند.
• واردسازی‌های SDK/هسته به‌صورت وابستگی همتا یا واردسازی‌های فراهم‌شدهٔ OpenClaw هستند.
• Pluginهای توسعهٔ محلی وابستگی‌های ازپیش‌نصب‌شدهٔ خود را همراه دارند.
• Pluginهای npm و git در ریشه‌های بسته‌ای که تحت مالکیت OpenClaw هستند نصب می‌شوند.

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

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

ریشه‌های نصب

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

• بسته‌های npm در پروژه‌های جداگانهٔ هر Plugin در مسیر ~/.openclaw/npm/projects/<encoded-package> نصب می‌شوند.
• بسته‌های git در ~/.openclaw/git همسانه‌سازی می‌شوند.
• نصب‌های محلی/مسیر/بایگانی بدون ترمیم وابستگی کپی یا ارجاع داده می‌شوند.

نصب‌های npm در ریشهٔ همان پروژهٔ مختص Plugin اجرا می‌شوند:

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-pack از همان ریشهٔ پروژهٔ npm مختص Plugin استفاده می‌کند: OpenClaw فرادادهٔ npm تاربال را می‌خواند، آن را به‌عنوان یک وابستگی کپی‌شدهٔ file: به پروژهٔ مدیریت‌شده اضافه می‌کند، نصب عادی npm بالا را اجرا می‌کند و سپس پیش از اعتماد به Plugin، فرادادهٔ لاک‌فایل نصب‌شده را اعتبارسنجی می‌کند. این مسیر برای اثبات پذیرش بسته و نامزد انتشار وجود دارد؛ جایی که یک مصنوع بسته‌بندی‌شدهٔ محلی باید مانند مصنوع رجیستری که شبیه‌سازی می‌کند رفتار کند.

هنگام آزمایش بسته‌های Plugin رسمی یا خارجی پیش از انتشار، از npm-pack: استفاده کنید. نصب از بایگانی خام یا مسیر برای اشکال‌زدایی محلی مفید است، اما همان مسیر وابستگی یک بستهٔ نصب‌شده از npm یا ClawHub را اثبات نمی‌کند. npm-pack: ساختار نصب بستهٔ مدیریت‌شده را اثبات می‌کند؛ اما به‌تنهایی ثابت نمی‌کند که Plugin محتوای رسمیِ متصل به کاتالوگ است.

وقتی رفتار به وضعیت Plugin همراه یا Plugin رسمی مورد اعتماد وابسته است، اثبات بستهٔ محلی را با نصب رسمیِ مبتنی بر کاتالوگ یا مسیر بستهٔ منتشرشده‌ای همراه کنید که اعتماد رسمی را ثبت می‌کند. دسترسی به ابزارهای کمکی ممتاز و مدیریت دامنهٔ رسمیِ مورد اعتماد باید در همان مسیر نصب مورد اعتماد اعتبارسنجی شود، نه اینکه از نصب یک تاربال محلی استنباط شود.

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

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

مولد، devDependenciesهای Plugin را حذف می‌کند، سیاست بازنویسی فضای کاری را اعمال می‌کند و برای هر Plugin دارای openclaw.release.publishToNpm: true، فایل extensions/<id>/npm-shrinkwrap.json را می‌نویسد. بسته‌های Plugin شخص ثالث نیز می‌توانند یک shrinkwrap همراه داشته باشند؛ OpenClaw آن را برای بسته‌های جامعه الزامی نمی‌کند، اما npm در صورت وجود به آن احترام می‌گذارد.

پیش از آنکه یک بستهٔ محلی را اثبات نامزد انتشار در نظر بگیرید، تاربال نصب‌شونده را بررسی کنید:

npm pack --pack-destination /tmptar -xOf /tmp/<plugin-package>.tgz package/package.jsontar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

برای تغییرات وابستگی، همچنین بررسی کنید که یک نصب تولیدی بتواند بسته‌های زمان اجرا را بدون وابستگی‌های توسعه resolve کند:

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"

بسته‌های Plugin در npm که تحت مالکیت OpenClaw هستند همچنین می‌توانند با bundledDependencies صریح منتشر شوند. مسیر انتشار npm، فهرست نام وابستگی‌های زمان اجرا را هم‌پوشانی می‌کند، فرادادهٔ فضای کاریِ مختص توسعه را از مانیفست منتشرشده حذف می‌کند، یک نصب npm بدون اسکریپت برای وابستگی‌های زمان اجرای محلیِ بسته اجرا می‌کند و سپس تاربال Plugin را همراه با فایل‌های آن وابستگی‌ها بسته‌بندی یا منتشر می‌کند. بسته‌های سنگین از نظر کد بومی (Codex، ACPX، Copilot، llama.cpp، memory-lancedb، Tlon) با openclaw.release.bundleRuntimeDependencies: false از این فرایند مستثنا می‌شوند؛ آن‌ها همچنان یک shrinkwrap ارائه می‌کنند، اما npm به‌جای جاسازی همهٔ باینری‌های پلتفرم در تاربال Plugin، وابستگی‌های زمان اجرا را هنگام نصب resolve می‌کند. بستهٔ ریشهٔ openclaw درخت کامل وابستگی خود را همراه نمی‌کند.

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

نصب‌های git مخزن را همسانه‌سازی یا تازه‌سازی می‌کنند و سپس دستور زیر را اجرا می‌کنند:

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

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

Pluginهای محلی

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

Pluginهای محلی TypeScript متعلق به شخص ثالث، به‌عنوان یک مسیر اضطراری از طریق Jiti بارگذاری می‌شوند. Pluginهای JavaScript بسته‌بندی‌شده و Pluginهای داخلی همراه، در عوض از طریق 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 مراجعه کنید.

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

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

پاک‌سازی موارد قدیمی

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

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