# تكامل 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). لا يوجد إعلان رسمي عن إعادة تسمية — يبدأ سجل التغييرات ببساطة في استخدام TraeCode في عناوين الإصدارات اعتبارًا من v3.3.84 (2026-08-07). تحتفظ هذه الصفحة باسم ملفها و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، وفي هذه الحالة تشير الوثائق إلى إصدار أقدم من سجل الإصدارات.

#### المسار A: التثبيت من سوق الإضافات المدمج في Trae (موصى به)

1. افتح Trae وانتقل إلى لوحة الإضافات (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. ابحث عن **«Claude Code»** (الناشر: Anthropic)

3. انقر فوق **تثبيت**

إذا لم يعرض سوق Trae لديك Claude Code، فاستخدم المسار B. (لا توثّق الشركة المصنّعة أي عمليات بناء تفتقر إليه، لذلك لا ندّعي أيًا منها.)

#### المسار B: تثبيت محلي دون اتصال من ملف .vsix

استخدم هذا المسار عندما لا يوفر السوق الإضافة:

1. افتح [صفحة إضافة Claude Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)

2. نزّل ملف `.vsix` المطابق لـ **النظام الأساسي والبنية المعمارية** لديك. الطريقة في وثائق Trae نفسها: في صفحة الإضافة افتح **سجل الإصدارات**، وخذ الحقلين `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.

   أو انقر فوق **تنزيل الإضافة** في الشريط الجانبي الأيمن لصفحة الإضافة، إذا كانت صفحتك تعرض ذلك الرابط.

   > **نصيحة**: قد يتطلب الوصول إلى سوق VS Code من الصين القارية استخدام وكيل. إذا فشل التنزيل محليًا، فنزّل ملف `.vsix` على جهاز لديه اتصال دولي موثوق ثم انسخه إلى جهازك.

3. في Trae، افتح لوحة الإضافات → انقر على قائمة **⋯** في أعلى اليمين → **تثبيت من 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**، الموصوف حرفيًا بأنه متوافق مع مواصفات Anthropic `/v1/messages`، والمناسب لسلسلة Claude والخدمات المتوافقة، مع إدراج «بعض خدمات وسيط Claude API» كحالة نموذجية.

| | نموذج مخصص في الذكاء الاصطناعي المدمج | إضافة Claude Code |
|---|---|---|
| البروتوكول | تنسيق API: Anthropic Messages أو OpenAI Chat Completions | Anthropic Messages |
| الموضع | الإعدادات → **النماذج** → **إضافة نموذج** → **نموذج مخصص** | إعدادات الإضافة إلى جانب إعدادات `~/.claude/` |
| URL | وضعان: فعّل **URL كامل** وقدّم العنوان الكامل، أو اتركه معطّلًا وقدّم Base URL يكمله Trae وفقًا لتنسيق API | `ANTHROPIC_BASE_URL` |
| المأخذ | **لا يستدعي الوضع التلقائي النماذج المخصصة أبدًا** (وفقًا للوثائق)، لذا اترك الوضع التلقائي لاستخدام نماذجك | مستقلة عن الذكاء الاصطناعي المدمج؛ ويتعايشان معًا |

مُسقطة على نقاط نهاية 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. أو تواصل مع دعم QCode.cc للحصول على رابط مرآة لملف `.vsix` الخاص بإضافة Claude Code

3. ثبّت عبر «Install from VSIX» بعد توفر الملف محليًا

### لوحة Claude Code فارغة أو لا تبدأ

1. تأكد من وجود `~/.claude/config.json` ومن احتوائه على JSON صالح

2. تأكد من أن اسم الملف هو `config.json` وليس `settings.json` (المأزق الأكثر شيوعًا)

3. تأكد من تعيين متغيري البيئة `ANTHROPIC_BASE_URL` و`ANTHROPIC_AUTH_TOKEN`

4. شغّل `claude` في الطرفية للتحقق من عمل CLI

### تعارضات الاختصارات مع الذكاء الاصطناعي المدمج في Trae

إذا كان `Cmd+Esc` / `Ctrl+Esc` يلتقطه وكيل Trae أو دردشته:

1. افتح إعدادات Trae → اختصارات لوحة المفاتيح

2. ابحث عن `claude-code` أو `Claude Code`

3. أعد ربط «Claude Code: Toggle Panel» بمفتاح غير متعارض

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

1. تحقق من إمكانية الوصول إلى `https://asia.qcode.cc` من شبكتك

2. تحقق من متغير البيئة `ANTHROPIC_BASE_URL`

3. ينبغي لمستخدمي CN على شبكة لا تمر عبر وسيط تفضيل المسار السريع للبر الرئيسي `https://api.qcode.cc/api` (يدعم البحث عن الطلبات عبر [probe.qcode.cc](https://probe.qcode.cc))

## الخطوات التالية

- استكشف [نصائح CLI](/docs/usage/cli-tips) لتعزيز الكفاءة

- تعرّف على [نصائح سير العمل](/docs/usage/workflow-tips) لتحسين سير تطويرك

- راجع [تكامل VS Code](/docs/ide/vscode) إذا كنت تستخدم VS Code أيضًا

- راجع [إعداد المزوّد المخصص في ZCode](/docs/ide/zcode) لوكيل البرمجة من Zhipu، إذ يقبل كل من تطبيقه المكتبي وCLI الخاص به عناوين QCode

- راجع [إعداد Qoder مع QCode](/docs/ide/qoder) للنماذج المخصصة في تطبيق Qoder المكتبي وCLI