# راه‌اندازی Qwen Code

> **آخرین بازبینی**: 2026-10-13 · 📄 بر پایه مستندات رسمی (Qwen Code 0.25.1)

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (در سمت Anthropic تعریف می‌شود) · GPT ✅ · مدل‌های چینی ✅ (در سمت سازگار با OpenAI تعریف می‌شوند) · Gemini ❌ — QCode سری Gemini را ارائه نمی‌دهد، پس از Claude، GPT یا یک مدل چینی استفاده کنید |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · سازگار با OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | تنظیم `modelProviders` در `~/.qwen/settings.json`؛ درون یک نشست: `/auth`، `/model`، `/doctor` |
| مستندات رسمی | [احراز هویت](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/) · [مرجع تنظیمات](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) |

Qwen Code یک دستیار کدنویسی ترمینالی متن‌باز است که روی npm با نام `@qwen-code/qwen-code` منتشر شده؛ این صفحه در برابر نسخه `0.25.1` بررسی شده است. مستندات آن، اتصال «ارائه‌دهندگان شخص ثالث مانند OpenAI، Anthropic، Google، Azure OpenAI، OpenRouter، Requesty، ModelScope یا یک نقطه پایانی خودمیزبان» را زیر احراز هویت با کلید API دسته‌بندی می‌کند — همان مسیر نقطه پایانی که QCode از آن استفاده می‌کند. تنظیم `modelProviders` مشخص می‌کند کدام مدل‌ها وجود دارند و چگونه می‌توان به آن‌ها رسید، و `/model` در زمان اجرا میان آن‌ها جابه‌جا می‌شود.

## کدام پروتکل

| مدل‌هایی که می‌خواهید | کلید `modelProviders` (نوع احراز هویت) | Base URL برای وارد کردن |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT و مدل‌های چینی | `openai` | `https://api.qcode.cc/openai/v1` |

Qwen Code پروتکل را بخشی از کلید ارائه‌دهنده مستند می‌کند: برای ارائه‌دهندگان داخلی، کلید باید یک نوع احراز هویت معتبر باشد (`openai`، `anthropic`، `gemini`، `vertex-ai`). سپس هر ورودی مدل با پروتکل، `id` و `baseUrl` پیکربندی‌شده‌اش شناسایی می‌شود.

🔴 **هرگز Claude را از طریق Base URL سازگار با OpenAI فراخوانی نکنید.** نقطه پایانی OpenAI در QCode شناسه‌های مدل Claude را رد می‌کند؛ پاسخ چنین است: `Model '<id>' is not available on this endpoint`. Claude در سمت `anthropic` با `https://api.qcode.cc/api` پیکربندی می‌شود. شناسه‌های GPT هم در سمت Anthropic ارائه نمی‌شوند.

Base URL را دقیقاً همان‌گونه که در بالا آمده وارد کنید: **بدون اسلش پایانی**، و مسیر درخواست را در این فیلد قرار ندهید — شما پایه را وارد می‌کنید، نه `.../v1/messages` یا `.../chat/completions`. اگر از یک نود منطقه‌ای استفاده می‌کنید، پایه Anthropic به `https://asia.qcode.cc/api` یا `https://us.qcode.cc/api` تبدیل می‌شود؛ کلید همان کلید است.
## نصب

نصب با npm به Node.js 22 یا جدیدتر نیاز دارد:

```bash
npm install -g @qwen-code/qwen-code@latest
```

در macOS و Linux می‌توانید به‌جای آن از Homebrew استفاده کنید:

```bash
brew install qwen-code
```

سپس یک ترمینال در پروژه خود باز کنید و آن را اجرا کنید:

```bash
cd /path/to/your-project
qwen
```

برای مشاهده فهرست دستورها، در صفحه خوش‌آمدگویی `/help` را تایپ کنید.

## پیکربندی Claude (سمت Anthropic)

مسیر پیشنهادی Qwen Code یک فایل واحد است، `~/.qwen/settings.json`. هر کلید زیر عیناً از مستندات آن گرفته شده است: `modelProviders` به‌ازای هر نوع احراز هویت یک آرایه نگه می‌دارد، هر ورودی به یک `id` نیاز دارد، و `name`، `baseUrl` و `generationConfig` اختیاری هستند؛ `envKey` نام متغیر محیطی‌ای را مشخص می‌کند که اعتبارنامه را حمل می‌کند.

```json
{
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-sonnet-5",
        "name": "claude-sonnet-5",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.qcode.cc/api"
      }
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "cr_your_qcode_key"
  },
  "security": {
    "auth": {
      "selectedType": "anthropic"
    }
  },
  "model": {
    "name": "claude-sonnet-5"
  }
}
```

چهار بلوک چه کار می‌کنند، به‌گفته جدول رسمی: `modelProviders` اعلام می‌کند کدام مدل‌ها در دسترس هستند و چگونه به آن‌ها متصل شوید؛ `env` کلیدهای API را به‌عنوان جایگزین در `settings.json` ذخیره می‌کند، و `export` در پوسته و فایل‌های `.env` اولویت دارند؛ `security.auth.selectedType` به Qwen Code می‌گوید در هنگام راه‌اندازی از کدام پروتکل استفاده کند؛ `model.name` مدل پیش‌فرض فعال‌شده در هنگام راه‌اندازی است و باید با یکی از مقادیر `id` شما مطابقت داشته باشد.

پروتکل Anthropic شکل متغیر محیطی هم دارد — Qwen Code برای آن `ANTHROPIC_API_KEY`، `ANTHROPIC_BASE_URL` و `ANTHROPIC_MODEL` را فهرست می‌کند:

```bash
export ANTHROPIC_API_KEY="cr_your_qcode_key"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_MODEL="claude-sonnet-5"
qwen
```

همچنین می‌توانید `/auth` را درون CLI اجرا کنید: سومین گزینه سطح بالای آن، **Custom Provider**، ورودی مستندشده برای اتصال دستی «یک سرور محلی، پروکسی یا ارائه‌دهنده پشتیبانی‌نشده» است و از OpenAI، Anthropic، Gemini و سایر نقاط پایانی سازگار پشتیبانی می‌کند.

> **درباره مسیر Anthropic.** نمونه‌های رسمی Anthropic مقدار `baseUrl` را با پسوند `/v1` می‌نویسند (`"baseUrl": "https://api.anthropic.com/v1"`)، و مستندات مشخص نمی‌کند که نقطه پایانی Anthropic مسیر درخواست را چگونه از یک نشانی پایه می‌سازد. بنابراین این صفحه فقط مقدار مستندشده QCode را بیان می‌کند: `https://api.qcode.cc/api` را وارد کنید و چیزی بیشتر نه. ما نتیجه آزمایش‌شده‌ای را برای هیچ املای دیگری ادعا نمی‌کنیم.
## پیکربندی GPT و مدل‌های چینی (سمت سازگار با OpenAI)

نوع احراز هویت `openai` در مستندات به‌گونه‌ای توصیف شده است که نه‌تنها API خود OpenAI، بلکه هر نقطه پایانی سازگار با OpenAI را نیز پوشش می‌دهد، از جمله ارائه‌دهندگان تجمیعی — که همان نقطه پایانی‌ای است که GPT و مدل‌های چینی QCode روی آن ارائه می‌شوند. قاعده رسمی برای یک دروازه میزبانی‌شده در اینجا اعمال می‌شود: `baseUrl` را روی ریشه `/v1` مربوط به API تنظیم کنید، نه مسیر کامل چت، زیرا SDK خودش مسیر درخواست را اضافه می‌کند. `https://api.qcode.cc/openai/v1` همان ریشه است.

```json
{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-6.1-sol",
        "name": "gpt-6.1-sol",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.qcode.cc/openai/v1"
      },
      {
        "id": "deepseek-v4.1-flash",
        "name": "deepseek-v4.1-flash",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.qcode.cc/openai/v1"
      }
    ]
  },
  "env": {
    "OPENAI_API_KEY": "cr_your_qcode_key"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-6.1-sol"
  }
}
```

تنها `/model` انواع احراز هویت غیرپیش‌فرض را نمایش می‌دهد، بنابراین مدل‌هایی را که می‌خواهید به آرایه اضافه کنید و آن‌ها را همان‌جا انتخاب کنید. شناسه‌های مدل از کاتالوگ QCode می‌آیند: `gpt-6.1-sol`، `gpt-6-sol`، `gpt-5.6-terra`، یا شناسه‌ای چینی مانند [`glm-5.3`](/docs/usage/cn-models)، [`deepseek-v4.1-flash`](/docs/usage/cn-models) یا `qwen3.8-max`.

قالب متغیرهای محیطی از سه متغیری استفاده می‌کند که Qwen Code برای این پروتکل فهرست می‌کند:

```bash
export OPENAI_API_KEY="cr_your_qcode_key"
export OPENAI_BASE_URL="https://api.qcode.cc/openai/v1"
export OPENAI_MODEL="gpt-6.1-sol"
qwen
```

## بررسی

از CLI بپرسید چه می‌بیند:

```text
/doctor
/model
```

`/doctor` روش مستندشده برای بررسی پیکربندی فعلی شما در هر زمان است؛ در جدول فرمان‌های شروع سریع، سطر آن «Check current authentication and environment» است. `/model` انتخاب‌گر را روی ورودی‌هایی که اعلام کرده‌اید باز می‌کند، و جابه‌جایی بدون راه‌اندازی مجدد اعمال می‌شود — ویرایش‌های `modelProviders` در `settings.json` توسط یک نشست تعاملی در حال اجرا دریافت می‌شوند، اما برای دیدن آن‌ها باید `/model` را دوباره باز کنید.

سپس خود نقطه پایانی را مستقل از CLI بررسی کنید. درخواست Anthropic Messages کلید را در `x-api-key` و نسخه را در `anthropic-version` همراه دارد:

```bash
KEY="cr_your_qcode_key"
curl -X POST 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","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

این صفحه از روی مستندات گردآوری شده است، و ما کلید آزمایشی در اختیار نداریم، بنابراین هیچ پاسخی برای آن درخواست در اینجا ادعا نمی‌شود. اگر curl کار کند و CLI کار نکند، تفاوت در `~/.qwen/settings.json` شماست؛ اگر curl شکست بخورد، Base URL یا کلید مشکل دارد — با [عیب‌یابی](/docs/reference/troubleshooting) ادامه دهید.
## عیب‌یابی / محدودیت‌های شناخته‌شده

| نشانه | معنای آن | کاری که باید انجام دهید |
|---|---|---|
| یک شناسه Claude روی Base URL سازگار با OpenAI شکست می‌خورد | QCode مدل Claude را فقط از طریق پروتکل Anthropic ارائه می‌دهد | آن مدل را به آرایه `anthropic` منتقل کنید و `baseUrl` آن را روی `https://api.qcode.cc/api` تنظیم کنید |
| `security.auth.apiKey` یا `security.auth.baseUrl` در پیکربندی شما | هر دو تنظیم به‌عنوان منسوخ مستند شده‌اند، همراه با یادداشتی برای مهاجرت به `modelProviders` (`envKey` برای اولی) | آن‌ها را حذف کنید و مدل را زیر `modelProviders` تعریف کنید |
| `wireApi` تنظیم‌شده روی یک ورودی Anthropic | مستندات این را یک خطای پیکربندی فهرست می‌کنند: `wireApi` یک فیلد سمت OpenAI است | آن را از ورودی‌های Anthropic حذف کنید |
| به نظر می‌رسد `extra_body` هیچ کاری نمی‌کند | این فقط برای ارائه‌دهنده‌های سازگار با OpenAI یعنی `openai` و `qwen-oauth` پشتیبانی می‌شود؛ مستندات بیان می‌کند که برای ارائه‌دهنده‌های Anthropic و Gemini نادیده گرفته می‌شود | برای مدل‌های ارائه‌دهنده، جای مستندشده برای آن `modelProviders[].generationConfig.extra_body` است |
| `model.name` اثری ندارد | باید با یکی از مقادیر `id` در `modelProviders` شما مطابقت داشته باشد | از یک `id` تعریف‌شده استفاده کنید یا مدل را با `/model` انتخاب کنید |
| مدل موردنظر شما در انتخاب‌گر نیست | انواع احراز هویت غیرپیش‌فرض فقط از طریق `/model` در دسترس قرار می‌گیرند و مدل‌های Anthropic باید از طریق `modelProviders` تعریف شوند | ورودی را به `~/.qwen/settings.json` اضافه کنید، سپس `/model` را دوباره باز کنید |

نکات بیشتری که دانستنشان ارزشمند است:

- **Gemini**: Qwen Code را می‌توان برای نوع احراز هویت `gemini` پیکربندی کرد، اما QCode سری Gemini را ارائه نمی‌دهد — از Claude، GPT یا یک [مدل چینی](/docs/usage/cn-models) استفاده کنید.
- **ارائه نمی‌شود**: QCode مدل `gpt-6-luna` یا `gpt-5.6-luna` را ارائه نمی‌دهد؛ مدل GPT دیگری مانند `gpt-6.1-sol`، `gpt-6-sol` یا `gpt-5.6-terra` را انتخاب کنید. اینکه کدام مدل برای کدام کار مناسب است در [انتخاب مدل](/docs/usage/model-selection) پوشش داده شده است.
- **رفتار راه‌اندازی مجدد**: تغییرات `modelProviders` توسط یک نشست در حال اجرا دریافت می‌شوند، در حالی که `providerProtocol` یک بار در زمان شروع خوانده می‌شود و نیاز به راه‌اندازی مجدد دارد.
- **هیچ پرچم اعتبارنامه‌ای در این صفحه وجود ندارد**: صفحات رسمی پرچم Base URL مربوط به OpenAI را به دو شکل متفاوت می‌نویسند، بنابراین اعتبارنامه‌ها را فقط از طریق `~/.qwen/settings.json` یا متغیرهای محیطی پیکربندی کنید.
- **رعایت اصول Base URL**: بدون اسلش انتهایی، و هرگز مسیر درخواست را در `baseUrl` وارد نکنید.
- **هزینه**: صورت‌حساب بر اساس توکن است؛ نرخ‌های هر مدل در [qcode.cc/models](https://qcode.cc/models) فهرست شده‌اند. این صفحه هیچ قیمتی را ذکر نمی‌کند.

## مطالب مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — کدام پروتکل کدام خانواده مدل را ارائه می‌دهد
- [سازگاری ابزارها](/docs/ide/tool-compatibility) — سایر ابزارهای کدنویسی که با پروتکل‌های Anthropic یا سازگار با OpenAI صحبت می‌کنند
- [راه‌اندازی OpenCode](/docs/ide/opencode) — یک CLI ترمینالی دیگر روی همان دو نقطه پایانی
- [مدل‌های چینی](/docs/usage/cn-models)
- [انتخاب مدل](/docs/usage/model-selection)
- [عیب‌یابی](/docs/reference/troubleshooting)