# إعداد MiniMax Code مع QCode (BYOK)

> **آخر تحقق**: 2026-11-10 · 📄 وفق الوثائق الرسمية (صفحات BYOK لسطح المكتب محدَّثة في 2026-09-16؛ وثائق mcode CLI، npm `@minimax-ai/code` 0.7.6) · ✅ تم اختبار الوصول إلى QCode مع mcode 0.7.6 (2026-11-10)

هل يمكن لـ MiniMax Code استخدام مفتاح API الخاص بك؟ نعم. حتى 2026-11-10، تتيح لك صفحات BYOK («أحضر مفتاحك») الرسمية إضافة مزوّد نموذج مخصص في تطبيق سطح المكتب ضمن **Settings → Usage & model**، وتفعل أداة `mcode` CLI الشيء نفسه عبر `mcode provider add`. وكلتاهما تقبل ثلاث صيغ API هي `anthropic-messages` و`openai-completions` و`openai-responses`، ويقدّم QCode الثلاث جميعها، لذا يغطي مفتاح QCode واحد عائلات نماذج Claude وGPT والنماذج الصينية في الأداة نفسها. تم الاختبار في 2026-11-10 مع mcode 0.7.6: فبدون تسجيل الدخول إلى MiniMax، أجاب `mcode provider add … --use` متبوعًا بـ `mcode exec` على الصيغ الثلاث جميعها.

## نظرة سريعة

| البند | التفاصيل |
|---|---|
| ما هو | MiniMax Code تطبيق وكيل ذكاء اصطناعي لسطح المكتب يعمل على macOS وWindows؛ و`mcode` هو أداة CLI الطرفية الخاصة به (TUI تفاعلية، وضع بلا واجهة `mcode exec`، `mcode acp`). مصدر CLI متاح على GitHub بترخيص MIT؛ ويذكر المستودع أن مصدر تطبيق سطح المكتب غير مضمَّن |
| النماذج التي يمكنك استخدامها | Claude ✅ (`anthropic-messages`) · GPT ✅ (`openai-completions` أو `openai-responses`) · GLM / Kimi / DeepSeek / Qwen ✅ (`anthropic-messages` أو `openai-completions`) · Gemini ❌ (لا يوفّر QCode عائلة Gemini؛ استخدم Claude أو GPT أو نموذجًا صينيًا) |
| Base URL لكل صيغة | `anthropic-messages`: `https://api.qcode.cc/api` · `openai-completions`: `https://api.qcode.cc/openai/v1` · `openai-responses`: `https://api.qcode.cc/openai/v1` · الثلاث جميعها ✅ مختبَرة مع mcode 0.7.6 (2026-11-10) |
| أين تُضبط | CLI: `mcode provider add`، وتُحفظ ضمن `custom_provider` في `~/.minimax/config.yaml` (دليل البيانات الافتراضي). سطح المكتب: **Settings → Usage & model** → Custom model → Add model |
| مفتاح API | مفتاح QCode الخاص بك، `cr_xxx`. تقرأه أداة CLI من `MCODE_PROVIDER_API_KEY`، أو من المتغير المسمّى في `--api-key-env`، عند إضافة المزوّد |
| تسجيل الدخول إلى MiniMax | غير مطلوب عند استخدام مفتاحك الخاص؛ فـ `mcode login` مخصص لنماذج MiniMax الخاصة فقط |
| الوثائق الرسمية | [النماذج المخصصة / BYOK](https://code.minimax.io/docs/code/account/byok) · [ضبط نماذج BYOK مع وكيل](https://code.minimax.io/docs/code/account/byok-agent-setup) · [إعداد CLI](https://code.minimax.io/docs/cli/configuration) · [البدء السريع مع CLI](https://code.minimax.io/docs/cli/quick-start) · [GitHub: MiniMax-AI/minimax-code](https://github.com/MiniMax-AI/minimax-code) |

## أي بروتوكول

يحدد `API format` الذي تختاره أي نقطة نهاية لدى QCode يستدعيها MiniMax Code. يعرض دليل الإعداد الرسمي جدولًا يوضح كيف يتحول Base URL إلى طلب:

| تنسيق API | شكل Base URL في الجدول الرسمي | هدف الطلب | القيمة المطلوب إدخالها لـ QCode |
|---|---|---|---|
| `anthropic-messages` | `https://example.invalid`، أو بادئة توافق يحددها المزوّد | `<normalized base>/v1/messages` | `https://api.qcode.cc/api` |
| `openai-completions` | `https://example.invalid/v1` | `<base>/chat/completions` | `https://api.qcode.cc/openai/v1` |
| `openai-responses` | `https://example.invalid/v1` | `<base>/responses` | `https://api.qcode.cc/openai/v1` |

كيف تقرأها، حرفيًا من الدليل: «لا تحصل نقاط النهاية بنمط OpenAI تلقائيًا على `/v1`؛ أضِفها عند الحاجة. تُطبّع Messages اللواحق `/v1` أو `/messages` أو `/v1/messages`. لا تُلحق هذه بشكل متكرر ولا تزِل بادئة بوابة مثل `/proxy/anthropic`.» عمليًا:

- **`anthropic-messages`**: نقطة نهاية Anthropic لدى QCode هي البادئة `/api`، ويضيف MiniMax Code المسار `/v1/messages` بنفسه، لذا يصل الطلب إلى `https://api.qcode.cc/api/v1/messages`. أبقِ بادئة `/api` ولا تكتب `/v1/messages` بنفسك.
- **`openai-completions`**: يجب أن يحتوي Base URL مسبقًا على `/v1`، لأن الأداة تُلحق `/chat/completions` فقط. يصبح `https://api.qcode.cc/openai/v1` هو `https://api.qcode.cc/openai/v1/chat/completions`.
- **`openai-responses`**: القاعدة نفسها: يحتوي Base URL على `/v1` وتُلحق الأداة `/responses`. يصبح `https://api.qcode.cc/openai/v1` هو `https://api.qcode.cc/openai/v1/responses`، وهو مسار Responses المدرج في [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths).

اختُبرت القيم الثلاث كلها في العمود الأخير في 2026-11-10 باستخدام mcode 0.7.6، بنموذج واحد لكل تنسيق (`claude-haiku-5-5`، `deepseek-v4-flash`، `gpt-6.1-terra`).

أي النماذج تتوافق مع أي تنسيق:

| النماذج | `anthropic-messages` | `openai-completions` | `openai-responses` |
|---|:--:|:--:|:--:|
| Claude (`claude-opus-5-5`، `claude-sonnet-5-5`، `claude-haiku-5-5`) | ✅ | ❌ | ❌ |
| GPT (`gpt-6.1-sol`، `gpt-6.1-terra`) | ❌ | ✅ | ✅ |
| GLM / Kimi / DeepSeek / Qwen (مثل `glm-5.3`، `kimi-k3`، `deepseek-v4-flash`، `qwen3.8-max`) | ✅ | ✅ | ❌ |

يجب أن يطابق معرّف النموذج معرّف QCode: تقول الصفحة الرسمية «يجب أن يطابق معرّف النموذج المعرّف في وثائق المزوّد». ترد المعرّفات الحالية في [qcode.cc/models](https://qcode.cc/models)؛ وتوجد هناك أيضًا أسعار كل نموذج. لا تُقدَّم نماذج Claude إلا على نقطة نهاية Anthropic Messages، لذا فإن معرّفًا من نوع `claude-*` ضمن `openai-completions` أو `openai-responses` يعيد `model_not_available_on_endpoint` (انظر [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).

تنص ملاحظات CLI الرسمية على أن المصادقة تتبع التنسيق: يرسل `openai-completions` و`openai-responses` الترويسة `Authorization: Bearer <key>`، ويرسل `anthropic-messages` المفتاح ضمن `x-api-key`. وكلا نمطي الترويسة هما المستخدمان في أمثلة curl على صفحة نقاط النهاية لدى QCode.
## التثبيت

**سطح المكتب.** يدعم MiniMax Code نظام macOS 12 والإصدارات الأحدث وWindows 10 والإصدارات الأحدث. نزّله من الموقع العالمي (`code.minimax.io/about`) أو موقع الصين (`code.minimax.cn/about`)، أو استخدم Homebrew على macOS:

```bash
# Mainland China
brew install --cask minimax-ai/tap/minimax-code

# Overseas
brew install --cask minimax-ai/tap/minimax-code --language=en
```

**CLI (`mcode`).** لا يحتاج المثبّت الرسمي إلى `sudo`:

```bash
# macOS / Linux / WSL
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash

# Windows (PowerShell)
irm https://filecdn.minimax.chat/public/install.ps1 | iex

# or npm, with Node.js 22.19.0 or later (22.x), or Node.js 24, 25, 26
npm install -g @minimax-ai/code
```

أعد فتح الطرفية وتحقق منه (استخدم اختبار 2026-11-10 مسار npm، وطبع `mcode --version` القيمة `0.7.6`):

```bash
mcode --version
mcode --help
```

لا تحتاج إلى تسجيل الدخول إلى MiniMax لاستخدام مفتاحك الخاص. يقول README الخاص بالمستودع «لا يتطلب BYOK تسجيل الدخول إلى MiniMax.»، وقد جرى اختبار 2026-11-10 دون `mcode login`. سجّل الدخول باستخدام `mcode login` (حساب الصين القارية) أو `mcode login --region global` (حساب Global) فقط إذا كنت تريد أيضًا نماذج MiniMax الخاصة بها.

## تهيئة mcode CLI

ضع المفتاح في `MCODE_PROVIDER_API_KEY`، ثم أضف مزوّدًا واحدًا لكل تنسيق. هذه هي الأوامر التي اختُبرت في 2026-11-10 مع mcode 0.7.6؛ المفتاح وحده عنصر نائب:

```bash
export MCODE_PROVIDER_API_KEY="cr_xxx"

# Anthropic Messages: Claude
mcode provider add --name qcode-a \
  --base-url https://api.qcode.cc/api \
  --api-format anthropic-messages \
  --model claude-haiku-5-5 --use

# OpenAI Chat Completions: GPT and Chinese models
mcode provider add --name qcode-c \
  --base-url https://api.qcode.cc/openai/v1 \
  --api-format openai-completions \
  --model deepseek-v4-flash --use

# OpenAI Responses: GPT
mcode provider add --name qcode-r \
  --base-url https://api.qcode.cc/openai/v1 \
  --api-format openai-responses \
  --model gpt-6.1-terra --use
```

يطبع كل أمر ناجح `Provider added and selected: <name>`. ثم شغّل مهمة واحدة بالنموذج المحدد، أو اختر نموذجًا لتشغيل واحد باستخدام `--model custom_provider:<name>/<model-id>`:

```bash
mcode exec "Reply with exactly: OK"

mcode exec --model custom_provider:qcode-a/claude-haiku-5-5 \
  "Reply with exactly: OK"
```

ما ينبغي معرفته عن هذه الأوامر:

- **مكان حفظ المفتاح.** لا يُقرأ `MCODE_PROVIDER_API_KEY` و `--api-key-env <name>` إلا في لحظة إضافة المزوّد؛ ثم يحفظ mcode المفتاح كنص عادي باسم `options.apiKey` في `~/.minimax/config.yaml`. حافظ على سرية ذلك الملف. لتغيير المفتاح لاحقًا، أضف المزوّد مرة أخرى أو عدّل تلك القيمة.
- **اسم متغيرك الخاص.** أضف `--api-key-env QCODE_API_KEY` لقراءة المفتاح من `QCODE_API_KEY` بدلًا من ذلك (اختُبر مع إدخال `openai-completions`).
- **`--use`** يختبر أول نموذج مدرج، ثم يحفظ المزوّد ويحدد ذلك النموذج كافتراضي؛ اختبار الاتصال الفاشل يخرج برمز غير صفري ولا يحفظ شيئًا. الاختبار هو طلب نموذج حقيقي واحد. كل `--use` يغيّر الافتراضي، لذا أضف المزوّد الذي تريده افتراضيًا أخيرًا، أو بدّل لاحقًا باستخدام `/model`.
- **مزيد من النماذج.** مرّر `--model` أكثر من مرة لإضافة عدة نماذج إلى مزوّد واحد، على سبيل المثال `--model claude-haiku-5-5 --model claude-sonnet-5-5`. معرّف المزوّد هو `custom_provider:` مضافًا إليه قيمة `--name`، على سبيل المثال `custom_provider:qcode-a`.
- **الحدود.** بالنسبة إلى النماذج المخصصة يمكنك تعيين `--context-limit` و `--output-limit` (أعداد صحيحة موجبة، تُطبّق على كل `--model` متكرر). من دونهما، تعود النماذج المخصصة غير المعروفة افتراضيًا إلى 200,000 token للسياق و16,384 token للإخراج.
- **المضيفات الإقليمية.** في آسيا، بما في ذلك الصين القارية، يمكنك استخدام `asia.qcode.cc`؛ وفي أمريكا الشمالية وأوروبا، `us.qcode.cc`. حافظ على المسار، على سبيل المثال `https://asia.qcode.cc/api`.

داخل TUI، اختر نموذجًا باستخدام `/model [filter]` وأدر المزوّدات المحفوظة باستخدام `/provider`.
## إعداد تطبيق سطح المكتب

الخطوات الرسمية (Settings → Usage & model؛ تعرض النسخة الصينية المسار نفسه بتسميات صينية):

1. افتح **Settings → Usage & model**، ثم اختر **Add model** ضمن Custom model.
2. ابحث عن مزوّد معدّ مسبقًا، أو اختر **Others** وأدخل اسم المزوّد وBase URL ومفتاح API وتنسيق API.
3. أدخل معرّف النموذج، أو اختر **Fetch** للاختيار من قائمة المزوّد. يجب أن يطابق معرّف النموذج المعرّف الوارد في وثائق المزوّد.
4. اختر **Save**، ثم عُد إلى مربع الرسالة واختر النموذج الجديد من قائمة النماذج.

قيم استمارة «Others». وهي نفس عناوين Base URL الثلاثة التي جرى اختبارها باستخدام CLI أعلاه؛ لم يكن تطبيق سطح المكتب نفسه جزءًا من اختبار 2026-11-10، لذا فإن اختبار الاتصال داخل التطبيق هو الفيصل. أنشئ إدخالًا واحدًا لكل تنسيق؛ يمكن أن يخدم مفتاح QCode واحد عدة إدخالات:

| الحقل | Claude | GPT | GLM / Kimi / DeepSeek / Qwen |
|---|---|---|---|
| اسم المزوّد | `QCode Claude` | `QCode GPT` | `QCode CN` |
| Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` | `https://api.qcode.cc/openai/v1` |
| مفتاح API | `cr_xxx` | `cr_xxx` | `cr_xxx` |
| تنسيق API | `anthropic-messages` | `openai-completions` (أو `openai-responses`) | `openai-completions` (أو `anthropic-messages` مع `https://api.qcode.cc/api`) |
| معرّف النموذج | `claude-sonnet-5-5` | `gpt-6.1-sol` | `deepseek-v4-flash` |

وفقًا للصفحة الرسمية، فإن «Fetch» يقرأ فقط قائمة نماذج المزوّد ولا يحفظ أي شيء؛ ولا يشغّل «Save» اختبارًا ولا يبدّل نموذج المهمة الحالية. استخدم زر الاختبار المجاور لأحد النماذج (اختبار الاتصال) قبل الاعتماد عليه.

**أين يوجد الملف.** تُحفظ المزوّدات المخصصة في `<dataDir>/config.yaml` على macOS وفي `<dataDir>\config.yaml` على Windows، ضمن المفتاح `custom_provider`. يحذّر الدليل الرسمي من أن إعدادات التثبيت أو التشغيل المخصصة قد تغيّر دليل البيانات، لذلك لا يقدّم مسارًا ثابتًا واحدًا لتطبيق سطح المكتب، ولا تفعل هذه الصفحة ذلك أيضًا. الدليل مكتوب بحيث يقوم وكيل بتحرير الملف؛ والتحرير عبر شاشة Settings أعلاه هو المسار الأبسط. إذا حرّرت الملف فعلاً، فادمج إدخالًا كهذا في المحتوى الموجود، وخذ نسخة احتياطية منه أولاً، وتجنّب حفظ الإعدادات في التطبيق في الوقت نفسه:

```yaml
custom_provider:
  qcode-claude:
    name: "QCode Claude"
    kind: custom
    enabled: true
    api: anthropic-messages
    options:
      baseURL: "https://api.qcode.cc/api"
      apiKey: "cr_xxx"
    models:
      "claude-sonnet-5-5":
        name: "Claude Sonnet 5.5"
        enabled: true
        limit:
          context: 200000
          output: 8192
        modalities:
          input: [text]
          output: [text]
```

إن القيمتين `context` و`output` عنصران نائبان: يقول الدليل إن القيم الافتراضية للاستمارة ليست دليلًا على قدرات النموذج، وقيم `limit` أعداد صحيحة موجبة، وليست سلاسل نصية مثل `128K`. استخدم الحدود التي تحققت منها للنموذج. لا يتم توسيع `${API_KEY}`، لذا يحمل `apiKey` المفتاح الحقيقي.
## التحقق

CLI أولًا، لأن `provider test` يرسل طلبًا حقيقيًا:

```bash
mcode provider list
mcode provider test custom_provider:qcode-a
```

الصيغة الكاملة هي `mcode provider test <provider-id> [--model <id>] [--json]`. في اختبار 2026-11-10، طبع `Provider available: custom_provider:qcode-a` وخرج بالرمز 0. يعرض `mcode provider list` المفاتيح مقنّعة، ويسرد أيضًا إدخال `minimax_oauth` المضمّن (تسجيل الدخول المُدار)، وهو لا يؤثر في المزوّدات المخصصة لديك. في TUI، يعرض `/status` الحساب والنموذج، ويتحقق `/doctor` من الإعدادات.

سطح المكتب: شغّل اختبار الاتصال بجوار النموذج، ثم اختر النموذج من قائمة النماذج وأرسل رسالة قصيرة. تضيف الصفحة الرسمية أن نجاح الاختبار لا يُظهر سوى أن طلب الاختبار قد مرّ؛ لا يزال عليك التحقق من الصور والفيديو والمدخلات الأخرى بأمثلتك الخاصة.

لإجراء تحقق خارج الأداة، أرسل طلبًا واحدًا إلى نقطة النهاية التي تستخدمها صيغتك (استبدل المفتاح والنموذج):

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: cr_xxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

يعني رد JSON يتضمن محتوى أن المفتاح والمسار صحيحان. وإلا فاقرأ جسم خطأ JSON: فهو يفصل بين مسار أو مفتاح خاطئ ونموذج غير متاح على نقطة النهاية تلك.

## استكشاف الأخطاء وإصلاحها والقيود المعروفة

الصفوف الأربعة الأولى هي جدول استكشاف الأخطاء الرسمي للنماذج المخصصة:

| العَرَض | ما تنص الوثائق الرسمية على التحقق منه | ما يجب فعله مع QCode |
|---|---|---|
| لا يظهر النموذج المحفوظ | دليل البيانات الصحيح، وتمكين المزوّد والنموذج، ووجود الإعدادات ضمن `custom_provider`، وتحميل التطبيق للتغيير | أعد فتح تطبيق سطح المكتب إذا حرّرت الملف يدويًا |
| 401 / 403 | المفتاح ينتمي إلى هذا المزوّد؛ وعدم وجود قناع أو عنصر نائب غير موسّع؛ وأن الرؤوس المخصصة لم تتجاوز المصادقة | ألصق المفتاح الكامل `cr_`، وليس قيمة مقنّعة |
| 404 | تطابق صيغة API وBase URL؛ والحفاظ على `/v1` المطلوب وبادئة البوابة؛ ووجود معرّف النموذج المطابق تمامًا | `anthropic-messages` → `https://api.qcode.cc/api`؛ وصيغتا OpenAI → `https://api.qcode.cc/openai/v1`؛ ومعرّف النموذج منسوخ من [qcode.cc/models](https://qcode.cc/models) |
| فشل الاختبار لكن يظل النموذج قابلًا للاختيار | حالة الاختبار تشخيصية فقط؛ أصلح الخطأ الذي يبلغ عنه الاختبار بدلًا من تسجيل نجاح | أصلح الخطأ المعروض، ثم أعد الاختبار |
| `model_not_available_on_endpoint` | غير موجود في وثائق MiniMax؛ وهو خطأ QCode الخاص بإرسال معرّف Claude إلى صيغة OpenAI | استخدم `anthropic-messages` مع `claude-*` |
| النص يعمل لكن المرفقات أو الأدوات تفشل | يجب أن تكون القدرة المعلنة مدعومة من المزوّد والبروتوكول | أضف فقط القدرات التي تحققت منها |
| مفتاح QCode جديد، لكن mcode ما زال يرسل المفتاح القديم | نُسخ المفتاح إلى `config.yaml` عند إضافة المزوّد | أضف المزوّد مرة أخرى، أو حرّر `options.apiKey` في `~/.minimax/config.yaml` |
| سطر السجل `token counter endpoint missing; disabling remote counting for this base url` | غير موجود في وثائق MiniMax؛ ولوحظ في اختبار 2026-11-10 | معلوماتي: يتوقف mcode عن عدّ token عن بُعد لذلك Base URL، وتستمر المحادثة نفسها |

نقاط أخرى:

- يحتفظ طلب BYOK الفاشل بالمزوّد المحدد ويبلغ عن الخطأ؛ ولا يتحول MiniMax Code بصمت إلى نموذج مُدار أو مزوّد آخر.
- تدرج CLI أيضًا `google-generative-ai` كصيغة API رابعة لـ Google Gemini. لا يوفّر QCode عائلة Gemini، لذا لا يوجد إعداد QCode لها.
- لا يوفّر QCode `gpt-6-luna` أو `gpt-5.6-luna`؛ استخدم `gpt-6.1-sol` أو `gpt-6.1-terra`.
- الإصدارات، 2026-11-10: اختُبرت هذه الصفحة مع mcode 0.7.6، إصدار `latest` من npm `@minimax-ai/code`؛ ولا تزال صفحة GitHub Releases تشير إلى الوسم v0.7.2 بوصفه أحدث إصدار. شغّل `mcode --version` لرؤية بنيتك. وتحمل صفحات BYOK على سطح المكتب التاريخ 2026-09-16 وتقول إن الصيغ «قد تختلف بين إصدارات التطبيق».
- أي نموذج يناسب أي مهمة: [اختيار النموذج](/docs/usage/model-selection). أخطاء خارج هذه الأداة: [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting).
## ذات صلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths): البروتوكول مقابل عائلة النماذج
- [توافق الأدوات](/docs/ide/tool-compatibility): أي الأدوات تدعم أي بروتوكول
- [إعداد Kimi Code CLI](/docs/ide/kimi-code): وكيل طرفية آخر، جُرّب على نقاط النهاية الثلاث نفسها
- [النماذج الصينية](/docs/usage/cn-models): معرّفات النماذج على نقطة نهاية OpenAI Chat
- [اختيار النموذج](/docs/usage/model-selection): مطابقة النموذج بالمهمة