# إعداد محرر Zed

> **آخر تحقق**: 2026-11-09 · 📄 وفقًا للوثائق الرسمية (Zed stable v1.27.0، صدر في 2026-11-04؛ إدخالات ACP والمزوّد المذكورة أدناه مأخوذة من ملاحظات الإصدار 1.21.0 إلى 1.25.2؛ صدر 1.25.2 في 2026-10-21)

## نظرة سريعة

| العنصر | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (المسار A: ACP / المسار B: مزوّد متوافق مع Anthropic) · GPT ✅ (مزوّد متوافق مع OpenAI) · النماذج الصينية ✅ (كلا المسارين المتوافقين مع Anthropic) · Gemini ❌ (لا يوفّر QCode نماذج Gemini حاليًا) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` (يضيف Zed المسار `/v1/messages`، ولا يوجد `/v1` هنا) · OpenAI: `https://api.qcode.cc/openai/v1` (يضيف `/chat/completions`) |
| مكان التكوين | `~/.config/zed/settings.json` (macOS / Linux؛ Windows `%APPDATA%/Zed/settings.json`؛ تُطبَّق التعديلات دون إعادة تشغيل) |
| الوثائق الرسمية | [استخدام الوصول إلى API](https://zed.dev/docs/ai/use-api-access) · [تكوين Zed](https://zed.dev/docs/configuring-zed)

[Zed](https://zed.dev) محرر أكواد حديث عالي الأداء مكتوب بلغة Rust، ويدعم أصليًا منذ الربع الأول من 2026 [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol) — معيار مفتوح يفصل اتصال IDE بالوكيل الذكي، على غرار ما فعله LSP لخوادم اللغات. يدمج Zed وكيل Claude Agent (غلاف Claude Agent SDK المسمّى `claude-agent-acp`) عبر ACP، ويعرض لوحة وكيل لتنسيق مهام البرمجة متعددة الخطوات. يوضّح هذا الدليل كيفية تكوين QCode.cc كنقطة نهاية API لـ Claude Code داخل Zed، وكيفية إضافة QCode مباشرةً كمزوّد متوافق مع Anthropic / OpenAI في `settings.json` الخاص بـ Zed.

يستخدم QCode مفتاح API واحدًا في كل مكان (يبدأ بـ `cr_`). ويدعم المفتاح نفسه بروتوكولات Anthropic وOpenAI Chat وOpenAI Responses والصور، ويُقابَل بثلاثة نطاقات دخول — `api` / `asia` / `us` (ينبغي لمستخدمي البر الرئيسي للصين تفضيل `asia.qcode.cc`).

## لماذا تستخدم Zed

- **تكامل ACP أصلي**: افتح جلسات Claude Code داخل لوحة الوكيل وراقب استدلال الوكيل واستدعاءات الأدوات مباشرةً في المحرر
- **سياق 1M**: يدعم وضع BYOK نافذة السياق الكاملة البالغة 1M token من Opus 5 / 4.8 / 4.7
- **أداء Rust**: بدء بارد فائق السرعة وبصمة ذاكرة أقل بمقدار رتبة عشرية كاملة من محررات VS Code / المحررات المبنية على Electron
- **تخطيط متعدد الأجزاء**: المحرر + الطرفية + لوحة الوكيل جنبًا إلى جنب لسير عمل مُدمج
- **مسارا تكامل**: شغّل عبر Claude Code CLI (سطح الأدوات الكامل)، أو أضف QCode بصفته مزوّدًا مدمجًا في `settings.json`
## مقارنة مساري التكامل

يوفّر Zed مسارين متكاملين للوصول إلى QCode — اختر ما يناسب احتياجاتك:

| المسار | الوصف | الأنسب لـ |
|------|-------------|----------|
| **A. ACP / Claude Agent** (موصى به) | تُحمّل لوحة الوكيل Claude Agent عبر ACP، مع إعادة استخدام إعدادات متغيرات البيئة الخاصة بـ CLI | الرغبة في الخطافات / المهارات / MCP كاملة، ومشاركة الإعدادات مع سير عمل الطرفية |
| **B. مزوّد settings.json** | إدخال Base URL + المفتاح مباشرةً في إعدادات Zed، باستخدام عميل HTTP المدمج في Zed | عدم الرغبة في تثبيت CLI؛ مساعد داخل IDE بحت / إكمال مضمّن |

يغطي قسم «خطوات الإعداد» أدناه المسار A؛ ويغطي «تكوين مزوّد في settings.json» المسار B.

## المتطلبات المسبقة

- [Zed](https://zed.dev/download) مثبّت (macOS / Linux)
- [Claude Code CLI](/docs/getting-started/installation) مثبّت (يعتمد تكامل ACP في Zed على CLI كواجهة خلفية؛ تجاوز هذا إذا كنت تستخدم المسار B فقط)
- مفتاح API من QCode.cc (يبدأ بـ `cr_`)، متاح من [لوحة التحكم](https://qcode.cc/dashboard)
- Claude Code CLI مُهيّأ مسبقًا بمتغيرات بيئة QCode (وفق [البدء السريع](/docs/getting-started/quick-start))

## خطوات الإعداد (المسار A: ACP / Claude Code)

### الخطوة 1: تحقق من عمل Claude Code CLI في الطرفية

يشغّل Zed ACP عبر إنشاء عملية `claude`، لذا تحقق أولًا من عمل CLI في الطرفية:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # should print a version number (trust this machine + official Releases)
echo "ping" | claude   # simple echo test
```

> يجب أن **لا** يحتوي `ANTHROPIC_BASE_URL` على شرطة مائلة زائدة في النهاية؛ إذ يضيف Anthropic SDK المسار `/v1/messages` بنفسه. احفظ هذين المتغيرين البيئيين في ملف إعداد الصدفة لديك (`~/.zshrc` / `~/.bashrc`) حتى يرثهما Zed عند بدء التشغيل.

### الخطوة 2: افتح لوحة الوكيل في Zed

- macOS: `Cmd + ?`
- Linux: `Ctrl + ?`

عند فتح اللوحة للمرة الأولى، يطلب منك Zed اختيار مزوّد وكيل — اختر **Claude Code** (لا تختر BYOK Anthropic API؛ إذ يتجاوز ذلك المسار CLI ويتطلب منك إدخال Base URL بشكل منفصل في إعدادات Zed — راجع المسار B).

### الخطوة 3: تحقق من جلسة الوكيل

اكتب في حقل إدخال لوحة الوكيل: «اسرد الرموز المصدّرة في الملف الحالي.» يمرّر Zed الملف المفتوح حاليًا كسياق إلى Claude Code، ويستدعي الوكيل أداتي `read` / `grep` لتحليل المحتوى والرد.

إذا فشلت عملية الوكيل في البدء، فيمكن تثبيت أمر وكيل ACP صراحةً عبر `agent_servers.<name>.command / args / env` في `settings.json` (لا يوجد مفتاح إعداد `agent.path`). الأسماء والحقول: اتبع الوثائق الرسمية.

> تتطور إعدادات الوكيل / المساعد في Zed بسرعة بين الإصدارات؛ وللحصول على أسماء المفاتيح الدقيقة، راجع [الوثائق الرسمية لـ Zed](https://zed.dev/docs/ai/overview).
## إعداد مزوّد في settings.json (المسار B)

إذا كنت تفضّل عدم تثبيت CLI، فأضف QCode في `settings.json` — يُفتح ملف JSON نفسه عبر `Cmd+Alt+,` (`Ctrl+Alt+,` على Linux؛ `Cmd+,` يفتح واجهة محرر الإعدادات)؛ ويقع في `~/.config/zed/settings.json` (في Windows: `%APPDATA%/Zed/settings.json`) ويُطبَّق دون إعادة تشغيل. بالنسبة إلى البوابات الخارجية، الإدخالات الموصى بها رسميًا هي المزوّدات المخصصة **`anthropic_compatible` / `openai_compatible`**. يتحدث QCode بالبروتوكولين مع **المفتاح `cr_` نفسه**.

### مزوّد متوافق مع Anthropic

وجّه عنوان قاعدة مزوّد Anthropic المضمّن في Zed إلى نقطة نهاية Anthropic لدى QCode:

```json
{
  "language_models": {
    "anthropic_compatible": {
      "QCode": {
        "api_url": "https://api.qcode.cc/api"
      }
    }
  }
}
```

وفّر المفتاح عبر متغيّر بيئة (يرثه Zed عند بدء التشغيل):

```bash
export QCODE_API_KEY="cr_xxxxxxxx"
```

> يوجد أيضًا الإدخال المضمّن `language_models.anthropic.api_url` ويعمل، لكن نقطة الإدخال الموثّقة في Zed للبوابات الخارجية هي مزوّد `anthropic_compatible` الموضح أعلاه. ينتهي Base URL عند `/api` — **دون `/v1`** — ويضيف Zed المسار `/v1/messages` بنفسه. لا تضع مفاتيح API في `settings.json` (قاعدة رسمية)؛ استخدم المتغيّر المُولَّد `<PROVIDER_NAME>_API_KEY`.

### مزوّد متوافق مع OpenAI

يدعم Zed أيضًا مزوّدًا متوافقًا مع OpenAI، يمكنه الوصول إلى نماذج عائلة GPT لدى QCode. وجّه القاعدة إلى نقطة نهاية OpenAI Chat لدى QCode:

```json
{
  "language_models": {
    "openai_compatible": {
      "QCodeOpenAI": {
        "api_url": "https://api.qcode.cc/openai/v1",
        "available_models": [
          { "name": "gpt-5.6-terra" },
          { "name": "gpt-5.6-sol" },
          { "name": "glm-5.3" },
          { "name": "deepseek-v4-flash" }
        ]
      }
    }
  }
}
```

يأتي المفتاح أيضًا من متغيّر بيئة:

```bash
export QCODEOPENAI_API_KEY="cr_xxxxxxxx"
```

> قاعدة OpenAI Chat هي `https://api.qcode.cc/openai/v1` (ثم يضيف SDK المسار `/chat/completions`). دون شرطة مائلة في النهاية. يجب أن تتبع أسماء الحقول في `available_models` (`name` / `max_tokens`، إلخ) وثائق Zed الرسمية.

### تغييرات منذ 1.20.2 تؤثر في هذه الإعدادات (2026-10-26)

أصبح الإصدار المستقر من Zed الآن 1.27.0 (صدر في 2026-11-04)؛ وصدر 1.25.2 في 2026-10-21. تمسّ بنود ملاحظات الإصدار هذه مسارات ACP والمزوّد أعلاه (مقتبسة حرفيًا):

- **1.21.0** — «تحسين توافق ACP ومعالجة إيقاظ المهام غير المتزامنة.» و«إضافة دعم BYOK لـ Claude Opus 5.5 باستخدام مفتاح API من Anthropic.»
- **1.23.2** — «تحسين تحديثات الخطة من وكلاء ACP، بما في ذلك تحديثات اللوحة بعد تغييرات الحالة.» وإعداد `agent.max_idle_retained_threads`.
- **1.24.2** — «تحسين دعم نماذج Amazon Bedrock المخصصة مع إمكانية تهيئة استخدام الأدوات والصور والتفكير.» (توجيه Bedrock؛ يُهيَّأ QCode عبر المزوّدات المتوافقة أعلاه.)
- **1.25.2** — «تفعيل إشعارات الجلسة وضغط السياق للوكلاء الخارجيين الذين يستخدمون ACP.» بالإضافة إلى إضافات نماذج Bedrock.

مفاتيح الإعدادات المستخدمة أعلاه دون تغيير في الوثائق الرسمية التي جرى التحقق منها في 2026-10-26: `language_models.anthropic_compatible` / `openai_compatible`، و`api_url`، و`available_models`، والمتغيّر المُولَّد `<PROVIDER_NAME>_API_KEY`.
## اختيار النموذج

يتيح مفتاح QCode نفسه نماذج من عدة مزوّدين. بدّل بينها حسب الحاجة من القائمة المنسدلة للنموذج في لوحة الوكيل أو المساعد:

> **أي بروتوكول**: يعمل `claude-*` فقط على مزوّد Anthropic (`https://api.qcode.cc/api`)؛ ويعمل `gpt-*` فقط على مزوّد OpenAI (`https://api.qcode.cc/openai/v1`). خلطها يعيد `model_not_available_on_endpoint`.

| النموذج | يُستخدم في |
|-------|---------|
| `claude-opus-5` | الطراز الرائد — استدلال معقّد وإعادة هيكلة واسعة |
| `claude-opus-4-7` | بديل للطراز الرائد |
| `claude-sonnet-5` | الأداة اليومية الأساسية للبرمجة، بقيمة ممتازة |
| `claude-haiku-5-5` | إكمال سريع، ومهام خفيفة |
| `gpt-6-sol` | الطراز الرائد من GPT |
| `gpt-5.6-terra` | متخصص في البرمجة |

> الجدول أعلاه هو التوصية الحالية. لا تزال المعرّفات 4.x مثل `claude-sonnet-4-6` و`claude-opus-4-8` و`claude-opus-4-7` متاحة للبيع؛ والقائمة المباشرة على [qcode.cc/models](https://qcode.cc/models).

- في المسار A (Claude Code)، يتحدد النموذج من إعدادات Claude Code الخاصة به (بدّل باستخدام `/model` أو عيّن `ANTHROPIC_MODEL`).
- في المسار B مع مزوّد Anthropic، استخدم معرّفات نماذج `claude-*`؛ ومع مزوّد OpenAI، استخدم معرّفات نماذج `gpt-*`.
- بروتوكول الصور (`gpt-image-2`) ليس بالضرورة متاحًا بشكل أصلي في مساعد Zed؛ استدعِه مباشرة من CLI / النصوص البرمجية — راجع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) و[توليد الصور باستخدام gpt-image-2](/docs/usage/image-2).

## أمثلة على الاستخدام

### لوحة الوكيل: المهام العابرة للملفات

تتفوق لوحة الوكيل في المهام متعددة الخطوات والعابرة للملفات. على سبيل المثال:

> «حوّل كل الإدخال/الإخراج المتزامن ضمن `utils/` إلى غير متزامن وحدّث المستدعين.»

سيستخدم الوكيل `grep` لتحديد المواقع، و`read` للفحص، و`edit` للتعديل، ويعرض الفروقات خطوة بخطوة في المحرر لتتمكن من قبول / رفض كل منها.

### تغذية الوكيل بلقطات الشاشة (إدخال بصري)

يدعم Claude Opus 5 / Sonnet 5 وGPT-5.x الرؤية جميعها. يمكنك تمرير نماذج واجهة المستخدم، أو لقطات شاشة الأخطاء، أو مخططات البنية إلى الوكيل بوصفها **إدخالًا**:

- الصق صورة (`Ctrl+V`) أو اسحبها وأفلتها في إدخال لوحة الوكيل
- أو أشر إلى مسار ملف صورة محلي في prompt

حالات الاستخدام النموذجية: بناء واجهة مستخدم من نموذج تصميم، وتصحيح الأخطاء من لقطة شاشة خطأ، وقراءة مخططات البنية / الرسوم البيانية.

> ملاحظة: يتعلق هذا بـ**تغذية** النموذج بالصور (إدخال بصري)، وليس بـ**توليد** الصور. لتوليد الصور استخدم `gpt-image-2` — راجع [توليد الصور باستخدام gpt-image-2](/docs/usage/image-2).

### Dynamic Workflows (تنسيق الوكلاء الفرعيين في الخلفية)

يدعم Claude Code ميزة Dynamic Workflows: تنسيق عشرات إلى مئات من الوكلاء الفرعيين في الخلفية، وهو مثالي لمهام المراجعة والترحيل والبحث على مستوى قاعدة الشيفرة. شغّله بتضمين الكلمة المفتاحية `ultracode` في prompt أو ببساطة بطلب «تشغيل سير عمل»؛ واعرض عمليات التشغيل النشطة بالأمر `/workflows`. يستمر الوكلاء الفرعيون في العمل في الخلفية بينما تواصل عملك الآخر. يعمل على أي نموذج تمت تهيئة Claude Code به — لذا يعمل عندما يشير Claude Code إلى QCode. قراءة إضافية: [الوكلاء الفرعيون](/docs/advanced/subagents).

### تنسيقات الإخراج في الوضع بلا واجهة / الأتمتة

عند استدعاء Claude Code في CI / النصوص البرمجية، استخدم `claude -p` مع `--output-format`:

```bash
# JSON: one structured object with result / total_cost_usd / usage / session_id
claude -p "Summarize this change" --output-format json | jq .result

# stream-json: newline-delimited JSON event stream, good for real-time pipelines
claude -p "Refactor this module" --output-format stream-json

# text: plain text (default)
claude -p "Explain this code" --output-format text
```

مزيد من الاستخدام في [الأتمتة وCI/CD](/docs/advanced/headless).
## نقاط النهاية الأخرى

إذا تعذّر الوصول إلى نقطة النهاية الحالية، فبدّل `ANTHROPIC_BASE_URL` (أو `api_url` في settings.json):

| نقطة النهاية | Anthropic Base URL |
|----------|--------------------|
| عالمي | `https://api.qcode.cc/api` |
| أمريكا الشمالية / أوروبا | `https://us.qcode.cc/api` |
| آسيا (المفضلة لمستخدمي CN) | `https://asia.qcode.cc/api` |

للمسار المتوافق مع OpenAI، بدّل النطاق بالطريقة نفسها — مثلًا، قاعدة OpenAI Chat في آسيا هي `https://asia.qcode.cc/openai/v1`. للاطلاع على مرجع نقاط النهاية الكامل، راجع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths).

## الحصة المشتركة

يتشارك وكيل Claude Code داخل Zed مفتاح API نفسه في QCode والحصة نفسها مع CLI / Claude Desktop / Codex CLI — لا توجد فوترة مزدوجة. كما يتشارك المسار A والمسار B حصة المفتاح نفسها. راجع [الفوترة](/docs/reference/billing) للتفاصيل.

## القيود والملاحظات

- **وضع Anthropic المباشر باستخدام BYOK في Zed** يستخدم مزوّد Anthropic المدمج في Zed و**لا يمر عبر Claude Code CLI**. ويتطلب منك ضبط `api_url` يدويًا في إعدادات Zed ليشير إلى QCode (المسار B). يُفضّل وضع ACP / Claude Code المشروح هنا (المسار A) — فهو يحافظ على كامل نطاق أدوات CLI (الخطافات، المهارات، MCP).
- **يجب ألا يحتوي Base URL على شرطة مائلة لاحقة.** طلب الفحص الذاتي عند وصوله إلى مسار القاعدة يعيد `401`، وهذا متوقع (المسار صحيح، لكن ينقصه فقط المصادقة).
- تكامل ACP في مرحلة بيتا عامة (منذ 2026-04)؛ قد تتغير بعض واجهات API بعد. إذا لاحظت اختلافات في السلوك، فإن [الوثائق الرسمية لـ Zed](https://zed.dev/docs/ai/models) هي المرجع.
- مستخدمو بيئة العزل في Linux: إذا كان Zed مثبتًا عبر Flatpak، فقد تمنع بيئة العزل تشغيل العملية الفرعية `claude`. نوصي بتثبيت إصدار .deb / AppImage / Homebrew مباشرةً.
- تمت إحالة Gemini CLI إلى التقاعد (انتهاء الدعم في 2026-06-18 للإصدارات غير المؤسسية؛ مفاتيح المؤسسات المدفوعة غير متأثرة)؛ وخليفته هو Google Antigravity CLI. **لاحظ أن Antigravity CLI لا يقبل إلا نقطة نهاية متوافقة مع Gemini** (عبر `GOOGLE_GEMINI_BASE_URL`)، وليس نقطة نهاية متوافقة مع OpenAI. لا يوفّر QCode نماذج Gemini حاليًا — راجع [Antigravity CLI](/docs/ide/antigravity).

## الأسئلة الشائعة

### لوحة الوكيل تبلغ عن «Failed to start agent»

- هل يبدأ `claude` بشكل صحيح في الطرفية لديك؟ استبعد أولًا مشكلات الإعداد من جهة CLI.
- هل ورث Zed متغيرات البيئة `ANTHROPIC_*`؟ على macOS، يضمن تشغيل Zed عبر `open -a Zed` من الطرفية وراثتها.
- هل يشير `agent.path` في إعداداتك إلى مسار صالح؟ تحقّق باستخدام `which claude`.

### مزوّد settings.json يعيد 401 / فشل المصادقة

- تأكد من ضبط متغير البيئة الصحيح وأنه مفتاح QCode يبدأ بـ `cr_`: يستخدم المزوّدون المخصصون `<PROVIDER_NAME>_API_KEY` (مثل `QCODE_API_KEY` / `QCODEOPENAI_API_KEY`)؛ المزوّدون المدمجون فقط يستخدمون `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
- هل ورث Zed متغير البيئة ذلك؟ شغّل Zed من الطرفية للتحقق.
- هل أُضيفت إلى `api_url` شرطة مائلة لاحقة عن غير قصد؟ أزلها.

### النموذج الذي أريده ليس في القائمة المنسدلة

- يتطلب مزوّد OpenAI في المسار B إدراج النماذج صراحةً في `available_models` قبل ظهورها في القائمة المنسدلة.
- تحدد Claude Code النماذج المتاحة في المسار A؛ استخدم `/model` للعرض والتبديل.

### «Invalid model» / 404

- تحقق جيدًا من أن كتابة معرّف النموذج تطابق الجدول تمامًا (مثل `claude-opus-5`).
- تأكد من أن بروتوكول Base URL يطابق النموذج: يستخدم `claude-*` نقطة نهاية Anthropic، ويستخدم `gpt-*` نقطة نهاية OpenAI.

### الفرق عن وضع BYOK من Anthropic

| البُعد | وضع ACP / Claude Code (المسار A) | وضع مزوّد BYOK في Zed (المسار B) |
|-----------|---------------------------------|---------------------------------|
| الواجهة الخلفية | يشغّل عملية فرعية لـ CLI `claude` | عميل HTTP المدمج في Zed |
| دعم الأدوات | كامل (كل خطافات CLI / المهارات / MCP) | مقيّد بإطار عمل الوكيل المدمج في Zed |
| موقع الإعداد | متغيرات البيئة في Claude Code CLI | إعداد Zed `language_models.*.api_url` |
| نطاق النماذج | النماذج المضبوطة في Claude Code | نماذج Anthropic / OpenAI التي تدرجها في settings.json |
| موصى به لـ | مشاركة الإعداد مع سير عمل CLI في الطرفية | المستخدمون الذين لا يريدون تثبيت CLI ويفضلون تكامل IDE خالصًا |

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

- [دليل Claude Code](/docs/getting-started/claude-code-tutorial) — مرجع كامل لميزات CLI
- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — مرجع كامل للنطاقات الثلاثة للدخول
- [الوكلاء الفرعيون](/docs/advanced/subagents) — سير العمل الديناميكي وتنسيق الوكلاء المتعددين
- [الأتمتة وCI/CD](/docs/advanced/headless) — الوضع بلا واجهة وصيغ الإخراج
- [توليد الصور باستخدام gpt-image-2](/docs/usage/image-2) — توليد الصور (مختلف عن إدخال الرؤية)
- [تكامل VS Code](/docs/ide/vscode) — مقارنة مع المحررات المبنية على Electron
- [الفوترة](/docs/reference/billing) — قواعد الحصة المشتركة

> هل تريد الأسعار المباشرة ومواصفات السياق لكل نموذج؟ انتقل إلى [صفحة أسعار QCode](https://qcode.cc/pricing).