عیب‌یابیِ نصب و ورود

اگر نصب شکست خورد یا نمی‌توانی وارد شوی، خطایت را در ادامه پیدا کن. برای مشکلاتِ زمانِ اجرا پس از این‌که Claude Code کار می‌کند، به عیب‌یابی مراجعه کن. برای مشکلاتِ پیکربندی مثل اعمال‌نشدنِ تنظیمات یا اجرانشدنِ hooks، به عیب‌یابیِ پیکربندی مراجعه کن.

خطایت را پیدا کن

پیام یا نشانه‌ای که می‌بینی را به یک راه‌حل تطبیق بده:

چیزی که می‌بینی	راه‌حل
`command not found: claude` یا `'claude' is not recognized`	PATH خود را درست کن
`syntax error near unexpected token '<'`	اسکریپتِ نصب HTML برمی‌گرداند
`curl: (22) The requested URL returned error: 403`	اسکریپتِ نصب خطای 403 برگرداند
`curl: (23)` یا `curl: (56) Failure writing output to destination`	اتصال را بررسی کن یا از نصب‌کننده‌ی جایگزین استفاده کن
`Killed` هنگام نصب روی لینوکس	برای سرورهای کم‌حافظه فضای swap اضافه کن
`TLS connect error` یا `SSL/TLS secure channel`	گواهی‌های CA را به‌روزرسانی کن
`Failed to fetch version` یا عدم دسترسی به سرورِ دانلود	تنظیماتِ شبکه و پراکسی را بررسی کن
`irm is not recognized` یا `&& is not valid`	دستورِ درستِ متناسب با شِلِ خود را به‌کار ببر
`'bash' is not recognized as the name of a cmdlet`	دستورِ نصبِ ویندوز را به‌کار ببر
`Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`	یک شِل نصب کن
`Claude Code does not support 32-bit Windows`	به‌جای ورودیِ x86، Windows PowerShell را باز کن
`The process cannot access the file ... because it is being used by another process`	پوشه‌ی downloads را پاک کن و دوباره تلاش کن
`Error loading shared library`	نسخه‌ی نادرستِ باینری برای سیستمِ تو
`Illegal instruction`	ناسازگاریِ معماری یا مجموعه‌دستوراتِ CPU
`cannot execute binary file: Exec format error` در WSL	نقصِ باینریِ نِیتیو در WSL1
نصب‌کننده‌ی PowerShell تمام می‌شود ولی `claude` پیدا نمی‌شود یا نسخه‌ای قدیمی نشان می‌دهد	ترمینالت را ری‌استارت کن و PATH را تأیید کن
`dyld: cannot load`، `dyld: Symbol not found`، یا `Abort trap` روی macOS	ناسازگاریِ باینری
`Invoke-Expression: Missing argument in parameter list`	اسکریپتِ نصب HTML برمی‌گرداند
`App unavailable in region`	Claude Code در کشورِ تو در دسترس نیست. به کشورهای پشتیبانی‌شده مراجعه کن.
`unable to get local issuer certificate`	گواهی‌های CA سازمانی را پیکربندی کن
`OAuth error` یا `403 Forbidden`	احراز هویت را درست کن
`Could not load the default credentials` یا `Could not load credentials from any providers`	اعتبارنامه‌های Bedrock، Vertex یا Foundry
`ChainedTokenCredential authentication failed` یا `CredentialUnavailableError`	اعتبارنامه‌های Bedrock، Vertex یا Foundry
`API Error: 500`، `529 Overloaded`، `429`، یا دیگر خطاهای 4xx و 5xx که بالا فهرست نشده‌اند	به مرجعِ خطاها مراجعه کن

اگر مشکلت در فهرست نیست، بررسی‌های تشخیصیِ زیر را دنبال کن تا علت را محدود کنی.

بررسی‌های تشخیصی را اجرا کن

اتصالِ شبکه را بررسی کن

نصب‌کننده از downloads.claude.ai دانلود می‌کند. تأیید کن که می‌توانی به آن دسترسی داشته باشی:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

در PowerShell به‌جایش curl.exe -sI را اجرا کن. PowerShell نامِ curl را به Invoke-WebRequest نگاشت می‌کند که پرچم‌های -sI را نمی‌پذیرد.

یک خطِ HTTP/2 200 یعنی به سرور رسیده‌ای. اگر هیچ خروجی‌ای نمی‌بینی، یا Could not resolve host، یا یک timeoutِ اتصال می‌بینی، شبکه‌ات اتصال را مسدود کرده است. علت‌های رایج:

فایروال‌ها یا پراکسی‌های سازمانی که downloads.claude.ai را مسدود می‌کنند
محدودیت‌های شبکه‌ی منطقه‌ای: یک VPN یا شبکه‌ی جایگزین را امتحان کن
مشکلاتِ TLS/SSL: گواهی‌های CA سیستمت را به‌روزرسانی کن، یا بررسی کن آیا HTTPS_PROXY پیکربندی شده است

اگر پشتِ یک پراکسیِ سازمانی هستی، پیش از نصب HTTPS_PROXY و HTTP_PROXY را روی آدرسِ پراکسیت تنظیم کن. اگر آدرسِ پراکسی را نمی‌دانی، از تیمِ ITت بپرس، یا تنظیماتِ پراکسیِ مرورگرت را بررسی کن.

این مثال هر دو متغیرِ پراکسی را تنظیم می‌کند و سپس نصب‌کننده را از طریقِ پراکسیت اجرا می‌کند:

macOS/Linux
Windows PowerShell

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

PATH خود را تأیید کن

اگر نصب موفق بود ولی هنگامِ اجرای claude خطای command not found یا not recognized می‌گیری، دایرکتوریِ نصب در PATH تو نیست. شِلت برنامه‌ها را در دایرکتوری‌هایی که در PATH فهرست شده‌اند جست‌وجو می‌کند، و نصب‌کننده claude را روی macOS/Linux در ~/.local/bin/claude و روی ویندوز در %USERPROFILE%\.local\bin\claude.exe قرار می‌دهد.

با فهرست‌کردنِ ورودی‌های PATH و فیلترکردن برای local/bin بررسی کن آیا دایرکتوریِ نصب در PATH تو هست:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

اگر این /Users/you/.local/bin یا /home/you/.local/bin را چاپ کند، دایرکتوری در PATH تو هست و می‌توانی به بررسیِ نصب‌های متعارض بپری. اگر خروجی‌ای نیست، آن را به پیکربندیِ شِلت اضافه کن.

برای Zsh، پیش‌فرضِ macOS:

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

برای Bash، پیش‌فرضِ بیشترِ توزیع‌های لینوکس:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

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

برای شِل‌های دیگر مثل fish یا Nushell، ~/.local/bin را با استفاده از نحوِ پیکربندیِ خودِ آن شِل به PATH اضافه کن، سپس ترمینالت را ری‌استارت کن.

تأیید کن که راه‌حل کار کرد:

claude --version

$env:PATH -split ';' | Select-String '\.local\\bin'

اگر خروجی‌ای نیست، دایرکتوریِ نصب را به User PATH خود اضافه کن:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

برای اعمالِ تغییر، ترمینالت را ری‌استارت کن.

تأیید کن که راه‌حل کار کرد:

claude --version

echo %PATH% | findstr /i "local\bin"

اگر خروجی‌ای نیست، System Settings را باز کن، به Environment Variables برو، و %USERPROFILE%\.local\bin را به متغیرِ User PATH خود اضافه کن. ترمینالت را ری‌استارت کن.

تأیید کن که راه‌حل کار کرد:

claude --version

بررسیِ نصب‌های متعارض

چند نصبِ همزمانِ Claude Code می‌تواند باعثِ ناسازگاریِ نسخه یا رفتارِ غیرمنتظره شود. بررسی کن چه چیزی نصب شده است:

macOS/Linux
Windows PowerShell

همه‌ی باینری‌های claude که در PATH تو پیدا می‌شوند را فهرست کن:

which -a claude

اگر این چیزی چاپ نکرد، هنوز هیچ claudeای در PATH تو نیست. به PATH خود را تأیید کن برگرد.

سه مکانی که یک باینریِ claude می‌تواند از آن‌ها بیاید را بررسی کن. ~/.local/bin/claude نصب‌کننده‌ی نِیتیو است، ~/.claude/local/ یک نصبِ محلیِ قدیمیِ npm است که نسخه‌های قدیمی‌ترِ Claude Code ساخته‌اند، و فهرستِ سراسریِ npm یک نصبِ -g را نشان می‌دهد:

ls -la ~/.local/bin/claude

اگر هر کدام از دستورهای ls پیامِ No such file or directory چاپ کرد، این خطا نیست. یعنی چیزی در آن مکان نصب نشده، پس به بررسیِ بعدی برو.

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

همه‌ی باینری‌های claude که در PATH تو پیدا می‌شوند را فهرست کن:

where.exe claude

بررسی کن آیا نصب‌کننده‌ی نِیتیو یک باینری قرار داده است:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

اگر چند نصب پیدا کردی، فقط یکی را نگه دار. نصبِ نِیتیو در ~/.local/bin/claude روی macOS/Linux یا %USERPROFILE%\.local\bin\claude.exe روی ویندوز توصیه می‌شود. بقیه را حذف کن:

یک نصبِ سراسریِ npm را حذف کن:

npm uninstall -g @anthropic-ai/claude-code

نصبِ محلیِ قدیمیِ npm را حذف کن:

rm -rf ~/.claude/local

روی ویندوز، از PowerShell استفاده کن:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

یک نصبِ Homebrew روی macOS را حذف کن. اگر کَسکِ claude-code@latest را نصب کرده‌ای، آن نام را جایگزین کن:

brew uninstall --cask claude-code

یک نصبِ WinGet روی ویندوز را حذف کن:

winget uninstall Anthropic.ClaudeCode

دسترسی‌های دایرکتوری را بررسی کن

نصب‌کننده روی macOS و Linux به دسترسیِ نوشتن در ~/.local/bin/ و ~/.claude/ نیاز دارد. روی ویندوز مکانِ نصب زیرِ %USERPROFILE% است که به‌صورتِ پیش‌فرض توسطِ کاربرِ تو قابلِ نوشتن است، پس این بخش به‌ندرت آنجا کاربرد دارد.

بررسی کن آیا دایرکتوری‌ها قابلِ نوشتن هستند:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

اگر هر کدام از دایرکتوری‌ها قابلِ نوشتن نیست، دایرکتوریِ نصب را بساز و کاربرِ خودت را به‌عنوانِ مالک تنظیم کن:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

کارکردِ باینری را تأیید کن

اگر claude --version نسخه‌ای چاپ می‌کند ولی claude هنگامِ راه‌اندازی کرش یا هَنگ می‌کند، این بررسی‌ها را اجرا کن تا علت را محدود کنی. اگر claude --version می‌گوید command not found، اول به PATH خود را تأیید کن برو؛ دستورهای زیر فرض می‌کنند claude در PATH تو هست.

تأیید کن که باینری وجود دارد و قابلِ اجراست:

ls -la "$(command -v claude)"

روی ویندوز، از PowerShell استفاده کن:

Get-Command claude | Select-Object Source

روی لینوکس، کتابخانه‌های اشتراکیِ گم‌شده را بررسی کن. اگر ldd کتابخانه‌های گم‌شده را نشان داد، شاید لازم باشد بسته‌های سیستمی نصب کنی. روی Alpine Linux و دیگر توزیع‌های مبتنی بر musl، به راه‌اندازیِ Alpine Linux مراجعه کن.

ldd "$(command -v claude)" | grep "not found"

تأیید کن که باینری می‌تواند اجرا شود:

claude --version

مشکلاتِ رایجِ نصب

این‌ها پرتکرارترین مشکلاتِ نصب و راه‌حل‌هایشان هستند.

اسکریپتِ نصب به‌جای یک اسکریپتِ شِل، HTML برمی‌گرداند

هنگامِ اجرای دستورِ نصب، ممکن است یکی از این خطاها را ببینی:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

در PowerShell، همان مشکل این‌گونه ظاهر می‌شود:

Invoke-Expression: Missing argument in parameter list.

بسته به این‌که درخواست چگونه مسیریابی شده، ممکن است به‌جایش یک 403 بدونِ بدنه‌ی HTML ببینی:

curl: (22) The requested URL returned error: 403

همه‌ی این‌ها یعنی URLِ نصب به‌جای اسکریپتِ نصب، یک صفحه‌ی HTML یا یک وضعیتِ خطا برگردانده است. اگر صفحه‌ی HTML بگوید “App unavailable in region”، Claude Code در کشورِ تو در دسترس نیست. به کشورهای پشتیبانی‌شده مراجعه کن.

یک 403ِ خالی بدونِ بدنه اغلب همین علت را دارد، ولی می‌تواند از یک پراکسی یا فایروالِ سازمانی که دانلود را مسدود می‌کند هم بیاید. اگر در کشوری پشتیبانی‌شده هستی و باز هم 403 می‌بینی، پیش از امتحانِ نصب‌کننده‌های جایگزینِ زیر، اتصالِ شبکه را بررسی کن، چون آن‌ها به همان میزبان‌ها می‌رسند.

در غیرِ این صورت، این می‌تواند به‌علتِ مشکلاتِ شبکه، مسیریابیِ منطقه‌ای، یا یک اختلالِ موقتِ سرویس رخ دهد.

راه‌حل‌ها:

از یک روشِ نصبِ جایگزین استفاده کن:

روی macOS، از طریقِ Homebrew نصب کن:
Terminal window
```
brew install --cask claude-code
```
روی ویندوز، از طریقِ WinGet نصب کن:
Terminal window
```
winget install Anthropic.ClaudeCode
```
بعد از چند دقیقه دوباره تلاش کن: مشکل اغلب موقتی است. صبر کن و دستورِ اصلی را دوباره امتحان کن.

`command not found: claude` پس از نصب

نصب تمام شد ولی claude کار نمی‌کند. خطای دقیق بسته به پلتفرم متفاوت است:

پلتفرم	پیامِ خطا
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

این یعنی دایرکتوریِ نصب در مسیرِ جست‌وجوی شِلت نیست. برای راه‌حل روی هر پلتفرم به PATH خود را تأیید کن مراجعه کن.

`curl: (56) Failure writing output to destination`

دستورِ curl ... | bash اسکریپت را دانلود می‌کند و آن را برای اجرا به Bash می‌فرستد (pipe). این خطا و خطای مرتبطِ curl: (23) Failure writing output to destination یعنی Bash اسکریپتِ کامل را دریافت نکرده است. کدِ خروجِ 56 نشان می‌دهد خودِ دانلود قطع شده، و کدِ خروجِ 23 نشان می‌دهد curl نتوانسته آنچه دریافت کرده را در pipe بنویسد، که معمولاً به‌علتِ زودخارج‌شدنِ Bash است.

راه‌حل‌ها:

پایداریِ شبکه را بررسی کن: باینری‌های Claude Code روی downloads.claude.ai میزبانی می‌شوند. آزمایش کن که می‌توانی به آن برسی:
Terminal window
```
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```
یک خطِ HTTP/2 200 یعنی به سرور رسیده‌ای و خطای اولیه احتمالاً مقطعی بوده؛ دستورِ نصب را دوباره اجرا کن. اگر Could not resolve host یا یک timeoutِ اتصال می‌بینی، شبکه‌ات دانلود را مسدود می‌کند.
یک روشِ نصبِ جایگزین را امتحان کن:

روی macOS:
Terminal window
```
brew install --cask claude-code
```
روی ویندوز:
Terminal window
```
winget install Anthropic.ClaudeCode
```

خطاهای اتصالِ TLS یا SSL

خطاهایی مثل curl: (35) TLS connect error، schannel: next InitializeSecurityContext failed، یا Could not establish trust relationship for the SSL/TLS secure channel در PowerShell نشان‌دهنده‌ی شکستِ دست‌دهیِ (handshake) TLS هستند.

راه‌حل‌ها:

گواهی‌های CA سیستمت را به‌روزرسانی کن:

روی Ubuntu/Debian:
Terminal window
```
sudo apt-get update && sudo apt-get install ca-certificates
```
روی macOS، curlِ سیستمی از مخزنِ اعتمادِ Keychain استفاده می‌کند؛ به‌روزرسانیِ خودِ macOS، گواهی‌های ریشه را هم به‌روز می‌کند.

روی ویندوز، TLS 1.2 را فعال کن در PowerShell پیش از اجرای نصب‌کننده:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

تداخلِ پراکسی یا فایروال را بررسی کن: پراکسی‌های سازمانی که بازرسیِ TLS انجام می‌دهند می‌توانند باعثِ این خطاها شوند، از جمله unable to get local issuer certificate و SELF_SIGNED_CERT_IN_CHAIN. برای مرحله‌ی نصب، curl را با --cacert به بسته‌ی CA سازمانیت اشاره بده:
Terminal window
```
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
```
برای خودِ Claude Code پس از نصب، NODE_EXTRA_CA_CERTS را تنظیم کن تا درخواست‌های API به همان بسته اعتماد کنند:
Terminal window
```
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
اگر فایلِ گواهی را نداری، از تیمِ ITت بخواه. می‌توانی روی یک اتصالِ مستقیم هم امتحان کنی تا مطمئن شوی پراکسی علت است.
روی ویندوز، بررسی‌های ابطالِ گواهی را دور بزن اگر CRYPT_E_NO_REVOCATION_CHECK (0x80092012) یا CRYPT_E_REVOCATION_OFFLINE (0x80092013) می‌بینی. این‌ها یعنی curl به سرور رسیده ولی شبکه‌ات جست‌وجوی ابطالِ گواهی را مسدود می‌کند، که پشتِ فایروال‌های سازمانی رایج است. --ssl-revoke-best-effort را به دستورِ نصب اضافه کن:
Terminal window
```
curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
یا به‌جایش با winget install Anthropic.ClaudeCode نصب کن، که کلاً از curl استفاده نمی‌کند.

`Failed to fetch version from downloads.claude.ai`

نصب‌کننده نتوانست به سرورِ دانلود برسد. این معمولاً یعنی downloads.claude.ai روی شبکه‌ات مسدود است.

راه‌حل‌ها:

اتصال را مستقیماً آزمایش کن:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

اگر پشتِ یک پراکسی هستی، HTTPS_PROXY را تنظیم کن تا نصب‌کننده بتواند از طریقِ آن مسیریابی کند. برای جزئیات به پیکربندیِ پراکسی مراجعه کن.
Terminal window
```
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```
اگر روی یک شبکه‌ی محدود هستی، یک شبکه یا VPN متفاوت را امتحان کن، یا از یک روشِ نصبِ جایگزین استفاده کن:

روی macOS:
Terminal window
```
brew install --cask claude-code
```
روی ویندوز:
Terminal window
```
winget install Anthropic.ClaudeCode
```

دستورِ نصبِ نادرست روی ویندوز

اگر 'irm' is not recognized، The token '&&' is not valid، یا 'bash' is not recognized as the name of a cmdlet می‌بینی، دستورِ نصب را برای یک شِل یا سیستم‌عاملِ متفاوت کپی کرده‌ای.

irm شناخته نشد: در CMD هستی، نه PowerShell. دو گزینه داری:

PowerShell را با جست‌وجوی “PowerShell” در منوی Start باز کن، سپس دستورِ نصبِ اصلی را اجرا کن:
Terminal window
```
irm https://claude.ai/install.ps1 | iex
```
یا در CMD بمان و به‌جایش از نصب‌کننده‌ی CMD استفاده کن:
Terminal window
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& معتبر نیست: در PowerShell هستی ولی دستورِ نصب‌کننده‌ی CMD را اجرا کرده‌ای. از نصب‌کننده‌ی PowerShell استفاده کن:
Terminal window
```
irm https://claude.ai/install.ps1 | iex
```
bash شناخته نشد: نصب‌کننده‌ی macOS/Linux را روی ویندوز اجرا کرده‌ای. به‌جایش از نصب‌کننده‌ی PowerShell استفاده کن:
Terminal window
```
irm https://claude.ai/install.ps1 | iex
```

`The process cannot access the file` هنگامِ نصب روی ویندوز

اگر نصب‌کننده‌ی PowerShell با Failed to download binary: The process cannot access the file ... because it is being used by another process شکست خورد، نصب‌کننده نتوانسته در %USERPROFILE%\.claude\downloads بنویسد. این معمولاً یعنی یک تلاشِ نصبِ قبلی هنوز در حالِ اجراست، یا نرم‌افزارِ آنتی‌ویروس دارد یک باینریِ نیمه‌دانلودشده را در آن پوشه اسکن می‌کند.

هر پنجره‌ی دیگرِ PowerShell که نصب‌کننده را اجرا می‌کند ببند و صبر کن تا اسکن‌های آنتی‌ویروس فایل را آزاد کنند. سپس پوشه‌ی downloads را حذف کن و نصب‌کننده را دوباره اجرا کن:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

نصب روی سرورهای لینوکسِ کم‌حافظه kill می‌شود

اگر هنگامِ نصب روی یک VPS یا instanceِ ابری Killed می‌بینی:

Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

OOM killerِ لینوکس فرایند را خاتمه داده، چون سیستم حافظه‌اش تمام شده است. Claude Code به‌دستِ‌کم 4 گیگابایت RAM در دسترس نیاز دارد.

راه‌حل‌ها:

فضای swap اضافه کن اگر سرورت RAM محدودی دارد. swap از فضای دیسک به‌عنوانِ حافظه‌ی سرریز استفاده می‌کند و اجازه می‌دهد نصب حتی با RAM فیزیکیِ کم کامل شود.

یک فایلِ swapِ 2 گیگابایتی بساز و فعالش کن:
Terminal window
```
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
سپس نصب را دوباره تلاش کن:
Terminal window
```
curl -fsSL https://claude.ai/install.sh | bash
```
فرایندهای دیگر را ببند تا پیش از نصب حافظه آزاد شود.
از یک instanceِ بزرگ‌تر استفاده کن اگر ممکن است. Claude Code به‌دستِ‌کم 4 گیگابایت RAM نیاز دارد.

نصب در Docker هَنگ می‌کند

هنگامِ نصبِ Claude Code در یک کانتینرِ Docker، نصب به‌عنوانِ root داخلِ / می‌تواند باعثِ هَنگ شود.

راه‌حل‌ها:

یک دایرکتوریِ کاری تنظیم کن پیش از اجرای نصب‌کننده. وقتی از / اجرا شود، نصب‌کننده کلِ فایل‌سیستم را اسکن می‌کند، که باعثِ مصرفِ بیش‌ازحدِ حافظه می‌شود. تنظیمِ WORKDIR اسکن را به یک دایرکتوریِ کوچک محدود می‌کند:
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
محدودیت‌های حافظه‌ی Docker را افزایش بده اگر از Docker Desktop استفاده می‌کنی:
Terminal window
```
docker build --memory=4g .
```

Claude Desktop دستورِ `claude` را روی ویندوز بازنویسی می‌کند

اگر نسخه‌ای قدیمی‌تر از Claude Desktop نصب کرده باشی، ممکن است یک Claude.exe در دایرکتوریِ WindowsApps ثبت کند که در PATH بر Claude Code CLI اولویت دارد. اجرای claude به‌جای CLI اپلیکیشنِ Desktop را باز می‌کند.

برای رفعِ این مشکل، Claude Desktop را به آخرین نسخه به‌روزرسانی کن.

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Git for Windows اختیاری است. Claude Code وقتی Git Bash نباشد از ابزارِ PowerShell استفاده می‌کند، پس این خطا یعنی هیچ‌کدام از این دو شِل پیدا نشده است.

اگر PowerShell از PATH تو غایب است، مکانِ پیش‌فرضش C:\Windows\System32\WindowsPowerShell\v1.0\ است. آن دایرکتوری را به PATH خود اضافه کن، یا PowerShell 7 را نصب کن که pwsh را فراهم می‌کند.

برای نصبِ Git for Windows به‌جایش، آن را از git-scm.com/downloads/win دانلود کن. هنگامِ راه‌اندازی، گزینه‌ی “Add to PATH” را انتخاب کن. پس از نصب، ترمینالت را ری‌استارت کن. نصبِ آن، ابزارِ Bash را فعال می‌کند که هنگامِ کار با اسکریپت‌ها و ابزارهای مبتنی بر Bash مفید است.

اگر Git از قبل نصب است ولی Claude Code نمی‌تواند پیدایش کند، مسیر را در فایلِ settings.json تنظیم کن:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

اگر Git تو جای دیگری نصب شده، با اجرای where.exe git در PowerShell مسیر را پیدا کن و از مسیرِ bin\bash.exe در آن دایرکتوری استفاده کن.

اگر مسیر درست است و فایل وجود دارد ولی Claude Code هنوز آن را پیدا نشده گزارش می‌کند، نرم‌افزارِ امنیتیِ endpoint مثلِ AppLocker، سیاست‌های محدودیتِ نرم‌افزارِ Group Policy، یا عامل‌های EDR ممکن است مزاحمت ایجاد کنند. در نسخه‌های پیش از v2.1.116، Claude Code یک فرایندِ فرزند (cmd.exe) برای تأییدِ مسیر اجرا می‌کرد که این سیاست‌ها می‌توانند مسدودش کنند — یک نشانه‌ی رایج این است که cmd.exe /c dir "C:\Program Files\Git\bin\bash.exe" وقتی مستقیماً در PowerShell اجرایش کنی کار می‌کند ولی وقتی توسطِ claude.exe اجرا شود بی‌صدا شکست می‌خورد.

Claude Code نسخه‌ی v2.1.116 و بالاتر مستقیماً فایل‌سیستم را بررسی می‌کنند، پس اول به‌روزرسانی کن. اگر خطا روی نسخه‌ای جاری ادامه داشت، از تیمِ ITت بخواه claude.exe و فرایندهایی که اجرا می‌کند، از جمله cmd.exe و bash.exe، را در سیاستِ حفاظتِ endpoint خود به فهرستِ مجاز اضافه کند.

Claude Code does not support 32-bit Windows

ویندوز دو ورودیِ PowerShell در منوی Start دارد: Windows PowerShell و Windows PowerShell (x86). ورودیِ x86 به‌عنوانِ یک فرایندِ 32-بیتی اجرا می‌شود و این خطا را حتی روی یک ماشینِ 64-بیتی به‌راه می‌اندازد. برای بررسیِ این‌که در کدام حالت هستی، این را در همان پنجره‌ای که خطا را تولید کرد اجرا کن:

[Environment]::Is64BitOperatingSystem

اگر این True چاپ کند، سیستم‌عاملت مشکلی ندارد. پنجره را ببند، Windows PowerShell بدونِ پسوندِ x86 را باز کن، و دستورِ نصب را دوباره اجرا کن.

اگر این False چاپ کند، روی یک نسخه‌ی 32-بیتیِ ویندوز هستی. Claude Code به یک سیستم‌عاملِ 64-بیتی نیاز دارد. به نیازمندی‌های سیستم مراجعه کن.

ناسازگاریِ باینریِ musl یا glibc در لینوکس

اگر پس از نصب خطاهایی درباره‌ی کتابخانه‌های اشتراکیِ گم‌شده مثل libstdc++.so.6 یا libgcc_s.so.1 می‌بینی، نصب‌کننده شاید نسخه‌ی نادرستِ باینری را برای سیستمت دانلود کرده باشد.

Error loading shared library libstdc++.so.6: No such file or directory

این می‌تواند روی سیستم‌های مبتنی بر glibc که بسته‌های cross-compilationِ musl نصب دارند رخ دهد و باعث شود نصب‌کننده سیستم را اشتباهاً musl تشخیص دهد.

راه‌حل‌ها:

بررسی کن سیستمت از کدام libc استفاده می‌کند:
Terminal window
```
ldd --version 2>&1 | head -1
```
خروجی‌ای که GNU libc یا GLIBC را ذکر کند یعنی glibc. خروجی‌ای که musl را ذکر کند یعنی musl.
اگر روی glibc هستی ولی باینریِ musl را گرفته‌ای، نصب را حذف و دوباره نصب کن. می‌توانی باینریِ درست را با استفاده از manifest در https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json هم به‌صورتِ دستی دانلود کنی. یک issue در GitHub با خروجیِ ldd --version و ls /lib/libc.musl* ثبت کن.
اگر واقعاً روی musl هستی، مثلِ Alpine Linux، بسته‌های موردِنیاز را نصب کن:
Terminal window
```
apk add libgcc libstdc++ ripgrep
```

`Illegal instruction`

اگر اجرای claude یا نصب‌کننده Illegal instruction چاپ می‌کند، باینریِ نِیتیو از دستوراتِ CPUای استفاده می‌کند که پردازنده‌ات پشتیبانی نمی‌کند. دو علتِ مجزا وجود دارد.

ناسازگاریِ معماری. نصب‌کننده باینریِ نادرست را دانلود کرده، مثلاً x86 روی یک سرورِ ARM. با uname -m روی macOS یا Linux، یا $env:PROCESSOR_ARCHITECTURE در PowerShell بررسی کن. اگر نتیجه با باینری‌ای که دریافت کرده‌ای مطابقت ندارد، یک issue در GitHub ثبت کن و خروجی را بگنجان.

نبودِ مجموعه‌دستوراتِ AVX. اگر معماری‌ات درست است ولی باز هم Illegal instruction می‌بینی، CPUات احتمالاً فاقدِ AVX یا دستورِ دیگری است که باینری نیاز دارد. این تقریباً پردازنده‌های Intel و AMDِ پیش از 2013، و ماشین‌های مجازی‌ای که در آن‌ها hypervisor دستورِ AVX را به guest منتقل نمی‌کند را تحتِ تأثیر قرار می‌دهد.

روی یک VPS یا VM، grep -m1 -ow avx /proc/cpuinfo را اجرا کن؛ یک نتیجه‌ی خالی یعنی AVX برای guest در دسترس نیست.

هیچ راه‌حلی برای باینریِ نِیتیو وجود ندارد؛ برای وضعیت، issue شماره‌ی ۵۰۳۸۴ را دنبال کن، و هنگامِ گزارش، مدلِ CPUات را از grep -m1 "model name" /proc/cpuinfo روی لینوکس یا sysctl -n machdep.cpu.brand_string روی macOS بگنجان.

روش‌های نصبِ جایگزین همان باینریِ نِیتیو را دانلود می‌کنند و هیچ‌کدام از این دو علت را حل نمی‌کنند.

`dyld: cannot load` روی macOS

اگر هنگامِ نصب dyld: cannot load، dyld: Symbol not found، یا Abort trap: 6 می‌بینی، باینری با نسخه‌ی macOS یا سخت‌افزارت ناسازگار است.

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

یک خطای Symbol not found که به libicucore ارجاع می‌دهد هم نشان می‌دهد نسخه‌ی macOSات قدیمی‌تر از چیزی است که باینری پشتیبانی می‌کند:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

راه‌حل‌ها:

نسخه‌ی macOSات را بررسی کن: Claude Code به macOS 13.0 یا بالاتر نیاز دارد. منوی Apple را باز کن و About This Mac را برای بررسیِ نسخه‌ات انتخاب کن.
macOS را به‌روزرسانی کن اگر روی نسخه‌ای قدیمی‌تر هستی. باینری از load command‌ها و کتابخانه‌های سیستمی‌ای استفاده می‌کند که نسخه‌های قدیمی‌ترِ macOS پشتیبانی نمی‌کنند. روش‌های نصبِ جایگزین مثلِ Homebrew همان باینری را دانلود می‌کنند و این خطا را حل نمی‌کنند.

`Exec format error` روی WSL1

اگر اجرای claude در WSL خطای cannot execute binary file: Exec format error چاپ می‌کند، روی WSL1 هستی و به یک نقصِ شناخته‌شده‌ی باینریِ نِیتیو که در issue شماره‌ی ۳۸۷۸۸ دنبال می‌شود برخورده‌ای. هدرهای برنامه‌ی باینری به‌گونه‌ای تغییر کرده‌اند که loaderِ WSL1 نمی‌تواند مدیریتشان کند.

تمیزترین راه‌حل، تبدیلِ توزیعت به WSL2 از PowerShell است:

wsl --set-version <DistroName> 2

اگر باید روی WSL1 بمانی، باینری را از طریقِ dynamic linker اجرا کن. این تابع را به ~/.bashrc داخلِ WSL اضافه کن و اگر دایرکتوریِ خانه‌ات متفاوت است مسیر را جایگزین کن:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

سپس source ~/.bashrc را اجرا کن و claude را دوباره امتحان کن.

خطاهای نصبِ npm در WSL

این مشکلات وقتی صدق می‌کنند که Claude Code را با npm install -g داخلِ WSL نصب کرده باشی. اگر از نصب‌کننده‌ی نِیتیو استفاده کرده‌ای، از این بخش رد شو.

مشکلاتِ تشخیصِ OS یا پلتفرم. اگر npm هنگامِ نصب یک عدمِ‌تطابقِ پلتفرم گزارش می‌کند، احتمالاً WSL دارد npmِ ویندوز را برمی‌دارد. اول npm config set os linux را اجرا کن، سپس با npm install -g @anthropic-ai/claude-code --force نصب کن. از sudo استفاده نکن.

exec: node: not found هنگامِ اجرای claude. محیطِ WSLات احتمالاً دارد از نصبِ ویندوزیِ Node.js استفاده می‌کند. با which npm و which node مطمئن شو: مسیرهایی که با /mnt/c/ شروع می‌شوند باینری‌های ویندوزی هستند، در حالی که مسیرهای لینوکسی با /usr/ شروع می‌شوند. برای رفعِ این، Node را از طریقِ مدیرِ بسته‌ی توزیعِ لینوکست یا از طریقِ nvm نصب کن.

تعارض‌های نسخه‌ی nvm. اگر nvm را هم در WSL و هم در ویندوز نصب داری، تعویضِ نسخه‌های Node در WSL ممکن است خراب شود، چون WSL به‌صورتِ پیش‌فرض PATH ویندوز را وارد می‌کند و nvmِ ویندوز اولویت می‌گیرد. رایج‌ترین علت این است که nvm در شِلت بارگذاری نشده است. لودرِ nvm را به ~/.bashrc یا ~/.zshrc اضافه کن:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

یا آن را در نشستِ جاری بارگذاری کن:

source ~/.nvm/nvm.sh

اگر nvm بارگذاری شده ولی مسیرهای ویندوز هنوز اولویت دارند، مسیرِ Nodeِ لینوکست را به‌صراحت پیش‌تر بگذار:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

خطاهای دسترسی هنگامِ نصب

اگر نصب‌کننده‌ی نِیتیو با خطاهای دسترسی شکست خورد، دایرکتوریِ مقصد ممکن است قابلِ نوشتن نباشد. به دسترسی‌های دایرکتوری را بررسی کن مراجعه کن.

اگر قبلاً با npm نصب کرده‌ای و به خطاهای دسترسیِ خاصِ npm برمی‌خوری، به نصب‌کننده‌ی نِیتیو سوئیچ کن:

curl -fsSL https://claude.ai/install.sh | bash

باینریِ نِیتیو پس از نصبِ npm پیدا نمی‌شود

بسته‌ی npmِ @anthropic-ai/claude-code باینریِ نِیتیو را از طریقِ یک وابستگیِ اختیاریِ هر-پلتفرم مثلِ @anthropic-ai/claude-code-darwin-arm64 می‌آورد. اگر اجرای claude پس از نصب Could not find native binary package "@anthropic-ai/claude-code-<platform>" چاپ می‌کند، این علت‌ها را بررسی کن:

وابستگی‌های اختیاری غیرفعال هستند. --omit=optional را از دستورِ npm install، --no-optional را از pnpm، یا --ignore-optional را از yarn حذف کن، و بررسی کن که .npmrc مقدارِ optional=false را تنظیم نکرده باشد. سپس دوباره نصب کن. باینریِ نِیتیو فقط به‌صورتِ یک وابستگیِ اختیاری ارائه می‌شود، پس اگر رد شود هیچ fallbackِ جاوااسکریپتی وجود ندارد.
پلتفرمِ پشتیبانی‌نشده. باینری‌های ازپیش‌ساخته‌شده برای darwin-arm64، darwin-x64، linux-x64، linux-arm64، linux-x64-musl، linux-arm64-musl، win32-x64، و win32-arm64 منتشر شده‌اند. Claude Code برای پلتفرم‌های دیگر باینری ارائه نمی‌کند؛ به نیازمندی‌های سیستم مراجعه کن.
آینه‌ی npmِ سازمانی فاقدِ بسته‌های پلتفرم است. مطمئن شو رجیستریت علاوه بر بسته‌ی متا، هر هشت بسته‌ی پلتفرمِ @anthropic-ai/claude-code-* را هم آینه می‌کند.

نصب با --ignore-scripts این خطا را به‌راه نمی‌اندازد. مرحله‌ی postinstall که باینری را سرِ جایش link می‌کند رد می‌شود، پس Claude Code به یک wrapper برمی‌گردد که در هر راه‌اندازی باینریِ پلتفرم را پیدا و اجرا می‌کند. این کار می‌کند ولی کندتر شروع می‌شود؛ برای اجرای مستقیم، با اسکریپت‌های فعال دوباره نصب کن.

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

این بخش‌ها به شکست‌های ورود، خطاهای OAuth، و مشکلاتِ توکن می‌پردازند.

ورودت را ریست کن

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

/logout را اجرا کن تا کاملاً خارج شوی
Claude Code را ببند
با claude دوباره شروع کن و فرایندِ احراز هویت را دوباره کامل کن

اگر مرورگر هنگامِ ورود به‌صورتِ خودکار باز نشد، c را فشار بده تا URLِ OAuth در کلیپ‌بوردت کپی شود، سپس آن را دستی در یک مرورگر بچسبان. این وقتی هم کار می‌کند که URL در یک ترمینالِ باریک یا SSH روی چند خط می‌شکند و نمی‌توان مستقیماً رویش کلیک کرد.

OAuth error: Invalid code

اگر OAuth error: Invalid code. Please make sure the full code was copied می‌بینی، کدِ ورود منقضی شده یا هنگامِ کپی-پیست بریده شده است.

راه‌حل‌ها:

Enter را فشار بده تا دوباره تلاش کنی و پس از باز شدنِ مرورگر، ورود را سریع کامل کن
c را تایپ کن تا اگر مرورگر به‌صورتِ خودکار باز نشد، URLِ کامل کپی شود
اگر از یک نشستِ remote/SSH استفاده می‌کنی، ممکن است مرورگر روی ماشینِ اشتباه باز شود. URLِ نمایش‌داده‌شده در ترمینال را کپی کن و آن را به‌جایش در مرورگرِ محلیت باز کن.

403 Forbidden پس از ورود

اگر پس از ورود API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} می‌بینی:

کاربرانِ Claude Pro/Max: فعال‌بودنِ اشتراکت را در claude.ai/settings تأیید کن
کاربرانِ Anthropic Console: مطمئن شو حسابت نقشِ “Claude Code” یا “Developer” دارد. ادمین‌ها این را در Anthropic Console زیرِ Settings → Members تخصیص می‌دهند.
پشتِ یک پراکسی: پراکسی‌های سازمانی می‌توانند با درخواست‌های API تداخل کنند. برای راه‌اندازیِ پراکسی به پیکربندیِ شبکه مراجعه کن.

This organization has been disabled with an active subscription

اگر با وجودِ داشتنِ یک اشتراکِ فعالِ Claude، API Error: 400 ... "This organization has been disabled" می‌بینی، یک متغیرِ محیطیِ ANTHROPIC_API_KEY دارد اشتراکت را بازنویسی می‌کند. این معمولاً وقتی رخ می‌دهد که یک کلیدِ API قدیمی از یک کارفرما یا پروژه‌ی قبلی هنوز در پروفایلِ شِلت تنظیم شده باشد.

وقتی ANTHROPIC_API_KEY حاضر است و تو آن را تأیید کرده‌ای، Claude Code به‌جای اعتبارنامه‌های OAuthِ اشتراکت از آن کلید استفاده می‌کند. در حالتِ غیرتعاملی با پرچمِ -p، وقتی کلید حاضر باشد همیشه استفاده می‌شود. برای ترتیبِ کاملِ تفکیک، به اولویتِ احراز هویت مراجعه کن.

برای استفاده از اشتراکت به‌جایش، متغیرِ محیطی را unset کن و آن را از پروفایلِ شِلت حذف کن:

unset ANTHROPIC_API_KEY
claude

~/.zshrc، ~/.bashrc، یا ~/.profile را برای خطوطِ export ANTHROPIC_API_KEY=... بررسی کن و حذفشان کن تا تغییر دائمی شود. روی ویندوز، پروفایلِ PowerShellات را در $PROFILE و متغیرهای محیطیِ Userت را برای ANTHROPIC_API_KEY بررسی کن. /status را داخلِ Claude Code اجرا کن تا تأیید کنی کدام روشِ احراز هویت فعال است.

ورودِ OAuth در WSL2، SSH، یا کانتینرها شکست می‌خورد

وقتی Claude Code در WSL2، روی یک ماشینِ راه‌دور از طریقِ SSH، یا داخلِ یک کانتینر اجرا می‌شود، مرورگر معمولاً روی میزبانِ متفاوتی باز می‌شود و redirectِ آن نمی‌تواند به سرورِ callbackِ محلیِ Claude Code برسد. پس از ورود، مرورگر به‌جای redirectِ خودکار، یک کدِ ورود نشان می‌دهد. آن کد را در ترمینال در محلِ پرامپتِ Paste code here if prompted بچسبان تا ورود کامل شود.

اگر مرورگر اصلاً از WSL2 باز نشد، متغیرِ محیطیِ BROWSER را روی مسیرِ مرورگرِ ویندوزت تنظیم کن:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

یا به‌جایش، در پرامپتِ تعاملیِ ورود c را فشار بده تا URLِ OAuth کپی شود، یا URLی که claude auth login چاپ می‌کند را کپی کن، و آن را در یک مرورگر روی ماشینِ محلیت باز کن.

اگر چسباندنِ کد در پرامپتِ تعاملی کاری نمی‌کند، احتمالاً bindِ paste ترمینالت به فیلدِ ورودی نمی‌رسد. میان‌برِ pasteِ جایگزینِ ترمینالت را امتحان کن، که اغلب راست‌کلیک یا Shift+Insert در Windows Terminal است، یا به‌جایش از claude auth login استفاده کن، که کدِ چسبانده‌شده را از ورودیِ استاندارد می‌خواند:

claude auth login

این fallback روی ویندوزِ نِیتیو یا هر ترمینالی که چسباندن در پرامپتِ تعاملی در آن شکست می‌خورد هم صدق می‌کند.

وارد نشده‌ای یا توکن منقضی شده

اگر Claude Code پس از یک نشست از تو می‌خواهد دوباره وارد شوی، توکنِ OAuthات شاید منقضی شده باشد.

برای احراز هویتِ مجدد /login را اجرا کن. اگر این مکرراً اتفاق می‌افتد، بررسی کن ساعتِ سیستمت دقیق باشد، چون اعتبارسنجیِ توکن به timestampهای درست وابسته است.

روی macOS، ورود وقتی هم می‌تواند شکست بخورد که Keychain قفل باشد یا رمزش با رمزِ حسابت هماهنگ نباشد، که مانعِ ذخیره‌ی اعتبارنامه‌ها توسطِ Claude Code می‌شود. claude doctor را اجرا کن تا دسترسیِ Keychain را بررسی کنی. برای بازکردنِ دستیِ Keychain، security unlock-keychain ~/Library/Keychains/login.keychain-db را اجرا کن. اگر بازکردن کمکی نکرد، Keychain Access را باز کن، کیچینِ login را انتخاب کن، و Edit > Change Password for Keychain “login” را انتخاب کن تا با رمزِ حسابت دوباره هماهنگش کنی.

اعتبارنامه‌های Bedrock، Vertex، یا Foundry بارگذاری نمی‌شوند

اگر Claude Code را برای استفاده از یک ارائه‌دهنده‌ی ابری پیکربندی کرده‌ای و روی Bedrock Could not load credentials from any providers، روی Vertex Could not load the default credentials، یا روی Foundry ChainedTokenCredential authentication failed می‌بینی، CLIِ ارائه‌دهنده‌ی ابریت احتمالاً در شِلِ جاری احراز هویت نشده است.

برای Bedrock، تأیید کن اعتبارنامه‌های AWS تو معتبرند:

aws sts get-caller-identity

برای Vertex AI، تأیید کن ANTHROPIC_VERTEX_PROJECT_ID و CLOUD_ML_REGION در شِلت تنظیم شده‌اند، سپس application default credentials را تنظیم کن:

gcloud auth application-default login

برای Microsoft Foundry، تأیید کن ANTHROPIC_FOUNDRY_API_KEY تنظیم شده، یا با Azure CLI وارد شو تا زنجیره‌ی اعتبارنامه‌ی پیش‌فرض بتواند حسابت را پیدا کند:

az login

اگر اعتبارنامه‌ها در ترمینالت کار می‌کنند ولی در افزونه‌ی VS Code یا JetBrains نه، فرایندِ IDE احتمالاً محیطِ شِلت را به ارث نبرده است. متغیرهای محیطیِ ارائه‌دهنده را در تنظیماتِ خودِ IDE تنظیم کن، یا IDE را از یک ترمینالی که آن‌ها قبلاً در آن export شده‌اند راه‌اندازی کن.

برای راه‌اندازیِ کاملِ ارائه‌دهنده، به Amazon Bedrock، Google Vertex AI، یا Microsoft Foundry مراجعه کن.

هنوز گیر کرده‌ای

اگر هیچ‌کدام از موارد بالا مشکلت را حل نکرد:

مخزنِ GitHub را برای issueهای شناخته‌شده بررسی کن، یا یک issue جدید با سیستم‌عاملت، دستورِ نصبی که اجرا کردی، و خروجیِ کاملِ خطا باز کن
اگر claude --version کار می‌کند ولی چیزِ دیگری اشتباه است، claude doctor را اجرا کن تا یک گزارشِ تشخیصیِ خودکار بگیری
اگر می‌توانی یک نشست شروع کنی، از /feedback داخلِ Claude Code استفاده کن تا مشکل را گزارش کنی

عیب‌یابیِ نصب و ورود

خطایت را پیدا کن

بررسی‌های تشخیصی را اجرا کن

اتصالِ شبکه را بررسی کن

PATH خود را تأیید کن

بررسیِ نصب‌های متعارض

دسترسی‌های دایرکتوری را بررسی کن

کارکردِ باینری را تأیید کن

مشکلاتِ رایجِ نصب

اسکریپتِ نصب به‌جای یک اسکریپتِ شِل، HTML برمی‌گرداند

command not found: claude پس از نصب

curl: (56) Failure writing output to destination

خطاهای اتصالِ TLS یا SSL

Failed to fetch version from downloads.claude.ai

دستورِ نصبِ نادرست روی ویندوز

The process cannot access the file هنگامِ نصب روی ویندوز

نصب روی سرورهای لینوکسِ کم‌حافظه kill می‌شود

نصب در Docker هَنگ می‌کند

Claude Desktop دستورِ claude را روی ویندوز بازنویسی می‌کند

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Claude Code does not support 32-bit Windows

ناسازگاریِ باینریِ musl یا glibc در لینوکس

Illegal instruction

dyld: cannot load روی macOS

Exec format error روی WSL1

خطاهای نصبِ npm در WSL

خطاهای دسترسی هنگامِ نصب

باینریِ نِیتیو پس از نصبِ npm پیدا نمی‌شود

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

ورودت را ریست کن

OAuth error: Invalid code

403 Forbidden پس از ورود

This organization has been disabled with an active subscription

ورودِ OAuth در WSL2، SSH، یا کانتینرها شکست می‌خورد

وارد نشده‌ای یا توکن منقضی شده

اعتبارنامه‌های Bedrock، Vertex، یا Foundry بارگذاری نمی‌شوند

هنوز گیر کرده‌ای

`command not found: claude` پس از نصب

`curl: (56) Failure writing output to destination`

`Failed to fetch version from downloads.claude.ai`

`The process cannot access the file` هنگامِ نصب روی ویندوز

Claude Desktop دستورِ `claude` را روی ویندوز بازنویسی می‌کند

`Illegal instruction`

`dyld: cannot load` روی macOS

`Exec format error` روی WSL1