نظرة عامة على ACP

بروتوكول Agent Client Protocol: إعداد واحد يعمل عبر Zed وDevin Desktop وJetBrains — شغّل Claude Code بصفته وكيل ACP مع توجيه بيئته إلى QCode

آخر تحديث 2026-11-13

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

في هذه الصفحة

لمحة سريعة
المضيفون الذين يدعمون ACP
الوكلاء الذين يدعمون ACP
الإعداد: اضبط مرة واحدة، يعمل في كل مكان
- Claude Code (نقطة نهاية Anthropic)
- Codex CLI (نقطة نهاية OpenAI Responses)
🔴 فخ شائع: المحررات التي تُشغَّل بواجهة رسومية لا ترى بيئة الصدفة لديك
التحقق من وصول حركة المرور إلى QCode
كيف يبدأ ACP الوكيل: لماذا تكون متغيرات البيئة «موروثة»
شرح الإعدادات الأساسية
الأخطاء الشائعة وكيفية استكشافها وإصلاحها
الأسئلة الشائعة
روابط ذات صلة

آخر تحقق: 2026-10-15 · 📄 وفق الوثائق الرسمية (agentclientprotocol.com، تم التحقق في اليوم نفسه)

لمحة سريعة¶

العنصر	التفاصيل
النماذج التي يمكنك استخدامها	تعتمد على الوكيل المثبّت: Claude Agent / Claude Code (نقطة نهاية Anthropic) ✅ · GPT ✅ (وكلاء بأسلوب Codex) · النماذج الصينية ✅ · Gemini لا يقدمه QCode في الوقت الحالي
البروتوكول وBase URL	يُضبط في الوكيل نفسه: نقطة نهاية Anthropic `https://api.qcode.cc/api` لوكلاء عائلة Claude
مكان الضبط	بيئة الوكيل / ملف إعداداته الخاص؛ المضيف يكتفي بتشغيله
الوثائق الرسمية	Agent Client Protocol

Agent Client Protocol (ACP) معيار مفتوح يفصل المحررات عن وكلاء الذكاء الاصطناعي — فكّر في LSP، لكن للوكلاء. يمكن لأي محرر يدعم ACP أن يستضيف أي وكيل يدعم ACP، دون تكامل مخصص لكل وكيل.

وهذا له نتيجة عملية جدًا لمستخدمي QCode:

🔑 اضبط الوكيل نفسه (مثل Claude Code CLI) على QCode، وسيتبعه كل المضيفين تلقائيًا. يشغّل مضيفو ACP الوكيل بوصفه عملية فرعية، لذا يرث بيئتك. بمجرد ضبط ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN، تُوجّه الجلسات في Zed وDevin Desktop و JetBrains كلها عبر QCode — ولن تحتاج إلى تكرار الإعداد لكل محرر.

المضيفون الذين يدعمون ACP¶

المضيف	ملاحظات	وثائقنا
Zed	دعم أصلي؛ تُفتح الجلسات في لوحة الوكيل	إعداد Zed
Devin Desktop (المعروف سابقًا باسم Windsurf)	مدعوم منذ 2026-06-02، داخل Agent Command Center	إعداد Devin Desktop
JetBrains IDEs	عبر إضافة ACP	JetBrains IDEs
Neovim / Emacs / Sublime / Qt Creator وغيرها	مُدرجة في كتالوج المحررات الرسمي	—

الوكلاء الذين يدعمون ACP¶

من بين الإدخالات البارزة Claude Agent (الاسم في السجل الرسمي — غلاف ACP الخاص بـ Claude Agent SDK، claude-agent-acp) وOpenCode؛ الكتالوج الكامل على agentclientprotocol.com. يمكن تركيب أي شيء يطبّق ACP. يشحن كل مضيف المهايئ وأمر التشغيل الخاصين به، لذا ارجع إلى وثائق المضيف.

الإعداد: اضبط مرة واحدة، يعمل في كل مكان¶

Claude Code (نقطة نهاية Anthropic)¶

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_qcode_key"

اجعلها دائمة في ~/.zshrc / ~/.bashrc. من البر الرئيسي للصين، استخدم https://asia.qcode.cc/api.

يمكنك أيضًا وضعها في كتلة env داخل ~/.claude/settings.json للحصول على النتيجة نفسها. راجع متغيرات البيئة.

Codex CLI (نقطة نهاية OpenAI Responses)¶

يُضبط Codex عبر TOML بحيث ينتهي base_url عند /openai. راجع دليل Codex.

🔴 فخ شائع: المحررات التي تُشغَّل بواجهة رسومية لا ترى بيئة الصدفة لديك¶

على macOS وLinux، المحرر الذي يبدأ من Dock أو من مشغّل تطبيقات أو من أيقونة سطح المكتب لا يقرأ ~/.zshrc. العَرَض: يصل claude إلى QCode من الطرفية، لكن جلسة ACP داخل المحرر تفشل في المصادقة.

طريقتان للتعامل مع ذلك:

شغّل المحرر من الطرفية (مثل zed .) ليرث بيئة الصدفة الحالية
ضع الإعدادات في ملف إعدادات الوكيل نفسه بدلًا من ملف تعريف الصدفة (Claude Code: كتلة env في ~/.claude/settings.json)

الخيار 2 أكثر موثوقية لأنه لا يعتمد على كيفية بدء المحرر.

التحقق من وصول حركة المرور إلى QCode¶

KEY="cr_your_qcode_key"
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01"
# 400 = path and key are both fine (a missing body is expected); 401 = key problem

بعد التحقق من أن نقطة النهاية تعمل، افتح جلسة في المضيف. إذا استمر الفشل، فالمشكلة في طريقة تشغيل المضيف للوكيل (عادةً فخ البيئة أعلاه)، وليست في QCode.

يُبلَّغ عن كل طلب يمر عبر QCode إلى probe.qcode.cc — أدخل مفتاح API الخاص بك لتأكيد وصول الطلبات فعليًا.

كيف يبدأ ACP الوكيل: لماذا تكون متغيرات البيئة «موروثة»¶

حتى 2026-10-15، ووفقًا لوثائق النقل الرسمية الخاصة بـ ACP: يرمّز ACP الرسائل بصيغة JSON-RPC، ومع نقل stdio الموصى به يشغّل العميل (المحرر) الوكيل كعملية فرعية؛ يقرأ الوكيل رسائل JSON-RPC من الإدخال القياسي ويكتب الرسائل إلى الإخراج القياسي، مفصولة بأسطر جديدة، وقد يكتب السجلات إلى الخطأ القياسي (stderr). كما يمنع البروتوكول الوكيل من كتابة أي شيء إلى stdout ليس رسالة ACP صالحة.

ينتج عن ذلك استنتاجان عمليان لاستكشاف الأخطاء وإصلاحها:

ترث العملية الفرعية افتراضيًا بيئة الجهة التي شغّلتها، لذا فإن ما إذا كان ANTHROPIC_BASE_URL المعيّن في الصدفة لديك ساريًا يعتمد على كيفية بدء المحرر نفسه (راجع فخ التشغيل بواجهة رسومية أعلاه).
إذا غلّفت الوكيل في سكربتك الخاص، فلا تستخدم echo لإخراج تحيات أو مخرجات تصحيح إلى stdout داخله، وإلا ستُعامَل كرسالة غير صالحة؛ اكتب هذه المخرجات إلى stderr بدلًا من ذلك.

شرح الإعدادات الأساسية¶

الإعداد	الغرض	ملاحظات
`ANTHROPIC_BASE_URL`	نقطة النهاية لوكلاء عائلة Claude	استخدم `https://api.qcode.cc/api`، من دون `/v1` ومن دون شرطة مائلة لاحقة
`ANTHROPIC_AUTH_TOKEN`	مفتاح QCode الخاص بك	يبدأ بـ `cr_`، ويُرسَل ضمن ترويسة `Authorization: Bearer`
الكتلة `env` في `~/.claude/settings.json`	تكتب القيمتين أعلاه في إعدادات الوكيل نفسه	مستقلة عن طريقة تشغيل المحرر؛ الخيار الأكثر موثوقية
`base_url` في Codex	نقطة النهاية لوكلاء بأسلوب Codex	ينتهي عند `/openai`؛ راجع دليل Codex الكامل
أمر تشغيل الوكيل في المضيف	يخبر المحرر بكيفية بدء الوكيل	يختلف حسب المضيف؛ اتبع وثائق المضيف

الأخطاء الشائعة وكيفية استكشافها وإصلاحها¶

العَرَض	السبب المحتمل	الحل
يعمل `claude` في الطرفية لكن جلسة ACP في المحرر تفشل في المصادقة	شُغّل المحرر من Dock أو المشغّل ولم يقرأ متغيرات الصدفة الخاصة بك	شغّل المحرر من الطرفية، أو ضع الإعدادات في الكتلة `env` من `~/.claude/settings.json`
401 / `Invalid API key`	مفتاح خاطئ أو محاط بمسافات، أو `ANTHROPIC_API_KEY` قديم يتولى المصادقة	شغّل `env \\| grep -i anthropic` للعثور على البقايا
404	إضافة `/v1` إلى Base URL، أو وجود شرطة مائلة في النهاية	أعده إلى `https://api.qcode.cc/api`
`model_not_available_on_endpoint`	اختير نموذج GPT في وكيل من عائلة Claude، أو نموذج Claude في وكيل بأسلوب Codex	يستخدم Claude واجهة Anthropic ويستخدم GPT واجهة OpenAI Responses؛ راجع نقاط النهاية وصيغ API
تعلّق الجلسة عند «starting» أو تنقطع فورًا	تعذّر بدء الوكيل كعملية فرعية، أو أن سكربت غلاف يكتب إلى stdout	شغّل أمر التشغيل نفسه يدويًا في الطرفية أولًا، ثم افحص سكربت الغلاف
لا تظهر أي طلبات على جانب QCode	لم يُرسَل الطلب، أو ذهب إلى عنوان آخر	تحقق باستخدام مفتاحك على probe.qcode.cc، ثم أعد التحقق من Base URL

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

هل يجب عليّ إعداد QCode بشكل منفصل في كل محرر؟¶

لا. أنت تهيّئ الوكيل نفسه (على سبيل المثال Claude Code)؛ ولا يقوم المحرر إلا بتشغيله. بمجرد أن يتصل الوكيل بـ QCode، تستخدم جلسات ACP في Zed وDevin Desktop وJetBrains الإعدادات نفسها.

ما علاقة ACP بـ LSP؟¶

الفكرة مشابهة: يفصل LSP المحررات عن خوادم اللغات، ويفصل ACP المحررات عن وكلاء الذكاء الاصطناعي. يمكن للمحرر الذي يدعم ACP أن يركّب أي وكيل يدعم ACP من دون تكامل مخصص لكل واحد منها.

كيف أتأكد من أن محررًا شُغّل من Dock قد تلقى متغيرات البيئة؟¶

افتح جلسة ACP في المحرر وأرسل رسالة واحدة، ثم أدخل مفتاحك على probe.qcode.cc لترى ما إذا كان ذلك الطلب يظهر. إذا لم يظهر، فإن المتغيرات لم تصل إلى الوكيل؛ ضع الإعدادات في الكتلة env من ~/.claude/settings.json بدلًا من ذلك.

هل يمكن لجلسات ACP استخدام GPT؟¶

يعتمد ذلك على الوكيل الذي تركّبه. يستخدم وكلاء عائلة Claude واجهة Anthropic فقط، مع نماذج Claude والنماذج الصينية. لاستخدام GPT، ركّب وكيلًا بأسلوب Codex ووجّه base_url الخاص به إلى https://api.qcode.cc/openai كما يتوقع Codex. لا يوفّر QCode حاليًا نماذج Gemini.