عیبیابی
این صفحه به مشکلاتِ کارایی، پایداری و جستوجو میپردازد؛ یعنی وقتی Claude Code از قبل در حال اجراست. برای مشکلاتِ دیگر، از صفحهای شروع کن که با جایی که گیر کردهای جور است:
| نشانه | برو به |
|---|---|
command not found، شکستِ نصب، مشکلاتِ PATH، EACCES، خطاهای TLS | عیبیابیِ نصب و ورود |
حلقههای ورود، خطاهای OAuth، 403 Forbidden، «organization disabled»، اعتبارنامههای Bedrock/Vertex/Foundry | عیبیابیِ نصب و ورود |
| اعمالنشدنِ تنظیمات، شلیکنشدنِ Hooks، بارگذارینشدنِ سرورهای MCP | اشکالزداییِ پیکربندی |
API Error: 5xx، 529 Overloaded، 429، خطاهای اعتبارسنجیِ درخواست | مرجعِ خطاها |
model not found یا you may not have access to it | مرجعِ خطاها |
| اتصالنگرفتن یا شناسایینشدنِ Claude در افزونهی VS Code | یکپارچگیِ VS Code |
| شناسایینشدنِ پلاگینِ JetBrains یا IDE | یکپارچگیِ JetBrains |
| CPU یا حافظهی بالا، پاسخهای کند، هنگکردن، پیدانشدنِ فایلها در جستوجو | کارایی و پایداری در پایین |
اگر مطمئن نیستی کدام مورد است، داخلِ Claude Code دستور /doctor را اجرا کن تا نصب، تنظیمات، سرورهای MCP و میزانِ مصرفِ کانتکستت بهصورتِ خودکار بررسی شود. اگر claude اصلاً بالا نمیآید، بهجایش claude doctor را از شِلِ خودت اجرا کن.
کارایی و پایداری
Section titled “کارایی و پایداری”این بخشها مشکلاتِ مربوط به مصرفِ منابع، پاسخگویی و رفتارِ جستوجو را پوشش میدهند.
مصرفِ بالای CPU یا حافظه
Section titled “مصرفِ بالای CPU یا حافظه”Claude Code طوری طراحی شده که با بیشترِ محیطهای توسعه کار کند، اما هنگامِ پردازشِ کدبیسهای بزرگ ممکن است منابعِ زیادی مصرف کند. اگر با مشکلاتِ کارایی روبهرو هستی:
- مرتب از
/compactاستفاده کن تا اندازهی کانتکست کم شود - بینِ کارهای بزرگ، Claude Code را ببند و دوباره باز کن
- اضافهکردنِ دایرکتوریهای بزرگِ build به فایلِ
.gitignoreرا در نظر بگیر - با
claude --safe-modeدوباره بالا بیا تا ببینی آیا یک پلاگین، سرورِ MCP یا Hook منشأِ مشکل است. این کار همهی شخصیسازیها را برای آن نشست غیرفعال میکند؛ اگر مصرف افت کرد، برای پیداکردنِ مقصر به اشکالزداییِ پیکربندی سر بزن
اگر بعد از این مراحل مصرفِ حافظه همچنان بالا ماند، دستور /heapdump را اجرا کن تا یک snapshot از heapِ JavaScript و یک تفکیکِ حافظه در ~/Desktop نوشته شود. روی لینوکس و بدونِ پوشهی Desktop، فایلها در دایرکتوریِ خانگیات نوشته میشوند.
این تفکیک، resident set size، heapِ JS، آرایهبافرها و حافظهی نِیتیوِ بهحسابنیامده را نشان میدهد که کمک میکند تشخیص دهی رشدِ مصرف در آبجکتهای JavaScript است یا در کدِ نِیتیو. برای بررسیِ retainerها، فایلِ .heapsnapshot را در Chrome DevTools از مسیرِ Memory → Load باز کن. هنگامِ گزارشِ یک مشکلِ حافظهای در GitHub، هر دو فایل را پیوست کن.
توقفِ فشردهسازیِ خودکار با خطای thrashing
Section titled “توقفِ فشردهسازیِ خودکار با خطای thrashing”اگر پیامِ Autocompact is thrashing: the context refilled to the limit... را دیدی، یعنی فشردهسازیِ خودکار موفق بوده اما یک فایل یا خروجیِ ابزار بلافاصله چند بارِ پیاپی پنجرهی کانتکست را دوباره پر کرده است. Claude Code برای جلوگیری از هدررفتنِ فراخوانیهای API روی حلقهای که پیشرفتی ندارد، تلاشِ مجدد را متوقف میکند.
برای بازیابی:
- از Claude بخواه فایلِ بیشازحد بزرگ را بهجای کلِ فایل، در تکههای کوچکتر بخواند، مثلاً یک بازهی خاص از خطوط یا یک تابع
- دستور
/compactرا با تمرکزی اجرا کن که خروجیِ بزرگ را کنار بگذارد، برای مثال/compact keep only the plan and the diff - کارِ فایلِ بزرگ را به یک سابایجنت منتقل کن تا در پنجرهی کانتکستِ جداگانهای اجرا شود
- اگر دیگر به گفتوگوی قبلی نیازی نیست،
/clearرا اجرا کن
هنگکردن یا فریزشدنِ دستور
Section titled “هنگکردن یا فریزشدنِ دستور”اگر Claude Code بیپاسخ بهنظر میرسد:
- برای تلاش جهتِ لغوِ عملیاتِ جاری، Ctrl+C را بزن
- اگر باز هم بیپاسخ بود، ممکن است لازم باشد ترمینال را ببندی و دوباره شروع کنی
شروعِ مجدد، گفتوگوی تو را از بین نمیبرد. در همان دایرکتوری claude --resume را اجرا کن تا نشست را از جایی که بودی ادامه بدهی.
متنِ بههمریخته یا خراب در ترمینالِ یکپارچهی ویرایشگر
Section titled “متنِ بههمریخته یا خراب در ترمینالِ یکپارچهی ویرایشگر”اگر هنگامِ اجرای Claude Code در ترمینالِ یکپارچهی VS Code، Cursor یا Devin Desktop، کاراکترها بهصورتِ مربع، لکه یا گلیفِ اشتباه نمایش داده میشوند، احتمالاً رِندرکنندهی GPUِ ترمینال علتِ کار است. داخلِ Claude Code دستور /terminal-setup را اجرا کن تا terminal.integrated.gpuAcceleration روی "off" تنظیم شود، یا آن را بهصورتِ دستی در تنظیماتِ ویرایشگرت تنظیم کن و پنجره را دوباره بارگذاری کن. برای دیدنِ بقیهی تنظیماتی که /terminal-setup مینویسد، به پیکربندیِ ترمینال نگاه کن.
مشکلاتِ جستوجو و کشف
Section titled “مشکلاتِ جستوجو و کشف”اگر ابزارِ Search، اشارههای @file، ایجنتهای سفارشی یا Skillهای سفارشی فایلها را پیدا نمیکنند، ممکن است باینریِ همراهِ ripgrep روی سیستمِ تو اجرا نشود. بستهی ripgrep مخصوصِ پلتفرمت را نصب کن و به Claude Code بگو بهجای آن از این یکی استفاده کند:
brew install ripgrepsudo apt install ripgrepapk add ripgreppacman -S ripgrepwinget install BurntSushi.ripgrep.MSVCسپس در محیطِ خودت USE_BUILTIN_RIPGREP=0 را تنظیم کن.
نتایجِ جستوجوی کند یا ناقص روی WSL
Section titled “نتایجِ جستوجوی کند یا ناقص روی WSL”جریمههای کاراییِ خواندن از دیسک هنگامِ کار میانِ فایلسیستمها روی WSL ممکن است باعث شود هنگامِ استفاده از Claude Code روی WSL، تعدادِ تطبیقها کمتر از حدِ انتظار باشد. جستوجو همچنان کار میکند، اما نتایجِ کمتری نسبت به یک فایلسیستمِ نِیتیو برمیگرداند.
راهحلها:
-
جستوجوهای مشخصتری بفرست: با تعیینِ دایرکتوریها یا نوعِ فایلها، تعدادِ فایلهای جستوجوشده را کم کن: «منطقِ اعتبارسنجیِ JWT را در پکیجِ auth-service جستوجو کن» یا «استفاده از هشِ md5 را در فایلهای JS پیدا کن».
-
پروژه را به فایلسیستمِ لینوکس منتقل کن: اگر ممکن است، مطمئن شو پروژهات روی فایلسیستمِ لینوکس (
/home/) قرار دارد، نه فایلسیستمِ ویندوز (/mnt/c/). -
بهجایش از ویندوزِ نِیتیو استفاده کن: برای کاراییِ بهترِ فایلسیستم، اجرای Claude Code را بهصورتِ نِیتیو روی ویندوز در نظر بگیر، نه از طریقِ WSL.
کمکِ بیشتر
Section titled “کمکِ بیشتر”اگر با مشکلاتی روبهرو هستی که اینجا پوشش داده نشدهاند:
- دستور
/doctorرا اجرا کن تا سلامتِ نصب، اعتبارِ تنظیمات، پیکربندیِ MCP و میزانِ مصرفِ کانتکست در یک مرحله بررسی شود - از دستور
/feedbackداخلِ Claude Code استفاده کن تا مشکلات را مستقیماً به Anthropic گزارش بدهی - مخزنِ GitHub را برای مشکلاتِ شناختهشده بررسی کن
- دربارهی قابلیتها و امکاناتِ Claude مستقیماً از خودش بپرس. Claude بهصورتِ درونساخت به مستنداتِ خود دسترسی دارد.