# راهنمای عیب‌یابی

## کلید پیکربندی شده اما درخواست‌ها همچنان شکست می‌خورند؟ به این ترتیب بررسی کنید

ادامه این صفحه بر اساس کد خطا سازمان‌دهی شده است؛ اگر **کلید و URL‌ها را دقیقاً مطابق مستندات وارد کرده‌اید و درخواست‌ها همچنان ناموفق‌اند**، ابتدا این فهرست بررسی را مرور کنید (خودآزمایی curl و خواندن کد HTTP: [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths)، بخش 5):

1. **ابتدا یک خودآزمایی curl اجرا کنید.** کد را تفسیر کنید: `401` = مشکل کلید؛ `404` = پیشوند مسیر اشتباه؛ `400` همراه با `model_not_available_on_endpoint` = پروتکل اشتباه (نه کلید — به مورد 4 مراجعه کنید)؛ اتصال هرگز برقرار نمی‌شود = شبکه/پروکسی، به مورد 6 مراجعه کنید؛ `402` با کدی مانند `*_cost_limit_exceeded` = مسیر و کلید درست‌اند، سهمیه به‌سادگی تمام شده است (به [کدهای خطا](/docs/reference/errors#402-quota-exhausted) مراجعه کنید).
2. **متغیر درست، جایگاه اشتباه.** `ANTHROPIC_AUTH_TOKEN` به‌صورت هدر `Authorization: Bearer` ارسال می‌شود و `ANTHROPIC_API_KEY` به‌صورت `x-api-key` — اگر کلید را در جای اشتباه قرار دهید، دروازه هرگز اعتبارنامه معتبری نمی‌بیند. **متغیرهای قدیمی در محیط شما تنظیمات فعلی را بازنویسی می‌کنند**: دستورهای `env | grep -i anthropic` و `env | grep -i openai` را اجرا کنید و باقی‌مانده‌ها را حذف کنید.
3. **ساختار Base URL.** خانواده Claude Code: `https://api.qcode.cc/api` (**بدون `/v1`**)؛ SDK OpenAI / کلاینت‌های سازگار: `https://api.qcode.cc/openai/v1`؛ Codex CLI در فایل پیکربندی خود: `https://api.qcode.cc/openai` همراه با `wire_api = "responses"`. یک بخش مسیر بیشتر یا کمتر = 404.
4. **ناسازگاری پروتکل / مدل.** ارسال یک مدل Claude به نقطه پایانی OpenAI پیش از احراز هویت `model_not_available_on_endpoint` را برمی‌گرداند — با استفاده از ماتریس در [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) بخش 2، نقطه پایانی یا مدل را تغییر دهید.
5. **رگرسیون‌های نسخه کلاینت (Claude Code):**
   - **2.1.265–2.1.267**: هر درخواست کد 400 برمی‌گرداند (طرح‌واره ابزار Artifact رد می‌شود) — به **≥2.1.268** ارتقا دهید یا `CLAUDE_CODE_DISABLE_ARTIFACT=1` را تنظیم کنید.
   - **2.1.275**: وقتی `ANTHROPIC_BASE_URL` به یک دروازه اشاره می‌کند، هر درخواست با `400 … Input tag 'advisor_20260301'` ناموفق می‌شود — به **≥2.1.276** ارتقا دهید.
   - خطاهای `Unexpected value(s) … anthropic-beta` — `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` را تنظیم کنید.
6. **پروکسی سیستم در برابر دامنه دسترسی.** `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` ترافیک را تغییر مسیر می‌دهند؛ `*.qcode.cc` را به `NO_PROXY` اضافه کنید یا آن‌ها را موقتاً حذف کنید و دوباره تلاش کنید.
7. **هنوز مشکل دارید**: درخواست را با کلید خود در [probe.qcode.cc](https://probe.qcode.cc) بررسی کنید تا ببینید واقعاً چه چیزی ارسال شده است، سپس **با شناسه درخواست با پشتیبانی تماس بگیرید** (چت زنده یا hi@qcode.cc).

معانی کدهای خطا در [کدهای خطا](/docs/reference/errors) آمده است؛ برای پرسش‌های «آیا اشتراک من می‌تواند به‌عنوان API عمل کند» به [اشتراک‌ها در برابر کلیدهای API در برابر کلیدهای QCode](/docs/reference/subscription-vs-api-key) مراجعه کنید.

اگر هنگام استفاده از Claude Code با مشکلی روبه‌رو شدید، نگران نشوید. این راهنما بر اساس جریان «خودبررسی سریع → عیب‌یابی گام‌به‌گام → راه‌حل‌ها» سازمان‌دهی شده است تا به شما کمک کند مشکلات را به‌شکل کارآمد پیدا و رفع کنید.
## بررسی سریع اولیه

وقتی با مشکلی روبه‌رو می‌شوید، با این سه بررسی سریع شروع کنید—80% مشکلات در همین مرحله شناسایی می‌شود.

### 1. بررسی نسخه Claude Code

```bash
claude --version
```

مطمئن شوید که از آخرین نسخه استفاده می‌کنید. Claude Code مرتباً به‌روزرسانی می‌شود و بسیاری از مشکلات در نسخه‌های جدیدتر رفع شده‌اند.

**ارتقا به آخرین نسخه:**

```bash
npm update -g @anthropic-ai/claude-code
```

### 2. اجرای عیب‌یابی خودکار

```bash
claude /doctor
```

دستور `/doctor` به‌طور خودکار این موارد را بررسی می‌کند:
- اینکه نسخه Node.js الزامات را برآورده می‌کند یا نه (≥ 18)
- اینکه کلید API معتبر است یا نه
- اینکه اتصال شبکه عادی است یا نه
- اینکه فایل پیکربندی خطای نحوی دارد یا نه

### 3. بررسی نسخه Node.js

Claude Code به Node.js نسخه 18 یا بالاتر نیاز دارد:

```bash
node --version
# Should output v18.x.x or higher
```

اگر نسخه بیش از حد پایین است، ارتقا دهید:

```bash
# Use nvm to manage Node.js versions (recommended)
nvm install 22
nvm use 22

# Or download and install directly
# Visit https://nodejs.org/ to download the LTS version
```

## مشکلات نصب

### خطای مجوز در npm install

**نشانه‌ها:**

```bash
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
```

**راه‌حل 1: استفاده از sudo (سریع است اما برای استفاده بلندمدت توصیه نمی‌شود)**

```bash
sudo npm install -g @anthropic-ai/claude-code
```

**راه‌حل 2: تغییر پوشه سراسری npm (توصیه‌شده)**

```bash
# Create a user-level global package directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (write to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g @anthropic-ai/claude-code
```

**راه‌حل 3: استفاده از nvm برای مدیریت Node.js**

```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js
nvm install 22
nvm use 22

# Node.js installed via nvm doesn't require sudo
npm install -g @anthropic-ai/claude-code
```

### مشکلات شبکه که باعث شکست نصب می‌شوند

**نشانه‌ها:**

```bash
npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT
```

**راه‌حل: استفاده از یک آینه داخلی**

```bash
# Temporarily use the Taobao mirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# Or permanently set the mirror
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```

اگر از پروکسی استفاده می‌کنید:

```bash
# Set npm proxy
npm config set proxy http://your-proxy-address:port
npm config set https-proxy http://your-proxy-address:port

# After installation, you can remove the proxy settings
npm config delete proxy
npm config delete https-proxy
```

### سیاست اجرای PowerShell در Windows

**نشانه‌ها:**

```bash
claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.
```

**راه‌حل:**

```powershell
# Open PowerShell as administrator and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then run claude again
claude
```

یا به‌جای PowerShell از CMD استفاده کنید:

```cmd
# Run directly in CMD
claude
```
## مشکلات اتصال

مشکلات اتصال رایج‌ترین نوع مشکلی است که کاربران در چین با آن روبه‌رو می‌شوند.

### خطای قالب کلید API

**قالب کلید API در QCode.cc:**

```text
cr_xxxxxxxxxxxxxxxx
```

توجه کنید پیشوند `cr_` است، نه `sk-ant-` رسمی Anthropic.

**بررسی پیکربندی کلید API:**

```bash
# View current environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Correct setup (QCode.cc key)
export ANTHROPIC_AUTH_TOKEN="cr_your-key"
```

**خطاهای رایج:**

| خطا | توضیح |
|------|------|
| فاصله پیش یا پس از کلید | `cr_ xxx` → `cr_xxx` |
| از قالب کلید رسمی استفاده شده است | `sk-ant-xxx` کلید رسمی Anthropic است، نه کلید QCode.cc |
| کلید بریده شده است | بررسی کنید کلید را به‌طور کامل کپی کرده‌اید یا نه |
| از کلید منقضی‌شده استفاده شده است | وضعیت کلید را در داشبورد QCode.cc تأیید کنید |

### خطای پیکربندی ANTHROPIC_BASE_URL

هنگام استفاده از سرویس QCode.cc باید Base URL را به‌درستی تنظیم کنید:

```bash
# QCode.cc's Base URL
export ANTHROPIC_BASE_URL="https://your-service-address"
```

**مراحل عیب‌یابی:**

```bash
# 1. Check current configuration
echo $ANTHROPIC_BASE_URL

# 2. Confirm URL format is correct
#    - Must start with https://
#    - No trailing slash /
#    - Should not contain paths (like /v1/messages)

# Correct: the Anthropic protocol needs the /api prefix, but no request-path segment
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"

# Wrong: missing https / an extra trailing slash / the path segment spelled out
export ANTHROPIC_BASE_URL="http://api.qcode.cc/api"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/v1/messages"
```

### شکست اتصال ناشی از پروکسی/VPN

**نشانه‌ها:**

```text
Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com
```

**مراحل عیب‌یابی:**

```bash
# 1. Check if proxy is correctly set
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. Test network connectivity
curl -v https://your-service-address/health

# 3. If using a proxy, ensure Claude Code can use it
export HTTP_PROXY="http://proxy-address:port"
export HTTPS_PROXY="http://proxy-address:port"

# 4. If you don't need a proxy but have one set, unset it
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY
```

**نکته‌های VPN:**

- اطمینان حاصل کنید VPN درخواست‌های API را رهگیری نمی‌کند
- برخی قواعد تونل‌سازی تقسیم‌شده VPN ممکن است بر اتصال‌های API اثر بگذارند
- اگر VPN مشکل ایجاد می‌کند، دامنه API را به قواعد اتصال مستقیم اضافه کنید

### مشکلات گواهی SSL/TLS

**نشانه‌ها:**

```text
Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
```

**راه‌حل‌ها:**

```bash
# Solution 1: Update system CA certificates
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# Solution 2: For corporate network mitm certificates, set Node.js to trust them
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# Solution 3: Temporarily skip certificate verification (only for testing, not recommended for long-term use)
export NODE_TLS_REJECT_UNAUTHORIZED=0
```

### آزمون اتصال

برای آزمایش مستقیم اتصال API از curl استفاده کنید:

```bash
# Test basic connectivity
curl -s -o /dev/null -w "%{http_code}" \
  https://your-service-address/health

# Test API call (replace with your key and address)
curl https://your-service-address/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**نتایج مورد انتظار:**
- بررسی سلامت `200` برمی‌گرداند
- فراخوانی API پاسخ JSON برمی‌گرداند

**مرجع مشکلات رایج:**

| نتیجه curl | علت احتمالی | راه‌حل |
|-------------|---------------|----------|
| `connection refused` | آدرس سرویس اشتباه است یا سرویس در حال اجرا نیست | ANTHROPIC_BASE_URL را بررسی کنید |
| `connection timeout` | شبکه در دسترس نیست یا توسط فایروال مسدود شده است | تنظیمات شبکه/پروکسی را بررسی کنید |
| `401 Unauthorized` | کلید API نامعتبر است | بررسی کنید کلید درست است یا نه |
| `403 Forbidden` | کلید مجوزهای لازم را ندارد | با ارائه‌دهنده سرویس تماس بگیرید |
| خطاهای مرتبط با SSL | مشکل گواهی | به بخش SSL بالا مراجعه کنید |

## مشکلات مجوزها

### مجوز کافی برای خواندن/نوشتن فایل وجود ندارد

**نشانه‌ها:**

```text
Error: EACCES: permission denied, open '/path/to/file'
```

**راه‌حل‌ها:**

```bash
# 1. Check file permissions
ls -la /path/to/file

# 2. Ensure current user has read/write permissions
chmod u+rw /path/to/file

# 3. Check directory permissions (Claude needs write permission to create new files)
chmod u+w /path/to/directory

# 4. If file was created by root, change ownership
sudo chown $(whoami) /path/to/file
```

**پیکربندی مجوزهای Claude Code:**

Claude Code یک سیستم مجوز دارد که عملیات قابل انجام را کنترل می‌کند. اگر متوجه شدید Claude از انجام عملیاتی مسدود شده است:

```bash
# View current permission settings
claude /permissions

# Configure allowed directories in settings.json
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}
```

### رد شدن عملیات Git

**نشانه‌ها:**

```text
fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403
```

**راه‌حل‌ها:**

```bash
# 1. Check Git configuration
git config --list

# 2. Confirm SSH key or Token configuration
ssh -T git@github.com          # Test SSH connection
gh auth status                  # Test GitHub CLI authentication

# 3. If using HTTPS, check credentials
git config credential.helper    # View credential helper

# 4. Ensure Claude Code is in the correct Git repository
git status                      # Confirm you're in the repository directory
```

### شکست اجرای فرمان Bash

Claude Code هنگام اجرای فرمان‌های bash ممکن است به تأیید شما نیاز داشته باشد. اگر یک فرمان پیوسته رد می‌شود:

```bash
# View permission configuration
claude /permissions

# If it's a project you trust, you can configure allowed commands in CLAUDE.md
# CLAUDE.md
## Allowed Commands
allowedTools:
  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)
```

## مشکلات کارایی

### کندی سرعت پاسخ

**علت‌های احتمالی و راه‌حل‌ها:**

| علت | روش تشخیص | راه‌حل |
|------|------------------|----------|
| تأخیر شبکه | `ping service-address` | بررسی شبکه/پروکسی |
| استفاده از مدل Opus | `/model` برای مشاهده | تغییر به Sonnet |
| زمینه بیش‌ازحد بزرگ | `/cost` برای مشاهده تعداد توکن | `/compact` برای فشرده‌سازی |
| بار زیاد سرور | بررسی زمان پاسخ HTTP | بعداً دوباره تلاش کنید |

**پیشنهادهای بهینه‌سازی شبکه (برای کاربران در چین):**

```bash
# Test latency to the server
ping service-address

# If latency exceeds 500ms, consider:
# 1. Check if proxy configuration is optimal
# 2. Try using at different times (avoid peak hours)
# 3. Contact QCode.cc customer service for optimal nodes
```

### سرریز زمینه

**نشانه‌ها:**
- پاسخ‌های Claude شروع به «فراموش کردن» مطالب گفته‌شده پیشین می‌کنند
- کیفیت پاسخ به‌طور چشمگیری کاهش می‌یابد
- محتوای تکراری یا متناقض ظاهر می‌شود

**راه‌حل‌ها:**

```bash
# Solution 1: Compress context (retain key information)
/compact

# Solution 2: Clear completely (if you can start over)
/clear

# Solution 3: Streamline each input
# Don't send large amounts of file content at once
# Use @ to reference files instead of pasting
# Handle one task at a time
```

**اقدامات پیشگیرانه:**

- پس از تکمیل هر وظیفه مستقل، استفاده از `/compact` را در نظر بگیرید
- هنگام تغییر به موضوع‌های مختلف، در استفاده از `/clear` تردید نکنید
- از `.claudeignore` برای کنار گذاشتن فایل‌های بزرگ نامرتبط استفاده کنید
- از `@` برای ارجاع دقیق به فایل‌های موردنیاز استفاده کنید؛ نگذارید Claude به‌صورت سراسری جست‌وجو کند

### مصرف زیاد حافظه

**نشانه‌ها:**
- سیستم کند می‌شود
- فرایند Claude Code حافظه زیادی مصرف می‌کند

**راه‌حل‌ها:**

```bash
# 1. Check Node.js memory usage
node -e "console.log(process.memoryUsage())"

# 2. Upgrade Node.js to the latest LTS version
nvm install 22
nvm use 22

# 3. If the problem persists, limit Node.js maximum memory
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. Restart Claude Code
# Exit current session and restart
exit
claude
```
## مرجع کدهای خطای رایج

| کد خطا | معنا | علت | راه‌حل |
|-----------|---------|-------|----------|
| **400** | درخواست نامعتبر | قالب درخواست نادرست است | نویسه‌های غیرمجاز در ورودی را بررسی کنید؛ Claude Code را به آخرین نسخه به‌روزرسانی کنید |
| **401** | غیرمجاز | کلید API نامعتبر یا منقضی شده است | تنظیم `ANTHROPIC_AUTH_TOKEN` را بررسی کنید؛ مطمئن شوید کلید منقضی نشده است |
| **402** | نیاز به پرداخت | سهمیه تمام شده است، یا سرویس موقتاً درخواست را رد می‌کند | `error.type` = `insufficient_quota` یعنی سهمیه تمام شده است (`code` را بررسی کنید: سهمیه روزانه در 00:00 به وقت پکن بازنشانی می‌شود، بسته‌های تقویتی در دسترس هستند)؛ در غیر این صورت مدل یا دامنه نقطه پایانی را تغییر دهید؛ [کدهای خطا](/docs/reference/errors#402-quota-exhausted) را ببینید |
| **403** | ممنوع | دسترسی وجود ندارد | مطمئن شوید کلید برای مدل مربوطه مجوز دسترسی دارد |
| **404** | یافت نشد | مدل یا مسیر وجود ندارد | بررسی کنید `ANTHROPIC_BASE_URL` و نام مدل درست باشند |
| **429** | درخواست‌های بیش از حد | درخواست‌ها بیش از حد مکرر هستند | 30-60 ثانیه صبر کنید و دوباره تلاش کنید؛ درخواست‌های هم‌زمان را کاهش دهید |
| **500** | خطای داخلی سرور | خطای داخلی سرور | بعداً دوباره تلاش کنید؛ اگر ادامه داشت، با پشتیبانی تماس بگیرید |
| **502** | درگاه نامعتبر | سرویس بک‌اند در دسترس نیست | بعداً دوباره تلاش کنید؛ اعلان‌های سرویس را بررسی کنید |
| **503** | سرویس در دسترس نیست | سرویس موقتاً بیش از حد بارگذاری شده است | چند دقیقه صبر کنید و دوباره تلاش کنید |
| **529** | API بیش از حد بارگذاری شده | Claude API بیش از حد بارگذاری شده است | این به دلیل بار بالای سرور Anthropic است؛ صبر کنید و دوباره تلاش کنید |

### 402 سهمیه تمام شده: چه چیزهایی را به ترتیب بررسی کنید

اگر پاسخ 402 است و `error.type` برابر `insufficient_quota` است، به این ترتیب آن را بررسی کنید:

1. **`code` را بخوانید** تا ببینید کدام سهمیه تمام شده است (جزئیات در [مرجع خطا](/docs/reference/errors#402-quota-exhausted)).
2. **`daily_cost_limit_exceeded` (سهمیه روزانه پلن شخصی)**: منتظر بازنشانی خودکار در 00:00 به وقت پکن بمانید، یا یک بسته تقویتی در داشبورد بخرید.
3. **`total_cost_limit_exceeded` (سهمیه کل)**: کارت **کلید پرداخت به‌ازای مصرف** را در داشبورد برای دیدن سهمیه باقی‌مانده و تاریخ انقضا بررسی کنید، و زمانی که تمام شد **تمدید** کنید (تمدیدها روی همان کلید انباشته می‌شوند، قواعد در [بسته‌های پرداخت به‌ازای مصرف](/docs/reference/payg-packs))؛ برای سهمیه ماهانه Ultimate [پرسش‌های متداول](/docs/reference/faq) را ببینید. مبلغ داخل پرانتز در پیام، سقف تجمعی است، نه مقدار باقی‌مانده.
4. **سقف هفتگی برای مدل‌های Claude**: به‌صورت خودکار در چرخه‌ای که برای کلید پیکربندی شده است بازنشانی می‌شود؛ در این فاصله می‌توانید به مدل دیگری هم تغییر دهید.
5. **401** به‌جای 402: کلید منقضی شده است. تمدید یک بسته همان کلید را بازیابی می‌کند (روی گره‌های خارج از کشور ممکن است تا حدود 5 دقیقه طول بکشد).

خطای 402 با ارسال مجدد برطرف نمی‌شود، بنابراین حلقه تلاش مجدد ننویسید.

### 429 به‌تفصیل: محدودیت نرخ درخواست

429 رایج‌ترین خطاست و ارزش دارد که به‌تفصیل توضیح داده شود:

**محرک‌ها:**

1. **فراوانی بیش از حد درخواست‌ها**: ارسال درخواست‌های بیش از حد در هر ثانیه
2. **مصرف توکن بیش از حد سریع**: مصرف تعداد زیادی توکن در زمان کوتاه
3. **نشست‌های هم‌زمان بیش از حد**: اجرای چندین نمونه Claude Code به‌طور هم‌زمان

> **تمام شدن سهمیه خطای 429 نیست**: وقتی سهمیه روزانه، کل یا هفتگی تمام می‌شود، پاسخ **402** (`insufficient_quota`) است — [کدهای خطا](/docs/reference/errors#402-quota-exhausted) را ببینید.

**پاسخ مرحله‌ای:**

```bash
# Occasional 429
# → Wait 30 seconds for automatic retry, Claude Code has built-in retry logic

# Frequent 429
# → Reduce request frequency
# → Use /compact to reduce context size
# → Avoid running multiple Claude Code instances simultaneously

# Persistent 429
# → Check how many sessions you are running in parallel
# → Log in to QCode.cc Dashboard to view usage
# → A used-up quota returns 402, not 429 — see the error code reference
```

### 529 به‌تفصیل: API بیش از حد بارگذاری شده

529 یک کد خطای مخصوص Anthropic است که نشان‌دهنده بار بیش از حد سرور Claude API است:

```text
Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.
```

**اقدامات پاسخ:**

- این مشکل شما نیست؛ یک وضعیت موقت در سرور Anthropic است
- معمولاً از چند دقیقه تا چند ده دقیقه طول می‌کشد
- 1-2 دقیقه صبر کنید و دوباره تلاش کنید
- اگر ادامه داشت، می‌توانید موقتاً به مدل دیگری (مانند سری GPT) تغییر دهید
- برای اطلاع از وضعیت سرویس، [Anthropic Status](https://status.anthropic.com/) را دنبال کنید
## سایر مشکلات رایج

### عدم پاسخ‌دهی پس از اجرای Claude Code

```bash
# 1. Check if properly installed
which claude
npm list -g @anthropic-ai/claude-code

# 2. View detailed error information
claude --debug

# 3. Try clearing cache and restarting
rm -rf ~/.claude/cache
claude
```

### بی‌اثر بودن CLAUDE.md

```bash
# 1. Confirm file location is correct
ls -la CLAUDE.md                # Project root directory
ls -la .claude/CLAUDE.md        # Project private configuration
ls -la ~/.claude/CLAUDE.md      # Global configuration

# 2. Confirm file encoding is UTF-8
file CLAUDE.md
# Should display: CLAUDE.md: UTF-8 Unicode text

# 3. Confirm no syntax errors (although it's Markdown, some special characters may cause parsing issues)
# Avoid using special markers other than ``` in CLAUDE.md

# 4. Restart Claude Code for configuration to take effect
# Exit and re-enter
```

### نمایش نویسه‌های چینی به‌صورت متن به‌هم‌ریخته

```bash
# 1. Check terminal encoding settings
echo $LANG
# Should include UTF-8, for example en_US.UTF-8 or zh_CN.UTF-8

# 2. Set correct encoding
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. Confirm terminal supports UTF-8
# macOS Terminal / iTerm2 supports by default
# Windows Terminal supports by default
# Windows CMD requires: chcp 65001
```

### شکست عملیات Claude به‌دلیل تعارض‌های Git

```bash
# 1. First resolve Git conflicts
git status     # View conflicting files
git diff       # View conflict content

# 2. Let Claude help resolve conflicts
> "View the current git conflict files and help me resolve these conflicts. Keep changes from both sides."

# 3. Continue after resolution
git add .
git commit -m "resolve merge conflicts"
```

### مشکلات مرتبط با Docker (کاربران پیشرفته)

اگر از Claude Code در یک کانتینر Docker استفاده می‌کنید:

```bash
# Ensure container has Node.js 22+
docker run -it node:22-slim bash

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Pass necessary environment variables
docker run -it \
  -e ANTHROPIC_AUTH_TOKEN="cr_your-key" \
  -e ANTHROPIC_BASE_URL="https://your-service-address" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude
```

## خلاصه روند عیب‌یابی

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

```text
1. Quick Self-Check
   ├── claude --version (is version latest)
   ├── claude /doctor (automatic diagnostics)
   └── node --version (Node.js ≥ 18)

2. Network Connectivity
   ├── curl test API address
   ├── Check proxy/VPN settings
   └── Check DNS resolution

3. Authentication Configuration
   ├── Is ANTHROPIC_AUTH_TOKEN format correct
   ├── Is ANTHROPIC_BASE_URL correct
   └── Is key expired

4. Permission Check
   ├── File system permissions
   ├── Git permissions
   └── Claude Code permission configuration

5. Performance Optimization
   ├── /compact to compress context
   ├── /model to switch to appropriate model
   └── .claudeignore to exclude large files

6. If none of the above solves it → Get Help
```

## دریافت کمک

اگر هیچ‌یک از روش‌های بالا مشکل شما را برطرف نکرد، می‌توانید از طریق این کانال‌ها کمک بگیرید:

### خدمات مشتریان آنلاین QCode.cc

روی آیکون خدمات مشتریان آنلاین در گوشه پایین-راست وب‌سایت [QCode.cc](https://qcode.cc) کلیک کنید. در ساعات کاری، معمولاً می‌توانید در عرض چند دقیقه پاسخ بگیرید.

**هنگام پرسیدن سؤال، لطفاً این موارد را ارائه کنید:**
- نسخه Claude Code (خروجی `claude --version`)
- سیستم‌عامل و نسخه آن
- پیام کامل خطا
- راه‌حل‌هایی که امتحان کرده‌اید

### GitHub Issues

Claude Code یک پروژه متن‌باز است و می‌توانید Issues را در GitHub ثبت کنید:

- **آدرس مخزن**: [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
- Issues موجود را جست‌وجو کنید تا ببینید آیا کسی با همین مشکل روبه‌رو شده است
- هنگام ثبت Issue جدید، آن را به انگلیسی توصیف کنید (دریافت پاسخ رسمی آسان‌تر است)

### منابع انجمن

- **مستندات رسمی Claude Code**: [docs.anthropic.com](https://docs.anthropic.com)
- **وضعیت سرویس Anthropic**: [status.anthropic.com](https://status.anthropic.com)
- **مستندات کاربران QCode.cc**: [docs.qcode.cc](https://docs.qcode.cc)

> از بروز مشکل نترسید؛ بیشتر مشکلات راه‌حل ساده‌ای دارند. با پیروی از روند عیب‌یابی این راهنما، معمولاً می‌توانید مشکل را در عرض چند دقیقه برطرف کنید.