# یکپارچه‌سازی Cline

> **آخرین بازبینی**: 2026-09-18 · 📄 بر اساس مستندات رسمی (افزونه VS Code نسخه 4.1.19، منتشر شده در 2026-09-17؛ Cline Desktop در ادامه)

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (مسیر A: ارائه‌دهنده Anthropic) · GPT ✅ · مدل‌های چینی ✅ (مسیر B: OpenAI Compatible) · Gemini ❌ (هیچ مسیر Gemini در اینجا مستند نشده است) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | تنظیمات افزونه VS Code (API Provider + «Use custom base URL»)؛ برنامه دسکتاپ از همان منطق پیروی می‌کند |
| مستندات رسمی | [cline.bot](https://cline.bot) · [GitHub](https://github.com/cline/cline) |

[Cline](https://github.com/cline/cline) یک افزونه محبوب کدنویسی با هوش مصنوعی برای VS Code است (میلیون‌ها نصب) که از هر مدل هوش مصنوعی و نقاط پایانی API سفارشی پشتیبانی می‌کند. این افزونه با حالت‌های دوگانه Plan / Act، پیش‌نمایش تفاوت ویرایش فایل، اجرای ترمینال و فراخوانی ابزارهای MCP ارائه می‌شود. با جفت‌کردن Cline با API QCode.cc می‌توانید Claude، GPT و [مدل‌های خانواده چین](/docs/usage/cn-models) را در VS Code با هزینه کم استفاده کنید.

## چرا Cline؟

- **بدون کارمزد اضافه**: هیچ مبلغی به هزینه مدل‌ها افزوده نمی‌شود — شما فقط هزینه‌های API QCode.cc را پرداخت می‌کنید

- **تغییر انعطاف‌پذیر مدل**: بین `claude-sonnet-5`، `claude-opus-5`، `gpt-5.6-terra` و موارد بیشتر در همان رابط کاربری جابه‌جا شوید (4.x همچنان کار می‌کند)

- **یکپارچه‌سازی عمیق با VS Code**: پنل نوار کناری، اقدامات درون‌خطی کد، پیش‌نمایش تفاوت ویرایش فایل، تأیید خودکار

- **حالت‌های دوگانه Plan / Act**: ابتدا برنامه‌ریزی، سپس اجرا — تغییرات پیچیده را تحت کنترل نگه می‌دارد

- **کاملاً متن‌باز**: کد شفاف، جامعه فعال

- **پشتیبانی از MCP**: ابزارهای خارجی (پایگاه‌های داده، مرورگرها، مستندات) را از طریق Model Context Protocol متصل کنید

## نصب و پیکربندی

### گام 1: نصب افزونه Cline

در VS Code:

1. پنل Extensions را باز کنید (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. عبارت **«Cline»** را جستجو کنید

3. روی **Install** کلیک کنید

4. پس از نصب، آیکون Cline در نوار فعالیت سمت چپ ظاهر می‌شود

> Cline همچنین یک نسخه خط فرمان (Cline CLI) ارائه می‌دهد که از همان پیکربندی در ترمینال شما استفاده می‌کند؛ این راهنما بر افزونه VS Code تمرکز دارد.

### گام 2: پیکربندی API QCode.cc

یک کلید API QCode.cc (با شروع `cr_`) با هر دو پروتکل Anthropic و OpenAI سازگار است. Cline دو روش برای اتصال ارائه می‌دهد — **یکی را انتخاب کنید**:

#### گزینه A: سازگار با Anthropic (توصیه‌شده برای مدل‌های Claude)

در تنظیمات Cline (آیکون چرخ‌دنده)، منوی کشویی **API Provider** را باز کنید و **«Anthropic»** را انتخاب کنید، سپس موارد زیر را پر کنید:

| تنظیم | مقدار |
|---------|-------|
| API Key | کلید API QCode.cc شما (با شروع `cr_`) |
| Use custom base URL | آن را علامت بزنید و `https://api.qcode.cc/api` را وارد کنید |
| مدل | `claude-sonnet-5` (پیش‌فرض روزانه) یا `claude-opus-5` (کارهای دشوار). `claude-sonnet-4-6` / `claude-opus-4-8` همچنان در فروش هستند |

> SDK به‌طور خودکار `/v1/messages` را بعد از Base URL اضافه می‌کند، بنابراین Base URL را روی `/api` تنظیم کنید — **نه** `/api/v1/messages` بنویسید و **اسلش پایانی را قرار ندهید**.

#### گزینه B: سازگار با OpenAI

در منوی کشویی **API Provider**، گزینه **«OpenAI Compatible»** را انتخاب کنید، سپس موارد زیر را پر کنید:

| تنظیم | مقدار |
|---------|-------|
| Base URL | `https://api.qcode.cc/openai/v1` |
| API Key | کلید API QCode.cc شما (با شروع `cr_`) |
| شناسه مدل | `gpt-5.6-terra`، `gpt-6-sol`، یا یک [شناسه خانواده چین](/docs/usage/cn-models) مانند `glm-5.2`. **`claude-*` اینجا کار نمی‌کند** |

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

### گام 3: بررسی اتصال

یک پیام ساده (مثلاً «سلام») در کادر چت Cline تایپ کنید. اگر پاسخی دریافت کنید، پیکربندی موفق بوده است.

همچنین می‌توانید با curl در ترمینال خودتان بررسی کنید (کد `401` یعنی مسیر درست است و فقط احراز هویت وجود ندارد):

```bash
# Anthropic protocol
curl -i https://api.qcode.cc/api/v1/messages \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

# OpenAI protocol (note: this endpoint only accepts GPT or China-family ids)
curl -i https://api.qcode.cc/openai/v1/chat/completions \
  -H "content-type: application/json" \
  -d '{"model":"gpt-6-sol","messages":[{"role":"user","content":"hi"}]}'
```
## نقاط پایانی جایگزین

همان کلید روی 3 دامنه دسترسی کار می‌کند و می‌توانید بین آن‌ها جابه‌جا شوید. اگر دامنه اصلی ناپایدار بود، `api` را در Base URL با زیردامنه متناظر زیر عوض کنید:

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

> کاربران در چین سرزمین اصلی بهتر است `asia.qcode.cc` را ترجیح دهند، که معمولاً نقطه پایانی نزدیک‌تری است. برای جزئیات به [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) مراجعه کنید.

## Cline Desktop

در 2026-09-14، Cline یک اپلیکیشن دسکتاپ منتشر کرد ([اعلام رسمی](https://cline.bot/blog/cline-desktop-an-open-source-app-for-open-weight-models): *«کلید API خود را بیاورید و به‌صورت بومی به هر ارائه‌دهنده‌ای متصل شوید — Anthropic، OpenAI، Gemini، مدل‌های با وزن باز، یا یک نقطه پایانی محلی»*؛ [صفحه محصول](https://cline.bot/desktop) تاریخی ندارد). اپلیکیشن دسکتاپ از همان منطق ارائه‌دهنده افزونه پیروی می‌کند (یک API Provider + Base URL سفارشی انتخاب کنید)؛ نام‌های فیلدها برای نسخه دسکتاپ به‌طور جداگانه در بالادست مستند نشده است — بر اساس آنچه اپلیکیشن نمایش می‌دهد عمل کنید. دانلودها و پشتیبانی پلتفرم: [cline.bot/desktop](https://cline.bot/desktop).

## دو حالت Plan / Act

Cline زیر کادر چت یک کلید جابه‌جایی **Plan** / **Act** ارائه می‌دهد:

- **Plan**: Cline کد را می‌خواند، سؤال می‌پرسد و یک طرح پیاده‌سازی پیشنهاد می‌دهد، اما فایل‌ها را تغییر **نمی‌دهد**. برای هم‌راستا شدن روی نیازمندی‌ها پیش از هر تغییری عالی است.

- **Act**: Cline در واقع فایل‌ها را ایجاد/ویرایش می‌کند، فرمان‌ها را اجرا می‌کند و ابزارها را فراخوانی می‌کند. هر تغییر به‌صورت یک diff نمایش داده می‌شود تا آن را تأیید کنید یا تأیید خودکار را فعال کنید.

یک گردش‌کار معمول: ابتدا از حالت **Plan** استفاده کنید تا مدل رویکرد را تشریح و تأیید کند، سپس به حالت **Act** بروید تا آن را گام‌به‌گام پیاده‌سازی کنید. برای کارهای پیچیده، با `claude-opus-5` برنامه‌ریزی و سپس با `claude-sonnet-5` اجرا کنید. نسخه‌های 4.x نیز همچنان برای مقایسه در دسترس‌اند.

## نکات استفاده

### 1. راهنمای انتخاب مدل

| سناریو | مدل پیشنهادی | یادداشت |
|----------|-------------------|-------|
| کدنویسی روزمره | `claude-sonnet-5` | رده متعادل کنونی، 1M / 128K؛ در زمان نگارش این متن، ورودی از 4.6 ارزان‌تر بود |
| معماری پیچیده / حالت Plan | `claude-opus-5` | پرچم‌دار کنونی. `claude-opus-4-8` همچنان به فروش می‌رسد |
| کارهای سبک / ویرایش متن | `claude-haiku-5-5` | کمترین هزینه |
| ترجیح سبک GPT | `gpt-5.6-terra` | قابل انتخاب تحت پروتکل OpenAI |
| مدل‌های خانواده چین / قیمت واحد پایین‌تر | `glm-5.2` / `deepseek-v4-pro` | [مدل‌های خانواده چین](/docs/usage/cn-models) را ببینید |

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

### 2. پیکربندی ابزارهای MCP

Cline از پروتکل Model Context Protocol (MCP) پشتیبانی می‌کند و به مدل اجازه می‌دهد ابزارهای بیرونی (پرس‌وجوی پایگاه داده، مرورگرها، جست‌وجوی اسناد و غیره) را فراخوانی کند. در پنل **MCP Servers** در Cline یک سرور اضافه کنید:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}
```

سرورهای MCP از مدلی که استفاده می‌کنید جدا هستند — فراخوانی ابزارها چه با پروتکل Anthropic و چه با پروتکل OpenAI به QCode.cc متصل شوید کار می‌کند. برای مراحل نصب و پارامترهای هر سرور، به مستندات رسمی آن ابزار مراجعه کنید.

### 3. دستورهای سفارشی سطح پروژه (.clinerules)

یک فایل `.clinerules` در ریشه پروژه ایجاد کنید تا زمینه ثابتی برای آن مخزن تزریق شود — سبک کد، قراردادهای پشته فناوری، چیدمان دایرکتوری. Cline این قواعد را در هر گفتگو لحاظ می‌کند، بنابراین لازم نیست آن‌ها را مکرراً بچسبانید:

```text
# .clinerules
- Use TypeScript everywhere, strict mode
- Prefer reusing helpers under src/lib
- Run `pnpm test` before committing
```

برای فیلدهای فایل قواعد و استفاده پیشرفته، به مستندات رسمی Cline مراجعه کنید.

### 4. ورودی تصویر (بینایی)

`claude-opus-5`، `claude-sonnet-5` (و 4.8 / 4.6 که همچنان به فروش می‌رسند) و GPT-5.x همگی از ورودی بینایی پشتیبانی می‌کنند. یک اسکرین‌شات از رابط کاربری، تصویر یک خطا یا یک نمودار معماری را مستقیم به کادر چت Cline بکشید و بگذارید مدل بر اساس آن کد بنویسد یا آن را اشکال‌زدایی کند.

> توجه: این مورد درباره **خواندن** تصاویر توسط مدل است. برای **تولید** تصویر، از [تولید تصویر gpt-image-2](/docs/usage/image-2) با نام مدل `gpt-image-2` استفاده کنید.

### 5. تأیید خودکار و کنترل هزینه

- در تنظیمات می‌توانید **Auto-approve** را جداگانه برای «خواندن فایل‌ها»، «نوشتن فایل‌ها» و «اجرای فرمان‌ها» فعال کنید تا وقفه‌ها کمتر شود؛ برای عملیات پرخطر تأیید دستی را حفظ کنید.

- Cline مصرف توکن و هزینه تخمینی هر درخواست را نمایش می‌دهد و پیگیری هزینه‌ها را آسان می‌کند. برای کارهای پیچیده، ابتدا دامنه را با حالت Plan محدود کنید تا رفت‌وبرگشت‌های غیرضروری کاهش یابد.

- برای پایگاه‌های کد بزرگ، از `@` (اشاره به یک فایل/پوشه/URL) استفاده کنید تا زمینه دقیق در اختیار مدل قرار دهید، به‌جای اینکه مدل کل پروژه را اسکن کند — این کار در مصرف توکن‌ها صرفه‌جویی می‌کند و تمرکز را حفظ می‌کند.

### 6. ترکیب با Claude Code CLI

Cline و Claude Code CLI هر یک نقاط قوت خود را دارند — آن‌ها را با هم به کار ببرید:

| سناریو | ابزار پیشنهادی |
|----------|------------------|
| ویرایش‌های سریع در VS Code | Cline |
| تحلیل پروژه پیچیده | Claude Code CLI |
| بازآرایی چندفایلی | Cline |
| عملیات Git، بازبینی کد | Claude Code CLI |
| مهاجرت/بازبینی در سطح کل پایگاه کد | Claude Code CLI ([زیرعامل‌ها](/docs/advanced/subagents)) |
| خودکارسازی CI/CD | Claude Code CLI ([حالت headless](/docs/advanced/headless)) |

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

Cline و Claude Code CLI از همان کلید API QCode.cc استفاده می‌کنند و سهمیه پلن را مشترکاً به کار می‌برند — نیازی به درخواست کلید جداگانه برای هر ابزار نیست.
## پرسش‌های متداول

### اتصال ناموفق / 401 / 404؟

1. مطمئن شوید Base URL در انتها **هیچ** `/` ندارد

2. در حالت Anthropic، Base URL را روی `/api` تنظیم کنید (SDK مسیر `/v1/messages` را به آن اضافه می‌کند) — مسیر کامل را دستی ننویسید

3. در حالت OpenAI، Base URL را روی `/openai/v1` تنظیم کنید

4. بررسی کنید که کلید API با `cr_` شروع می‌شود و به‌طور کامل کپی شده است

5. تغییر به یک نقطه پایانی جایگزین (مثلاً `asia.qcode.cc`) را امتحان کنید

6. تأیید کنید که شبکه شما می‌تواند به سرویس‌های QCode.cc دسترسی داشته باشد

### فهرست مدل‌ها خالی است؟

در حالت سازگار با OpenAI، نام مدل را دستی در فیلد Model ID وارد کنید (مثلاً `glm-5.3`) — نیازی نیست از فهرست انتخاب کنید.

### حالت Plan فایل‌ها را تغییر نمی‌دهد؟

این رفتار مورد انتظار است. حالت Plan فقط برنامه‌ریزی می‌کند؛ تغییرات تنها پس از تغییر به حالت Act نوشته می‌شوند.

### با وجود درست به نظر رسیدن تنظیمات، خطای 401 دریافت می‌کنید؟

یک `401` معمولاً یعنی مسیر درست است و فقط احراز هویت شکست خورده است. دوباره بررسی کنید که کلید API کامل باشد و نوع ارائه‌دهنده درست (Anthropic در مقابل OpenAI Compatible) را با Base URL متناظر آن انتخاب کرده باشید.

## Cline CLI 3.0.69 (2026-10-07)

یادداشت‌های انتشار GitHub مربوط به **Cline CLI v3.0.69** که در 2026-10-07 منتشر شده‌اند، شامل یک مورد هستند که به تنظیمات بالا مربوط می‌شود. به زبان خود یادداشت‌ها:

> Claude از طریق یک Base URL سفارشی Anthropic (Azure AI Foundry، دروازه‌های شرکتی) دیگر با خطای 400 ناموفق نمی‌شود

منبع: [github.com/cline/cline/releases/tag/cli-v3.0.69](https://github.com/cline/cline/releases/tag/cli-v3.0.69). یادداشت‌ها هیچ بازه‌ای از نسخه‌های تحت تأثیر و هیچ توضیحی فراتر از آن جمله ارائه نمی‌دهند؛ خود عبارت‌بندی می‌گوید که این خرابی در این انتشار برطرف شده است، یعنی یک درخواست Claude که از طریق یک Base URL سفارشی Anthropic ارسال می‌شود در بیلدهای پیشین Cline CLI خطای `400` برمی‌گرداند. یادداشت‌ها به QCode اشاره نمی‌کنند و هیچ‌چیز در اینجا با یک نقطه پایانی QCode تأیید نشده است. اگر Cline CLI برای Claude از طریق یک Base URL سفارشی `400` برمی‌گرداند، ابتدا نسخه CLI خود را بررسی کنید.

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

- [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) را برای مشاهده همه پروتکل‌ها و دامنه‌ها ببینید

- [یکپارچه‌سازی Aider](/docs/ide/aider) را برای ابزار متن‌باز دیگری سازگار با QCode.cc ببینید

- [یکپارچه‌سازی VS Code](/docs/ide/vscode) را برای استفاده از افزونه رسمی Claude Code ببینید

- [مدل‌های خانواده چین](/docs/usage/cn-models) را برای فراخوانی GLM / Kimi / DeepSeek / Qwen با همان فیلدهای سازگار با OpenAI ببینید

- [صورت‌حساب](/docs/reference/billing) را برای جزئیات قیمت‌گذاری ببینید

> هنوز کلید API ندارید؟ [پلن‌ها و قیمت‌گذاری QCode.cc را ببینید →](https://qcode.cc/pricing)