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

أضف QCode.cc إلى تطبيق MiniMax Code لسطح المكتب أو أداة mcode CLI: عناوين Base URL الخاصة بـ Anthropic وOpenAI Chat وResponses، والثلاثة جميعها مختبَرة مع mcode 0.7.6

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

آخر تحقق: 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 على الصيغ الثلاث جميعها.

نظرة سريعة¶

أي بروتوكول¶

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

كيف تقرأها، حرفيًا من الدليل: «لا تحصل نقاط النهاية بنمط 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.

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

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

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

تنص ملاحظات 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:

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

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

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

# 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):

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؛ المفتاح وحده عنصر نائب:

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>:

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 واحد عدة إدخالات:

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

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

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 يرسل طلبًا حقيقيًا:

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 من الإعدادات.

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

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

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: فهو يفصل بين مسار أو مفتاح خاطئ ونموذج غير متاح على نقطة النهاية تلك.

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

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

نقاط أخرى:

• يحتفظ طلب 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 وتقول إن الصيغ «قد تختلف بين إصدارات التطبيق».
• أي نموذج يناسب أي مهمة: اختيار النموذج. أخطاء خارج هذه الأداة: استكشاف الأخطاء وإصلاحها.

ذات صلة¶

• نقاط النهاية ومسارات API: البروتوكول مقابل عائلة النماذج
• توافق الأدوات: أي الأدوات تدعم أي بروتوكول
• إعداد Kimi Code CLI: وكيل طرفية آخر، جُرّب على نقاط النهاية الثلاث نفسها
• النماذج الصينية: معرّفات النماذج على نقطة نهاية OpenAI Chat
• اختيار النموذج: مطابقة النموذج بالمهمة

المؤسسات ←