# استفاده از QCode با 9router

[9router](https://github.com/decolua/9router) یک **پروکسی مسیریابی محلی چندارائه‌دهنده هوش مصنوعی** است: سرویسی سازگار با OpenAI را روی دستگاه خودتان اجرا می‌کند (به‌طور پیش‌فرض `http://localhost:20128/v1`)، درخواست‌های ابزارهایی مانند Claude Code، Cursor، Cline و Codex را تحویل می‌گیرد و آن‌ها را بر اساس قواعد شما به چندین ارائه‌دهنده مدل ارسال می‌کند (از جمله جایگزینی خودکار / جابه‌جایی هنگام اتمام سهمیه / فشرده‌سازی خروجی برای صرفه‌جویی در توکن‌ها و غیره). از نظر مفهومی شبیه CCR خود QCode است — تفاوت در این است که 9router روی **دستگاه خودتان** اجرا می‌شود و توسط خودتان مدیریت می‌شود.

> برای مشاهده دقیق قابلیت‌ها، پورت‌ها و رابط کاربری به [مخزن رسمی 9router](https://github.com/decolua/9router) مراجعه کنید؛ این مقاله فقط به «نحوه افزودن QCode به آن» می‌پردازد.

## چه زمانی به آن نیاز دارید

- **اتصال مستقیم به QCode ساده‌تر است**: اگر فقط از QCode استفاده می‌کنید، کافی است BASE_URL ابزار خود را روی `api.qcode.cc` تنظیم کنید — به 9router نیازی ندارید.
- **زمانی که 9router منطقی است**: وقتی می‌خواهید QCode را با سایر ارائه‌دهنده‌ها **ترکیب** کنید (پلن‌های اشتراکی، اعتبارهای تبلیغاتی، خودمیزبان و غیره) و به یک نقطه ورود یکپارچه، جایگزینی خودکار، جابه‌جایی میان ارائه‌دهنده‌ها یا فشرده‌سازی توکن نیاز دارید، می‌توانید QCode را به‌عنوان یکی از ارائه‌دهنده‌های 9router ثبت کنید (به‌عنوان ارائه‌دهنده اصلی یا به‌عنوان یک لایه جایگزین).

## افزودن QCode به‌عنوان ارائه‌دهنده

1. 9router را طبق مستندات آن راه‌اندازی کنید و کنسول محلی را باز کنید (به‌طور پیش‌فرض `http://localhost:20128`).
2. در بخش **«Providers»**، یک ارائه‌دهنده **سفارشی / سازگار با OpenAI (Compatible Node)** اضافه کنید:
   - **نقطه پایانی / Base URL**:
     - چت (خانواده GPT): `https://api.qcode.cc/openai/v1`
     - چت (خانواده Claude، اگر 9router از نودهای پروتکل Anthropic پشتیبانی کند): `https://api.qcode.cc/api`
     - تصویر (اختیاری): `https://api.qcode.cc/qcode-img/v1` (به نکته زیر مراجعه کنید)
     - در چین سرزمین اصلی، دامنه را با `asia.qcode.cc` (نقطه دسترسی نزدیک آسیا) جایگزین کنید.
   - **کلید API**: کلید API شما در QCode (که با `cr_` شروع می‌شود).
   - **مدل‌ها / نام‌های مستعار**: `claude-opus-5`، `claude-sonnet-5`، `gpt-6-sol`، `gpt-5.6-terra` و غیره را بر اساس نیاز ثبت کنید (نسخه‌های 4.x مانند `claude-sonnet-4-6` همچنان به فروش می‌رسند).
3. این ارائه‌دهنده QCode را در **زنجیره لایه‌ها / جایگزینی** خود قرار دهید (مثلاً به‌عنوان ارائه‌دهنده اصلی، یا به‌عنوان یک لایه جایگزین وقتی سهمیه سایر ارائه‌دهنده‌ها تمام می‌شود).
4. ابزارهای خود (Claude Code / Cursor / Cline و غیره) را به نقطه ورود محلی 9router یعنی `http://localhost:20128/v1` اشاره دهید — از آن پس 9router تصمیم می‌گیرد چه زمانی درخواست را به QCode مسیردهی کند.
## QCode مستقیم در برابر QCode از طریق 9router

| | QCode مستقیم | از طریق 9router |
|---|---|---|
| پیچیدگی پیکربندی | کم (یک BASE_URL) | متوسط (باید ارائه‌دهنده / سطح / نام‌های مستعار را تنظیم کنید) |
| جایگزینی چندارائه‌دهنده | هیچ | بله (QCode می‌تواند اصلی یا جایگزین باشد) |
| اشتراک‌گذاری تیمی | بله (سرویس ابری) | خیر (9router فقط محلی است؛ پیکربندی بین اعضا به اشتراک گذاشته نمی‌شود) |
| آمار مصرف | دقیق از طریق داشبورد QCode [probe.qcode.cc](https://probe.qcode.cc) | 9router فقط انتخاب‌های مسیریابی خودش را بازتاب می‌دهد؛ سهمیه‌ها همچنان از داشبورد QCode تبعیت می‌کنند |
| مسیر | مستقیم | یک لایه پروکسی محلی اضافه |

## نکته‌ها

- **فقط محلی**: 9router به‌صورت محلی اجرا می‌شود و پیکربندی آن بین اعضای تیم به اشتراک گذاشته نمی‌شود.
- **مسیریابی تصویر نیاز به آزمایش خودتان دارد**: 9router مسیر `/v1/images/generations` را ارائه می‌دهد، اما «فراخوانی `gpt-image-2` در QCode از طریق 9router» **آزمایش‌نشده** است و ممکن است به پیکربندی اضافی نیاز داشته باشد؛ اگر به قابلیت اطمینان نیاز دارید، تصاویر را از طریق [image-2 مستقیم](/docs/usage/image-2) مسیریابی کنید.
- **سهمیه‌ها از داشبورد QCode تبعیت می‌کنند**: آمار 9router با سهمیه واقعی حساب کاربری QCode شما یکسان نیست (سقف‌های روزانه هر کلید و غیره از داشبورد QCode / [probe.qcode.cc](https://probe.qcode.cc) تبعیت می‌کنند).
- **نگاشت پروتکل به مسیر**: `/openai/v1` از پروتکل OpenAI استفاده می‌کند، `/api` از پروتکل Anthropic استفاده می‌کند، و `/qcode-img/v1` برای تصاویر است — [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) را ببینید.

## نصب و نقطه پایانی محلی (بر اساس README رسمی 9router)

تا تاریخ 2026-10-15، شروع سریع در README رسمی 9router این‌گونه است: با `npm install -g 9router` نصب کنید، آن را با `9router` اجرا کنید و به‌طور پیش‌فرض داشبورد را در `http://localhost:20128` باز کنید. در ابزاری که می‌خواهید به آن متصل شوید، نقطه پایانی را روی `http://localhost:20128/v1` تنظیم کنید و کلید API را از داشبورد 9router کپی کنید. README همچنین بیان می‌کند که نقاط پایانی سازگار با OpenAI / Anthropic سفارشی پشتیبانی می‌شوند و QCode از همین طریق اضافه می‌شود.

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

| مورد در 9router | چه چیزی برای QCode وارد کنید | نکته‌ها |
|---|---|---|
| نوع | سفارشی / سازگار با OpenAI (گره سازگار) | مدل‌های Claude به گره‌ای با پروتکل Anthropic نیاز دارند؛ اینکه رابط کاربری چنین گزینه‌ای ارائه می‌دهد یا نه به 9router بستگی دارد |
| Base URL | `https://api.qcode.cc/openai/v1` (GPT، مدل‌های چینی) یا `https://api.qcode.cc/api` (Claude) | بدون اسلش انتهایی؛ در سرزمین اصلی چین از `asia.qcode.cc` استفاده کنید |
| کلید API | کلید QCode شما که با `cr_` شروع می‌شود | همان کلیدی که برای اتصال مستقیم استفاده می‌کنید |
| مدل / نام مستعار | برای مثال `claude-sonnet-5`، `gpt-6-sol` | نام مستعار فقط نام داخلی 9router است؛ آنچه به QCode می‌رسد باید شناسه واقعی مدل باشد |
| سطح / زنجیره جایگزینی | QCode را در جایگاه اصلی یا جایگزین قرار دهید | 9router ترتیب را تعیین می‌کند؛ QCode فقط درخواست‌هایی را می‌بیند که واقعاً می‌رسند |

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

| نشانه | علت احتمالی | راه‌حل |
|---|---|---|
| ابزار نمی‌تواند به `localhost:20128` دسترسی پیدا کند | 9router در حال اجرا نیست، یا پورت اشغال شده است | بررسی کنید داشبورد در مرورگر باز می‌شود، سپس در ابزار دوباره آزمایش کنید |
| `Invalid API key` | کلید QCode اشتباه یا دارای فاصله اضافی است، یا کلید خود 9router در ارائه‌دهنده QCode وارد شده است | این‌ها دو کلید متفاوت‌اند: ابزار کلید را از داشبورد 9router می‌گیرد و ارائه‌دهنده QCode کلید `cr_` را دریافت می‌کند |
| `model_not_available_on_endpoint` | یک مدل Claude به نقطه پایانی OpenAI مسیریابی شده است | برای Claude یک گره جداگانه با پروتکل Anthropic (`/api`) بسازید؛ به [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) مراجعه کنید |
| 404 | `/v1` در Base URL اضافه یا حذف شده است، یا اسلش انتهایی وجود دارد | با جدول بالا مقایسه کنید |
| مصرف با داشبورد QCode تفاوت دارد | آمار 9router فقط مسیریابی خودش را بازتاب می‌دهد | به داشبورد QCode و [probe.qcode.cc](https://probe.qcode.cc) اعتماد کنید |

ابتدا QCode را مستقیماً با `curl` فراخوانی کنید (بخش 5 از [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths)) تا کلید و مسیر را تأیید کنید، سپس لایه 9router را اشکال‌زدایی کنید. این کار باعث صرفه‌جویی زیادی در رفت‌وبرگشت می‌شود.

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

### اگر فقط از QCode استفاده می‌کنم، آیا به 9router نیاز دارم؟

خیر. اگر فقط از QCode استفاده می‌کنید، BASE_URL ابزار را مستقیماً روی `api.qcode.cc` (یا `asia.qcode.cc` در سرزمین اصلی چین) تنظیم کنید. این ساده‌تر است: یک پراکسی محلی کمتر و یک نقطه کمتر برای بروز مشکل.

### چرا هزینه نمایش‌داده‌شده در 9router با صورت‌حساب QCode من تفاوت دارد؟

اعداد در 9router تخمین‌های خودش بر اساس انتخاب‌های مسیریابی‌اش هستند. QCode بر اساس توکن صورت‌حساب می‌کند، با نرخ‌های هر مدل که در [qcode.cc/models](https://qcode.cc/models) فهرست شده‌اند، و این داشبورد QCode است که واقعاً ملاک است.

### آیا Claude Code می‌تواند از مدل‌های Claude از طریق 9router استفاده کند؟

فقط اگر 9router از یک گره با پروتکل Anthropic پشتیبانی کند و شما آدرس `/api` مربوط به QCode را به‌عنوان چنین گره‌ای پیکربندی کرده باشید. با تنها یک گره سازگار با OpenAI، مدل‌های Claude رد می‌شوند. رابط کاربری دقیق در مخزن رسمی 9router توضیح داده شده است.

### چگونه تأیید کنم درخواست‌هایی که از 9router عبور می‌کنند واقعاً به QCode می‌رسند؟

کلید `cr_` خود را در [probe.qcode.cc](https://probe.qcode.cc) وارد کنید؛ اگر مدل و توکن‌های درخواست را می‌بینید، درخواست رسیده است. در غیر این صورت، بررسی کنید که آیا ارائه‌دهنده QCode در سطح / زنجیره جایگزینی 9router قرار دارد و آیا به اندازه کافی در ابتدای آن قرار گرفته است.

---

> یک کلید API در دو پروتکل (Anthropic / OpenAI) کار می‌کند، چه مستقیماً متصل شوید و چه از طریق روتری مانند 9router. درباره [قیمت‌گذاری QCode.cc](https://qcode.cc/pricing) اطلاعات کسب کنید.