# مدل‌های سفارشی CodeBuddy با QCode

> **آخرین بازبینی**: 2026-11-10 · 📄 بر اساس مستندات رسمی (CodeBuddy IDE 4.12.4، منتشر شده در 2026-11-06؛ مستندات CLI برای v2.182.0) · ✅ اتصال QCode با CodeBuddy Code CLI 2.182.0 آزمایش شده است (2026-11-10)

بله، CodeBuddy می‌تواند از کلید خودتان استفاده کند: مدل‌های سفارشی در `models.json` قرار می‌گیرند (سطح کاربر `~/.codebuddy/models.json`)، و مستندات رسمی می‌گویند «در حال حاضر فقط از API با قالب رابط OpenAI پشتیبانی می‌کند». در تاریخ 2026-11-10، با CodeBuddy Code CLI 2.182.0 آزمایش شده است: QCode از طریق OpenAI Chat Completions (`url` مسیر کامل است) و OpenAI Responses (`url` مقدار پایه است) کار می‌کند، و CLI از این مدل‌ها بدون ورود به حساب کاربری Tencent استفاده می‌کند. مراحل IDE مطابق مستندات رسمی است.

## در یک نگاه

| مورد | جزئیات |
|---|---|
| آیا می‌توانم از کلید خودم استفاده کنم؟ | بله. IDE و CLI فایل `models.json` را می‌خوانند؛ CLI برای آن نیازی به ورود ندارد (✅ آزمایش شده) |
| مدل‌های قابل استفاده | Claude ❌ (این پروتکل نقطه پایانی Anthropic نیست) · GPT ✅ · مدل‌های چینی ✅ · Gemini ❌ (QCode فعلاً Gemini ارائه نمی‌دهد) |
| Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` (مسیر کامل) · ✅ آزمایش‌شده با CLI |
| Responses (CLI) | `"api": "openai-responses"`، `url`: `https://api.qcode.cc/openai/v1` · ✅ آزمایش‌شده با CLI |
| متغیرهای محیطی (CLI) | `CODEBUDDY_BASE_URL=https://api.qcode.cc/openai/v1` (OpenAI Chat) · ✅ آزمایش‌شده با CLI |
| فایل‌های پیکربندی | سطح کاربر `~/.codebuddy/models.json`؛ سطح پروژه `<project-root>/.codebuddy/models.json` |
| مستندات رسمی | [IDE models.json](https://www.codebuddy.ai/docs/ide/Features/models) · [CLI models.json](https://www.codebuddy.ai/docs/cli/models) · [متغیرهای محیطی CLI](https://www.codebuddy.ai/docs/cli/env-vars) |

CodeBuddy ابزار کدنویسی با هوش مصنوعی Tencent Cloud است. در سه شکل عرضه می‌شود: یک افزونه برای VS Code و JetBrains IDE‌ها، CodeBuddy IDE مستقل، و CodeBuddy Code، یک ابزار خط فرمان که فرمان آن `codebuddy` است. سایت‌ها [codebuddy.cn](https://www.codebuddy.cn) (سرزمین اصلی چین) و [codebuddy.ai](https://www.codebuddy.ai) (بین‌المللی) هستند؛ مسیر فایل مدل سفارشی در هر دو مجموعه مستندات یکسان است. WorkBuddy، عامل اداری همان تیم، زیربنای مشترکی دارد؛ به [مدل‌های سفارشی WorkBuddy](/docs/ide/workbuddy) مراجعه کنید.

QCode.cc وابسته به Tencent یا CodeBuddy نیست. رابط کاربری و فیلدها از نسخه‌ای که نصب کرده‌اید پیروی می‌کنند.
## کدام پروتکل

| مورد | پروتکل | مقدار QCode | مدل‌ها |
|---|---|---|---|
| `models.json` (IDE و CLI) | OpenAI Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` | GPT، DeepSeek / GLM / Kimi / Qwen |
| `models.json` با `"api": "openai-responses"` (CLI) | OpenAI Responses | `url`: `https://api.qcode.cc/openai/v1` | GPT |
| `CODEBUDDY_BASE_URL` (CLI) | OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT، DeepSeek / GLM / Kimi / Qwen |

این پروتکل‌ها روی QCode با GPT و مدل‌های چینی کار می‌کنند. مدل‌های Claude روی نقطه پایانی Anthropic ارائه می‌شوند، و مدل‌های سفارشی CodeBuddy از آن پروتکل استفاده نمی‌کنند. اگر به Claude نیاز دارید، از ابزاری استفاده کنید که از نقطه پایانی Anthropic پشتیبانی می‌کند، مانند [Claude Code](/docs/getting-started/installation)، [ZCode](/docs/ide/zcode) یا [Qoder](/docs/ide/qoder). این سه پروتکل در [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) مقایسه شده‌اند. در سرزمین اصلی چین می‌توانید از `asia.qcode.cc` به جای `api.qcode.cc` استفاده کنید؛ مسیر تغییر نمی‌کند و همان کلید کار می‌کند.

## نصب CodeBuddy Code CLI

راهنمای نصب رسمی این روش را فهرست می‌کند (پیش‌نیاز: Node.js 18.20 یا بالاتر)؛ این همان نصبی است که در آزمون 2026-11-10 استفاده شده است:

```bash
npm install -g @tencent-ai/codebuddy-code
```

بدون Node.js، راهنما همچنین Homebrew و یک باینری بومی (Beta) ارائه می‌دهد:

```bash
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

در Windows PowerShell از `irm https://www.codebuddy.cn/cli/install.ps1 | iex` استفاده کنید. نصب را با `codebuddy --version` بررسی کنید (آزمون از 2.182.0 استفاده کرد). مدل‌های سفارشی زیر بدون ورود به حساب کاربری Tencent کار می‌کنند. برای IDE یا افزونه، از [codebuddy.ai](https://www.codebuddy.ai) دانلود کنید؛ اگر فقط از IDE استفاده می‌کنید، از این بخش صرف‌نظر کنید.

## پیکربندی models.json

### مکان فایل‌ها

مستندات دو سطح را توصیف می‌کند:

- سطح کاربر: `~/.codebuddy/models.json`، سراسری، برای همه پروژه‌ها اعمال می‌شود
- سطح پروژه: `<project-root>/.codebuddy/models.json`، اولویت بالاتر از سطح کاربر

اولویت ادغام به‌ترتیب سطح پروژه، سپس سطح کاربر، و سپس پیش‌فرض‌های داخلی است. مدلی با `id` یکسان بازنویسی می‌شود؛ مدلی با `id` متفاوت اضافه می‌شود. IDE و CLI همان مسیرها را می‌خوانند.

### CLI: models.json حداقلی (✅ آزموده شده)

این را به‌عنوان `~/.codebuddy/models.json` ذخیره کنید. مورد اول از Chat Completions استفاده می‌کند، دومی از Responses؛ کلید از یک متغیر محیطی می‌آید:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}
```

سپس کلید را export کنید و به هر مدل یک تست یک‌خطی بفرستید:

```bash
export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra
```

پاسخ `OK` به این معناست که مدل کار می‌کند. `id` به‌عنوان نام مدل به QCode فرستاده می‌شود، بنابراین باید یک id فعال در [qcode.cc/models](https://qcode.cc/models) باشد، کاراکتر به کاراکتر. برای موارد Chat می‌توانید از `gpt-6.1-sol`، `deepseek-v4-pro`، `glm-5.3`، `kimi-k3` یا `qwen3.8-max` نیز استفاده کنید (به [مدل‌های چینی](/docs/usage/cn-models) مراجعه کنید)؛ موارد Responses شناسه‌های GPT را می‌پذیرند. قیمت هر مدل در https://qcode.cc/models است. `maxInputTokens`، `maxOutputTokens` و پرچم‌های تصویر یا استدلال را روی مقداری تنظیم کنید که مدل انتخاب‌شده پشتیبانی می‌کند.

### دو قاعده `url`

برای Chat Completions (پیش‌فرض)، عبارت رسمی این است: «فیلد url باید مسیر کامل رابط باشد، معمولاً با /chat/completions پایان می‌یابد»، با این نمونه‌های نادرست:

```text
❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434
```

وقتی `api` روی `openai-responses` تنظیم شود، قاعده برعکس می‌شود. عبارت رسمی: «وقتی api روی openai-responses تنظیم شود، مدل از OpenAI Responses API استفاده می‌کند: درخواست‌ها به {url}/responses می‌روند»، و «url مقدار Base URL را می‌گیرد؛ /responses در انتها اختیاری است.»

| مقدار `url` | نتیجه |
|---|---|
| `https://api.qcode.cc/openai/v1/chat/completions` | ✅ Chat Completions (آزموده شده) |
| `https://api.qcode.cc/openai/v1` | ✅ با `"api": "openai-responses"` (آزموده شده)؛ برای Chat مسیر کامل نیست |
| `https://api.qcode.cc/api` | ❌ پیشوند Anthropic Messages است، نه یک مسیر OpenAI |

برای Responses، `https://api.qcode.cc/openai` نیز آزمون را پاس کرد؛ این صفحه از `/openai/v1` استفاده می‌کند تا هر دو مورد یک Base URL مشترک داشته باشند. مستندات همچنین می‌گوید تنها `api` که به‌صراحت در مورد مدل نوشته شده باشد، پروتکل را تغییر می‌دهد.

### CodeBuddy IDE (📄 طبق مستندات رسمی)

مستندات IDE همان مسیرهای فایل و فیلدهای Chat را فهرست می‌کند. صفحه IDE `apiKey` را «مقدار واقعی کلید، نه نام متغیر محیطی» توصیف می‌کند، بنابراین خود کلید را بنویسید. یک مورد Chat برای IDE:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}
```

جدول فیلدهای IDE هیچ فیلد `api` ندارد، بنابراین موارد Responses برای CLI هستند. اگر از IDE و CLI با همان `~/.codebuddy/models.json` استفاده می‌کنید، در هر مورد خود کلید را بنویسید؛ CLI یک کلید تحت‌اللفظی را نیز می‌پذیرد. توصیه رسمی: یک `models.json` که کلید واقعی دارد را به کنترل نسخه نسپارید، و مجوزهای فایل را روی 600 تنظیم کنید (فقط خواندن/نوشتن برای مالک).

### جدول فیلدها

| فیلد | نوع | توضیحات (عبارت رسمی) |
|---|---|---|
| `id` | string | الزامی. شناسه یکتای مدل |
| `name` | string | نام نمایشی مدل |
| `vendor` | string | ارائه‌دهنده مدل (مثلاً OpenAI، Google) |
| `apiKey` | string | کلید API. صفحه IDE می‌گوید «مقدار واقعی کلید، نه نام متغیر محیطی»؛ صفحه CLI می‌گوید «از ارجاع به متغیر محیطی پشتیبانی می‌کند» |
| `maxInputTokens` | number | حداکثر توکن‌های ورودی |
| `maxOutputTokens` | number | حداکثر توکن‌های خروجی |
| `url` | string | URL نقطه پایانی API (باید مسیر کامل رابط باشد، معمولاً با /chat/completions پایان می‌یابد) |
| `supportsToolCall` | boolean | آیا فراخوانی ابزار پشتیبانی می‌شود |
| `supportsImages` | boolean | آیا ورودی تصویر پشتیبانی می‌شود |
| `supportsReasoning` | boolean | آیا حالت استدلال پشتیبانی می‌شود |

صفحه CLI سه فیلد اضافه می‌کند: `api` (پروتکل درخواست؛ `openai-responses` به Responses API تغییر می‌دهد)، `temperature` (دمای نمونه‌گیری، 0-2) و `relatedModels` (کدام id مدل برای سناریوهایی مانند lite و reasoning استفاده شود). `availableModels` سطح بالا یک آرایه از رشته‌هاست؛ فقط idهایی که در آن فهرست شده‌اند در منوی کشویی ظاهر می‌شوند، و آرایه خالی یا غایب همه مدل‌ها را نشان می‌دهد.

### ارجاع به متغیرهای محیطی با `${VAR_NAME}` در CLI

صفحه CLI می‌گوید فیلدهای `apiKey` و `url` از نحو ارجاع `${VAR_NAME}` پشتیبانی می‌کنند؛ ارجاع `apiKey` در بلوک بالا آزمون را پاس کرد. نکات رسمی: مقدار متغیرهای محیطی هنگام شروع CLI جایگزین می‌شود؛ اگر متغیر محیطی وجود نداشته باشد، جای‌نگهدار اصلی حفظ می‌شود، که باعث شکست درخواست API می‌شود.

### بارگذاری مجدد خودکار

طبق مستندات، فایل‌های پیکربندی از بارگذاری مجدد خودکار پشتیبانی می‌کنند: تغییرات به‌طور خودکار با یک تأخیر 1 ثانیه‌ای تشخیص داده می‌شوند، برای هر دو فایل `models.json` بالا.
## متغیرهای محیطی CLI

صفحه رسمی متغیرهای محیطی سه متغیر مرتبط با مدل‌های شخص ثالث را فهرست می‌کند:

| متغیر | توضیح رسمی |
|---|---|
| `CODEBUDDY_API_KEY` | کلید API. این کلید را برای فراخوانی‌های API مدل تنظیم کنید. در حالت غیرتعاملی (-p) همیشه از این کلید استفاده می‌کند |
| `CODEBUDDY_BASE_URL` | نشانی نقطه پایانی API را بازنویسی می‌کند، معمولاً همراه با `CODEBUDDY_API_KEY` استفاده می‌شود |
| `CODEBUDDY_MODEL` | مدل پیش‌فرض عامل را بازنویسی می‌کند |

تا تاریخ 2026-11-10، با CodeBuddy Code CLI 2.182.0 آزمایش شده است: `CODEBUDDY_BASE_URL` یک Base URL از OpenAI Chat Completions می‌پذیرد و CLI مسیر `/chat/completions` را به آن می‌افزاید. آن را روی `https://api.qcode.cc/openai/v1` تنظیم کنید و یک مدل GPT یا چینی انتخاب کنید؛ این مسیر به `models.json` نیازی ندارد:

```bash
export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
```

`CODEBUDDY_BASE_URL` را روی `/openai/v1` نگه دارید: با `https://api.qcode.cc/api` درخواست به `/api/chat/completions` می‌رود و QCode پاسخ HTTP 400 می‌دهد.

## تأیید

ابتدا تأیید کنید که مسیر OpenAI در QCode از شبکه شما کار می‌کند (همان آزمون موجود در [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths)):

```bash
KEY="cr_xxx"

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix
```

سپس:

1. CLI: آزمون‌های `codebuddy -p` بالا را اجرا کنید؛ `OK` یعنی کار می‌کند. برای یک نشست تعاملی، `codebuddy --model deepseek-v4-flash` را اجرا کنید.
2. IDE: فهرست کشویی مدل را باز کنید. مستندات می‌گوید مدل‌هایی که از طریق `models.json` اضافه می‌شوند به‌طور خودکار با برچسب `custom` مشخص می‌شوند، که به شما کمک می‌کند آن‌ها را ببینید و فیلتر کنید. یک پیام کوتاه به مدل جدید بفرستید.
3. کلید خود را در [probe.qcode.cc](https://probe.qcode.cc) وارد کنید تا درخواست و مدلی را که پاسخ داده است ببینید.

## عیب‌یابی

### پیکربندی اعمال نمی‌شود

چک‌لیست رسمی: بررسی کنید که JSON معتبر است؛ مسیر فایل را تأیید کنید؛ گزارش‌ها را بخوانید تا ببینید آیا پیکربندی بارگذاری شده است؛ تأیید کنید که کلید API در متغیر محیطی تنظیم شده است. بارگذاری مجدد خودکار 1 ثانیه تأخیر دارد، پس مطمئن شوید که فایل واقعاً روی دیسک ذخیره شده است.

### مدل در فهرست کشویی وجود ندارد

طبق مستندات: بررسی کنید که شناسه مدل در `availableModels` فهرست شده باشد و پیکربندی `models` درست باشد. `availableModels` در سطح پروژه، نسخه سطح کاربر را کاملاً بازنویسی می‌کند و ادغامی انجام نمی‌شود. فهرست عیب‌یابی رسمی «id, name, provider» را به‌عنوان فیلدهای الزامی نام می‌برد، در حالی که جدول فیلدها فقط `id` را الزامی علامت می‌زند و نام فیلد را `vendor` می‌نامد؛ پر کردن `id`، `name` و `vendor` هر دو را پوشش می‌دهد.

### HTTP 404

`url` یک ورودی Chat به `/chat/completions` نمی‌رسد، یا برابر `https://api.qcode.cc/api` است. ورودی‌های Chat همیشه از مسیر کامل `https://api.qcode.cc/openai/v1/chat/completions` استفاده می‌کنند؛ فقط ورودی‌هایی با `"api": "openai-responses"` در `/openai/v1` متوقف می‌شوند.

### HTTP 400 `model_not_available_on_endpoint`

یک شناسه `claude-…` به مسیر OpenAI ارسال شده است، برای مثال از طریق یک ورودی `models.json` یا از طریق `CODEBUDDY_BASE_URL` تنظیم‌شده روی `https://api.qcode.cc/api`. مدل‌های Claude فقط روی نقطه پایانی Anthropic ارائه می‌شوند؛ اینجا از یک مدل GPT یا چینی استفاده کنید، یا به ابزاری مانند [Claude Code](/docs/getting-started/installation) تغییر دهید. این خطا به معنای نامعتبر بودن کلید نیست.

### HTTP 401

کلید باید با `cr_` شروع شود و هیچ فاصله‌ای نداشته باشد. در ارجاع به متغیر محیطی، بررسی کنید که متغیر واقعاً export شده است: مستندات می‌گوید متغیر غایب، جای‌نگهدار اصلی را نگه می‌دارد، بنابراین مقدار تحت‌اللفظی `${QCODE_API_KEY}` به‌عنوان کلید ارسال می‌شود.

### آیا باید به حساب Tencent وارد شوم؟

برای این مدل‌ها خیر. در آزمون 2.182.0، `codebuddy -p` از طریق `models.json` و از طریق `CODEBUDDY_BASE_URL` بدون نیاز به ورود پاسخ داد.

### آیا یک مدل سفارشی سرآیندهای هویت پلتفرم Tencent را ارسال می‌کند؟

یادداشت‌های انتشار رسمی CLI v2.180.0 می‌گوید مدل‌های سفارشی دیگر سرآیندهای درخواست هویت پلتفرم را همراه ندارند: وقتی یک مدل سفارشی مستقیماً به یک نقطه پایانی شخص ثالث متصل می‌شود، اطلاعات هویت دیگر به سرویسی که پیکربندی کرده‌اید ارسال نمی‌شود.
## مطالب مرتبط

- [مدل‌های سفارشی WorkBuddy](/docs/ide/workbuddy) — عامل اداری از همان تیم، همچنین روی OpenAI Chat Completions
- [ZCode](/docs/ide/zcode) — ارائه‌دهندگان سفارشی روی پروتکل‌های Anthropic و OpenAI، از جمله Claude
- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — سه پروتکل، سه دامنه، نگاشت `BASE_URL`
- [مدل‌های چینی](/docs/usage/cn-models) — شناسه‌های مدل GLM / Kimi / DeepSeek / Qwen
- [نمای کلی سازگاری ابزارها](/docs/ide/tool-compatibility) — پروتکل‌های هر ابزار و اینکه Claude کار می‌کند یا نه
- شناسه‌ها و قیمت‌های به‌روز: [qcode.cc/models](https://qcode.cc/models)