راه‌اندازی MiniMax Code با QCode (BYOK)

QCode.cc را به MiniMax Code دسکتاپ یا CLI mcode اضافه کنید: Base URLهای Anthropic، OpenAI Chat و Responses؛ هر سه با mcode 0.7.6 آزمایش شده‌اند

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

آخرین بازبینی: 2026-11-10 · 📄 طبق مستندات رسمی (صفحه‌های BYOK دسکتاپ به‌روزرسانی‌شده در 2026-09-16؛ مستندات CLI mcode، 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 اضافه کنید، و CLI mcode همین کار را با 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 که انتخاب می‌کنید تعیین می‌کند MiniMax Code کدام نقطه پایانی QCode را فراخوانی کند. راهنمای رسمی پیکربندی جدولی ارائه می‌کند که نشان می‌دهد 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) دانلود کنید، یا در macOS از Homebrew استفاده کنید:

# 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 اجرا شد. تنها اگر مدل‌های خود MiniMax را هم می‌خواهید، با mcode login (حساب کاربری چین سرزمین اصلی) یا mcode login --region global (حساب کاربری جهانی) وارد شوید.

پیکربندی CLI mcode¶

کلید را در 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 ذخیره می‌کند. آن فایل را خصوصی نگه دارید. برای تغییر کلید در آینده، ارائه‌دهنده را دوباره اضافه کنید یا آن مقدار را ویرایش کنید.
• نام متغیر خودتان. برای خواندن کلید از QCODE_API_KEY به‌جای آن، --api-key-env 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 توکن زمینه و 16,384 توکن خروجی بازمی‌گردند.
• میزبان‌های منطقه‌ای. در آسیا، از جمله چین سرزمین اصلی، می‌توانید از asia.qcode.cc استفاده کنید؛ در آمریکای شمالی و اروپا، از us.qcode.cc. مسیر را حفظ کنید، برای مثال https://asia.qcode.cc/api.

در TUI، مدلی را با /model [filter] انتخاب کنید و ارائه‌دهنده‌های ذخیره‌شده را با /provider مدیریت کنید.

پیکربندی برنامه دسکتاپ¶

مراحل رسمی (مسیر «Settings → Usage & model»؛ نسخه چین همان مسیر را با برچسب‌های چینی نشان می‌دهد):

1. «Settings → Usage & model» را باز کنید، سپس زیر «Custom model» گزینه «Add model» را انتخاب کنید.
2. یک ارائه‌دهنده از پیش تعریف‌شده را جست‌وجو کنید، یا «Others» را انتخاب کنید و نام ارائه‌دهنده، Base URL، کلید API و قالب API را وارد کنید.
3. یک شناسه مدل وارد کنید، یا «Fetch» را انتخاب کنید تا از فهرست ارائه‌دهنده انتخاب کنید. شناسه مدل باید با شناسه موجود در مستندات ارائه‌دهنده مطابقت داشته باشد.
4. «Save» را انتخاب کنید، به کادر پیام بازگردید و مدل جدید را از منوی مدل انتخاب کنید.

مقادیر فرم «Others». این‌ها همان سه Base URL آزمایش‌شده با CLI در بالا هستند؛ خود برنامه دسکتاپ بخشی از آزمون 2026-11-10 نبود، بنابراین آزمون اتصال درون‌برنامه‌ای تعیین‌کننده است. برای هر قالب یک ورودی بسازید؛ یک کلید QCode می‌تواند چند ورودی را پوشش دهد:

بر اساس صفحه رسمی، «Fetch» فقط فهرست مدل‌های ارائه‌دهنده را می‌خواند و چیزی ذخیره نمی‌کند؛ «Save» آزمونی اجرا نمی‌کند و مدل وظیفه فعلی را تغییر نمی‌دهد. پیش از اتکا به یک مدل، از دکمه آزمون کنار آن (آزمون اتصال) استفاده کنید.

محل فایل. ارائه‌دهنده‌های سفارشی در macOS در <dataDir>/config.yaml و در Windows در <dataDir>\config.yaml، زیر کلید 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 دارای content یعنی کلید و مسیر درست هستند. در غیر این صورت بدنه خطای 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
• انتخاب مدل: تطبیق مدل با وظیفه

سازمانی ←