# یکپارچه‌سازی JetBrains IDE

> **آخرین بازبینی**: 2026-09-18 · 📄 طبق مستندات رسمی (افزونه JetBrains برای Claude Code نسخه 0.1.14-beta (Marketplace؛ نیازمند IDE ≥2024.2))

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (افزونه Claude Code، پیکربندی CLI را به اشتراک می‌گذارد) · GPT / مدل‌های چینی ⚠️ بخش مدل‌های سفارشی JetBrains AI Assistant را ببینید (بخش جداگانه) · Gemini ❌ |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` (در محیط CLI `claude` / settings.json تنظیم می‌شود) |
| محل پیکربندی | Settings → Tools → Claude Code [Beta] در IDE؛ در زیر آن، `~/.claude/` را به اشتراک می‌گذارد |
| مستندات رسمی | [code.claude.com/docs/en/jetbrains](https://code.claude.com/docs/en/jetbrains) |

Claude Code یک افزونه رسمی JetBrains ارائه می‌دهد. مستندات شش IDE را نام می‌برند (شامل Android Studio که به Ladybug 2024.2.1 یا جدیدتر نیاز دارد؛ JetBrains MPS به‌طور جداگانه به 2024.3+ نیاز دارد)، و فهرست سازگاری Marketplace شامل RubyMine، CLion، Rider، DataGrip و سایر IDEهای مبتنی بر IntelliJ می‌شود — بنابراین ما وعده «هر IDE مبتنی بر IntelliJ» را نمی‌دهیم: پیش از نصب، صفحه افزونه را در IDE خودتان بررسی کنید. این راهنما نشان می‌دهد چگونه افزونه را نصب کنید و آن را به دروازه QCode متصل کنید تا بتوانید مدل‌های شاخصی مانند Claude Opus 5 و Sonnet 5 را با هزینه کمتر فراخوانی کنید.

افزونه همان پیکربندی نسخه خط فرمان را به اشتراک می‌گذارد: تا زمانی که CLI `claude` شما بتواند به QCode دسترسی داشته باشد، افزونه IDE نیز کار می‌کند.

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

1. **CLI Claude Code نصب شده و کار می‌کند** (با `claude --version` تأیید کنید؛ عدد قدیمی این صفحه را مبنا نگیرید)
   - برای تکمیل نصب، [راهنمای نصب](/docs/getting-started/installation) را دنبال کنید
   - برای پیکربندی API QCode، راهنمای [متغیرهای محیطی](/docs/getting-started/environment) را دنبال کنید
   - برای تأیید کارکرد، `claude --version` را در ترمینال اجرا کنید

2. **JetBrains IDE نسخه 2024.2 یا جدیدتر** (ورودی Marketplace حداقل بیلد `242.0` یعنی 2024.2 را ذکر می‌کند؛ در 2024.1 افزونه ناسازگار نمایش داده می‌شود)

3. **یک کلید API QCode** (با `cr_` شروع می‌شود) — همان کلید برای همه نقاط پایانی کار می‌کند

## مراحل نصب

### گام 1: نصب افزونه Claude Code

1. IDE JetBrains خود را باز کنید

2. به **Settings / Preferences** → **Plugins** → **Marketplace** بروید

3. جست‌وجوی **Claude Code [Beta]** — این نام واقعی آن در Marketplace است (ناشر **Anthropic PBC**، xmlId `com.anthropic.code.plugin`). ⚠️ جست‌وجوی صرف «Claude Code» چندین افزونه مشابه شخص ثالث و نامرتبط را ابتدا نشان می‌دهد؛ آن را که Anthropic PBC منتشر کرده نصب کنید

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

5. IDE را دوباره راه‌اندازی کنید

> نکته: اگر شبکه شما نمی‌تواند مستقیماً به JetBrains Marketplace دسترسی داشته باشد، بسته `.zip` را از صفحه اصلی افزونه دانلود کنید و آن را به‌صورت آفلاین از طریق **Plugins** → آیکون چرخ‌دنده → **Install Plugin from Disk...** نصب کنید. برای جزئیات به مستندات رسمی JetBrains مراجعه کنید.

### گام 2: پیکربندی دسترسی به QCode

افزونه پیکربندی CLI Claude Code را دوباره استفاده می‌کند. هسته آن دو متغیر محیطی است:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
```

> **کاربران در سرزمین اصلی چین**: جایگزینی `api.qcode.cc` با `asia.qcode.cc` معمولاً انتخاب بهتری است:
>
> ```bash
> export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
> ```
>
> سه دامنه `api` / `asia` / `us` از یک کلید API مشترک استفاده می‌کنند، بنابراین هر کدام که برای منطقه شما بهتر است را انتخاب کنید. `BASE_URL` نباید **اسلش انتهایی** داشته باشد.

> **نکته**: IDEهای JetBrains متغیرهای محیطی سیستم را به ارث می‌برند. اگر آن‌ها را قبلاً در `~/.zshrc` یا `~/.bashrc` پیکربندی کرده‌اید، IDE هنگام راه‌اندازی آن‌ها را برمی‌دارد — به شرطی که IDE از محیطی راه‌اندازی شود که آن پیکربندی در آن بارگذاری شده باشد (به پرسش‌های متداول زیر مراجعه کنید).

اگر ترجیح می‌دهید به متغیرهای محیطی سراسری تکیه نکنید، می‌توانید آن‌ها را به‌ازای هر پروژه تنظیم کنید (به [پرسش‌های متداول](#environment-variables-not-taking-effect) مراجعه کنید).

### گام 3: تأیید

1. در IDE، `Cmd+Esc` (macOS) یا `Ctrl+Esc` (Windows/Linux) را برای باز کردن پنل Claude Code فشار دهید

2. یک پیام ساده (مثلاً «hello») برای آزمایش اتصال تایپ کنید

3. اگر پاسخ عادی دریافت کردید، افزونه با موفقیت از طریق QCode متصل شده است

همچنین می‌توانید با `curl` بررسی کنید که خود دروازه قابل دسترسی است (`401` یعنی مسیر درست است و فقط احراز هویت وجود ندارد که انتظار می‌رود):

```bash
curl -i https://api.qcode.cc/api/v1/messages
# HTTP/2 401  ← path is correct, as expected
```
## نحوه استفاده

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

| میان‌بر | کارکرد |
|----------|----------|
| `Cmd+Esc` / `Ctrl+Esc` | باز و بستن پنل Claude Code |
| `Cmd+Option+K` / `Ctrl+Alt+K` | درج ارجاع به فایل جاری (@file) در prompt |
| `Esc` | قطع تولید فعلی |

> میان‌برهای واقعی به نسخه افزونه و keymap شما بستگی دارد؛ برای سفارشی‌سازی، در **Settings** → **Keymap** عبارت «Claude» را جست‌وجو کنید.

### قابلیت‌های اصلی

1. **توضیح کد**: کد را انتخاب کنید → راست‌کلیک کنید → **Ask Claude** را بزنید تا منطق آن را توضیح دهد

2. **تولید کد**: نیازمندی‌های خود را به زبان ساده در پنل Claude توصیف کنید و بگذارید کد را تولید یا تغییر دهد

3. **رفع خطا**: یک stack trace یا پیام خطا را برای تحلیل و رفع به Claude بفرستید

4. **بازآرایی کد**: کد هدف را انتخاب کنید و از Claude بخواهید ساختار آن را بهبود دهد، توابع را استخراج کند یا تست اضافه کند

### نمای diff بومی

افزونه به‌طور عمیق با JetBrains یکپارچه شده است: وقتی Claude تغییرات فایل را پیشنهاد می‌دهد، آن‌ها در **نمای diff کنار‌به‌کنار بومی** IDE نمایش داده می‌شوند تا بتوانید هر تغییر را بررسی کنید، آن را بپذیرید یا رد کنید و سپس روی دیسک بنویسید. این روش از یک diff ساده در ترمینال شفاف‌تر و ایمن‌تر است.

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

ترمینال داخلی IDEهای JetBrains می‌تواند دستور `claude` را نیز مستقیماً اجرا کند و تجربه کامل CLI را فراهم آورد. افزونه به‌طور خودکار فایل باز فعلی و انتخاب شما را به‌عنوان زمینه به CLI می‌فرستد، بنابراین این دو در کنار هم بهترین کارایی را دارند.

### ورودی تصویر (بینایی)

مدل‌های دارای قابلیت بینایی (Claude Opus 5 / Sonnet 5 و خانواده GPT-5.x) می‌توانند تصاویر را به‌عنوان ورودی **بخوانند**:

- یک اسکرین‌شات را مستقیماً (`Ctrl+V`) در پنل Claude بچسبانید
- یک فایل تصویر را به داخل کادر چت بکشید و رها کنید
- در prompt خود به مسیر یک فایل تصویر ارجاع دهید

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

> این **ورودی تصویر** است، نه تولید تصویر. برای اینکه مدلی تصویر **تولید** کند، از مدل `gpt-image-2` استفاده کنید — به [تولید تصویر gpt-image-2](/docs/usage/image-2) مراجعه کنید.

### انتخاب مدل

در پنل Claude می‌توانید با دستور `/model` مدل را عوض کنید؛ همه مدل‌ها از طریق همان کلید QCode فراخوانی می‌شوند. گزینه‌های رایج:

| مدل | پنجره زمینه | مناسب برای |
|------|--------|----------|
| `claude-opus-5` | 1M | پرچم‌دار، بازآرایی پیچیده و استدلال معماری |
| `claude-opus-4-7` | 1M | جایگزین پرچم‌دار |
| `claude-sonnet-5` | 1M | کدنویسی روزمره، ارزش متعادل |
| `claude-haiku-5-5` | 1M | کارهای سبک، پرسش و پاسخ سریع |

قیمت‌ها در این صفحه کپی نشده‌اند — از ارقام به‌روز [qcode.cc/models](https://qcode.cc/models) استفاده کنید (مدیران می‌توانند نرخ‌ها را تغییر دهند).

> QCode از مدل‌های GPT نیز پشتیبانی می‌کند (مانند `gpt-6-sol` و `gpt-5.6-terra`؛ در حال حاضر Gemini را ارائه نمی‌دهد)، اما افزونه Claude Code برای JetBrains بر پروتکل Anthropic تمرکز دارد؛ GPT بهتر است در ابزار خودش مانند Codex استفاده شود. قیمت واحد همان است که [qcode.cc/models](https://qcode.cc/models) نشان می‌دهد. شناسه‌های 4.x مانند `claude-sonnet-4-6` و `claude-opus-4-8` همچنان به فروش می‌رسند.

### استفاده پیشرفته

- **گردش‌کارهای پویا**: کلیدواژه **`ultracode`** را در prompt خود بگنجانید (یا فقط بخواهید «یک workflow اجرا شود») تا برای کارهای بزرگ (بازبینی کد در کل مخزن، مهاجرت انبوه، پژوهش میان‌فایلی و غیره) ده‌ها تا صدها زیرعامل پس‌زمینه را به‌صورت موازی هماهنگ کنید. زیرعامل‌ها در پس‌زمینه اجرا می‌شوند و شما به کار خود ادامه می‌دهید؛ پیشرفت را با دستور `/workflows` بررسی کنید. این قابلیت روی هر مدلی که Claude Code با آن پیکربندی شده باشد اجرا می‌شود — پس هنگام اتصال به QCode نیز کار می‌کند. به [زیرعامل‌ها](/docs/advanced/subagents) مراجعه کنید.

- **اجرای بدون رابط / خودکارسازی**: در ترمینال IDE می‌توانید برای فراخوانی‌های اسکریپتی از `claude -p "<prompt>"` همراه با `--output-format json|text|stream-json` استفاده کنید. `json` یک شیء ساخت‌یافته شامل `result`، `total_cost_usd`، `usage` و `session_id` برمی‌گرداند که تجزیه آن با `jq` آسان است. به [خودکارسازی و CI/CD](/docs/advanced/headless) مراجعه کنید.
## افزونه صفحه تنظیمات اختصاصی خود را دارد

به‌صورت رسمی: **Settings → Tools → Claude Code [Beta]**. موارد مستندشده عبارت‌اند از:

- **Claude command** — دستوری که افزونه برای اجرای Claude Code به کار می‌برد، مثلاً `claude`،
  `/usr/local/bin/claude`، `npx @anthropic-ai/claude-code`. **وقتی IDE نمی‌تواند `claude` را پیدا کند، راه‌حل رسمی قرار دادن یک مسیر مطلق در اینجاست**، نه تغییر روش اجرای شل
- **Suppress notification for when Claude Command is not found** — خاموش کردن اعلان «command not found»
- **Enable using Option+Enter for multi-line prompts** — فقط macOS
- **Enable automatic updates** — بررسی و نصب به‌روزرسانی‌های افزونه، که پس از راه‌اندازی مجدد اعمال می‌شود

## اتصال یک ترمینال خارجی: `/ide`

بر اساس مستندات رسمی، اجرای `/ide` در Claude Code در هر ترمینال خارجی، آن را به IDE در حال اجرای JetBrains متصل می‌کند و همه امکانات را فعال می‌سازد. در صورت موفقیت، Claude Code پاسخی مانند
`Connected to IntelliJ IDEA.` می‌دهد؛ اگر IDE‌ای بدون افزونه تشخیص داده شود، `/ide` افزونه را نصب می‌کند و
از شما می‌خواهد برنامه را دوباره راه‌اندازی کنید. با QCode نیز همین‌گونه کار می‌کند — فرمان `claude` خارجی از
همان `ANTHROPIC_BASE_URL` که قبلاً پیکربندی کرده‌اید استفاده می‌کند.

## JetBrains Remote Development: نصب روی میزبان

مستندات صریح است: در JetBrains Remote Development افزونه باید **روی میزبان راه‌دور**
و از طریق **Settings → Plugins → Plugin (Host)** نصب شود. نصب آن روی کلاینت محلی هیچ کاری نمی‌کند.

## AI Assistant محصول دیگری است

این صفحه درباره **افزونه Claude Code** است که CLI `claude` خودتان را از طریق پروتکل Anthropic و با
Base URL گرفته‌شده از یک متغیر محیطی هدایت می‌کند. **AI Assistant** در JetBrains هم می‌تواند از
مدل‌های شخص ثالث استفاده کند، اما از مسیر دیگری: **Settings | Tools | AI Assistant | Providers & API
keys**؛ و بر اساس مستندات رسمی **تنها نوع «OpenAI-compatible» فیلد URL دارد** —
انواع کلید API مربوط به Anthropic و Gemini فقط فیلد کلید دارند.

| مسیر | پروتکل | آدرس سفارشی؟ | چه چیزی از QCode می‌تواند در آنجا ارائه شود |
|---|---|---|---|
| افزونه Claude Code (همین صفحه) | Anthropic Messages | بله، `ANTHROPIC_BASE_URL` = `https://api.qcode.cc/api` | مدل‌های Claude و خانواده‌های چینی (نقطه پایانی Anthropic) |
| AI Assistant → OpenAI-compatible | OpenAI Chat Completions | بله، فیلد URL وجود دارد | مدل‌های GPT و خانواده‌های چینی (`https://api.qcode.cc/openai/v1`) |
| AI Assistant → Anthropic / Gemini | بومی | **فیلد آدرس در مستندات وجود ندارد**، فقط کلید ارائه‌دهنده | نمی‌توان آن را به QCode متصل کرد |

تکمیل خودکار AI در AI Assistant (تکمیل درون‌خطی / ویرایش بعدی) نیز به همین ترتیب فقط نقطه پایانی
«OpenAI Compatible» را می‌پذیرد، و مستندات هشدار می‌دهد که تکمیل درون‌خطی به پشتیبانی Fill-in-the-Middle نیاز دارد
که مدل‌های چت عمومی معمولاً از آن بی‌بهره‌اند.
## پرسش‌های متداول

### پنل Claude Code نمایش داده نمی‌شود؟

1. تأیید کنید که افزونه نصب و فعال شده است (**Settings** → **Plugins** → **Installed**)

2. تأیید کنید که Claude Code CLI به‌صورت سراسری نصب شده است: در ترمینال دستور `claude --version` را اجرا کنید — باید شماره نسخه را چاپ کند (به [انتشارهای رسمی](https://github.com/anthropics/claude-code/releases) مراجعه کنید)

3. تأیید کنید که نسخه IDE ≥ 2024.2 است

4. IDE را دوباره راه‌اندازی کنید؛ در صورت نیاز **File** → **Invalidate Caches / Restart** را اجرا کنید

### `Esc` تولید فعلی را متوقف نمی‌کند؟

مورد رسمی عیب‌یابی: در ترمینال‌های JetBrains، کلید `Esc` توسط IDE برای انتقال فوکوس به ویرایشگر گرفته می‌شود. آن را در **Settings → Tools → Terminal** اصلاح کنید — یا تیک **"Move focus to the editor with Escape"** را بردارید، یا روی **"Configure terminal keybindings"** کلیک کنید و میان‌بر "Switch focus to Editor" را حذف کنید.

### متغیرهای محیطی اعمال نمی‌شوند؟

IDEهای JetBrains ممکن است متغیرهای محیطی را از فایل‌های پیکربندی شل شما دریافت نکنند (فرایندهایی که از طریق GUI اجرا می‌شوند اغلب `~/.zshrc` را بارگذاری نمی‌کنند). راه‌حل‌ها:

- **macOS**: IDE را به‌جای کلیک روی آیکون Dock از ترمینال اجرا کنید (مثلاً `open -a "IntelliJ IDEA"`)؛ یا از **Tools** → **Create Command-line Launcher** استفاده کنید و آن را از ترمینال شروع کنید

- **همه پلتفرم‌ها**: `ANTHROPIC_BASE_URL` و `ANTHROPIC_AUTH_TOKEN` را به‌صورت دستی در **Run/Debug Configurations** → **Environment variables** اضافه کنید

- **ماندگاری**: آن‌ها را از طریق JetBrains Toolbox، `*.vmoptions` یا متغیرهای محیطی سطح سیستم تنظیم کنید تا در هر اجرا خوانده شوند

### خطای احراز هویت / 401 / 403؟

1. بررسی کنید که `ANTHROPIC_AUTH_TOKEN` یک کلید معتبر QCode است که با `cr_` شروع می‌شود و فاصله یا گیومه اضافی ندارد

2. تأیید کنید که `ANTHROPIC_BASE_URL` **هیچ** اسلش انتهایی ندارد و مسیر آن `/api` است (پروتکل Anthropic)

3. دستور `curl -i https://api.qcode.cc/api/v1/messages` را اجرا کنید: کد `401` یعنی دروازه در دسترس است (فقط احراز هویت وجود ندارد)؛ خطای اتصال نشان‌دهنده مشکل شبکه/پروکسی است

### پایان مهلت اتصال / مسدود بودن پشت پروکسی شرکتی؟

- کاربران در سرزمین اصلی چین باید ابتدا به `asia.qcode.cc` تغییر دهند

- اگر پشت پروکسی شرکتی هستید، مطمئن شوید که مسیر **Settings** → **Appearance & Behavior** → **System Settings** → **HTTP Proxy** در IDE به‌درستی پیکربندی شده است، یا متغیر محیطی `HTTPS_PROXY` را برای ترمینال تنظیم کنید

- تأیید کنید که فایروال شما دسترسی خروجی فرایند IDE به `*.qcode.cc:443` را مجاز می‌کند

### متغیرهای محیطی را تغییر داده‌اید اما IDE متوجه نمی‌شود؟

متغیرهای محیطی فقط یک‌بار در زمان شروع فرایند خوانده می‌شوند. پس از ویرایش `~/.zshrc` یا متغیرهای سیستم، باید **به‌طور کامل از IDE خارج شوید و آن را دوباره راه‌اندازی کنید** (نه فقط پنجره را دوباره باز کنید) تا تغییرات اعمال شوند.

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

- برای مشاهده سه دامنه و Base URL هر پروتکل، [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) را ببینید

- برای افزونه VS Code، [یکپارچه‌سازی با VS Code](/docs/ide/vscode) را ببینید

- برای یک افزونه هوش مصنوعی دیگر برای VS Code، [یکپارچه‌سازی با Cline](/docs/ide/cline) را ببینید

- برای نکات استفاده از ترمینال، [نکات CLI](/docs/usage/cli-tips) را ببینید

> نمی‌دانید کدام مدل برای اجرا در JetBrains به‌صرفه‌ترین است؟ [صفحه قیمت‌گذاری QCode](https://qcode.cc/pricing) را ببینید و بر اساس بودجه خود Opus / Sonnet / Haiku را انتخاب کنید.