عیب‌یابی کدهای خطای Claude Code

ابتدا مشخص کنید خطا در کدام لایه است

INSTALL

نصب / اجرا

command not found، نسخه Node، مجوزهای npm، مسیر WSL و مشکلات نصب‌کننده بومی.

AUTH

ورود / احراز هویت

مشکلات callback در OAuth، کلید API، سازمان در Console، SSO و وضعیت احراز هویت محلی.

NETWORK

شبکه / پروکسی

پروکسی سازمانی، فایروال، گواهی‌ها، پایان مهلت، 403/429 و دامنه‌های ضروری غیرقابل دسترس.

خطاهای رایج و راه‌حل‌ها

claude: command not found

علت رایج: پوشه نصب در PATH نیست، یا shell فعلی هنوز پیکربندی خود را دوباره بارگذاری نکرده است.

راه‌حل: یک ترمینال جدید باز کنید، یا پوشه نصب Claude Code را به PATH اضافه کنید و پیکربندی shell را دوباره بارگذاری کنید.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Node version not supported / silent crash

علت رایج: نسخه Node پایین‌تر از الزامات رسمی است، یا WSL نسخه Node سمت Windows را فراخوانی می‌کند.

راه‌حل: Node را ارتقا دهید یا از نصب‌کننده بومی رسمی استفاده کنید. در WSL با which node / which npm مسیر را بررسی کنید تا مطمئن شوید از محیط Linux است.

node -v
which node
which npm

EACCES / permission denied

علت رایج: پوشه سراسری npm متعلق به root است، یا نصب قبلی با sudo مجوزها را به هم ریخته است.

راه‌حل: Claude Code را با sudo نصب نکنید. پیشوند npm (prefix) را به یک پوشه کاربری تغییر دهید، یا از نصب‌کننده بومی استفاده کنید.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Waiting for authentication...

علت رایج: callback مربوط به OAuth در مرورگر به CLI محلی نمی‌رسد - این مشکل در SSH راه دور، devcontainerها، فایروال‌های سخت‌گیر یا مسدود بودن callbackهای localhost رایج است.

راه‌حل: مطمئن شوید مرورگر و CLI روی یک دستگاه به هم دسترسی دارند. در صورت نیاز از حساب خارج شوید، Claude Code را دوباره راه‌اندازی کنید و احراز هویت را از نو انجام دهید.

/logout
# 关闭 Claude Code 后重新运行
claude

SELF_SIGNED_CERT_IN_CHAIN / certificate error

علت رایج: یک پروکسی سازمانی یا دروازه امنیتی یک CA خودامضا تزریق می‌کند که Node به‌طور پیش‌فرض به آن اعتماد ندارد.

راه‌حل: CA bundle سازمانی را از واحد IT بگیرید و آن را با NODE_EXTRA_CA_CERTS مشخص کنید.

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

proxy connection failed / timeout

علت رایج: متغیرهای پروکسی اشتباه تنظیم شده‌اند، پروتکل پروکسی پشتیبانی نمی‌شود، NO_PROXY دامنه مقصد را مستثنا کرده است، یا فایروال سازمانی دسترسی را مسدود می‌کند.

راه‌حل: Claude Code از متغیرهای محیطی استاندارد پروکسی HTTP/HTTPS استفاده می‌کند؛ طبق مستندات، پروکسی‌های SOCKS پشتیبانی نمی‌شوند. ابتدا با HTTPS_PROXY دوباره تست کنید.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

403 Forbidden

علت رایج: سازمان Claude Code را فعال نکرده است، لیست سفید سازمانی شامل خروجی فعلی نیست، محدودیت‌های حساب کاربری/منطقه/سیاست اعمال می‌شود، یا پروکسی رد می‌شود.

راه‌حل: برای حساب‌های کاربری شخصی، ابتدا مناطق پشتیبانی‌شده و وضعیت حساب را بررسی کنید؛ برای حساب‌های سازمانی، از مدیر بخواهید مجوزهای Claude Code، SSO، لیست سفید IP و قواعد فایروال را بررسی کند.

429 / rate limit

علت رایج: درخواست‌ها بیش از حد پرتکرار است، همزمانی خیلی بالاست، یا پلن حساب کاربری یا سازمان به محدودیت نرخ رسیده است.

راه‌حل: همزمانی لایه بیرونی را کم کنید، حلقه‌های تلاش مجدد را متوقف کنید و منتظر بمانید تا محدودیت بازنشانی شود. Claude Code را برای افزایش اجباری سرعت در چند worker نپیچانید.

API key not recognized / SSO mismatch

علت رایج: کلید API از shell دیگری آمده است، کلید Console با نشست OAuth تداخل دارد، یا سازمان ورود با SSO را الزامی کرده است.

راه‌حل: بررسی کنید آیا ANTHROPIC_API_KEY در shell فعلی تنظیم شده است. حساب‌های کاربری سازمانی باید روند ورود Console/SSO تعیین‌شده توسط مدیر را دنبال کنند.

echo $ANTHROPIC_API_KEY

مبانی پروکسی و شبکه سازمانی

مستندات رسمی می‌گوید Claude Code از متغیرهای محیطی استاندارد HTTPS_PROXY / HTTP_PROXY / NO_PROXY پشتیبانی می‌کند، اما از پروکسی‌های SOCKS پشتیبانی نمی‌کند. برای گواهی‌های خودامضای سازمانی، CA bundle را با NODE_EXTRA_CA_CERTS مشخص کنید.

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1"
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

روند حداقلی بازتولید خطا

مطمئن شوید `node -v` با الزامات رسمی مطابقت دارد، یا از نصب‌کننده بومی Claude Code استفاده کنید.
همه اسکریپت‌های پوششی و workerها را ببندید و `claude` را فقط در یک پنجره ترمینال اجرا کنید.
با `echo $HTTPS_PROXY` و `echo $NO_PROXY` مطمئن شوید متغیرهای پروکسی درست تنظیم شده‌اند.
بررسی کنید که دسترسی به api.anthropic.com، claude.ai، statsig.anthropic.com و sentry.io از طریق فایروال مجاز باشد.
اگر ورود گیر کرده است، `/logout` را اجرا کنید و Claude Code را دوباره راه‌اندازی کنید؛ در صورت نیاز پیش از ورود دوباره، فایل‌های احراز هویت محلی را پاک کنید.

منابع رسمی

پیکربندی شبکه سازمانی Claude Code

پروکسی، CA، mTLS و URLهای دسترسی ضروری.

عیب‌یابی نصب و احراز هویت Claude Code

فهرست رسمی مشکلات رایج نصب، Node، مجوزها، پروکسی و ورود.

داده‌ها و تله‌متری Claude Code

Statsig، Sentry، /bug و متغیرهای محیطی برای غیرفعال کردن ترافیک غیرضروری.

پرسش‌های متداول Claude Code

پروکسی‌های سازمانی، سازمان‌ها در Console و مشکلات رایج مجوز.