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

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

## لمحة سريعة

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

**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](/docs/ide/zed) |
| Devin Desktop (المعروف سابقًا باسم Windsurf) | مدعوم منذ 2026-06-02، داخل Agent Command Center | [إعداد Devin Desktop](/docs/ide/devin-desktop) |
| JetBrains IDEs | عبر إضافة ACP | [JetBrains IDEs](/docs/ide/jetbrains) |
| Neovim / Emacs / Sublime / Qt Creator وغيرها | مُدرجة في كتالوج المحررات الرسمي | — |

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

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

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

```bash
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` للحصول على النتيجة نفسها.
> راجع [متغيرات البيئة](/docs/getting-started/environment).

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

يُضبط Codex عبر TOML بحيث ينتهي `base_url` عند `/openai`. راجع [دليل Codex](/docs/ide/codex).

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

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

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

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

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

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

```bash
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](https://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 الكامل](/docs/ide/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](/docs/getting-started/endpoints-and-api-paths) |
| تعلّق الجلسة عند «starting» أو تنقطع فورًا | تعذّر بدء الوكيل كعملية فرعية، أو أن سكربت غلاف يكتب إلى stdout | شغّل أمر التشغيل نفسه يدويًا في الطرفية أولًا، ثم افحص سكربت الغلاف |
| لا تظهر أي طلبات على جانب QCode | لم يُرسَل الطلب، أو ذهب إلى عنوان آخر | تحقق باستخدام مفتاحك على [probe.qcode.cc](https://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](https://probe.qcode.cc) لترى ما إذا كان ذلك الطلب يظهر. إذا لم يظهر، فإن المتغيرات لم تصل إلى الوكيل؛ ضع الإعدادات في الكتلة `env` من `~/.claude/settings.json` بدلًا من ذلك.

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

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

### أي نطاق ينبغي أن أستخدم في البر الرئيسي للصين؟

استبدل `api.qcode.cc` بـ `asia.qcode.cc` (نقطة نهاية آسيا)؛ يبقى المفتاح نفسه. ارجع إلى النطاق السابق إذا كان غير مستقر.

## روابط ذات صلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — جدول البروتوكول × عائلة النموذج
- [متغيرات البيئة](/docs/getting-started/environment)
- [إعداد Zed](/docs/ide/zed) · [إعداد Devin Desktop](/docs/ide/devin-desktop) · [بيئات JetBrains IDE](/docs/ide/jetbrains)