# نماذج 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 IDEs، و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"]
}
```

ثم صدّر المفتاح وأرسل اختبارًا من سطر واحد إلى كل نموذج:

```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 باسم النموذج، لذا يجب أن يكون معرّفًا نشطًا على [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` كي يشترك المدخلان في قاعدة واحدة. تقول الوثائق أيضًا إن `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 | الحد الأقصى من tokens الإدخال |
| `maxOutputTokens` | number | الحد الأقصى من tokens الإخراج |
| `url` | string | عنوان URL لنقطة نهاية API (يجب أن يكون مسار الواجهة الكامل، وينتهي عادةً بـ /chat/completions) |
| `supportsToolCall` | boolean | هل استدعاءات الأدوات مدعومة |
| `supportsImages` | boolean | هل إدخال الصور مدعوم |
| `supportsReasoning` | boolean | هل وضع الاستدلال مدعوم |

تضيف صفحة CLI ثلاثة حقول: `api` (بروتوكول الطلب؛ ويبدّل `openai-responses` إلى Responses API)، و`temperature` (درجة حرارة أخذ العينات، 0-2)، و`relatedModels` (معرّف النموذج الذي يُستخدم في سيناريوهات مثل lite والاستدلال). و`availableModels` في المستوى الأعلى مصفوفة من السلاسل النصية؛ لا تظهر في القائمة المنسدلة إلا المعرّفات المدرجة هناك، وتعرض المصفوفة الفارغة أو المفقودة جميع النماذج.

### الإشارة إلى متغيّرات البيئة باستخدام `${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` أساس 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_` وألا يحتوي على مسافات. عند استخدام مرجع متغير بيئة، تحقق من أن المتغير مُصدَّر فعليًا: تقول الوثائق إن المتغير المفقود يبقي العنصر النائب الأصلي، لذا يُرسل النص الحرفي `${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)