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

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

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

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

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

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

برای تغییرات وابستگی، همچنین تأیید کنید که نصب production می‌تواند بسته‌های زمان اجرا را بدون وابستگی‌های توسعه 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 بدون اجرای اسکریپت انجام می‌دهد، سپس tarball مربوط به Plugin را همراه با فایل‌های آن وابستگی‌ها بسته‌بندی یا منتشر می‌کند. بسته‌های سنگین از نظر مؤلفه‌های بومی (Codex، ACPX، Copilot، llama.cpp، memory-lancedb، Tlon) با openclaw.release.bundleRuntimeDependencies: false از این روند خارج می‌شوند؛ آن‌ها همچنان یک shrinkwrap ارائه می‌کنند، اما npm به‌جای جاسازی همه فایل‌های اجرایی هر پلتفرم در tarball مربوط به 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های شخص ثالث نصب شوند.

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

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

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

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