# تكامل Cherry Studio

> **آخر تحقق**: 2026-10-15 · 📄 وفق الوثائق الرسمية (Cherry Studio v2.0.14، صدر في 2026-09-09)

## نظرة سريعة

| العنصر | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (نوع Anthropic) · GPT ✅ (نوع OpenAI) · النماذج الصينية ✅ (نوع OpenAI) · Gemini ❌ (لا يوفره QCode في الوقت الحالي) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai` (عناوين URL الجذرية فقط — انظر أدناه) |
| مكان الإعداد | داخل التطبيق: Settings → Model Services → "+ Add a provider" |
| الوثائق الرسمية | [إعداد المزوّد](https://docs.cherryai.com.cn/) |

يُعد Cherry Studio أحد أكثر عملاء الذكاء الاصطناعي المكتبيين مفتوحي المصدر شيوعًا بين المستخدمين الناطقين بالصينية (Windows / macOS / Linux): المحادثة والترجمة وقواعد المعرفة وMCP في نافذة واحدة. **لا يوجد نظام حسابات، والإعداد محلي بالكامل** — وجّهه إلى أي نقطة نهاية متوافقة مع OpenAI / Anthropic وابدأ.

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

- أن يكون Cherry Studio مثبّتًا (توفّر صفحة التنزيل إصداري Global وCN، بمعماريتي x64 / ARM64؛ ولم يذكر المزوّد الحد الأدنى لإصدارات نظام التشغيل — انظر [صفحة التنزيل](https://www.cherryai.com.cn/)). لا حاجة إلى حساب Cherry Studio ولا إلى حسابات مزوّدي النماذج.
- مفتاح `cr_` من QCode.cc ([لوحة التحكم](https://qcode.cc/dashboard)).
- من البر الرئيسي للصين، استبدل `api.qcode.cc` بـ `asia.qcode.cc` في كل ما يرد أدناه — القدرات متطابقة.

## الإعداد

افتح **Settings → Model Services**، وانقر على "**+ Add a provider**" أسفل القائمة، واعمل في مربع الحوار "Add custom provider". القاعدة الرسمية: **حقل "API Host" يأخذ عنوان URL الجذري فقط — لا `/v1` ولا مسارات** — يضيف Cherry Studio الباقي بناءً على النوع الذي اخترته (مثلًا نوع OpenAI يضيف `/v1/chat/completions`)؛ لتعطيل الإضافة بالكامل، أنهِ عنوان URL بـ `#`.

### المسار A: نماذج Claude (نوع Anthropic، موصى به)

1. اختر النوع **Anthropic**.
2. مضيف API: `https://api.qcode.cc/api`.
3. مفتاح API: مفتاحك `cr_`.
4. أضف معرّفات النماذج التي تريدها (مثل `claude-sonnet-5`) في إعدادات نقطة النهاية/النموذج، أو اجلب قائمة النماذج.
5. تنص الوثائق الرسمية على أن **ميزة Cherry Agent تتطلب نقطة نهاية تدعم بروتوكول Anthropic** — إذا كنت تريد وكلاء داخل التطبيق، فهذا هو المسار.

### المسار B: نماذج GPT والنماذج الصينية (نوع OpenAI)

1. اختر النوع **OpenAI**.
2. مضيف API: `https://api.qcode.cc/openai` (يبني Cherry المسار `/openai/v1/chat/completions` منه).
3. مفتاح API: مفتاح `cr_` نفسه.
4. معرّفات النماذج: أي GPT (مثل `gpt-5.6-sol`) أو نموذج صيني (`glm-5.3`، `kimi-k3`، `deepseek-v4.1-flash`، `qwen3.8-max`، …) — القائمة الحالية على [qcode.cc/models](https://qcode.cc/models).

### الأنواع المتبقية

- **OpenAI Responses**: المضيف نفسه `https://api.qcode.cc/openai`؛ لاحظ أن نقطة نهاية Responses لدى QCode تخدم **نماذج GPT فقط** — لا Claude ولا نماذج صينية (المصفوفة: [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).
- **Gemini** (لا يوفّر QCode Gemini في الوقت الحالي؛ هذا الإدخال يصف نوع Cherry فقط): مضيف API `https://api.qcode.cc/gemini`؛ لم نتحقق من المسار الدقيق الذي يضيفه Cherry لهذا النوع — عند ظهور خطأ 404، عدّل باستخدام أسلوب عنوان URL الجذري مع `#` في النهاية.
## تحقق من أنه يعمل

أرسل رسالة واحدة إلى النموذج الجديد في أي تبويب محادثة، أو استخدم «fetch model list» داخل التطبيق (فهو يطلب `<api host>/models`). إذا لم تأتِ أي استجابة: تحقق أولًا من أن النوع يطابق عائلة النموذج (يحتاج Claude إلى نوع Anthropic)، ثم تحقق من أنك لم تكتب يدويًا `/v1/...` في المضيف (وإلا فسيتضاعف إلى `/v1/v1`). هل ما زلت متعثرًا؟ اتبع [دليل استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting)؛ فكل طلب ظاهر على [probe.qcode.cc](https://probe.qcode.cc).

## القيود المعروفة

- **لا يستطيع Claude استخدام نوع OpenAI**: تقوم نقطة نهاية OpenAI في QCode برفض نماذج Claude رفضًا صريحًا (`model_not_available_on_endpoint`)؛ استخدم نوع Anthropic.
- **لا** تلصق مسارات كاملة مثل `/v1/chat/completions` في مضيف API — فالإلحاق هو السلوك الافتراضي؛ وعلامة `#` اللاحقة هي وسيلة التجاوز.
- تُسمّي وثائق Cherry ثنائية اللغة الخاصة بها صفحة الإعدادات بكل من «Model Services» و«Model Provider» وفقًا للإصدار؛ وقد يظهر زر «fetch model list» باسم «sync models» في نسختك.
- لتوليد الصور / تحريرها حقول Base URL خاصة بها؛ نموذج الصور لدى QCode (`gpt-image-2`) موثّق في [توليد الصور وتحريرها باستخدام gpt-image-2](/docs/usage/image-2) — ولم يُتحقَّق هنا من سلوك جهة Cherry.
- انتقل نطاق الوثائق الرسمي مؤخرًا (يعيد docs.cherry-ai.com الآن توجيه 301 إلى docs.cherryai.com.cn)؛ وستُوجَّه الإشارات المرجعية القديمة.

## أنواع المزوّد وعناوين QCode

حتى 2026-10-15، وفقًا لقسم «أنواع المزوّد» في وثائق Cherry Studio: يستخدم النوع المتوافق مع OpenAI المسار `/v1/chat/completions`، ويستخدم النوع المتوافق مع Anthropic المسار `/v1/messages`، و**يتطلب Cherry Agent نوع Anthropic**؛ ويمكن لمزوّد مخصص ربط أي نقطة نهاية متوافقة مع OpenAI / Anthropic / Gemini. وفيما يلي تعيينها إلى QCode:

| نوع Cherry Studio | عنوان API | النماذج القابلة للاستخدام | ما تطلبه Cherry فعليًا |
|---|---|---|---|
| Anthropic | `https://api.qcode.cc/api` | Claude؛ والنماذج الصينية تعمل أيضًا | `/api/v1/messages` |
| OpenAI | `https://api.qcode.cc/openai` | GPT، والنماذج الصينية | `/openai/v1/chat/completions` |
| OpenAI Responses | `https://api.qcode.cc/openai` | GPT فقط | `/openai/v1/responses` |

في البر الرئيسي للصين، استبدل `api.qcode.cc` بـ `asia.qcode.cc`.

## شرح الإعدادات الرئيسية

| الإعداد | الشرح |
|---|---|
| نوع المزوّد | يحدد البروتوكول والمسار الملحق؛ وهو أكثر ما يسهل الخطأ فيه، وعادةً ما يظهر الاختيار الخاطئ على هيئة 404 أو `model_not_available_on_endpoint` |
| عنوان API | أدخل الجذر فقط؛ لا تكتب `/v1` أو مسارًا كاملًا. أضف `#` في النهاية فقط عندما تحتاج إلى مسار ثابت وتريد إيقاف الإلحاق التلقائي |
| مفتاح API | مفتاح QCode الخاص بك الذي يبدأ بـ `cr_`، دون مسافات حوله |
| معرّف النموذج | أضف معرّف النموذج يدويًا أو استخدم «fetch model list»؛ ومعرّفات Claude وGPT الحقيقية موجودة على [qcode.cc/models](https://qcode.cc/models) |

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

| العَرَض | السبب المحتمل | الإصلاح |
|---|---|---|
| `model_not_available_on_endpoint` | نموذج من Claude موضوع تحت مزوّد من نوع OpenAI | أنشئ مزوّدًا منفصلًا من نوع Anthropic بعنوان `https://api.qcode.cc/api` |
| 404 | كتابة `/v1` في عنوان API (فيصبح `/v1/v1`)، أو عدم تطابق النوع والعنوان | أزل `/v1` وتحقق من جدول التعيين أعلاه |
| `Invalid API key` | مفتاح خاطئ، أو مسافات حوله، أو إدخال مفتاح خدمة أخرى | انسخ المفتاح `cr_` مرة أخرى |
| «Fetch model list» فارغة أو تفشل | يجري الجلب إلى `<API address>/models`، والنوع أو العنوان خاطئ | صحّح النوع والعنوان أولًا؛ وإن بقيت فارغة، أضف معرّفات النماذج يدويًا |
| ميزات الوكيل لا تعمل | المزوّد الحالي ليس من نوع Anthropic | اضبط مزوّدًا من نوع Anthropic كما في المسار A |
| غير مستقر في البر الرئيسي للصين | مسار الشبكة إلى النطاق الافتراضي ضعيف | بدّل إلى `asia.qcode.cc` |

إذا لم تتمكن من التحديد بعد ذلك، أدخل مفتاحك في [probe.qcode.cc](https://probe.qcode.cc) لترى ما إذا كانت الطلبات تصل إلى QCode، ثم تابع مع [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting).

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

### هل أحتاج إلى حساب في Cherry Studio؟

لا. إنه عميل يعتمد على الإعدادات المحلية فقط: أدخل عنوان QCode والمفتاح وستكون جاهزًا.

### لماذا أنشئ مزوّدين لمفتاح واحد؟

لأن Claude يعمل فقط عبر واجهة Anthropic بينما يستخدم GPT والنماذج الصينية واجهة OpenAI، ولا يمكن لمزوّد في Cherry Studio أن يحمل سوى نوع واحد. يستخدم المزوّدان المفتاح `cr_` نفسه؛ ولا يختلفان إلا في العنوان والنوع.

### كيف أضبط ميزة Agent داخل التطبيق؟

وفق الوثائق الرسمية، يحتاج Cherry Agent إلى مزوّد من نوع Anthropic: اختر Anthropic، واضبط عنوان API على `https://api.qcode.cc/api`، وأضف نماذج Claude.

### متى أحتاج إلى `#` في نهاية عنوان API؟

فقط عندما تتطلب خدمة مسارًا كاملًا ثابتًا ولا تريد أن يضيف Cherry Studio مسارًا حسب النوع. في الاستخدام العادي لـ QCode، أدخل عنوان الجذر فقط من جدول التعيين أعلاه؛ ولا حاجة إلى `#`.

### هل يمكنني استخدام Gemini عبر Cherry Studio؟

لا يوفّر QCode نماذج Gemini حاليًا. الرجاء استخدام Claude أو GPT أو النماذج الصينية بدلًا منها.

## الوثائق ذات الصلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)
- [نظرة عامة على توافق الأدوات](/docs/ide/tool-compatibility)
- [النماذج الصينية](/docs/usage/cn-models)
- [الاشتراكات مقابل مفاتيح API مقابل مفاتيح QCode](/docs/reference/subscription-vs-api-key)
- [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting)
- [إعداد LobeChat](/docs/ide/lobechat) — عميل آخر لسطح المكتب/السحابة؛ يوضع العنوان في حقل Proxy URL ضمن App Settings → AI Providers