# یکپارچه‌سازی Trae

> **آخرین بررسی**: 2026-09-18 · 📄 طبق مستندات رسمی (Trae 3.3.101 (منتشرشده در 2026-09-15))

## مرور کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (افزونه Claude Code؛ هوش مصنوعی داخلی نیز مدل‌های سفارشی با قالب Anthropic Messages را می‌پذیرد) · GPT ✅ · مدل‌های چینی ✅ (هوش مصنوعی داخلی، قالب OpenAI) · Gemini ❌ |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | هوش مصنوعی داخلی: تنظیمات → مدل‌های سفارشی؛ افزونه Claude Code پوشه `~/.claude/` را به اشتراک می‌گذارد |
| مستندات رسمی | [docs.trae.ai](https://docs.trae.ai) |

Trae یک IDE بومی هوش مصنوعی از ByteDance است که از VS Code برگرفته شده است؛ از نسخه v3.3.56 (2026-05-08)، عامل‌های قدیمی Builder آن در Agent ادغام شدند. برای اجرای Claude Code در Trae، افزونه Claude Code را از بازارچه نصب کنید (یا یک `.vsix` سازگار با پلتفرم)، `primaryApiKey` را در `~/.claude/config.json` تنظیم کنید، `ANTHROPIC_BASE_URL` و `ANTHROPIC_AUTH_TOKEN` را به QCode.cc اشاره دهید، سپس Trae را دوباره راه‌اندازی کنید. این صفحه همچنین افزودن QCode.cc به‌عنوان مدل سفارشی هوش مصنوعی داخلی Trae را پوشش می‌دهد.

> **یادداشت نام‌گذاری**: سایت مستندات رسمی (چینی و انگلیسی) در حال حاضر این IDE را **TraeCode** می‌نامد، در حالی که سایت بازاریابی چینی با **TraeWork** (حالت‌های Work / Code / Design) پیش می‌رود. هیچ اعلام رسمی تغییر نام وجود ندارد — فهرست تغییرات به‌سادگی از نسخه v3.3.84 (2026-08-07) استفاده از TraeCode را در عنوان‌های انتشار آغاز می‌کند. این صفحه نام فایل و URL خود را حفظ می‌کند.

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

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

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

2. **Trae یا Trae CN نصب شده و به‌روز است**
   - نسخه بین‌المللی: [trae.ai](https://www.trae.ai/)
   - نسخه چین (Trae CN): [trae.com.cn](https://www.trae.com.cn/)

> **Trae CN یا نسخه بین‌المللی؟** مستندات رسمی هیچ تفاوت منطقه‌ای را توصیف نمی‌کنند. فقط می‌گویند: «اگر افزونه موردنیاز شما در بازارچه افزونه TraeCode موجود نیست، می‌توانید افزونه‌ای را از بازارچه افزونه VS Code در TraeCode نصب کنید.» بنابراین هر مرحله «در بازارچه پیدا نشد» در ادامه شرطی است: اگر بازارچه افزونه را دارد از آن استفاده کنید، در غیر این صورت از یک `.vsix` استفاده کنید.
## مراحل نصب

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

افزونه Claude Code از دو مسیر قابل نصب است — آن‌ها را به‌ترتیب امتحان کنید. به هشدار رسمی نیز توجه کنید: نسخه‌ای از افزونه که به APIهای جدیدتر VS Code وابسته است ممکن است در TraeCode کار نکند؛ در این صورت مستندات شما را به نسخه قدیمی‌تر در Version History ارجاع می‌دهد.

#### مسیر A: نصب از بازارچه افزونه داخلی Trae (توصیه‌شده)

1. Trae را باز کنید و به پنل افزونه‌ها بروید (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. **"Claude Code"** را جست‌وجو کنید (ناشر: Anthropic)

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

اگر بازارچه Trae شما Claude Code را فهرست نمی‌کند، از مسیر B استفاده کنید. (فروشنده مستند نکرده است کدام بیلدها آن را ندارند، بنابراین ما هیچ ادعایی نمی‌کنیم.)

#### مسیر B: نصب محلی آفلاین .vsix

زمانی از این مسیر استفاده کنید که بازارچه افزونه را ارائه نمی‌دهد:

1. [صفحه افزونه Claude Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) را باز کنید.

2. فایل `.vsix` متناسب با **پلتفرم و معماری** خود را دانلود کنید. روشی که در مستندات خود Trae آمده است: در صفحه افزونه **Version History** را باز کنید، فیلدهای `itemName` و `version` را بردارید و URL دانلود را بسازید:

   ```text
   https://marketplace.visualstudio.com/_apis/public/gallery/publishers/<publisher>/vsextensions/<extension>/<version>/vspackage
   ```

   برای Claude Code این است: `publishers/anthropic/vsextensions/claude-code/<version>/vspackage`.
   🔴 **معماری درست را انتخاب کنید**: Claude Code برای هر پلتفرم جداگانه منتشر می‌شود (نام فایل‌ها پسوندهایی مانند `@win32-x64` یا `@alpine-arm64` دارند)، و مستندات Trae صریحاً هشدار می‌دهد که افزونه‌های مخصوص معماری باید برای پلتفرمی که اجرا می‌کنید دانلود شوند. بیلد اشتباه نصب می‌شود و سپس هیچ کاری نمی‌کند. macOS بین Apple Silicon / Intel تفکیک می‌کند؛ Linux و Windows بین x64 / arm64.

   یا اگر صفحه شما آن لینک را نشان می‌دهد، در نوار کناری سمت راست صفحه افزونه روی **Download Extension** کلیک کنید.

   > **نکته**: دسترسی به VS Code Marketplace از سرزمین اصلی چین ممکن است به پروکسی نیاز داشته باشد. اگر دانلود به‌صورت محلی ناموفق بود، فایل `.vsix` را روی ماشینی با اتصال بین‌المللی مطمئن دانلود کنید و آن را کپی کنید.

3. در Trae، پنل افزونه‌ها را باز کنید → روی منوی **⋯** در بالا سمت راست کلیک کنید → **Install from VSIX** را انتخاب کنید و فایل `.vsix` دانلودشده را برگزینید.

   مستندات یک روش دیگر هم ارائه می‌دهد: **فایل `.vsix` دانلودشده را به داخل پنل افزونه‌ها بکشید** و Trae نصب آن را به‌طور خودکار آغاز می‌کند.
   برخی محیط‌ها واقعاً فرمان اجرای `trae` را دارند، اما مستندات Trae هیچ گزینه‌ای برای نصب افزونه با آن ثبت نکرده است و ما آن را آزمایش نکرده‌ایم، بنابراین در اینجا فرمانی چاپ نمی‌کنیم.

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

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

> **خبر خوب**: Trae همان مسیر پیکربندی VS Code را به اشتراک می‌گذارد (`~/.claude/config.json`). کاربرانی که قبلاً VS Code را پیکربندی کرده‌اند نیازی به تکرار این مرحله ندارند.

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

#### Windows

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

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

</div>

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

#### macOS

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

```bash
mkdir -p ~/.claude

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

</div>

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

#### Linux

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

```bash
mkdir -p ~/.claude

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

</div>

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

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

### مرحله 3: راه‌اندازی مجدد Trae

پس از پیکربندی، Trae را راه‌اندازی مجدد کنید تا تغییرات اعمال شوند.
## رابطه با هوش مصنوعی داخلی Trae

هوش مصنوعی داخلی Trae (**Agent** و **Chat**) دیگر محدود به بک‌اند اختصاصی ByteDance نیست. مستندات رسمی بیان می‌کند که علاوه بر مدل‌های داخلی می‌توانید مدل‌های سفارشی اضافه کنید، و نوع **پیکربندی سفارشی** یک **قالب API**، یک **URL درخواست**، یک **شناسه مدل** و اعتبارنامه‌ها می‌خواهد — یکی از قالب‌های API، **Anthropic Messages** است که به‌صورت عیناً به‌عنوان سازگار با مشخصات `/v1/messages` در Anthropic توصیف شده، مناسب برای سری Claude و سرویس‌های سازگار، و «برخی سرویس‌های پراکسی API Claude» به‌عنوان نمونه معمول ذکر شده‌اند.

| | مدل سفارشی در هوش مصنوعی داخلی | افزونه Claude Code |
|---|---|---|
| پروتکل | قالب API: Anthropic Messages یا OpenAI Chat Completions | Anthropic Messages |
| محل | تنظیمات → **مدل‌ها** → **افزودن مدل** → **مدل سفارشی** | تنظیمات افزونه به‌علاوه پیکربندی `~/.claude/` |
| URL | دو حالت: **URL کامل** را روشن کنید و نشانی کامل را وارد کنید، یا آن را خاموش بگذارید و یک Base URL وارد کنید که Trae بر اساس قالب API آن را تکمیل می‌کند | `ANTHROPIC_BASE_URL` |
| نکته مهم | **حالت Auto هرگز مدل‌های سفارشی را فراخوانی نمی‌کند** (مستندات این را بیان می‌کنند)، بنابراین Auto را رها کنید تا از مدل خودتان استفاده کنید | مستقل از هوش مصنوعی داخلی؛ هر دو هم‌زمان وجود دارند |

نگاشت‌شده به نقاط پایانی QCode (**فقط جهت مرجع — ما این را داخل Trae اجرا نکردیم**):

| قالب API | URL کامل روشن | URL کامل خاموش (Base URL) |
|---|---|---|
| Anthropic Messages | `https://api.qcode.cc/api/v1/messages` | `https://api.qcode.cc/api` |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1/chat/completions` | `https://api.qcode.cc/openai/v1` |

از **شناسه مدل** دقیقاً همان‌طور که در [qcode.cc/models](https://qcode.cc/models) فهرست شده استفاده کنید و کلید `cr_` خود را به‌عنوان **کلید API** به کار ببرید.

اگر قبلاً اشتراک QCode.cc را خریده‌اید، توصیه می‌کنیم از افزونه Claude Code به‌عنوان ابزار اصلی خود استفاده کنید تا بیشترین بهره را از پلن خود ببرید.

## استفاده

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

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

### ویژگی‌های رایج

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

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

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

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

در تنظیمات Trae می‌توانید رفتار افزونه Claude Code را تنظیم کنید (این تنظیمات با VS Code یکسان هستند):

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

2. جستجوی «Claude Code»

3. گزینه‌ها را در صورت نیاز تنظیم کنید

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

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

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

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

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

## عیب‌یابی

### Claude Code در مارکت‌پلیس پیدا نمی‌شود

**علائم**: جستجوی «Claude Code» در پنل افزونه‌های Trae نتیجه‌ای برنمی‌گرداند، یا نتایج، افزونه رسمی منتشرشده توسط Anthropic نیستند.

**راه‌حل**: از **مسیر B: نصب محلی .vsix به‌صورت آفلاین** استفاده کنید (به گام 1 بالا مراجعه کنید). موضع فروشنده فقط این است که افزونه‌هایی که در مارکت‌پلیس TraeCode وجود ندارند را می‌توان از مارکت‌پلیس VS Code نصب کرد؛ این را بر اساس بیلدهای چین / بین‌المللی تفکیک نمی‌کند.

### Trae CN نمی‌تواند .vsix را دانلود کند

**علائم**: دسترسی به `marketplace.visualstudio.com` ناموفق است یا دانلود با سرعت 0 B/s انجام می‌شود.

**راه‌حل**:

1. فایل `.vsix` را از طریق یک اتصال بین‌المللی پایدار یا با پروکسی دانلود کنید

2. یا برای دریافت لینک آینه‌ای افزونه Claude Code `.vsix` با پشتیبانی QCode.cc تماس بگیرید

3. پس از در دسترس قرار گرفتن فایل به‌صورت محلی، از طریق «Install from VSIX» نصب کنید

### پنل Claude Code خالی است یا شروع نمی‌شود

1. تأیید کنید که `~/.claude/config.json` وجود دارد و JSON معتبری در خود دارد

2. تأیید کنید که نام فایل `config.json` است، نه `settings.json` (رایج‌ترین اشتباه)

3. تأیید کنید که متغیرهای محیطی `ANTHROPIC_BASE_URL` و `ANTHROPIC_AUTH_TOKEN` تنظیم شده‌اند

4. برای بررسی کارکرد CLI، `claude` را در ترمینال اجرا کنید

### تعارض کلیدهای میان‌بر با هوش مصنوعی داخلی Trae

اگر Agent یا Chat در Trae کلیدهای `Cmd+Esc` / `Ctrl+Esc` را در اختیار بگیرد:

1. تنظیمات Trae → میان‌برهای صفحه‌کلید را باز کنید

2. جستجوی `claude-code` یا `Claude Code`

3. «Claude Code: Toggle Panel» را به کلیدی بدون تعارض اختصاص دهید

### مهلت اتصال

1. بررسی کنید که `https://asia.qcode.cc` از شبکه شما قابل دسترسی باشد

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

3. کاربران چین در شبکه بدون پروکسی بهتر است مسیر سریع سرزمین اصلی `https://api.qcode.cc/api` را ترجیح دهند (از جستجوی درخواست از طریق [probe.qcode.cc](https://probe.qcode.cc) پشتیبانی می‌کند)

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

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

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

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

- برای عامل کدنویسی Zhipu که اپ دسکتاپ و CLI آن هر دو آدرس‌های QCode را می‌پذیرند، [راه‌اندازی ارائه‌دهنده سفارشی ZCode](/docs/ide/zcode) را ببینید

- برای مدل‌های سفارشی در اپ دسکتاپ و CLI Qoder، [راه‌اندازی Qoder با QCode](/docs/ide/qoder) را ببینید