MiniMax Code Setup with QCode (BYOK)

Add QCode.cc to MiniMax Code desktop or the mcode CLI: Anthropic, OpenAI Chat and Responses base URLs, all three tested with mcode 0.7.6

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-11-10 · 📄 Per official docs (desktop BYOK pages updated 2026-09-16; mcode CLI docs, npm @minimax-ai/code 0.7.6) · ✅ QCode access tested with mcode 0.7.6 (2026-11-10)

Can MiniMax Code use your own API key? Yes. As of 2026-11-10, the official BYOK ("bring your own key") pages let you add a custom model provider in the desktop app under Settings → Usage & model, and the mcode CLI does the same with mcode provider add. Both accept three API formats, anthropic-messages, openai-completions and openai-responses, and QCode serves all three, so one QCode key covers Claude, GPT and the Chinese model families in the same tool. Tested on 2026-11-10 with mcode 0.7.6: without a MiniMax login, mcode provider add … --use followed by mcode exec answered on all three formats.

At a glance¶

Which protocol¶

The API format you pick decides which QCode endpoint MiniMax Code calls. The official configuration guide gives a table of how the Base URL is turned into a request:

How to read it, word for word from the guide: "OpenAI-style endpoints do not automatically acquire /v1; include it when required. Messages normalizes trailing /v1, /messages, or /v1/messages. Do not append these repeatedly or remove a gateway prefix such as /proxy/anthropic." In practice:

• anthropic-messages: QCode's Anthropic endpoint is the prefix /api, and MiniMax Code adds /v1/messages itself, so the request lands on https://api.qcode.cc/api/v1/messages. Keep the /api prefix and do not type /v1/messages yourself.
• openai-completions: the Base URL must already contain /v1, because the tool appends only /chat/completions. https://api.qcode.cc/openai/v1 becomes https://api.qcode.cc/openai/v1/chat/completions.
• openai-responses: same rule, the Base URL contains /v1 and the tool appends /responses. https://api.qcode.cc/openai/v1 becomes https://api.qcode.cc/openai/v1/responses, which is the Responses path listed on Endpoints & API Paths.

All three values in the last column were tested on 2026-11-10 with mcode 0.7.6, one model per format (claude-haiku-5-5, deepseek-v4-flash, gpt-6.1-terra).

Which models go with which format:

The model ID must match QCode's: the official page says "The model ID must match the ID in the provider's documentation." Current IDs are listed on qcode.cc/models; per-model prices are there too. Claude models are served only on the Anthropic Messages endpoint, so a claude-* ID under openai-completions or openai-responses returns model_not_available_on_endpoint (see Endpoints & API Paths).

The official CLI notes say authentication follows the format: openai-completions and openai-responses send Authorization: Bearer <key>, and anthropic-messages sends the key as x-api-key. Both header styles are what the curl examples on the QCode endpoints page use.

Install¶

Desktop. MiniMax Code supports macOS 12 and later and Windows 10 and later. Download it from the global site (code.minimax.io/about) or the China site (code.minimax.cn/about), or on macOS use Homebrew:

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

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

CLI (mcode). The official installer needs no 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

Reopen the terminal and check it (the 2026-11-10 test used the npm route, and mcode --version printed 0.7.6):

mcode --version
mcode --help

You do not need a MiniMax login to use your own key. The repository README says "BYOK does not require a MiniMax login.", and the 2026-11-10 test ran without mcode login. Sign in with mcode login (mainland China account) or mcode login --region global (Global account) only if you also want MiniMax's own models.

Configure the mcode CLI¶

Put the key in MCODE_PROVIDER_API_KEY, then add one provider per format. These are the commands tested on 2026-11-10 with mcode 0.7.6; only the key is a placeholder:

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

Each successful command prints Provider added and selected: <name>. Then run one task with the selected model, or pick a model for a single run with --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"

What to know about these commands:

• Where the key ends up. MCODE_PROVIDER_API_KEY and --api-key-env <name> are read only at the moment you add the provider; mcode then saves the key in plain text as options.apiKey in ~/.minimax/config.yaml. Keep that file private. To change the key later, add the provider again or edit that value.
• Your own variable name. Add --api-key-env QCODE_API_KEY to read the key from QCODE_API_KEY instead (tested with the openai-completions entry).
• --use tests the first listed model, then saves the provider and selects that model as the default; a failed connection test exits nonzero and saves nothing. The test is one real model request. Each --use moves the default, so add the provider you want as default last, or switch later with /model.
• More models. Pass --model more than once to add several models to one provider, for example --model claude-haiku-5-5 --model claude-sonnet-5-5. The provider ID is custom_provider: plus the --name value, for example custom_provider:qcode-a.
• Limits. For custom models you can set --context-limit and --output-limit (positive integers, applied to every repeated --model). Without them, unknown custom models fall back to 200,000 context tokens and 16,384 output tokens.
• Regional hosts. In Asia, including mainland China, you can use asia.qcode.cc; in North America and Europe, us.qcode.cc. Keep the path, for example https://asia.qcode.cc/api.

Inside the TUI, pick a model with /model [filter] and manage saved providers with /provider.

Configure the desktop app¶

The official steps (Settings → Usage & model; the China version shows the same path with Chinese labels):

1. Open Settings → Usage & model, then select Add model under Custom model.
2. Search for a preset provider, or select Others and enter the provider name, base URL, API key and API format.
3. Enter a model ID, or select Fetch to choose from the provider's list. The model ID must match the ID in the provider's documentation.
4. Select Save, return to the message box and choose the new model from the model menu.

Values for the "Others" form. They are the same three Base URLs tested with the CLI above; the desktop app itself was not part of the 2026-11-10 test, so the in-app connectivity test has the final word. Create one entry per format; one QCode key can serve several entries:

Per the official page, "Fetch" only reads the provider's model list and does not save anything; "Save" does not run a test and does not switch the current task's model. Use the test button next to a model (the connectivity test) before relying on it.

Where the file lives. Custom providers are kept in <dataDir>/config.yaml on macOS and <dataDir>\config.yaml on Windows, under the custom_provider key. The official guide warns that custom installation or launch settings can change the data directory, so it does not give one fixed path for the desktop app, and neither does this page. The guide is written for having an agent edit the file; editing through the Settings screen above is the simpler route. If you do edit the file, merge an entry like this into the existing content, back it up first, and avoid saving settings in the app at the same time:

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]

The numbers context and output are placeholders: the guide says form defaults are not evidence of model capabilities, and limit values are positive integers, not strings like 128K. Use the limits you have confirmed for the model. ${API_KEY} is not expanded, so apiKey holds the real key.

Verify¶

CLI first, because provider test sends a real request:

mcode provider list
mcode provider test custom_provider:qcode-a

The full form is mcode provider test <provider-id> [--model <id>] [--json]. In the 2026-11-10 test it printed Provider available: custom_provider:qcode-a and exited with 0. mcode provider list shows keys masked, and it also lists the built-in minimax_oauth entry (managed login), which does not affect your custom providers. In the TUI, /status shows the account and model, and /doctor checks the configuration.

Desktop: run the connectivity test next to the model, then pick the model from the model menu and send a short message. The official page adds that a passing test only shows the test request went through; images, video and other inputs still have to be checked with your own examples.

For a check outside the tool, send one request to the endpoint your format uses (replace the key and model):

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"}]}'

A JSON reply with content means key and path are right. Otherwise read the JSON error body: it separates a wrong path or key from a model not offered on that endpoint.

Troubleshooting and known limitations¶

The first four rows are the official troubleshooting table for custom models:

Other points:

• A failed BYOK request keeps the selected provider and reports the error; MiniMax Code does not silently switch to a managed model or another provider.
• The CLI also lists google-generative-ai as a fourth API format for Google Gemini. QCode does not offer the Gemini family, so there is no QCode setup for it.
• QCode does not offer gpt-6-luna or gpt-5.6-luna; use gpt-6.1-sol or gpt-6.1-terra.
• Versions, 2026-11-10: this page was tested with mcode 0.7.6, the latest version of npm @minimax-ai/code; the GitHub Releases page still marks tag v0.7.2 as the latest release. Run mcode --version to see your build. The desktop BYOK pages carry the date 2026-09-16 and say formats "may differ between app versions".
• Which model fits which job: Model Selection. Errors outside this tool: Troubleshooting.

Related¶

• Endpoints & API Paths: protocol against model family
• Tool Compatibility: which tools speak which protocol
• Kimi Code CLI Setup: another terminal agent, tested on the same three endpoints
• Chinese Models: model IDs on the OpenAI Chat endpoint
• Model Selection: matching model to task

Enterprise →