# یکپارچه‌سازی 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 ریشه — به پایین مراجعه کنید) |
| محل پیکربندی | درون برنامه: تنظیمات → سرویس‌های مدل → «+ 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` جایگزین کنید — قابلیت‌ها یکسان است.

## راه‌اندازی

**تنظیمات → سرویس‌های مدل** را باز کنید، روی «**+ 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، بر اساس بخش «provider types» در مستندات 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 | در آدرس API عبارت `/v1` تایپ شده (و به `/v1/v1` تبدیل شده)، یا نوع و آدرس با هم هم‌خوانی ندارند | `/v1` را حذف کنید و جدول نگاشت بالا را بررسی کنید |
| `Invalid API key` | کلید اشتباه، فاصله در اطراف آن، یا کلید سرویس دیگری وارد شده است | کلید `cr_` را دوباره کپی کنید |
| «Fetch model list» خالی است یا شکست می‌خورد | واکشی به `<API address>/models` انجام می‌شود و نوع یا آدرس اشتباه است | ابتدا نوع و آدرس را اصلاح کنید؛ اگر هنوز خالی بود، شناسه‌های مدل را دستی اضافه کنید |
| ویژگی‌های Agent کار نمی‌کنند | ارائه‌دهنده فعلی از نوع Anthropic نیست | مانند مسیر A یک ارائه‌دهنده از نوع Anthropic پیکربندی کنید |
| در سرزمین اصلی چین ناپایدار است | مسیر شبکه دامنه پیش‌فرض ضعیف است | به `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 قرار بگیرد