# راه‌اندازی Base URL سفارشی و کلید API در Cursor

> **آخرین بازبینی**: 2026-10-20 · 📄 طبق مستندات رسمی (صفحه دانلود Cursor هنوز در 2026-10-20 نسخه 3.24 را به‌عنوان آخرین نسخه فهرست می‌کند، و جدیدترین ورودی فهرست تغییرات تاریخ 2026-10-16 دارد؛ صفحه راهنمای BYOK همان روز بررسی شد؛ پاسخ انجمن به تاریخ 2026-08-11 درباره فیلدهای Override به‌عنوان سابقه نگه داشته شده است)

**بله.** Cursor به شما اجازه می‌دهد کلید API خودتان را وارد کنید و گزینه Override OpenAI Base URL (یا Override Anthropic Base URL) را روشن کنید تا به QCode اشاره کند؛ در نتیجه Chat، Composer و Inline Edit روی QCode اجرا می‌شوند. تکمیل با Tab همچنان از مدل‌های داخلی Cursor استفاده می‌کند، و درخواست‌ها هنوز برای ساخت نهایی prompt از بک‌اند Cursor عبور می‌کنند.

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (Override Anthropic Base URL) · GPT ✅ · مدل‌های چینی ✅ (Override OpenAI Base URL؛ درخواست‌ها همچنان توسط سرورهای Cursor رله می‌شوند) · Gemini ❌ (QCode در حال حاضر Gemini را ارائه نمی‌دهد) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` — در فیلدهای Override در Settings → Models وارد می‌شود (مکان و باگ شناخته‌شده: بخش بعدی) |
| محل پیکربندی | Settings → Models درون برنامه (بخش API Keys) |
| مستندات رسمی | [cursor.com/docs](https://cursor.com/docs) |

## فیلدها کجا هستند و یک باگ شناخته‌شده

**محل وارد کردن URL، Settings → Models → API Keys است.** صفحه راهنمای BYOK در Cursor ([cursor.com/help/models-and-usage/api-keys](https://cursor.com/help/models-and-usage/api-keys)) فقط چهار مرحله را فهرست می‌کند: **Cursor Settings → Models** را باز کنید، ارائه‌دهنده را انتخاب کنید (OpenAI، Anthropic، Google، Azure یا AWS Bedrock)، **کلید API خود را در فیلد متنی بچسبانید**، روی **Save** کلیک کنید — اما فیلدهای Override را برنمی‌شمارد. این فیلدها وجود دارند؛ deanrie، از کارکنان Cursor، آن‌ها را در انجمن رسمی نام برد:

> «اصلاح فیلدهای OpenAI API Key و Override OpenAI Base URL، و سایر فیلدهای کلید ارائه‌دهنده، که با کلیک ماوس فوکوس نمی‌گرفتند، ادغام شده و در به‌روزرسانی 3.15 آینده منتشر خواهد شد. هنوز در 3.15.6 نیست. پس از به‌روزرسانی به نسخه‌ای جدیدتر از 3.15.6، لطفاً دوباره تلاش کنید.» (2026-08-11، [رشته اصلی](https://forum.cursor.com/t/regression-models-openai-api-key-base-url-inputs-not-editable-in-3-15-6-ok-in-3-14-27/167685))

سه نکته قابل اجرا:

- این فیلدها **Override OpenAI Base URL** (پروتکل OpenAI) و **Override Anthropic Base URL** (پروتکل Anthropic) هستند و هر کدام سوئیچ فعال‌سازی جداگانه دارند.
- **3.15.6 یک رگرسیون شناخته‌شده دارد**: ماوس نمی‌تواند روی آن ورودی‌ها فوکوس کند. راه‌حل موقت رسمی این است که سوئیچ مربوطه را در **Settings → Models** روشن کنید، سپس **Tab** را فشار دهید تا فوکوس به فیلد منتقل شود — پس از آن تایپ کردن و Ctrl+V کار می‌کنند. بازگشت به 3.14.27 هم کار می‌کند. اصلاح در به‌روزرسانی‌ای پس از 3.15.6 منتشر می‌شود، بنابراین به نسخه‌ای بالاتر از 3.15.6 ارتقا دهید و دوباره تلاش کنید (بازبینی‌شده در 2026-10-20: صفحه دانلود هم‌اکنون نسخه 3.24 را دارد، و این پاسخ انجمن به تاریخ 2026-08-11 به‌عنوان سابقه تاریخی دوره 3.15.6 نگه داشته شده است).
- همان صفحه عیناً می‌گوید: «کلید API شما روی سرورهای ما ذخیره نمی‌شود. با هر درخواست به بک‌اند ما فرستاده می‌شود چون **همه درخواست‌ها برای ساخت نهایی prompt از سرورهای Cursor عبور می‌کنند**» — حتی با کلید خودتان، درخواست‌ها از بک‌اند Cursor عبور می‌کنند؛ ویرایشگر مستقیماً با ارائه‌دهنده مدل شما صحبت نمی‌کند.

سه محدودیت دیگر و یک ریسک زمانی:

- در پلن‌های تیمی / سازمانی، **نرخ توکن Cursor حتی با کلید خودتان نیز اعمال می‌شود**، و توضیح BYOK برای OpenAI محدود به «مدل‌های چت استاندارد، غیراستدلالی» است.
- برای اینکه ترافیک کاملاً خارج از بک‌اند Cursor بماند، به کلاینتی نیاز دارید که از Base URL سفارشی پشتیبانی کند: [Claude Code](/docs/getting-started/installation)، [Codex CLI](/docs/ide/codex)، [Cline](/docs/ide/cline)، [Zed](/docs/ide/zed) و موارد مشابه.
- **ریسک زمانی**: در بیانیه‌ای به تاریخ 2026-08-28، OpenAI نوشت که «قصد دارد قرارداد خود برای ارائه مدل‌های OpenAI به Cursor را به‌تدریج متوقف کند، با تاریخ **پیشنهادی** قطع سرویس در 12 نوامبر 2026» — پیشنهادی، و هنوز لازم‌الاجرا نیست. Cursor تا 2026-09-18 هیچ اطلاعیه متناظری منتشر نکرده است. منبع: [openai.com](https://openai.com/index/our-decision-on-cursor-following-its-acquisition-by-spacex/).

[Cursor](https://cursor.com) یک ویرایشگر بومی هوش مصنوعی است که روی VS Code ساخته شده است. فهرست تغییرات Cursor بر اساس شماره نسخه سازمان‌دهی نشده است و جدیدترین ورودی آن تاریخ 2026-10-16 را دارد؛ صفحه دانلود در 2026-10-20 نسخه 3.24 را به‌عنوان آخرین نسخه فهرست کرده بود. این راهنما توضیح می‌دهد چگونه QCode.cc را به Cursor متصل کنید — اما ابتدا بخش بعدی را بخوانید، چون تعیین می‌کند که آیا این مسیر اصلاً برای شما کار می‌کند یا نه.
## چرا از Cursor استفاده کنید

- **Agents Window** (جدید در v3): چندین عامل هوش مصنوعی را به‌صورت موازی در نوار کناری و بدون تداخل اجرا کنید
- **Cursor Composer**: ویرایش چندفایلی با بازآرایی آگاه به زمینه، مناسب‌تر از Cursor Chat برای تغییرات بزرگ
- **Inline Edit (Cmd+K)**: کد را انتخاب کنید و یک دستور را به‌صورت درون‌خطی صادر کنید — سریع‌ترین چرخه تکرار
- **ساخته‌شده بر VS Code**: کل اکوسیستم افزونه‌های VS Code را به ارث می‌برد (از جمله افزونه VS Code مربوط به Claude Code)

## پیش‌نیازها

- [Cursor](https://cursor.com/download) نصب شده باشد (macOS / Windows / Linux)
- یک کلید API از QCode.cc (با شروع `cr_`) که از [داشبورد](https://qcode.cc/dashboard) در دسترس است
- همان کلید API در همه پروتکل‌های QCode و هر سه دامنه ورودی (`api` / `asia` / `us`) کار می‌کند؛ کاربران در سرزمین اصلی چین بهتر است `asia.qcode.cc` را ترجیح دهند

## مدل‌های موجود

جدول زیر شناسه‌های مدل‌هایی را فهرست می‌کند که معمولاً در QCode استفاده می‌کنیم (فهرست زنده و قیمت‌ها در [qcode.cc/models](https://qcode.cc/models))؛ این‌ها دقیقاً همان چیزهایی هستند که در Cursor تایپ می‌کنید. مکان فیلدها و باگ ورودی 3.15.6 در بخش بالا توضیح داده شده است.

| مدل | زمینه | مناسب برای |
|-------|------|------|
| `claude-opus-5-5` | 1M | پرچم‌دار؛ بازآرایی‌های پیچیده / زمینه بلند |
| `claude-sonnet-5-5` | 1M | مدل کاری روزمره، ارزش عالی |
| `claude-haiku-5-5` | 1M | تکمیل‌های سریع / کارهای سبک |
| `gpt-6.1-sol` | 1.05M | پرچم‌دار OpenAI، پیش‌فرض توصیه‌شده |
| `gpt-6-sol` | 1.05M | GPT-6 Sol |
| `gpt-6-astra` | ببینید [qcode.cc/models](https://qcode.cc/models) | قوی‌ترین رده، قیمت ممتاز |
| `gpt-5.6-terra` | 272K | متمرکز بر کد |

> QCode در حال حاضر نه سری Gemini را ارائه می‌دهد و نه gpt-6-luna / gpt-5.6-luna را. جدول بالا توصیه فعلی است؛ `claude-opus-5`، `claude-sonnet-5`، `claude-sonnet-4-6`، `claude-opus-4-8` و موارد دیگر همچنان قابل فراخوانی هستند. مدل‌های قابل فراخوانی و نرخ‌ها در [qcode.cc/models](https://qcode.cc/models) آمده‌اند.

## مراحل پیکربندی

دو مسیر زیر به دو فیلد Override نگاشت می‌شوند؛ **مسیر A (پروتکل OpenAI) بهترین سازگاری را دارد**. اگر ورودی‌ها فوکوس نمی‌گیرند، از راه‌حل موقت Tab در بالا استفاده کنید یا نسخه را به بالاتر از 3.15.6 به‌روزرسانی کنید.

### مسیر A: نقطه پایانی سفارشی سازگار با OpenAI (توصیه‌شده)

از پروتکل OpenAI برای ارتباط با مسیر `/openai/v1` در QCode استفاده کنید که **مدل‌های GPT و چهار خانواده چینی** (GLM / Kimi / DeepSeek / Qwen) را ارائه می‌دهد.

> 🔴 **این مسیر نمی‌تواند Claude را ارائه دهد.** نقطه پایانی OpenAI در QCode فقط آن دو گروه را می‌پذیرد؛ شناسه `claude-…` خطای `model_not_available_on_endpoint` را برمی‌گرداند. QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد. برای Claude از مسیر B زیر استفاده کنید. [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) را ببینید.

1. تنظیمات Cursor را باز کنید: `Cmd + ,` (macOS) / `Ctrl + ,` (Windows/Linux)
2. **Models** → به پایین اسکرول کنید و **Override OpenAI Base URL** را پیدا کنید
3. موارد زیر را پر کنید:

   | فیلد | مقدار |
   |-------|-------|
   | OpenAI API Key | کلید API QCode.cc شما (با شروع `cr_`) |
   | Override OpenAI Base URL | `https://api.qcode.cc/openai/v1` |

4. در فهرست **Models**، مدل‌هایی را که می‌خواهید فعال کنید علامت بزنید (مثلاً `gpt-6.1-sol`، `gpt-5.6-terra`)؛ برای هر مدلی که فهرست نشده است، روی **+ Add model** کلیک کنید و شناسه مدل را به‌صورت دستی وارد کنید
5. برای آزمایش اتصال روی **Verify** کلیک کنید؛ پس از موفقیت، می‌توانید از آن در Cursor Chat / Composer استفاده کنید

> **Base URL نباید با اسلش پایانی تمام شود.** یک درخواست خودآزمایی QCode کد `401` را برمی‌گرداند، که یعنی مسیر درست است و فقط احراز هویت وجود ندارد — این طبیعی است و تأیید می‌کند که نقطه پایانی قابل دسترسی است.

مرجع Base URL برای هر پروتکل (همان کلید برای همه آن‌ها کار می‌کند):

| پروتکل | Base URL | آنچه SDK اضافه می‌کند | استفاده در Cursor |
|----------|----------|------|------|
| OpenAI Chat | `https://api.qcode.cc/openai/v1` | `/chat/completions` | ✅ این را برای مسیر A وارد کنید |
| OpenAI Responses (سبک Codex) | `https://api.qcode.cc/openai` | `/v1/responses` | معمولاً نیازی به وارد کردن دستی نیست |
| Anthropic | `https://api.qcode.cc/api` | `/v1/messages` | مسیر B / Claude Code CLI |

### مسیر B: نقطه پایانی سفارشی Anthropic (پروتکل بومی Claude)

اگر می‌خواهید از پروتکل بومی Anthropic برای مدل‌های Claude استفاده کنید، Base URL مربوط به Anthropic در QCode برابر `https://api.qcode.cc/api` است (SDK به‌طور خودکار `/v1/messages` را اضافه می‌کند).

در تنظیمات Cursor، **Models → Anthropic API** را باز کنید، کلید QCode خود را وارد کنید و **Override Anthropic Base URL** را با آدرس بالا فعال کنید.

> 🔴 **دو Override با یکدیگر تداخل دارند.** بر اساس گزارش کاربران: وقتی **Override OpenAI Base URL** تنظیم می‌شود، Cursor ترافیک Claude را نیز به همان نقطه پایانی OpenAI هدایت می‌کند و مدل‌های Claude با خطای 422 شکست می‌خورند. **مستندات Cursor این رفتار را ثبت نکرده است** — این یک مشاهده از سوی جامعه کاربران است و ممکن است با نسخه‌ها تغییر کند.   **برای استفاده از Claude، فقط Override مربوط به Anthropic را تنظیم کنید و Override مربوط به OpenAI را خالی بگذارید.** اگر به هر دو نیاز دارید، از پروفایل‌های جداگانه Cursor استفاده کنید یا بر اساس نیاز جابه‌جا شوید.

> ⚠️ در حالت Agent، برخی قابلیت‌ها از سبکی از OpenAI Responses API استفاده می‌کنند که در برخی سناریوها با مسیر پروتکل Anthropic ناسازگار است (معمولاً تبدیل اسکیما برای برخی فراخوانی‌های ابزار شکست می‌خورد). گزینه‌های فعال‌سازی نقطه پایانی Cursor هرازگاهی تغییر می‌کنند، بنابراین **به مستندات رسمی Cursor مراجعه کنید**.
## کدام قابلیت‌ها روی نقطه پایانی سفارشی کار می‌کنند

Cursor قابلیت‌های هوش مصنوعی خود را به چند دسته تقسیم می‌کند و یک نقطه پایانی سفارشی OpenAI آن‌ها را با درجات متفاوت پوشش می‌دهد. جدول زیر ارزیابی عملی بر اساس مشاهدات فعلی است؛ Cursor اغلب به‌روزرسانی می‌شود، بنابراین **حرف آخر را مستندات رسمی Cursor می‌زند**:

| قابلیت | پشتیبانی از نقطه پایانی سفارشی | نکات |
|---------|------|------|
| Cursor Chat | ✅ پایدار | مستقیماً از Base URL پیکربندی‌شده شما عبور می‌کند |
| Composer (ویرایش چندفایلی) | ✅ پایدار | یک شناسه مدل فعال انتخاب کنید |
| Inline Edit (Cmd+K) | ✅ کار می‌کند | نکته تأخیر را در پایین ببینید |
| Cursor Tab (تکمیل درون‌خطی) | ❌ از نقطه پایانی سفارشی استفاده نمی‌کند (رسمی) | صفحه BYOK مربوط به Cursor (2026-10-20): «کلیدهای API سفارشی فقط با مدل‌های چت کار می‌کنند. تکمیل Tab همچنان از مدل‌های داخلی Cursor استفاده می‌کند.» |
| Agents Window / عامل‌های پس‌زمینه | ⚠️ وابسته به نسخه | پایدارترین حالت روی پروتکل‌های رایج OpenAI/Anthropic؛ برخی زیرقابلیت‌های عامل ممکن است به مدل‌های داخلی Cursor نیاز داشته باشند |
| Bug Bot / ایندکس‌سازی و سایر قابلیت‌های مدیریت‌شده | ⚠️ وابسته به نسخه | چنین قابلیت‌هایی ممکن است فقط با مدل‌های داخلی Cursor در دسترس باشند |

به‌طور خلاصه: **سه‌گانه Chat / Composer / Inline Edit قابل‌اعتمادترین روی نقطه پایانی QCode است**؛ قابلیت‌های به‌شدت مدیریت‌شده (بخش‌هایی از جریان عامل) ممکن است روی مدل‌های خود Cursor باقی بمانند. ردیف Tab اکنون از عبارت‌پردازی رسمی پیروی می‌کند (بررسی‌شده در 2026-10-20، جدول بالا را ببینید)؛ بقیه این بخش مشاهده است، نه مستندات رسمی — اعلامیه‌های Cursor را دنبال کنید.

## یک جریان کاری معمول

پس از پیکربندی نقطه پایانی، یک جریان کاری روزمره Composer تقریباً چنین است:

1. یک مدل در Composer انتخاب کنید (مثلاً `claude-sonnet-5-5` برای کار روزمره، `claude-opus-5-5` برای تغییرات بزرگ)
2. Composer را با `Cmd + I` باز کنید و فایل‌هایی را که می‌خواهید ویرایش کنید به ناحیه زمینه بکشید
3. هدف را با زبان طبیعی توصیف کنید، مثلاً «مدیریت وضعیت این کامپوننت را از useState به useReducer مهاجرت بده، بدون تغییر propsهای موجود»
4. diff را بررسی کنید و بلوک‌به‌بلوک بپذیرید / رد کنید
5. برای ویرایش‌های محلی سریع، به‌جای باز کردن Composer در هر بار، از Inline Edit (`Cmd + K`) استفاده کنید

کل این جریان روی نقطه پایانی QCode که پیکربندی کرده‌اید اجرا می‌شود و سهمیه طبق قواعد [صورتحساب](/docs/reference/billing) تسویه می‌شود.
## سایر نقاط ورود

| نقطه پایانی | OpenAI Base URL | Anthropic Base URL |
|----------|-----------------|--------------------|
| جهانی (توصیه‌شده برای کاربران خارج از چین) | `https://api.qcode.cc/openai/v1` | `https://api.qcode.cc/api` |
| آسیا (توصیه‌شده برای سرزمین اصلی چین) | `https://asia.qcode.cc/openai/v1` | `https://asia.qcode.cc/api` |
| آمریکای شمالی / اروپا | `https://us.qcode.cc/openai/v1` | `https://us.qcode.cc/api` |

این سه دامنه نقاط ورود متفاوتی به یک سرویس واحد هستند و **همان کلید API روی هر سه کار می‌کند**. برای مرجع کامل، [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) را ببینید.

## ورودی تصویر در برابر تولید تصویر

- **ورودی تصویر (به مدل اجازه دهید تصویر را «ببیند»)**: Cursor به شما اجازه می‌دهد اسکرین‌شات‌ها / ماکت‌های طراحی را در گفتگو جای‌گذاری یا بکشید تا مدلی دارای قابلیت بینایی بتواند آن‌ها را بخواند — برای نمونه، ساخت یک کامپوننت از یک طرح UI یا اشکال‌زدایی از روی اسکرین‌شات خطا. مدل‌های دارای قابلیت بینایی در QCode شامل Claude Opus 5.5 / Sonnet 5.5 / Haiku 5.5 و مدل‌های GPT (مانند gpt-6.1-sol و gpt-5.6-terra) هستند.
- **تولید تصویر (به مدل اجازه دهید «رسم کند»)**: این موضوع متفاوتی است. برای تولید تصویر، از مدل `gpt-image-2` در QCode از طریق نقطه پایانی اختصاصی تصویر استفاده کنید — **نه در جریان ویرایشگر Cursor**. [تولید تصویر gpt-image-2](/docs/usage/image-2) را ببینید.

## استفاده در کنار Claude Code

هوش مصنوعی داخلی Cursor با [Claude Code CLI](/docs/getting-started/installation) مستقل تعارضی ندارد — هر دو می‌توانند کنار هم در همان پنجره Cursor اجرا شوند:

- **Cursor Chat / Composer**: هوش مصنوعی درون‌ویرایشگر که از نقطه پایانی پیکربندی‌شده در تنظیمات Cursor استفاده می‌کند
- **Claude Code CLI**: `claude` را در ترمینال یکپارچه Cursor اجرا کنید (``Ctrl + ` ``)؛ این ابزار از متغیر محیطی `ANTHROPIC_BASE_URL` مخصوص خود CLI استفاده می‌کند

Claude Code را از ترمینال یکپارچه به QCode (پروتکل Anthropic) اشاره دهید:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_key"
claude
```

این دو مسیر به‌صورت مستقل احراز هویت می‌کنند، اما استفاده از همان کلید API QCode در هر دو به معنای **سهمیه مشترک** است (برای جزئیات [صورتحساب](/docs/reference/billing) را ببینید). [زیرعامل‌ها](/docs/advanced/subagents) و [اتوماسیون و CI/CD](/docs/advanced/headless) در Claude Code هر دو به‌طور مستقیم در این ترمینال کار می‌کنند.
## محدودیت‌ها و نکات

- **Privacy Mode**: Cursor به‌طور پیش‌فرض قطعه‌کدها را به نقطه پایانی پیکربندی‌شده می‌فرستد. اگر Privacy Mode را در تنظیمات Cursor فعال کرده‌اید، تأیید کنید که پیکربندی کلید API همچنان به شما امکان دسترسی به QCode را می‌دهد؛ Privacy Mode بر ترافیک خروجی تأثیری ندارد و فقط مانع ذخیره promptهای شما توسط خود Cursor می‌شود
- **اشتراک Cursor Pro** و کلید API QCode دو سیستم مستقل هستند — Cursor Pro سهمیه داخلی Cursor را به شما می‌دهد (با استفاده از مخزن مدل خود Cursor)، در حالی که کلید API QCode از سرویس QCode عبور می‌کند. وقتی هر دو فعال باشند، مسیریابی از اولویت پیکربندی‌شده در Cursor پیروی می‌کند
- **Agents Window و عامل‌های پس‌زمینه** با ارائه‌دهندگان جریان اصلی (پروتکل‌های OpenAI / Anthropic) بهترین کارایی را دارند؛ سرورهای مدل متن‌باز خودمیزبان نتیجه قابل اتکایی ندارند
- **بازنویسی یک سوئیچ سراسری است**: پر کردن Override OpenAI Base URL درخواست‌هایی را که به‌طور پیش‌فرض از پروتکل OpenAI استفاده می‌کنند به QCode هدایت می‌کند، و پاک کردن آن به پیش‌فرض Cursor بازمی‌گردد. اما بر اساس عبارت رسمی، درخواست‌ها همچنان برای ساخت prompt از بک‌اند Cursor عبور می‌کنند، بنابراین این فرض که «فقط ترافیک جابه‌جا شده و چیز دیگری تغییر نکرده است» برقرار نیست
- **Zero Data Retention برای کلید خود شما اعمال نمی‌شود** (صفحه BYOK در Cursor، بررسی‌شده در 2026-10-20): وقتی از کلید API خودتان استفاده می‌کنید، سیاست Zero Data Retention در Cursor اعمال نمی‌شود؛ مدیریت داده از سیاست حریم خصوصی ارائه‌دهنده انتخابی شما (OpenAI، Anthropic، Google، Azure یا AWS) پیروی می‌کند
- **Teams و Enterprise همچنان Cursor Token Rate را پرداخت می‌کنند** (صفحه BYOK در Cursor، بررسی‌شده در 2026-10-20): حتی با کلید خودتان، هر درخواست به مدل شخص ثالث در Teams / Enterprise با Cursor Token Rate برابر با $0.25 به‌ازای هر یک میلیون توکن (ورودی، خروجی و کش‌شده) محاسبه می‌شود؛ در پلن‌های فردی (Premium، Super و Ultra و همچنین پلن‌های قدیمی Pro)، درخواست‌های با کلید خودتان از مصرف شامل‌شده شما کسر نمی‌شود

## نکات کاربردی

- **برای هر کار یک مدل انتخاب کنید**: در مسیر B (Anthropic، `https://api.qcode.cc/api`)، `claude-sonnet-5-5` بهترین ارزش را برای ویرایش روزمره ارائه می‌دهد و `claude-opus-5-5` بازآرایی‌های بزرگ را مدیریت می‌کند؛ در مسیر A (OpenAI)، `gpt-5.6-terra` را برای تکمیل کد محض و `gpt-6.1-sol` را برای کارهای عمومی امتحان کنید
- **برای زمینه طولانی، رده 1M را ترجیح دهید**: مدل‌های با پنجره زمینه 1M مانند `claude-opus-5-5` / `gpt-6.1-sol` برای تغییرات Composer که کل یک مخزن را وارد می‌کنند مناسب‌اند
- **در هزینه صرفه‌جویی کنید**: یک مدل رده میانی را به‌عنوان پیش‌فرض Composer تنظیم کنید و فقط برای مسائل دشوار به‌صورت دستی به یک مدل پرچمدار تغییر دهید
- **از نزدیک‌ترین نقطه پایانی استفاده کنید**: در سرزمین اصلی چین، Base URL را به نقطه ورود آسیا `https://asia.qcode.cc/openai/v1` تغییر دهید (توصیه‌شده برای سرزمین اصلی)
- **وقتی رفتار عجیب شد، ابتدا Verify را بزنید**: رفتار نقطه پایانی می‌تواند پس از به‌روزرسانی Cursor تغییر کند، بنابراین پیش از پیگیری مسائل دیگر یک بار روی **«Verify»** کلیک کنید
## پرسش‌های متداول

### Cursor خطای «API key not valid» را گزارش می‌کند

1. بررسی کنید که کلید API کامل است، با `cr_` شروع می‌شود و فاصله اضافی در ابتدا یا انتها ندارد
2. در تنظیمات Cursor روی **Verify** کلیک کنید تا خطای مشخص را ببینید
3. اتصال را از خط فرمان آزمایش کنید:
   ```bash
   curl -H "Authorization: Bearer YOUR_KEY" \
        https://api.qcode.cc/openai/v1/models
   ```
   اگر پاسخ یک فهرست JSON باشد، هم نقطه پایانی و هم کلید API درست هستند

### Verify شکست می‌خورد اما curl کار می‌کند

این معمولاً به‌دلیل **اسلش انتهایی در Base URL** یا مسیری است که `/v1` ندارد. تأیید کنید که `https://api.qcode.cc/openai/v1` (پروتکل OpenAI) را بدون `/` انتهایی وارد کرده‌اید. توجه: درخواست مستقیم به مسیر پایه و دریافت `401` طبیعی است (مسیر درست است، احراز هویت وجود ندارد) و به معنای اشتباه بودن پیکربندی نیست.

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

Composer به‌طور پیش‌فرض از پروتکل OpenAI استفاده می‌کند و نقطه پایانی OpenAI در QCode **مدل‌های Claude را نمی‌پذیرد** — افزودن `claude-opus-5-5` به فهرست **Models** کمکی نمی‌کند، زیرا درخواست با `model_not_available_on_endpoint` رد می‌شود.

به‌جای آن از **مسیر B** استفاده کنید: در **Models → Anthropic API**، کلید QCode خود را وارد کنید، گزینه **Override Anthropic Base URL** را با `https://api.qcode.cc/api` روشن کنید و **Override OpenAI Base URL** را پاک کنید (در غیر این صورت Cursor ترافیک Claude را به نقطه پایانی OpenAI می‌فرستد و 422 برمی‌گرداند).

### Inline Edit (Cmd+K) کند است

Cmd+K در Cursor به‌طور پیش‌فرض از مدل سریع خود Cursor استفاده می‌کند؛ با تغییر به QCode، مسیر‌یابی از طریق Base URL پیکربندی‌شده انجام می‌شود، بنابراین تأخیر نخستین توکن کمی بیشتر از گزینه داخلی Cursor است (یک پرش اضافی). در تنظیمات می‌توانید **Cursor Tab** را روی پیش‌فرض Cursor نگه دارید و در همان حال **Chat / Composer** را از نقطه پایانی QCode عبور دهید.

### پنجره Agents / عامل‌های پس‌زمینه خطا می‌دهند یا از QCode استفاده نمی‌کنند

برخی زیرقابلیت‌های عامل، الزاماتی برای منبع مدل دارند و ممکن است استفاده از مدل‌های داخلی Cursor را به‌جای یک نقطه پایانی سفارشی تحمیل کنند. این موضوع از سمت Cursor طراحی‌شده است و بین نسخه‌ها تغییر می‌کند، بنابراین **به مستندات رسمی Cursor مراجعه کنید**؛ می‌توانید Chat / Composer را به QCode تغییر دهید و در همان حال جریان‌های عامل را روی پیش‌فرض Cursor باقی بگذارید.

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

تأیید کنید که در فهرست **Models** هم مدل را **تیک** زده‌اید و هم شناسه آن را به‌درستی از طریق **+ Add model** وارد کرده‌اید (حساس به بزرگی و کوچکی حروف، بدون فاصله اضافی). پس از تغییر، Cursor را یک بار دوباره راه‌اندازی کنید تا فهرست به‌روز شود.

## گام‌های بعدی

- [یکپارچه‌سازی با VS Code](/docs/ide/vscode) — ویرایشگری از همان خانواده با الگوهای پیکربندی مشترک
- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — مرجع کامل سه پروتکل و سه دامنه ورودی QCode.cc
- [تولید تصویر با gpt-image-2](/docs/usage/image-2) — نقطه پایانی اختصاصی تولید تصویر
- [زیرعامل‌ها](/docs/advanced/subagents) — شیوه استفاده از زیرعامل Claude Code
- [اتوماسیون و CI/CD](/docs/advanced/headless) — جریان‌های کاری headless
- [آموزش Claude Code](/docs/getting-started/claude-code-tutorial) — مرجع جریان کاری CLI
- [صورتحساب](/docs/reference/billing) — قواعد مشترک سهمیه

> هنوز کلید API ندارید؟ یک پلن را در [qcode.cc/pricing](https://qcode.cc/pricing) انتخاب کنید — یک کلید در Cursor، Claude Code و هر ابزاری که از نقاط پایانی سفارشی پشتیبانی می‌کند کار می‌کند.