آموزش رفع مشکل اجرا نشدن OpenClaw در ویندوز
چگونه مشکل اجرا نشدن OpenClaw را در ویندوز برطرف کنیم؟
اگر برنامه یا گیت‌وی (Gateway) مربوط به OpenClaw در ویندوز اجرا نمی‌شود، کرش می‌کند یا با خطای دستور مواجه می‌شوید، برای عیب‌یابی و رفع مشکل مراحل زیر را به ترتیب انجام دهید:
۱. بررسی نصب و سازگاری نسخه Node.js
از آنجا که OpenClaw بر پایه محیط Node.js فعالیت می‌کند، نسخه نامناسب یا نصب‌نشده‌ی آن مانع اجرای برنامه‌ها می‌شود:
- پاورشل (PowerShell) یا Command Prompt را باز کنید.
- دستور زیر را برای بررسی نسخه وارد کنید:
node --version - مطمئن شوید که از نسخه سازگار و مدرن (Node.js LTS نسخه ۱۸ یا بالاتر) استفاده می‌کنید. در صورت نیاز، آخرین نسخه را از وب‌سایت رسمی Node.js دانلود و نصب کنید.
۲. تنظیم متغیرهای محیطی (PATH)
اگر سیستم خطای «command not found» یا مشابه آن را می‌دهد، مسیر اجرایی OpenClaw در متغیرهای ویندوز ثبت نشده است:
- پوشه محل نصب OpenClaw (معمولاً در درایو C بخش Program Files یا پوشه اپلیکیشن‌های کاربر) را پیدا کنید.
- مسیر دقیق پوشه را کپی کنید (Copy as path).
- کلیدهای Win + X را زده و گزینه‌ی System را انتخاب کنید. به بخش تنظیمات پیشرفته سیستم (Advanced system settings) و سپس Environment Variables بروید و مسیر اجرایی را به متغیر
PATHاضافه کنید. - پاورشل را کاملاً بسته و دوباره باز کنید تا تغییرات اعمال شوند.
۳. بررسی تداخل پورت‌ها (Port Conflicts)
گیت‌وی OpenClaw به طور پیش‌فرض روی پورت‌های خاصی (مانند 18789) متصل می‌شود؛ اگر برنامه دیگری در حال استفاده از این پورت باشد، سرویس اجرا نخواهد شد:
- پاورشل را با دسترسی Run as administrator باز کنید.
- برای بررسی وضعیت پورت دستور زیر را وارد کنید:
netstat -ano | findstr 18789 - اگر پورت توسط برنامه دیگری اشغال شده است، می‌توانید سرویس متخلف را ببندید یا پورت پیش‌فرض OpenClaw را از طریق فایل کانفیگ تغییر دهید.
۴. پاکسازی کش پکیج‌ها و نصب مجدد وابستگی‌ها
فایل‌های موقت آسیب‌دیده یا تداخل در پکیج‌های npm می‌تواند جلوی اجرای پردازش‌ها را بگیرد:
- دستور پاکسازی کش زیر را اجرا کنید:
npm cache clean --force - سپس به پوشه پروژه خود رفته و برای دریافت مجدد و سالم فایل‌های وابسته دستور زیر را بزنید:
npm install
۵. استفاده از محیط WSL یا Docker (روش جایگزین و پایدار)
اگر اجرای مستقیم OpenClaw روی ویندوز با خطاهای ساختاری مواجه می‌شود، استفاده از لینوکسِ زیرسیستم ویندوز یا کانتینرها پایدارترین روش است:
- با اجرای دستور
wsl --installدر پاورشل، زیرسیستم لینوکس را فعال کنید. - همچنین استفاده از Docker Desktop با فعال‌سازی بک‌اند WSL 2 یکی از ساده‌ترین راهکارها برای اجرای بدون دردسر OpenClaw بدون درگیر شدن با خطاهای ویندوزی است.
نکته کاربردی: اگر آنتی‌ویروس یا Windows Defender به اشتباه فایل‌های اجرایی OpenClaw یا اسکریپت‌های گیت‌وی را مسدود می‌کند، پوشه نصب برنامه را در بخش exclusions (استثنائات) آنتی‌ویروس خود قرار دهید تا از حذف یا قرنطینه شدن فایل‌های سیستمی جلوگیری شود.
