# راه‌اندازی Qoder با QCode (BYOK)

> **آخرین بازبینی**: 2026-11-10 · 📄 بر اساس مستندات رسمی (Qoder 0.5.7 و Qoder CLI 1.1.86، هر دو منتشرشده در 2026-11-09؛ مستندات در 2026-11-10 خوانده شد)

## یک نگاه کلی

| مورد | جزئیات |
|---|---|
| معرفی | Qoder خانواده‌ای از محصولات عامل کدنویسی است: اپلیکیشن دسکتاپ Qoder، Qoder CLI (`qoder`)، Qoder IDE و یک افزونه JetBrains. این صفحه اپلیکیشن دسکتاپ و CLI را پوشش می‌دهد. سایت جهانی qoder.com است (مستندات در docs.qoder.com)؛ سایت چین Qoder CN است (مستندات در docs.qoder.cn) |
| کلید API اختصاصی؟ | بله. بر اساس صفحه رسمی مدل‌های سفارشی، Qoder از مدل‌های ارائه‌دهندگان شخص ثالث از طریق کلید API، از جمله نقاط پایانی سفارشی، پشتیبانی می‌کند. نسخه: صفحه CLI می‌گوید «Available edition: Individual plan»؛ یادداشت انتشار نسخه دسکتاپ می‌گوید «Personal plan BYOK» |
| محل پیکربندی | دسکتاپ: **Settings** → **Models** → **Add model** → **Provider** → **Custom**. CLI: `/model` → زبانه **Custom** → **Add custom model...** |
| پروتکل‌ها | **OpenAI Compatible** (سپس **Chat Completions API** یا **Responses API**) · **Anthropic Compatible** |
| مقادیر QCode | Anthropic Compatible: `https://api.qcode.cc/api` · OpenAI Compatible: `https://api.qcode.cc/openai/v1` |
| مدل‌های قابل استفاده | Claude ✅ (Anthropic Compatible) · GPT ✅ (OpenAI Compatible) · GLM / Kimi / DeepSeek / Qwen ✅ (با هر یک از دو پروتکل) · Gemini ❌ (QCode فعلاً مدل‌های Gemini را ارائه نمی‌دهد) |
| مستندات رسمی | [مدل‌های سفارشی (جهانی)](https://docs.qoder.com/qoder/custom-models) · [مدل‌های سفارشی (چین)](https://docs.qoder.cn/qoder/custom-models) · [مدل‌های سفارشی CLI](https://docs.qoder.com/cli/custom-models) · [یادداشت‌های انتشار](https://changelog.qoder.com/app) |

Qoder IDE، محصولی جداگانه در همین خانواده، صفحه مدل‌های سفارشی اختصاصی خود را دارد (docs.qoder.com/user-guide/chat/custom-models) که فقط ارائه‌دهندگان از پیش تعیین‌شده را فهرست می‌کند. Base URL سفارشی در اپلیکیشن دسکتاپ Qoder (از نسخه 0.1.8، 2026-09-05) و در Qoder CLI — که کاربران نسخه شخصی، آن‌ها را از صفحه Custom در `/model` مدیریت می‌کنند (از نسخه 1.1.50، 2026-09-11) — در دسترس است؛ این صفحه همان دو مورد را پوشش می‌دهد.
## کدام پروتکل

فرم نقطه پایانی سفارشی دو نوع ارائه‌دهنده ارائه می‌دهد، و **سازگار با OpenAI** گزینه دومی برای نوع API دارد. ردیفی را انتخاب کنید که با خانواده مدل مطابقت دارد:

| انتخاب Qoder | Base URL | شناسه‌های مدل (نمونه‌ها) |
|---|---|---|
| **سازگار با Anthropic** | `https://api.qcode.cc/api` | `claude-sonnet-5-5`، `claude-opus-5-5`، `deepseek-v4.1-flash`، `glm-5.3` |
| **سازگار با OpenAI** + **Chat Completions API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`، `deepseek-v4.1-flash`، `glm-5.3`، `kimi-k3`، `qwen3.8-max` |
| **سازگار با OpenAI** + **Responses API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`، `gpt-6.1-terra` |

مدل‌های Claude فقط روی پروتکل Anthropic کار می‌کنند، پس شناسه‌های `claude-…` را پشت **سازگار با Anthropic** قرار دهید؛ مدل‌های GPT فقط روی دو پروتکل OpenAI کار می‌کنند. چهار خانواده چینی روی هر دو کار می‌کنند. برای جدول کامل، [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) را ببینید و شناسه‌های مدل را از [qcode.cc/models](https://qcode.cc/models) کاراکتربه‌کاراکتر کپی کنید.

**فرم Base URL.** به گفته خود Qoder: «Base URL دقیقی را که سرویس مدل ارائه می‌دهد وارد کنید. Qoder قالب نمونه را به‌صورت https://api.example.com/v1 نمایش می‌دهد.» آن نمونه به `/v1` ختم می‌شود، بنابراین برای گزینه‌های OpenAI، URL مربوط به QCode را که به `/v1` ختم می‌شود وارد کنید. برای گزینه Responses API این کار جواب می‌دهد چون QCode مسیرهای `/openai/responses` و `/openai/v1/responses` را یکسان ارائه می‌دهد. مستندات Qoder نمی‌گویند Qoder کدام مسیر را برای **سازگار با Anthropic** اضافه می‌کند. با Base URL مربوط به Anthropic در QCode، یعنی `https://api.qcode.cc/api` (بدون اسلش انتهایی) شروع کنید. اگر **اعتبارسنجی و افزودن مدل** شکست خورد، `https://api.qcode.cc/api/v1` را وارد کنید و دوباره اعتبارسنجی کنید: هر دو به همان نقطه پایانی QCode یعنی `/api/v1/messages` می‌رسند، و تنها تفاوت این است که Qoder خودش چند بخش مسیر اضافه می‌کند.

در آسیا یا آمریکای شمالی می‌توانید دامنه را با `asia.qcode.cc` یا `us.qcode.cc` عوض کنید؛ مسیرها یکسان می‌مانند.

## نصب

اپلیکیشن دسکتاپ را از [صفحه دانلود Qoder](https://qoder.com/download) (macOS 12+، Windows 10+ یا Linux) دانلود کنید و وارد شوید. برای CLI، همان صفحه موارد زیر را فهرست می‌کند:

```sh
# macOS / Linux
curl -fsSL https://qoder.com/install | bash

# Windows PowerShell
irm https://qoder.com/install.ps1 | iex
```

Qoder CN اپلیکیشن و مستندات خودش را در docs.qoder.cn دارد. نسخه‌ای را که اجرا می‌کنید با نسخه‌های بالا بررسی کنید.
## پیکربندی

### دسکتاپ: تنظیمات → مدل‌ها

این‌ها مراحل صفحه رسمی مدل‌های سفارشی هستند، با عبارت‌پردازی رابط کاربری مستندات انگلیسی:

1. **تنظیمات** را باز کنید، سپس در ناوبری سمت چپ **مدل‌ها** را انتخاب کنید.
2. روی **افزودن مدل** کلیک کنید. برای یک نقطه پایانی سفارشی، **ارائه‌دهنده** را باز کنید و زیر **سفارشی**، **سازگار با OpenAI** یا **سازگار با Anthropic** را انتخاب کنید.
3. برای **سازگار با OpenAI**، **Chat Completions API** یا **Responses API** را انتخاب کنید.
4. **Base URL**، کلید API خود و حداقل یک **شناسه مدل** را وارد کنید. برای پیکربندی مدل‌های بیشتر برای همان نقطه پایانی، روی **افزودن شناسه مدل** کلیک کنید.
5. قابلیت‌هایی را که صفحه فهرست می‌کند پیکربندی کنید: **نام نمایشی**، **پنجره زمینه** (مقادیر پشتیبانی‌شده را انتخاب کنید، سپس یک **پنجره زمینه پیش‌فرض**)، **بینایی** (وقتی مدل تصاویر را می‌پذیرد آن را روشن کنید) و **تفکر** (وقتی مدل از استدلال پشتیبانی می‌کند آن را روشن کنید، سپس سطوح تلاش آن را انتخاب کنید).
6. روی **اعتبارسنجی و افزودن مدل** کلیک کنید. «Qoder اتصال را اعتبارسنجی می‌کند و مدل را پس از موفقیت اعتبارسنجی ذخیره می‌کند.»
7. مدل جدید را در رابط چت انتخاب کنید.

مقادیری که باید برای QCode وارد کنید (جای‌نگهدار کلید `cr_xxx`):

| فیلد | سازگار با Anthropic | سازگار با OpenAI |
|---|---|---|
| Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| نوع API | — | **Chat Completions API** (یا **Responses API** برای GPT) |
| کلید API | `cr_xxx` | `cr_xxx` |
| شناسه مدل | `claude-sonnet-5-5` | `gpt-6.1-sol` |

برای هر پروتکلی که نیاز دارید یک ورودی اضافه کنید؛ هر ورودی Base URL خودش را دارد.

**تفاوت‌های جهانی و CN.** ارائه‌دهنده‌های از پیش تعیین‌شده‌ای که در صفحه جهانی فهرست شده‌اند عبارت‌اند از Alibaba Cloud Model Studio، DeepSeek، Z.ai، Kimi، MiniMax، Xiaomi MIMO، OpenAI، Google و OpenRouter. صفحه CN شامل Alibaba Cloud Model Studio، DeepSeek، Zhipu، Kimi، MiniMax و Xiaomi MIMO است، بدون OpenAI، Google و OpenRouter. هر دو همان دو ارائه‌دهنده سفارشی، **سازگار با OpenAI** و **سازگار با Anthropic**، و همان مراحل را فهرست می‌کنند.

برای تغییر کلید در ادامه، از عملیات **ویرایش** در پنل **مدل‌ها** استفاده کنید؛ گزینه **حذف** مدل را حذف می‌کند.

### CLI: /model → سفارشی

1. Qoder CLI را اجرا کنید و `/model` را وارد کنید.
2. به تب **سفارشی** بروید.
3. **افزودن مدل سفارشی...** را انتخاب کنید و Enter را فشار دهید.
4. از ویزارد پیروی کنید: «Provider → model type → model»، سپس کلید API و هر اطلاعات دیگری را که درخواست می‌کند وارد کنید.
5. پس از موفقیت اعتبارسنجی، پیکربندی به‌طور خودکار ذخیره می‌شود و مدل بلافاصله قابل انتخاب است. آن را از تب **سفارشی** انتخاب کنید؛ برای حذف مدل، در آنجا روی یک مدل `d` را فشار دهید.

صفحه رسمی همچنین می‌گوید: «BYOK را به‌صورت دستی در settings.json پیکربندی نکنید؛ ارائه‌دهنده‌ها، مدل‌ها و فیلدهای اعتبارنامه موجود توسط کاتالوگ BYOK قابل‌دسترس برای حساب کاربری فعلی تعیین می‌شوند.» صفحه CLI فیلدهای ویزارد را فهرست نمی‌کند. یادداشت انتشار CLI 1.1.50 می‌گوید کاربران نسخه شخصی می‌توانند مدل‌های BYOK را «با نقاط پایانی URL سفارشی از صفحه سفارشی در /model» پیکربندی کنند، و حساب رسمی Qoder در X آن را به‌صورت وارد کردن Base URL، شناسه مدل و کلید API توصیف کرده است. برای آن فیلدها از مقادیر QCode در جدول بالا استفاده کنید.
## بررسی

1. مدلی را که اضافه کرده‌اید انتخاب کنید و یک پیام کوتاه مانند `ping` بفرستید.
2. [probe.qcode.cc](https://probe.qcode.cc) را باز کنید، کلید QCode خود را وارد کنید و بررسی کنید که درخواست با همان مدل نمایش داده می‌شود.
3. برای آزمایش کلید و مسیر بدون Qoder:

```bash
KEY="cr_your_key"

# OpenAI Compatible, Chat Completions API
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-6.1-sol","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

# Anthropic Compatible
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

## عیب‌یابی

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

| بررسی رسمی | در QCode |
|---|---|
| «اینکه Base URL کامل است و پروتکل سازگار و نوع API انتخاب‌شده با نقطه پایانی مطابقت دارند» | سازگار با Anthropic → `https://api.qcode.cc/api` (یا `https://api.qcode.cc/api/v1`، به بالا مراجعه کنید)؛ سازگار با OpenAI → `https://api.qcode.cc/openai/v1`، بدون `/` در انتها |
| «اینکه کلید API درست است و فاصله اضافی ندارد، و منقضی یا غیرفعال نشده است» | کلید `cr_` را دوباره بدون فاصله بچسبانید |
| «اینکه شناسه مدل درست است و برای حساب کاربری ارائه‌دهنده قابل دسترسی است» | شناسه را از [qcode.cc/models](https://qcode.cc/models) کپی کنید |
| «اینکه حساب کاربری ارائه‌دهنده موجودی کافی دارد» | موجودی را در داشبورد QCode خود بررسی کنید |
| «اینکه اتصال شبکه عادی است» | `asia.qcode.cc` یا `us.qcode.cc` را با همان مسیرها امتحان کنید |

دو پیام مخصوص QCode وجود دارد: `model_not_available_on_endpoint` یعنی یک شناسه `claude-…` زیر یک گزینه OpenAI اضافه شده است؛ بنابراین آن را به‌جای آن زیر **سازگار با Anthropic** اضافه کنید؛ این یک ناسازگاری پروتکل است، نه مشکل کلید. `Invalid API key` یک مشکل کلید است.

صفحه رسمی درباره CLI می‌گوید: اگر زبانه **Custom** یا گزینه افزودن وجود ندارد، تأیید کنید که BYOK برای حساب کاربری و پلن فعلی در دسترس است؛ اگر ارائه‌دهنده یا مدلی وجود ندارد، کاتالوگ زنده ویزارد مرجع نهایی است.

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

- رسمی: «تولید تصویر و ویدیو در حال حاضر هنگام استفاده از مدل‌های متصل‌شده با کلید API خودتان (BYOK) در دسترس نیست.»
- رسمی: هزینه‌های مدل سفارشی به حساب API ارائه‌دهنده شما صورت‌حساب می‌شوند و «از Qoder Credits استفاده نمی‌کنند». Repo Wiki از یک مدل ثابت استفاده می‌کند و همچنان Qoder Credits مصرف می‌کند.
- Qoder نمونه `https://api.example.com/v1` را فقط به‌عنوان یک قالب نمایش می‌دهد؛ مستندات توضیح نمی‌دهند که Qoder برای هر پروتکل کدام مسیر را اضافه می‌کند، بنابراین نتیجه **Validate and add model** حرف آخر را می‌زند.
- QoderWork یک محصول جداگانه است. صفحه مدل‌های آن سطح‌های Premium، Advanced و Standard به‌همراه Qwen3.7-Max و Qwen3.7-Plus را فهرست می‌کند و تا تاریخ 2026-11-10 ورودی مدل سفارشی ندارد. صفحه دانلود Qoder می‌گوید QoderWork در 5 سپتامبر 2027 عملیات خود را متوقف می‌کند و جابه‌جایی به Qoder Desktop را توصیه می‌کند که شامل ابزارهای ورود داده است.
- سطح مدل Lite در 18 سپتامبر 2026 ساعت 14:00 به وقت سنگاپور (UTC+8)، بر اساس اطلاعیه رسمی، از انتخاب‌گر مدل حذف شد.

## مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — جدول پروتکل × خانواده مدل
- [مرور سازگاری ابزارها](/docs/ide/tool-compatibility) — کدام ابزارها با کدام پروتکل صحبت می‌کنند
- [DeepSeek Harness](/docs/ide/deepseek-harness) — ابزار دیگری با فرم مدل سفارشی
- [LobsterAI](/docs/ide/lobsterai) — یک عامل دسکتاپ که ارائه‌دهندگان سفارشی آن نیز قالب‌های Anthropic و OpenAI را می‌پذیرند
- [مدل‌های چینی](/docs/usage/cn-models) — شناسه‌ها و مسیرهای GLM / Kimi / DeepSeek / Qwen
- [راهنمای BYOK مدل سفارشی Qoder در qcode.cc](https://qcode.cc/en/qoder-custom-model-byok-setup) — تاریخ‌ها و پیشینه