# یکپارچه‌سازی Chatbox: اتصال QCode قدم‌به‌قدم


**پاسخ کوتاه**: در Chatbox وارد `Settings → Model Provider` شوید، یک ارائه‌دهنده سفارشی با `API Mode` روی `Claude API Compatible` اضافه کنید، `https://api.qcode.cc/api/v1` را در `API Host` بگذارید، کلید `cr_` خود را بچسبانید و شناسه مدل `claude-sonnet-5` را اضافه کنید.

| مورد | مقدار |
|---|---|
| Claude API Host | `https://api.qcode.cc/api/v1` |
| API Path | `/messages` |
| OpenAI API Host | `https://api.qcode.cc/openai/v1` |
| API Key | `cr_xxxxxxxx` |
| Model ID | `claude-sonnet-5` |

بررسی‌شده در 2026-11-21 · Chatbox 1.24.6 · Windows 11


تصویرهای زیر را روی یک رایانه ویندوزی دنبال کنید: در پایان QCode به‌عنوان یک ارائه‌دهنده در Chatbox اضافه شده، یک مدل Claude در پنجره گفت‌وگو انتخاب شده و پاسخ روی صفحه آمده است. در هیچ مرحله‌ای به حساب کاربری Chatbox نیاز ندارید.


- **مناسب برای**: ویندوز 10 / 11 (64-bit)؛ تصویرها روی ویندوز 11 گرفته شده‌اند
- **نسخه نرم‌افزار**: Chatbox 1.24.6 (رابط انگلیسی)
- **تصویرها به‌روزرسانی شده در**: 2026-11
- **زمان لازم**: حدود 15 دقیقه، که بیشترش صرف دانلود یک فایل نصب 230 MiB می‌شود
- **چیزهایی که لازم دارید**: یک کلید API از QCode که با `cr_` شروع می‌شود


پیش از نخستین تصویر، مطمئن شوید این‌ها را دارید:


- یک رایانه ویندوز 10 یا 11، 64-bit، که بتواند وب‌سایت باز کند
- حدود 1 GB فضای خالی دیسک؛ فایل نصب زیر حساب کاربری خودتان اجرا می‌شود و به رمز مدیر نیازی ندارد
- یک کلید API از QCode که از داشبورد خود کپی کرده‌اید (`cr_xxxxxxxx`)؛ کلید تنها چیزی است که نمی‌توان از آن صرف‌نظر کرد. هنوز حساب ندارید؟ ابتدا [ثبت‌نام کنید](https://qcode.cc/fa/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-chatbox-before)، در [صفحه قیمت‌ها](https://qcode.cc/fa/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-chatbox-before) یک پلن انتخاب کنید و سپس در [داشبورد](https://qcode.cc/fa/dashboard) کلید بسازید.
- بدون حساب Chatbox: صفحه خوش‌آمد دکمه `Skip guide` را دارد و همه‌چیز به‌صورت محلی پیکربندی می‌شود


## دانلود و نصب Chatbox

Chatbox برای ویندوز یک فایل نصب عرضه می‌کند. ردیفی را انتخاب کنید که مناسب موقعیت شماست:

**سایر مناطق**

**chatboxai.app/en/download** را باز کنید. زیر `Desktop App`، ردیف ویندوز `64-bit` می‌گوید؛ روی دکمه `Download` آن کلیک کنید. فایل `Chatbox-1.24.6-Setup.exe` را می‌گیرید، حدود 230 MiB.

اگر صفحه باز نمی‌شود، از **GitHub Releases** (github.com/chatboxai/chatbox/releases) استفاده کنید: بخش `Downloads` را باز کنید و روی `Windows (x64)` کلیک کنید. تازه‌ترین نسخه آنجا v1.24.4 است، قدیمی‌تر از فایل نصبی سایت، پس صفحه دانلود را ترجیح دهید.

![صفحه GitHub Releases: فهرست Downloads شامل پیوند Windows (x64) است و آخرین نسخه v1.24.4 است، قدیمی‌تر از فایل نصبی سایت](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/03-github-releases.webp)


**سرزمین اصلی چین**

**chatboxai.app/zh/download** را باز کنید و در ردیفی که زیر `Windows` نوشته `64-bit`، روی `Download` کلیک کنید. نام فایل `Chatbox-1.24.6-Setup.exe` و حجمش حدود 230 MiB است. سایت بین‌المللی (chatboxai.app/en/download) همان فایل نصب را عرضه می‌کند، پس اگر صفحه چینی کند است از آن استفاده کنید.




### باز کردن صفحه دانلود

به **chatboxai.app/en/download** بروید. زیر `Desktop App`، ① ردیف ویندوز `64-bit` می‌گوید و ② `Download` دکمه سمت راست آن است. روی ② کلیک کنید.

![صفحه رسمی دانلود انگلیسی: زیر Desktop App ردیف ویندوز 64-bit است و دکمه Download در سمت راست برجسته شده](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/01-download-page.webp)


اگر درست پیش بروید این را می‌بینید: مرورگر شما دانلود فایلی به نام `Chatbox-1.24.6-Setup.exe` را آغاز می‌کند، حدود 230 MiB. شماره نسخه در نام فایل به‌مرور زمان تغییر می‌کند.




### بررسی پایان دانلود

پنل دانلودهای مرورگر را باز کنید. ① فایل نصب تمام‌شده را با حجم کاملش نشان می‌دهد.

![پنل دانلودهای مرورگر که فایل تمام‌شده Chatbox-1.24.6-Setup.exe را با حجم حدود 230 MiB نشان می‌دهد](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/02-download-done.webp)


اگر درست پیش بروید این را می‌بینید: ① یک ردیف کامل‌شده به نام `Chatbox-1.24.6-Setup.exe` بدون نوار پیشرفت. ردیفی که به `.crdownload` ختم می‌شود هنوز در حال دانلود است — صبر کنید تا نامش به `.exe` تبدیل شود.




### انتخاب اینکه نصب برای چه کسی باشد

فایل دانلودشده را دوبار کلیک کنید. در صفحه نخست پنجره نصب، ① `Only for me (user)` را انتخاب کنید و سپس روی ② `Next >` کلیک کنید.

![صفحه Chatbox Setup با عنوان Choose Installation Options: گزینه Only for me (user) انتخاب شده و دکمه Next برجسته است](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/04-installer-options.webp)

**گیر کرده‌اید؟ ویندوز رمز مدیر می‌خواهد**

با انتخاب `Only for me (user)` فایل نصب در پوشه AppData خودتان می‌نویسد و به دسترسی مدیر نیاز ندارد. اگر پنجره رمز ظاهر شد، آن را لغو کنید و نصب را دوباره شروع کنید — صفحه نخست باید `Only for me (user)` را انتخاب‌شده نشان دهد.



اگر درست پیش بروید این را می‌بینید: ① `Only for me (user)` تیک‌خورده است و پنجره به `Choose Install Location` می‌رود.




### نگه داشتن پوشه پیش‌فرض

صفحه دوم نشان می‌دهد برنامه کجا نصب می‌شود، به‌طور پیش‌فرض زیر پوشه AppData خودتان. آن را تغییر ندهید و روی ① `Install` کلیک کنید.

![صفحه Chatbox Setup با عنوان Choose Install Location، پوشه پیش‌فرض AppData کاربر و دکمه Install برجسته](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/05-installer-location.webp)


اگر درست پیش بروید این را می‌بینید: دکمه رفته و پنجره به `Please wait while Chatbox is being installed.` تغییر می‌کند.




### انتظار برای نوار پیشرفت

چیزی برای کلیک نیست. روی یک رایانه معمولی نوار در حدود 20 ثانیه پر می‌شود.

![صفحه پیشرفت Chatbox Setup با نوار پیشرفت نصب که نیمه‌کاره است](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/06-installer-installing.webp)


اگر درست پیش بروید این را می‌بینید: نوار به انتها می‌رسد و پنجره خودبه‌خود به `Completing Chatbox Setup` می‌رود.




### اجرای Chatbox

در صفحه آخر، `Run Chatbox` را تیک‌خورده نگه دارید و روی ① `Finish` کلیک کنید.

![صفحه Completing Chatbox Setup با گزینه Run Chatbox تیک‌خورده و دکمه Finish برجسته](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/07-installer-finish.webp)


اگر درست پیش بروید این را می‌بینید: پنجره نصب بسته می‌شود و پنجره Chatbox خودبه‌خود باز می‌شود.




### عبور از صفحه خوش‌آمد

نخستین اجرا صفحه خوش‌آمد را باز می‌کند. به حساب کاربری نیاز ندارید: ① `I'm new to this` را دست نزنید و روی ② `Skip guide` در سمت راست کلیک کنید.

![صفحه خوش‌آمد نخستین اجرا: کارت I'm new to this در سمت چپ و کارت Skip guide در سمت راست](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/08-first-run-welcome.webp)

**گیر کرده‌اید؟ در صفحه خوش‌آمد «Skip guide» نیست**

مطمئن شوید نسخه 1.24.6 یا جدیدتر را نصب کرده‌اید: صفحه خوش‌آمد در پایین دو کارت دارد، `I'm new to this` و `Skip guide`. اگر هیچ‌کدام را نمی‌بینید، نصب تمام نشده — به آخرین صفحه نصب برگردید و `Finish` را بزنید.



اگر درست پیش بروید این را می‌بینید: صفحه خوش‌آمد بسته می‌شود و پنجره اصلی می‌آید — فهرست گفت‌وگوها در سمت چپ، کادر پیام در پایین، و هیچ درخواست ورودی نیست.




### باز کردن Settings → Model Provider

روی `Settings` در پایین سمت چپ پنجره اصلی کلیک کنید. در ستون چپ صفحه تنظیمات روی ① `Model Provider` کلیک کنید؛ فهرست ارائه‌دهنده‌ها باز می‌شود. دکمه ارائه‌دهنده خودتان آخرین ردیف است: ② `+ Add`.

![صفحه تنظیمات: Model Provider در ستون چپ انتخاب شده و + Add در انتهای فهرست ارائه‌دهنده‌ها است](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/09-settings-model-provider.webp)

**گیر کرده‌اید؟ در ستون چپ «Model Provider» نیست**

در Chatbox 1.24.6 این مدخل در ستون چپ Settings است. اگر پیدایش نمی‌کنید، مطمئن شوید در Settings هستید و نه داخل یک گفت‌وگو: نخست `Settings` را در پایین سمت چپ پنجره اصلی بزنید، سپس ستون چپ را برای صفحه‌ای بگردید که ارائه‌دهنده‌هایی مثل OpenAI، Claude و Gemini را فهرست می‌کند.



اگر درست پیش بروید این را می‌بینید: ① `Model Provider` در ستون چپ برجسته است، فهرست ارائه‌دهنده‌ها در میانه، و ② `+ Add` آخرین ردیف آن فهرست.




### باز کردن فرم ارائه‌دهنده سفارشی

روی `+ Add` کلیک کنید. فهرستی از ارائه‌دهنده‌های شناخته‌شده باز می‌شود؛ `custom` را در کادر جست‌وجوی آن تایپ کنید و سپس روی ① `Add Custom Provider` کلیک کنید.

![فهرست ارائه‌دهنده‌ها با custom تایپ‌شده در کادر جست‌وجو، که Add Custom Provider را تنها نتیجه باقی می‌گذارد](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/10-add-provider-picker.webp)


اگر درست پیش بروید این را می‌بینید: پنجره‌ای با عنوان `Add provider` و دو فیلد، `Name` و `API Mode`.




### انتخاب حالت Claude API

① فهرست `API Mode` را باز کنید و `Claude API Compatible` را انتخاب کنید. این به Chatbox می‌گوید که پروتکل Claude را به کار ببرد؛ فیلدهای نشانی در قدم‌های بعد به آن وابسته‌اند.

![پنجره Add provider با فهرست بازشوی API Mode و گزینه Claude API Compatible برجسته](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/11-add-provider-mode.webp)


اگر درست پیش بروید این را می‌بینید: ① فیلد `API Mode` اکنون `Claude API Compatible` می‌خواند.




### نام‌گذاری ارائه‌دهنده

`QCode Claude` را در ① `Name` تایپ کنید. ② `API Mode` را روی `Claude API Compatible` بگذارید و سپس روی `Add` کلیک کنید.

![پنجره Add provider با نام QCode Claude تایپ‌شده و API Mode که روی Claude API Compatible مانده است](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/12-add-provider-filled.webp)


اگر درست پیش بروید این را می‌بینید: پنجره بسته می‌شود و صفحه ارائه‌دهنده جدید با فیلدهای `API Host`، `API Path` و `Preview` باز می‌شود.




### پر کردن Claude API Host

در ① `API Host` این را تایپ کنید: `https://api.qcode.cc/api/v1`. `API Path` را روی `/messages` بگذارید. Chatbox خودش این دو را به هم می‌چسباند: ② `Preview` باید `https://api.qcode.cc/api/v1/messages` را نشان دهد.

![صفحه ارائه‌دهنده با API Host روی https://api.qcode.cc/api/v1 و خط Preview که https://api.qcode.cc/api/v1/messages را نشان می‌دهد](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/13-claude-api-host.webp)

**گیر کرده‌اید؟ Preview مسیر /api/messages را نشان می‌دهد، بدون /v1**

Chatbox به یک میزبان Claude سفارشی فقط `/messages` را می‌افزاید — نه مثل `api.anthropic.com` که `/v1` را اضافه می‌کند، و نه مثل Cherry Studio که `/v1` را اضافه می‌کند. بخش نسخه را در فیلد Host بگذارید: `https://api.qcode.cc/api/v1`. نشانی پایه عمومی Anthropic در QCode یعنی `https://api.qcode.cc/api` برای کلاینت‌هایی است که SDKشان خودش `/v1/messages` را می‌افزاید.



اگر درست پیش بروید این را می‌بینید: ① با `/api/v1` تمام می‌شود و ② `https://api.qcode.cc/api/v1/messages` را می‌خواند.




### چسباندن کلید API

روی فیلد `API Key` کلیک کنید و کلیدی را که از داشبورد QCode کپی کرده‌اید بچسبانید. فیلد فقط نقطه نشان می‌دهد — این طبیعی است، کلید همان‌طور که تایپ کرده‌اید ذخیره می‌شود.

![فیلد API Key پر شده با کلید پوشیده QCode که به‌صورت ردیفی از نقطه نمایش داده می‌شود](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/14-api-key-filled.webp)

**به کلید API نیاز دارید؟**

اگر هنوز حساب QCode ندارید، ابتدا [ثبت‌نام کنید](https://qcode.cc/fa/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-chatbox-key). اگر پلن ماهانه نمی‌خواهید، با خرید [بسته‌های پرداخت به‌ازای مصرف](https://qcode.cc/fa/pay-as-you-go?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-chatbox-key) شروع کنید و سپس در [داشبورد](https://qcode.cc/fa/dashboard) کلید بسازید. رشته‌ای را که با `cr_` شروع می‌شود کپی کنید. می‌توانید با کارت اعتباری / نقدی (Visa / Mastercard)، یا Apple Pay / Google Pay، یا رمزارز پرداخت کنید — به [روش‌های پرداخت](/docs/reference/payment-methods) مراجعه کنید.



اگر درست پیش بروید این را می‌بینید: ردیفی از نقطه در فیلد و بدون متن جایگزین خاکستری. اگر فیلد خالی ماند، یک‌بار داخلش کلیک کنید، یک لحظه صبر کنید و بعد دوباره بچسبانید — بدون فاصله اضافی پیش یا پس از کلید.




### افزودن شناسه مدل

روی `+ New` کلیک کنید. در پنجره `Edit Model`، ① `claude-sonnet-5` را در `Model ID` تایپ کنید و سپس روی ② `Save` کلیک کنید. Chatbox فهرست مدل‌های QCode را نمی‌گیرد، پس شناسه دستی تایپ می‌شود.

![پنجره Edit Model با claude-sonnet-5 تایپ‌شده در فیلد Model ID و دکمه Save برجسته](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/15-add-model.webp)

**گیر کرده‌اید؟ فهرست مدل‌ها بعد از تازه‌سازی خالی می‌ماند**

یک ارائه‌دهنده سفارشی سازگار با Claude در Chatbox فهرست مدل‌ها را نمی‌گیرد، پس چیزی خودکار نمی‌آید. شناسه را دستی اضافه کنید، مثلاً `claude-sonnet-5`، `claude-opus-5-5` یا `claude-haiku-5-5`؛ همه شناسه‌هایی که می‌توانید استفاده کنید در [qcode.cc/models](https://qcode.cc/fa/models) فهرست شده‌اند. شناسه را دقیق و با خط تیره کپی کنید.



اگر درست پیش بروید این را می‌بینید: `claude-sonnet-5` یک ردیف در فهرست مدل‌های ارائه‌دهنده `QCode Claude` می‌شود.




### بررسی اتصال

روی `Check` کلیک کنید. وقتی می‌پرسد کدام مدل آزمایش شود، `claude-sonnet-5` را انتخاب کنید. ① `Model Test Results` سپس `Connection successful` را گزارش می‌کند، با متن، بینایی و استفاده از ابزار همه تیک‌خورده.

![پنجره Model Test Results که Connection successful را برای claude-sonnet-5 گزارش می‌کند، با متن، بینایی و استفاده از ابزار تیک‌خورده](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/16-check-result.webp)

**گیر کرده‌اید؟ Check با خطا شکست می‌خورد**

نخست دو فیلد را بررسی کنید: `API Host` باید `https://api.qcode.cc/api/v1` باشد و فیلد `API Key` باید نقطه نشان دهد. سپس دوباره `Check` را بزنید — یک اختلال کوچک شبکه معمولاً علت است. اگر پیام به مدل اشاره داشت، مطمئن شوید شناسه مدل دقیقاً `claude-sonnet-5` است.



اگر درست پیش بروید این را می‌بینید: ① `Connection successful` به رنگ سبز، و یک تیک کنار هر یک از متن، بینایی و استفاده از ابزار.




### انتخاب مدل در پنجره گفت‌وگو

Settings را ببندید و یک گفت‌وگوی تازه شروع کنید. انتخاب‌گر مدل را در پایین سمت راست باز کنید، فهرست را به `More Providers (BYOK)` تغییر دهید، ① `QCode Claude` را باز کنید و روی ② `claude-sonnet-5` کلیک کنید.

![انتخاب‌گر مدل گفت‌وگو با گروه QCode Claude باز زیر More Providers (BYOK) و claude-sonnet-5 در فهرست](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/19-model-picker.webp)


اگر درست پیش بروید این را می‌بینید: انتخاب‌گر مدل در پایین سمت راست اکنون به‌جای یکی از مدل‌های خود Chatbox، `claude-sonnet-5` را نشان می‌دهد.




### فرستادن نخستین پیام

روی کادر پیام کلیک کنید، `Say hello in one short sentence` را تایپ کنید و Enter را بزنید. ① پیام شما در گفت‌وگو است.

![ناحیه گفت‌وگو با پیام فرستاده‌شده Say hello in one short sentence و پاسخ Hello! زیر آن](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/20-first-reply.webp)

**گیر کرده‌اید؟ پاسخ به‌جای متن یک خطای سرخ است**

انتخاب‌گر مدل را باز کنید و مطمئن شوید مدل `claude-sonnet-5` زیر `QCode Claude` است، نه یک مدل GPT زیر ارائه‌دهنده OpenAI. مدل‌های Claude فقط از طریق ارائه‌دهنده `Claude API Compatible` با `https://api.qcode.cc/api/v1` پاسخ می‌دهند.



اگر درست پیش بروید این را می‌بینید: ① پیام شما در گفت‌وگو، پاسخ کوتاهی مثل `Hello!` زیرش، و خط کوچکی زیر پاسخ با `claude-sonnet-5` و شمارش توکن.




### پرسیدن یک پیگیری

`Was that last sentence your own answer just now?` را تایپ کنید و Enter را بزنید. ① پیگیری است؛ ② پاسخ مدل به آن.

![همان گفت‌وگو با پرسش پیگیری درباره جمله پیشین و پاسخ مدل زیر آن](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/21-followup-reply.webp)


اگر درست پیش بروید این را می‌بینید: مدل به چیزی که در نوبت پیشین گفته اشاره می‌کند، پس گفت‌وگو بافت خود را نگه می‌دارد.




## بررسی کارکرد

پیکربندی شما کامل است وقتی هر چهار مورد زیر درست باشد:

- در `Settings → Model Provider` ارائه‌دهنده‌ای به نام `QCode Claude` هست، `API Mode` آن `Claude API Compatible` است و `API Host` آن `https://api.qcode.cc/api/v1`.
- خط `Preview` روی آن ارائه‌دهنده `https://api.qcode.cc/api/v1/messages` را می‌خواند و فیلد کلید ردیفی از نقطه نشان می‌دهد.
- `Check` آن ارائه‌دهنده برای `claude-sonnet-5` نتیجه `Connection successful` را گزارش می‌کند.
- پیامی که در یک گفت‌وگوی تازه تایپ می‌کنید پاسخ عادی می‌گیرد، با `claude-sonnet-5` و شمارش توکن زیر پاسخ.

اگر می‌خواهید خود درخواست‌ها را ببینید، **probe.qcode.cc** را باز کنید، همان کلید را بچسبانید و ترافیکی را که به QCode می‌رسد بررسی کنید.


### تمام شد

شما QCode را به Chatbox وصل کرده‌اید و Claude در پنجره گفت‌وگو پاسخ می‌دهد. از اینجا می‌توانید:

- پلن‌ها را در [صفحه قیمت‌ها](https://qcode.cc/fa/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-chatbox-done) مقایسه کنید و مناسب‌ترین را برای استفاده بلندمدت انتخاب کنید
- برای بررسی مصرف و موجودی به [داشبورد](https://qcode.cc/fa/dashboard) برگردید
- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths)
- [مدل‌های چینی](/docs/usage/cn-models)
- [عیب‌یابی](/docs/reference/troubleshooting)


## خطاهای رایج

| متن خطا | علت | چه کار کنید |
|---|---|---|
| `Fetch uses /models while API Path is /v1/chat/completions` | بخش نسخه در `API Host` نیست، پس درخواست فهرست مدل‌ها به مسیر اشتباه می‌رود | نسخه را در Host بگذارید: `https://api.qcode.cc/openai/v1`، و `API Path` را روی `/chat/completions` نگه دارید |
| `API Error: Error from Custom Claude: TypeError: Load failed (api.example.com)` | درخواست هرگز از برنامه خارج نشد: میزبان در پیام قابل دسترسی نبود، یا نشانی اشتباه است یا شبکه آن را مسدود کرده | تقسیم را بررسی کنید: `API Host` برابر `https://api.qcode.cc/api/v1` و `API Path` برابر `/messages`؛ `Preview` باید `https://api.qcode.cc/api/v1/messages` را بخواند. اگر باز شکست خورد، `Improve Network Compatibility` را روشن کنید |
| `API Error: Error from Claude: TypeError: Failed to fetch(192.168.1.206:8080)` | درخواست داخل برنامه و پیش از خروج از دستگاه مسدود می‌شود، معمولاً به‌خاطر محدودیت شبکه WebView | روی ارائه‌دهنده سفارشی `Improve Network Compatibility` را روشن کنید، سپس مطمئن شوید `API Host` برابر `https://api.qcode.cc/api/v1` است |
| `API Error: Error from Custom OpenAl: Network Error: Failed to fetch (api.firefllyai.chat)` | همان محدودیت شبکه روی یک ارائه‌دهنده سفارشی؛ میزبان در پیام همان چیزی است که پیکربندی شده، نه میزبان QCode | برای ارائه‌دهنده سفارشی `Improve Network Compatibility` را روشن کنید، سپس بررسی کنید `API Host` برابر `https://api.qcode.cc/openai/v1` باشد |

## سوالات متداول

### آیا به حساب کاربری Chatbox نیاز دارم؟

خیر. Chatbox یک کلاینت محلی است: روی `Skip guide` در صفحه خوش‌آمد کلیک کنید، نشانی و کلید QCode را وارد کنید و آماده‌اید. هیچ‌جای این آموزش به ورود نیاز ندارد.

### چرا Claude API Host با /v1 تمام می‌شود؟

چون Chatbox آن را نمی‌افزاید. به میزبان Claude سفارشی فقط `/messages` افزوده می‌شود، پس `https://api.qcode.cc/api` به `https://api.qcode.cc/api/messages` تبدیل می‌شد و 404 برمی‌گرداند. نشانی پایه عمومی Anthropic در QCode یعنی `https://api.qcode.cc/api` برای کلاینت‌هایی است که SDKشان خودش `/v1/messages` را می‌افزاید — Cherry Studio این‌طور کار می‌کند، Chatbox نه.

### چرا فهرست مدل‌ها خالی است؟

یک ارائه‌دهنده سفارشی در Chatbox فهرست مدل‌ها را نمی‌گیرد، پس چیزی خودکار نمی‌آید. هر شناسه مدل را با `+ New` دستی اضافه کنید، مثلاً `claude-sonnet-5`، `claude-opus-5-5` یا `claude-haiku-5-5`؛ فهرست کامل در [qcode.cc/models](https://qcode.cc/fa/models) است. شناسه را دقیق و با خط تیره کپی کنید.

### آیا می‌توانم مدل‌های GPT را در همان برنامه استفاده کنم؟

بله. یک ارائه‌دهنده دوم با `API Mode` روی `OpenAI API Compatible`، `API Host` برابر `https://api.qcode.cc/openai/v1`، همان کلید `cr_` و شناسه مدل `gpt-6.2-sol` اضافه کنید. بخش اختیاری زیر آن را قدم‌به‌قدم توضیح می‌دهد. مدل‌ها را با انتخاب‌گر مدل عوض کنید؛ هر ارائه‌دهنده فهرست مدل‌های خودش را نگه می‌دارد.

### کلیدم منقضی شده — می‌توانم تمدیدش کنم؟

بستگی دارد کلید از کجا آمده باشد. کلید پلن شخصی ماهانه پس از انقضا تمدید نمی‌شود: یک پلن تازه باز کنید، در [داشبورد](https://qcode.cc/fa/dashboard) کلید جدید بسازید و مقدار جدید `cr_` را در فیلد `API Key` بچسبانید. کلید بستهٔ پرداخت به‌ازای مصرف با خرید یک بستهٔ دیگر دوباره فعال می‌شود؛ همان کلید است و در Chatbox لازم نیست چیزی را تغییر دهید.

### آیا Chatbox از Gemini از طریق QCode پشتیبانی می‌کند؟

خیر. QCode مدل‌های Gemini را ارائه نمی‌کند. از یک مدل Claude از طریق `Claude API Compatible` استفاده کنید، یا GPT و مدل‌های چینی را از طریق `OpenAI API Compatible`.

## اختیاری: استفاده از مدل‌های GPT هم

QCode مدل‌های GPT و چینی را از طریق پروتکل OpenAI ارائه می‌کند. هر ارائه‌دهنده Chatbox یک پروتکل می‌فهمد، پس این ارائه‌دهنده دومی است با همان کلید. اگر فقط Claude می‌خواهید، از این بخش بگذرید.



### افزودن ارائه‌دهنده‌ای سازگار با OpenAI

دوباره `Settings → Model Provider` را باز کنید و روی `+ Add` و سپس `Add Custom Provider` کلیک کنید. نامش را `QCode OpenAI` بگذارید، `API Mode` را روی `OpenAI API Compatible` قرار دهید و `https://api.qcode.cc/openai/v1` را در ① `API Host` بگذارید — باز هم با بخش نسخه، چون این حالت هم آن را نمی‌افزاید. ② `Preview` باید `https://api.qcode.cc/openai/v1/chat/completions` را بخواند. همان کلید را بچسبانید، سپس شناسه مدل `gpt-6.2-sol` را اضافه کنید؛ ③ آن را در فهرست مدل‌ها نشان می‌دهد.

![ارائه‌دهنده دوم QCode OpenAI: API Host روی https://api.qcode.cc/openai/v1، Preview که /openai/v1/chat/completions را نشان می‌دهد و gpt-6.2-sol در فهرست مدل‌ها](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/17-openai-provider.webp)

**گیر کرده‌اید؟ مدل‌های Claude اینجا پاسخ نمی‌دهند**

ارائه‌دهنده سازگار با OpenAI نمی‌تواند مدل‌های Claude را سرویس دهد. Claude را روی ارائه‌دهنده `QCode Claude` با `https://api.qcode.cc/api/v1` نگه دارید و از این ارائه‌دهنده دوم فقط برای GPT و مدل‌های چینی استفاده کنید.



اگر درست پیش بروید این را می‌بینید: ① با `/openai/v1` تمام می‌شود، ② با `/openai/v1/chat/completions` تمام می‌شود، و ③ `gpt-6.2-sol` را در فهرست مدل‌های `QCode OpenAI` نشان می‌دهد.




### بررسی اتصال GPT

روی `Check` کلیک کنید، وقتی پرسید `gpt-6.2-sol` را انتخاب کنید و منتظر ① `Model Test Results` بمانید.

![Model Test Results برای ارائه‌دهنده QCode OpenAI: gpt-6.2-sol نتیجه Connection successful را گزارش می‌کند](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/18-openai-check-result.webp)


اگر درست پیش بروید این را می‌بینید: ① `Connection successful` برای `gpt-6.2-sol`، یعنی همان کلید روی هر دو ارائه‌دهنده کار می‌کند.




## انواع ارائه‌دهنده و نشانی‌های QCode

Chatbox پروتکل را بر اساس `API Mode` تعیین می‌کند و سپس `API Path` را به `API Host` می‌افزاید. نگاشت را این‌طور ببینید:

| `API Mode` | `API Host` که وارد می‌کنید | `API Path` | `Preview` نشان می‌دهد | مدل‌هایی که کار می‌کنند |
|---|---|---|---|---|
| `Claude API Compatible` | `https://api.qcode.cc/api/v1` | `/messages` | `https://api.qcode.cc/api/v1/messages` | Claude؛ مدل‌های چینی هم روی این نقطه پایانی پاسخ می‌دهند |
| `OpenAI API Compatible` | `https://api.qcode.cc/openai/v1` | `/chat/completions` | `https://api.qcode.cc/openai/v1/chat/completions` | GPT و مدل‌های چینی — نه Claude |
| `Google Gemini API Compatible` | QCode مدل Gemini ارائه نمی‌کند | — | — | هیچ |

- **دو نقطه دسترسی دیگر**: `asia.qcode.cc` و `us.qcode.cc` همان مسیرها و همان کلیدها را می‌پذیرند — `api.qcode.cc` را عوض کنید و بقیه را دست نزنید، شامل `/api/v1` یا `/openai/v1`. اگر میزبان پیش‌فرض از شبکه شما کند است، آن‌ها را امتحان کنید.
- **بخش `/v1` جای‌اش در Host است.** Chatbox فقط Path را می‌افزاید، پس هر دو میزبان QCode بالا با بخش نسخه تمام می‌شوند. این تنها جایی است که Chatbox با کلاینت‌هایی مثل Cherry Studio فرق دارد، که SDKشان `/v1/messages` را به نشانی پایه عمومی Anthropic در QCode یعنی `https://api.qcode.cc/api` می‌افزاید.
- **`Preview` سریع‌ترین بررسی است.** نشانی دقیقی را نشان می‌دهد که Chatbox فراخوانی می‌کند؛ اگر `/api/messages` یا `/openai/chat/completions` را خواند، بخش نسخه در Host نیست.

## مدل‌هایی که می‌توانید استفاده کنید

- **Claude** — از طریق `Claude API Compatible`، مثلاً `claude-sonnet-5`، `claude-opus-5-5`، `claude-haiku-5-5`
- **GPT** — از طریق `OpenAI API Compatible`، مثلاً `gpt-6.2-sol`، `gpt-6.1-terra`
- **مدل‌های چینی** — از طریق `OpenAI API Compatible`، مثلاً `glm-5.3`، `kimi-k3`، `deepseek-v4-pro`
- **Gemini** — QCode آن را ارائه نمی‌کند؛ نشانی‌ای از QCode برای حالت Gemini در Chatbox نیست

هر شناسه مدل با `+ New` دستی اضافه می‌شود و بعداً قابل ویرایش است. فهرست کنونی در **qcode.cc/models** است.

## توضیح تنظیمات کلیدی

| تنظیم | کارش چیست |
|---|---|
| `Name` | فقط یک برچسب برای شما؛ `QCode Claude` کافی است. نام گروه در انتخاب‌گر مدل است |
| `API Mode` | پروتکل و مسیری را که Chatbox می‌افزاید تعیین می‌کند. حالت اشتباه به‌صورت 404 یا امتناع مدل‌های Claude از پاسخ ظاهر می‌شود |
| `API Host` | نشانی تا بخش نسخه و شامل آن: `https://api.qcode.cc/api/v1` یا `https://api.qcode.cc/openai/v1` |
| `API Path` | آخرین بخشی که Chatbox می‌افزاید: `/messages` برای Claude، `/chat/completions` برای OpenAI |
| `Preview` | خط فقط‌خواندنی که نشانی کامل ساخته‌شده از Host و Path را نشان می‌دهد |
| `API Key` | کلید QCode شما که با `cr_` شروع می‌شود، به‌صورت محلی ذخیره و به‌صورت نقطه نشان داده می‌شود |
| `Model ID` | نام دقیق مدل، که در پنجره `Edit Model` دستی تایپ می‌شود |
| `Check` | یک درخواست آزمایشی با مدلی که انتخاب می‌کنید می‌فرستد و `Model Test Results` را گزارش می‌کند |

## محدودیت‌های شناخته‌شده

- **افزودن خودکار `/v1` برای میزبان‌های Claude سفارشی وجود ندارد.** Chatbox `https://api.anthropic.com` را بازنویسی می‌کند تا `/v1` را بیفزاید، اما میزبان سفارشی همان‌طور که تایپ شده استفاده می‌شود؛ فقط `/messages` افزوده می‌شود. به همین دلیل میزبان Claude در QCode اینجا `https://api.qcode.cc/api/v1` است، نه `https://api.qcode.cc/api` عمومی.
- **فهرست خودکار مدل‌ها وجود ندارد.** یک ارائه‌دهنده سفارشی در Chatbox فهرست مدل‌ها را نمی‌گیرد، پس هر شناسه مدل دستی تایپ می‌شود؛ تازه‌سازی فهرست را پر نمی‌کند.
- **یک پروتکل برای هر ارائه‌دهنده.** Claude به ارائه‌دهنده `Claude API Compatible` نیاز دارد و GPT و مدل‌های چینی به `OpenAI API Compatible`؛ همان کلید روی هر دو کار می‌کند.
- **نام دکمه‌ها بین نسخه‌ها فرق می‌کند.** Chatbox 1.24.6 (انگلیسی) می‌گوید `Model Provider`، `+ Add`، `Add Custom Provider` و `Check`؛ نسخه‌های قدیمی‌تر ممکن است واژه‌های دیگری به کار ببرند.

## مستندات مرتبط

- [نقاط پایانی و مسیرهای 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)