# یکپارچه‌سازی VS Code

> **آخرین بازبینی**: 2026-09-18 · 📄 طبق مستندات رسمی (VS Code 1.138.0، منتشرشده در 2026-09-16)

## مرور کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (افزونه از طریق پروتکل Anthropic / Copilot از طریق Messages) · GPT ✅ · مدل‌های چینی ✅ (نقطه پایانی سفارشی Copilot) · Gemini ❌ |
| پروتکل و Base URL | افزونه Claude Code: متغیرهای محیطی روی `https://api.qcode.cc/api` · Copilot: URLهای کامل در `chatLanguageModels.json` |
| محل پیکربندی | `~/.claude/config.json` + متغیرهای محیطی؛ Copilot از `chatLanguageModels.json` استفاده می‌کند |
| مستندات رسمی | [افزونه Claude Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) · [مدل‌های زبانی](https://code.visualstudio.com/docs/agent-customization/language-models) |

> **از Trae IDE استفاده می‌کنید؟** Trae یک فورک از VS Code است، بنابراین بیشتر مراحل اینجا مستقیماً کاربرد دارد. برای جزئیات مخصوص Trae — تفاوت‌های بازارچه، نصب آفلاین `.vsix`، هم‌زیستی با هوش مصنوعی داخلی Trae — به [راهنمای یکپارچه‌سازی Trae](/docs/ide/trae) مراجعه کنید.

علاوه بر استفاده از Claude Code CLI در ترمینال، می‌توانید از افزونه VS Code برای دسترسی مستقیم به Claude Code در ویرایشگر استفاده کنید تا تجربه توسعه راحت‌تری داشته باشید.

## پیش‌نیازها

پیش از پیکربندی افزونه VS Code، مطمئن شوید که:

1. **Claude Code CLI نصب شده و به‌درستی کار می‌کند**
   - برای تکمیل نصب، [راهنمای نصب](/docs/getting-started/installation) را ببینید
   - برای تکمیل پیکربندی، [پیکربندی محیط](/docs/getting-started/environment) را ببینید

2. **نسخه VS Code >= 1.98.0**

## مراحل نصب

### مرحله 1: نصب VS Code

اگر VS Code نصب نیست، برای دانلود و نصب به [وب‌سایت VS Code](https://code.visualstudio.com/) مراجعه کنید.

### مرحله 2: نصب افزونه Claude Code

در VS Code:

1. پنل Extensions را باز کنید (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. عبارت **«Claude Code for VS Code»** را جستجو کنید

3. روی **Install** کلیک کنید

یا از طریق خط فرمان نصب کنید:

```bash
code --install-extension anthropic.claude-code
```

### مرحله 3: پیکربندی primaryApiKey

این یک مرحله حیاتی است! افزونه Claude Code به `primaryApiKey` در فایل پیکربندی نیاز دارد.

<div data-os="windows" markdown="1">

#### ویندوز

فایل پیکربندی `C:\Users\YourUsername\.claude\config.json` را ویرایش کنید یا بسازید:

```json
{
  "primaryApiKey": "qcode"
}
```

</div>

<div data-os="macos" markdown="1">

#### macOS

فایل پیکربندی `~/.claude/config.json` را ویرایش کنید یا بسازید:

```bash
# Create directory (if it doesn't exist)
mkdir -p ~/.claude

# Create config file
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

<div data-os="linux" markdown="1">

#### لینوکس

فایل پیکربندی `~/.claude/config.json` را ویرایش کنید یا بسازید:

```bash
# Create directory (if it doesn't exist)
mkdir -p ~/.claude

# Create config file
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

> **توجه**: مقدار `primaryApiKey` می‌تواند هر چیزی باشد (مثل `qcode`). فقط کافی است این فیلد پیکربندی شده باشد. احراز هویت واقعی API همچنان از `ANTHROPIC_AUTH_TOKEN` استفاده می‌کند که در متغیرهای محیطی پیکربندی کرده‌اید.

> **مهم**: فایل پیکربندی `config.json` است، نه `settings.json`. لطفاً این دو فایل را به‌دقت از هم تفکیک کنید.

### مرحله 4: راه‌اندازی مجدد VS Code

پس از پیکربندی، VS Code را راه‌اندازی مجدد کنید تا تغییرات اعمال شوند.
## استفاده

### میان‌برهای صفحه‌کلید

| میان‌بر | کارکرد |
|----------|----------|
| `Cmd+Esc` / `Ctrl+Esc` | باز و بستن پنل Claude Code |
| `Cmd+Shift+P` / `Ctrl+Shift+P` | باز کردن پالت فرمان‌ها، جست‌وجوی فرمان‌های Claude |

### قابلیت‌های رایج

1. **توضیح کد**
   - کد را انتخاب کنید
   - راست‌کلیک کنید و «Ask Claude» را انتخاب کنید یا از میان‌بر استفاده کنید
   - پرسش خود را وارد کنید، مثلاً «این کد را توضیح بده»

2. **تولید کد**
   - پنل Claude را باز کنید
   - قابلیتی را که نیاز دارید توصیف کنید
   - Claude کد را همراه با گزینه‌های درج تولید می‌کند

3. **بازآرایی کد**
   - کدی را که باید بازآرایی شود انتخاب کنید
   - از Claude برای بازآرایی کمک بگیرید
   - تغییرات را پیش‌نمایش و اعمال کنید

4. **رفع خطا**
   - وقتی کد خطا دارد
   - کد یا پیام خطا را انتخاب کنید
   - از Claude بخواهید آن را تحلیل کند و راه‌حل ارائه دهد

## گزینه‌های پیکربندی

در تنظیمات VS Code می‌توانید رفتار افزونه Claude Code را پیکربندی کنید:

1. تنظیمات را باز کنید (`Ctrl+,` / `Cmd+,`)

2. عبارت «Claude Code» را جست‌وجو کنید

3. گزینه‌ها را به‌تناسب نیاز تنظیم کنید

### تنظیمات رایج

```json
{
  "claude-code.autoSuggest": true,
  "claude-code.inlineChat": true
}
```

## استفاده همراه با CLI ترمینال

افزونه VS Code و CLI ترمینال را می‌توان با هم استفاده کرد:

| سناریو | ابزار پیشنهادی |
|----------|-----------------|
| ویرایش‌های سریع کد | افزونه VS Code |
| تحلیل پروژه پیچیده | CLI ترمینال |
| بازبینی کد | هر کدام |
| عملیات Git | CLI ترمینال |
| تولید فایل | هر کدام |

## نقاط پایانی سفارشی GitHub Copilot

از VS Code 1.122 به بعد، «Copilot Custom Endpoint» داخلی اجازه می‌دهد پروتکل‌های QCode را مستقیماً به Copilot متصل کنید (Claude فقط از طریق `messages`، مقدار `url` مسیر کامل را می‌گیرد). حداقل پیکربندی:

```json
[
  { "name": "QCode Claude", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "messages",
    "url": "https://api.qcode.cc/api/v1/messages",
    "toolCalling": true,
    "models": [ { "id": "claude-sonnet-5" } ] }
]
```

راه‌اندازی کامل هر سه پروتکل، BYOK در Copilot CLI و محدودیت‌های شناخته‌شده (تکمیل‌های درون‌خطی همچنان از طریق GitHub اجرا می‌شوند) در صفحه اختصاصی آمده است: [یکپارچه‌سازی با GitHub Copilot](/docs/ide/github-copilot).

## عیب‌یابی

### افزونه اجرا نمی‌شود

1. از نصب صحیح Claude Code CLI مطمئن شوید

2. پیکربندی متغیرهای محیطی را بررسی کنید

3. صحت قالب فایل `config.json` را تأیید کنید

### خطای primaryApiKey

1. از درستی مسیر فایل مطمئن شوید:
   - Windows: `C:\Users\YourUsername\.claude\config.json`
   - macOS/Linux: `~/.claude/config.json`

2. مطمئن شوید فایل `config.json` است نه `settings.json`

3. از معتبر بودن قالب JSON مطمئن شوید

### پایان مهلت اتصال

1. اتصال شبکه را بررسی کنید

2. متغیر محیطی `ANTHROPIC_BASE_URL` را بررسی کنید

3. اجرای `claude` در ترمینال را امتحان کنید تا از کارکرد CLI مطمئن شوید

## گام‌های بعدی

- [نکات CLI](/docs/usage/cli-tips) را بررسی کنید تا بهره‌وری را افزایش دهید

- [نکات جریان کار](/docs/usage/workflow-tips) را بیاموزید تا جریان توسعه را بهینه کنید