یکپارچه‌سازی Cherry Studio

افزودن QCode.cc به‌عنوان ارائه‌دهنده سفارشی در Cherry Studio: مسیر تنظیمات تا سرویس‌های مدل، URL موردنیاز هر یک از چهار نوع ارائه‌دهنده، و اینکه چرا قابلیت Agent به نقطه پایانی‌ای از نوع Anthropic نیاز دارد

به‌روزرسانی 2026-11-13

به کلید API نیاز دارید؟ ثبت‌نام ←نقاط پایانی و Base URL ←

در این صفحه

در یک نگاه
پیش‌نیازها
راه‌اندازی
بررسی کارکرد
محدودیت‌های شناخته‌شده
انواع ارائه‌دهنده و نشانی‌های QCode
توضیح تنظیمات کلیدی
خطاهای رایج و روش عیب‌یابی
پرسش‌های متداول
مستندات مرتبط

آخرین بازبینی: 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»
مستندات رسمی	پیکربندی ارائه‌دهنده

Cherry Studio یکی از محبوب‌ترین کلاینت‌های دسکتاپ هوش مصنوعی متن‌باز میان کاربران چینی‌زبان است (Windows / macOS / Linux): گفت‌وگو، ترجمه، پایگاه‌های دانش و MCP در یک پنجره. بدون سیستم حساب کاربری، پیکربندی کاملاً محلی — آن را به هر نقطه پایانی سازگار با OpenAI / Anthropic متصل کنید و شروع کنید.

پیش‌نیازها¶

Cherry Studio نصب شده باشد (صفحه دانلود نسخه‌های Global و CN را ارائه می‌دهد، x64 / ARM64؛ حداقل نسخه‌های سیستم‌عامل توسط سازنده اعلام نشده است — به صفحه دانلود مراجعه کنید). به حساب کاربری Cherry Studio و حساب‌های ارائه‌دهنده مدل نیازی نیست.
یک کلید cr_ از QCode.cc (داشبورد).
اگر از سرزمین اصلی چین استفاده می‌کنید، در همه موارد زیر 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، توصیه‌شده)¶

نوع Anthropic را انتخاب کنید.
میزبان API: https://api.qcode.cc/api.
کلید API: کلید cr_ شما.
شناسه‌های مدل موردنظر (مثلاً claude-sonnet-5) را در تنظیمات نقطه پایانی/مدل اضافه کنید، یا فهرست مدل‌ها را دریافت کنید.
مستندات رسمی می‌گوید قابلیت Cherry Agent به نقطه پایانی‌ای نیاز دارد که از پروتکل Anthropic پشتیبانی کند — اگر عامل‌های درون برنامه را می‌خواهید، این مسیر است.

مسیر B: مدل‌های GPT و چینی (نوع OpenAI)¶

نوع OpenAI را انتخاب کنید.
میزبان API: https://api.qcode.cc/openai (Cherry مسیر /openai/v1/chat/completions را از آن می‌سازد).
کلید API: همان کلید cr_.
شناسه‌های مدل: هر مدل GPT (مثلاً gpt-5.6-sol) یا مدل چینی (glm-5.3، kimi-k3، deepseek-v4.1-flash، qwen3.8-max، …) — فهرست فعلی در qcode.cc/models.

انواع باقی‌مانده¶

OpenAI Responses: همان میزبان https://api.qcode.cc/openai؛ توجه کنید که نقطه پایانی Responses در QCode فقط مدل‌های GPT را ارائه می‌دهد — نه Claude، نه مدل‌های چینی (ماتریس: نقاط پایانی و مسیرهای API).
Gemini (QCode فعلاً Gemini را ارائه نمی‌دهد؛ این مورد فقط نوع Cherry را توصیف می‌کند): میزبان API https://api.qcode.cc/gemini؛ ما مسیر دقیقی را که Cherry برای این نوع اضافه می‌کند تأیید نکرده‌ایم — در صورت دریافت 404، با تکنیک URL ریشه + # پایانی تنظیم کنید.

بررسی کارکرد¶

یک پیام به مدل جدید در هر تب چت بفرستید، یا از «fetch model list» درون‌برنامه‌ای استفاده کنید (که به <api host>/models درخواست می‌فرستد). اگر چیزی برنگشت: ابتدا بررسی کنید که نوع با خانواده مدل هم‌خوانی دارد (Claude به نوع Anthropic نیاز دارد)، سپس بررسی کنید که /v1/... را دستی در میزبان ننوشته باشید (وگرنه به /v1/v1 دو برابر خواهد شد). هنوز مشکل دارید؟ راهنمای عیب‌یابی را دنبال کنید؛ هر درخواست در 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 مستند شده است — رفتار سمت 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 قرار دارند

خطاهای رایج و روش عیب‌یابی¶

نشانه	علت احتمالی	راه‌حل
`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 وارد کنید تا ببینید درخواست‌ها به QCode می‌رسند یا نه، سپس با عیب‌یابی ادامه دهید.

پرسش‌های متداول¶

آیا به حساب کاربری 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، فقط آدرس ریشه را از جدول نگاشت بالا وارد کنید؛ نیازی به # نیست.