إعداد Zed + Claude Code عبر ACP (v1.27.0)

Zed 1.27.0 (2026-11-04): شغّل Claude Code في لوحة الوكيل عبر ACP، أو أضف QCode.cc كمزوّد anthropic_compatible / openai_compatible في settings.json.

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

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

نظرة سريعة¶

Zed محرر أكواد حديث عالي الأداء مكتوب بلغة Rust، ويدعم أصليًا منذ الربع الأول من 2026 Agent Client Protocol (ACP) — معيار مفتوح يفصل اتصال 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؛ ويغطي «تكوين مزوّد في settings.json» المسار B.

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

• Zed مثبّت (macOS / Linux)
• Claude Code CLI مثبّت (يعتمد تكامل ACP في Zed على CLI كواجهة خلفية؛ تجاوز هذا إذا كنت تستخدم المسار B فقط)
• مفتاح API من QCode.cc (يبدأ بـ cr_)، متاح من لوحة التحكم
• Claude Code CLI مُهيّأ مسبقًا بمتغيرات بيئة QCode (وفق البدء السريع)

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

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

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

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.

إعداد مزوّد في 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:

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

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

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:

{
  "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" }
        ]
      }
    }
  }
}

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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.

نقاط النهاية الأخرى¶

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

للمسار المتوافق مع OpenAI، بدّل النطاق بالطريقة نفسها — مثلًا، قاعدة OpenAI Chat في آسيا هي https://asia.qcode.cc/openai/v1. للاطلاع على مرجع نقاط النهاية الكامل، راجع نقاط النهاية ومسارات API.

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

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

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

• وضع 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 هي المرجع.
• مستخدمو بيئة العزل في 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.

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

لوحة الوكيل تبلغ عن «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¶

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

• دليل Claude Code — مرجع كامل لميزات CLI
• نقاط النهاية ومسارات API — مرجع كامل للنطاقات الثلاثة للدخول
• الوكلاء الفرعيون — سير العمل الديناميكي وتنسيق الوكلاء المتعددين
• الأتمتة وCI/CD — الوضع بلا واجهة وصيغ الإخراج
• توليد الصور باستخدام gpt-image-2 — توليد الصور (مختلف عن إدخال الرؤية)
• تكامل VS Code — مقارنة مع المحررات المبنية على Electron
• الفوترة — قواعد الحصة المشتركة

هل تريد الأسعار المباشرة ومواصفات السياق لكل نموذج؟ انتقل إلى صفحة أسعار QCode.

المؤسسات ←