# راه‌اندازی Claude Desktop

> **آخرین بازبینی**: 2026-09-18 · 📄 طبق مستندات رسمی (مستندات درگاه استنتاج شخص ثالث؛ نسخه برنامه در صفحه رسمی منتشر نشده است)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (پروتکل Anthropic) · مدل‌های چینی (GLM / Kimi / DeepSeek / Qwen، ارائه‌شده روی نقطه پایانی Anthropic) ✅ · GPT ❌ · Gemini ❌ |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` (سرزمین اصلی چین: `https://asia.qcode.cc/api`، بدون `/v1`) |
| محل پیکربندی | درون برنامه: راهنما → عیب‌یابی → فعال‌سازی حالت توسعه‌دهنده → توسعه‌دهنده → پیکربندی استنتاج شخص ثالث |
| مستندات رسمی | [اتصال درگاه LLM](https://code.claude.com/docs/en/llm-gateway-connect) |

[Claude Desktop](https://claude.com/download) برنامه دسکتاپ رسمی Anthropic (Windows / macOS / Linux) است؛ جایگزینی محلی برای برنامه وب claude.ai برای مدیریت جریان‌های کاری PowerPoint، Excel، سند و MCP. برنامه دسکتاپ به‌تازگی یک نقطه ورود **پیکربندی استنتاج شخص ثالث** اضافه کرده است که به شما امکان می‌دهد هر درگاه سازگار با Anthropic را به‌عنوان بک‌اند استنتاج تنظیم کنید، بدون ورود به حساب کاربری Anthropic. این راهنما نشان می‌دهد چگونه QCode.cc را در Claude Desktop متصل کنید تا بتوانید **از اشتراک Pro صرف‌نظر کنید و از سهمیه موجود QCode خود دوباره استفاده کنید**.

## چرا از API شخص ثالث استفاده کنیم

- **استفاده از سهمیه QCode شما در دسکتاپ**: جریان‌های کاری PowerPoint / Excel / MCP در دسکتاپ می‌توانند مستقیماً از سهمیه QCode شما استفاده کنند
- **Cowork تحت مدیریت حساب Claude شما است**: [Claude Cowork](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork) توسط اشتراک و تنظیمات سازمان شما کنترل می‌شود، و مستندات رسمی **هرگز** ترکیب آن با یک درگاه استنتاج شخص ثالث را توصیف نمی‌کنند (به یادداشت قرمز زیر مراجعه کنید)
- **سهمیه یکپارچه**: Claude Desktop، Claude Code و Codex CLI همگی از همان کلید API QCode استفاده می‌کنند
- **چندین خانواده مدل**: درگاه QCode.cc مدل‌های Anthropic (Opus 5 / 4.7، Sonnet 5 / 4.6، Haiku 4.5)، OpenAI و مدل‌های چینی را ارائه می‌دهد
- **استقرار تیمی**: پنل پیکربندی می‌تواند یک پروفایل JSON را خروجی بگیرد که آن را از طریق Jamf، Intune یا Group Policy برای اعضای تیم ارسال می‌کنید
## پیش‌نیازها

- Claude Desktop نصب‌شده ([دانلود رسمی](https://claude.com/download)، Windows / macOS / Linux)
- یک کلید API از QCode.cc (که با `cr_` شروع می‌شود)، در دسترس از [داشبورد](https://qcode.cc/dashboard)
- کاربران Windows 10/11: در نخستین نصب ممکن است از شما خواسته شود Virtual Machine Platform را فعال کنید و سیستم را دوباره راه‌اندازی کنید (فقط یک بار)

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

### مرحله 1: نخستین اجرا — وارد نشوید

> نکته: در حالت خارج‌شده از حساب، ممکن است دکمه منو در گوشه بالا-چپ به کلیک پاسخ ندهد. روی فیلد ورودی ایمیل کلیک کنید تا فوکوس بگیرد، سپس **Tab** را بزنید تا به دکمه منو بروید و Enter را بزنید تا باز شود.

### مرحله 2: فعال‌سازی حالت توسعه‌دهنده

روی **Menu → Help → Troubleshooting → Enable Developer Mode** کلیک کنید.

![فعال‌سازی حالت توسعه‌دهنده](/static/images/claude-desktop/1-help-menu.png)

پس از فعال‌سازی، گزینه جدید **Developer** در نوار منوی بالا ظاهر می‌شود.

### مرحله 3: باز کردن پیکربندی استنتاج شخص ثالث

روی **Menu → Developer → Configure Third-Party Inference...** کلیک کنید.

![باز کردن پیکربندی استنتاج شخص ثالث](/static/images/claude-desktop/2-dev-menu.png)

### مرحله 4: وارد کردن اعتبارنامه‌های گیت‌وی

در بخش Connection، حالت **Gateway** (سازگار با Anthropic) را انتخاب کنید و فیلدها را مطابق شکل پر کنید:

![وارد کردن اعتبارنامه‌های گیت‌وی](/static/images/claude-desktop/3-config.png)

| فیلد | مقدار |
|-------|-------|
| Base URL گیت‌وی | `https://asia.qcode.cc/api` |
| کلید API گیت‌وی | کلید API شما در QCode.cc (که با `cr_` شروع می‌شود) |
| روش احراز هویت گیت‌وی | **مقدار پیش‌فرض `bearer` را حفظ کنید** (گیت‌وی QCode.cc هم bearer و هم x-api-key را می‌پذیرد و نیازی به تغییر نیست) |
| هدرهای اضافی گیت‌وی | خالی بگذارید |

> به انتهای Base URL یک `/` اضافه **نکنید** — Claude Desktop به‌طور خودکار مسیرهای `/v1/messages`، `/v1/models` و مسیرهای دیگر را اضافه می‌کند.

### مرحله 5: اعمال پیکربندی

روی **Apply locally** در گوشه پایین-راست کلیک کنید. پیکربندی روی سیستم شما نوشته می‌شود و بلافاصله اعمال می‌شود، و فهرست کشویی مدل به‌طور خودکار با بیش از 25 مدل ارائه‌شده توسط QCode.cc پر می‌شود. برای شروع استفاده، در پنجره اصلی یک گفتگوی جدید باز کنید.

## انتخاب Base URL گیت‌وی

> **توجه**: نقطه پایانی‌ای را انتخاب کنید که با موقعیت مکانی شما مطابقت دارد:

| موقعیت مکانی شما | Base URL گیت‌وی |
|----------|------------------|
| چین سرزمین اصلی (توصیه‌شده) | `https://asia.qcode.cc/api` |
| چین سرزمین اصلی (جایگزین) | `https://api.qcode.cc/api` |
| خارج از چین سرزمین اصلی | `https://api.qcode.cc/api` |

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

در شرایط عادی، Claude Desktop نقطه پایانی `/v1/models` را فراخوانی می‌کند و منوی کشویی به‌طور خودکار با فهرست کامل پر می‌شود. **هیچ مرحله اضافه‌ای لازم نیست.**

اگر منوی کشویی خالی بماند (نادر است و به محیط بستگی دارد)، می‌توانید آن را به‌صورت دستی پر کنید:

1. در پنل پیکربندی، روی **Export ▾ → Open in file manager** کلیک کنید و فایل پیکربندی JSON مربوط به Claude Desktop را پیدا کنید
2. یک آرایه `inferenceModels` به JSON اضافه کنید:

```json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://asia.qcode.cc/api",
  "inferenceGatewayApiKey": "cr_xxxxxxxx",
  "inferenceModels": [
    "claude-opus-5",
    "claude-opus-4-7",
    "claude-sonnet-5",
    "claude-haiku-5-5"
  ]
}
```

3. ذخیره کنید و Claude Desktop را **کاملاً ببندید و دوباره اجرا کنید** (نه فقط بستن پنجره)

## استقرار تیمی (MDM)

دکمه **Export ▾** در گوشه پایین سمت راست، پیکربندی فعلی را به‌صورت JSON خروجی می‌دهد؛ این خروجی با ابزارهای MDM سازمانی برای استقرار گروهی جفت می‌شود — بدون پیکربندی دستی برای هر عضو تیم:

- macOS: یک پروفایل پیکربندی در سطح کاربر را از طریق Jamf یا Mosyle ارسال کنید
- Windows: از طریق Intune یا Group Policy به `%APPDATA%\Claude\` ارسال کنید
- Linux: از طریق Ansible یا Puppet در `~/.config/Claude/` بنویسید

Anthropic هیچ راهنمای رسمی MDM برای این JSON خروجی منتشر نکرده است؛ آنچه می‌توانید به آن تکیه کنید توانایی استقرار فایل در ابزار MDM خودتان است. برای تنظیمات مدیریت‌شده، [تنظیمات مدیریت‌شده Claude Code](https://code.claude.com/docs/en/managed-settings) را ببینید — این یک سازوکار Claude Code است، نه اپلیکیشن دسکتاپ

## سهمیه مشترک

Claude Desktop، CLI مربوط به Claude Code و CLI مربوط به Codex همگی از همان کلید API واحد QCode.cc استفاده می‌کنند و **در همان سهمیه پلن شریک‌اند**. ورود از چند کلاینت باعث دو بار صورت‌حساب شدن نمی‌شود. برای قواعد کامل قیمت‌گذاری، [صورت‌حساب](/docs/reference/billing) را ببینید.

## Claude Cowork

[Claude Cowork](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork) رسماً چنین توصیف شده است: معماری عامل کدنویسی Claude Code را بدون ترمینال به اشتراک می‌گذارد؛ شما یک نتیجه را توصیف می‌کنید، رهایش می‌کنید و بعد به اسناد قالب‌بندی‌شده، فایل‌های مرتب‌شده یا پژوهشی ترکیب‌شده بازمی‌گردید. همان مقاله می‌گوید که **نشست‌های Cowork در حال حاضر به‌صورت راه‌دور در ابر اجرا می‌شوند (بتا)**، به حساب کاربری Claude شما متصل‌اند و در دسکتاپ، وب و موبایل قابل پیگیری هستند؛ چون عامل‌محور و متصل به اینترنت است، Anthropic [راهنمای ایمنی](https://support.claude.com/en/articles/13364135-use-claude-cowork-safely) را نیز منتشر می‌کند

> 🔴 **ادعای اینکه اتصال QCode بدون Pro قابلیت Cowork را باز می‌کند پس گرفته شده است.** مستندات رسمی دروازه، Claude Code و سطوح آن را پوشش می‌دهد و **هرگز به Cowork اشاره نمی‌کند**؛ مقاله پشتیبانی که این صفحه پیش‌تر به آن استناد می‌کرد («نصب و پیکربندی Claude Cowork با پلتفرم‌های شخص ثالث») از تاریخ 2026-09-18 خطای 404 برمی‌گرداند، پس چیزی باقی نمانده که بتوان ادعا را با آن بررسی کرد. با Cowork مانند قابلیتی رفتار کنید که تابع پلن Claude و تنظیمات سازمان شماست و آن را در مصرف QCode حساب نکنید

### دروازه دسکتاپ در واقع کدام سطوح را پوشش می‌دهد

بر پایه مستندات رسمی ([اتصال Claude Code به دروازه LLM](https://code.claude.com/docs/en/llm-gateway-connect))، آنچه از دروازه خودتان عبور می‌کند **Claude Code و سطوح آن** است: افزونه VS Code، اپلیکیشن Desktop، GitHub Actions، Agent SDK و همچنین Slack / نشست‌های ابری / Remote Control. در سمت دسکتاپ، پس از پیکربندی استنتاج شخص ثالث، گفتگوها، Skills و فراخوانی‌های MCP که در آنجا انجام می‌دهید به دروازه‌ای می‌روند که تنظیم کرده‌اید — مراحل این صفحه همین را پوشش می‌دهد.

- **مدل را انتخاب کنید**: درون یک وظیفه به‌صراحت `claude-opus-5` یا `claude-sonnet-5` را انتخاب کنید (`claude-opus-4-7` هنوز به فروش می‌رسد) و به پیش‌فرض تکیه نکنید
- **اولین اجرا**: اپلیکیشن دسکتاپ ممکن است بار اول یک محیط اجرا دانلود کند (چند صد مگابایت) — منتظر بمانید تا کامل شود
- **چه چیزی مصرف QCode محسوب می‌شود**: فقط درخواست‌هایی که واقعاً از دروازه QCode خارج می‌شوند از پلن QCode شما برداشت می‌کنند؛ قواعد صورت‌حساب در [صورت‌حساب](/docs/reference/billing) آمده است
- **Cowork در آن فهرست نیست**: یادداشت سرخ بالا را ببینید — روی این حساب نکنید که «Cowork پس از اتصال QCode کار می‌کند»
- **برخی اتصال‌دهنده‌ها هنوز به حساب کاربری Anthropic نیاز دارند**: اتصال‌دهنده‌های سطح بالاتر مانند Google Drive یا Notion ممکن است همچنان به ورود به Anthropic نیاز داشته باشند؛ فهرست قابلیت‌ها در [شروع کار با Claude Cowork](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork) آمده است
## محدودیت‌ها و تفاوت‌ها

- **برنامه وب claude.ai پشتیبانی نمی‌شود**: پشتیبانی از API شخص ثالث ویژگی‌ای فقط مخصوص دسکتاپ است؛ مرورگر همچنان به حساب کاربری Anthropic شما هدایت می‌شود
- **حالت دروازه = فقط نشست‌های محلی**: طبق عبارت رسمی — انتخاب‌گر محیط هیچ نشست SSH و هیچ محیط ابری میزبانی‌شده توسط Anthropic ارائه نمی‌دهد؛ روی میزبان راه دور، CLI را همان‌جا با متغیرهای دروازه تنظیم‌شده اجرا کنید
- **Remote Control در دسترس نیست** تا زمانی که پیکربندی دروازه فعال است (رسمی)؛ همچنین به هویت claude.ai نیاز دارد که یک دروازه شخص ثالث آن را ارائه نمی‌دهد
- **`Gateway was unreachable`** طبق بیانیه رسمی یعنی برنامه در زمان راه‌اندازی نتوانسته به Base URL پیکربندی‌شده دسترسی پیدا کند — URL و مسیر شبکه را با یک آزمون curl بررسی کنید (به [عیب‌یابی](/docs/reference/troubleshooting) مراجعه کنید)

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

### منوی کشویی مدل خالی است

1. بررسی کنید که Base URL **هیچ** `/` پایانی نداشته باشد
2. تأیید کنید که کلید API کامل است و با `cr_` شروع می‌شود
3. اگر هنوز خالی است، از «یادداشت‌های فهرست مدل» پیروی کنید و `inferenceModels` را به‌صورت دستی در JSON پر کنید

### خطای 401 Unauthorized

1. کلید API باید با `cr_` شروع شود و هیچ فاصله ابتدایی یا انتهایی نداشته باشد
2. در [qcode.cc/dashboard](https://qcode.cc/dashboard) بررسی کنید که کلید هنوز معتبر است
3. شمای احراز هویت دروازه را روی مقدار پیش‌فرض `bearer` بگذارید — آن را به `x-api-key` تغییر ندهید

### تفاوت «اعمال محلی» و «خروجی گرفتن»

- **اعمال محلی**: در فایل پیکربندی محلی می‌نویسد و بلافاصله برای کاربر فعلی اعمال می‌شود
- **خروجی گرفتن**: یک فایل JSON برای استقرار MDM تیمی یا پشتیبان‌گیری صادر می‌کند

### آیا می‌توانم برنامه دسکتاپ و CLI را هم‌زمان اجرا کنم؟

بله. Claude Desktop و CLIهای Claude Code / Codex هرکدام پیکربندی خود را به‌طور مستقل می‌خوانند (برنامه دسکتاپ JSON خودش را می‌خواند؛ CLI فایل `~/.claude/settings.json` یا `~/.codex/config.toml` را می‌خواند). آن‌ها همان کلید API و سهمیه QCode را بدون تعارض به اشتراک می‌گذارند.

### این موضوع چه ارتباطی با CC Switch دارد؟

[CC Switch](/docs/ide/cc-switch) مدیریت جابه‌جایی Base URL و اعتبارنامه برای ابزارهای CLI (Claude Code، Codex و غیره) را بر عهده دارد؛ Claude Desktop پیکربندی حالت توسعه‌دهنده خود را مستقل اجرا می‌کند. این دو، دو شکل مختلف کلاینت را هدف می‌گیرند و جداگانه عمل می‌کنند.

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

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — مرجع کامل سه پروتکل و سه دامنه ورودی QCode.cc
- [آموزش Claude Code](/docs/getting-started/claude-code-tutorial) — به‌طور کامل بر گردش‌کار CLI مسلط شوید
- [راه‌اندازی CC Switch](/docs/ide/cc-switch) — چند Base URL مربوط به CLI را از یک برنامه مدیریت کنید
- [صورتحساب](/docs/reference/billing) — پلن‌ها و سهمیه را درک کنید