# MiniMax Code Setup with QCode (BYOK)

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

| Item | Details |
|---|---|
| What it is | MiniMax Code is a desktop AI Agent app for macOS and Windows; `mcode` is its terminal CLI (interactive TUI, `mcode exec` headless mode, `mcode acp`). The CLI source is on GitHub under MIT; the repository states the desktop application's source is not included |
| Models you can use | Claude ✅ (`anthropic-messages`) · GPT ✅ (`openai-completions` or `openai-responses`) · GLM / Kimi / DeepSeek / Qwen ✅ (`anthropic-messages` or `openai-completions`) · Gemini ❌ (QCode does not offer the Gemini family; use Claude, GPT or a Chinese model) |
| Base URL for each format | `anthropic-messages`: `https://api.qcode.cc/api` · `openai-completions`: `https://api.qcode.cc/openai/v1` · `openai-responses`: `https://api.qcode.cc/openai/v1` · all three ✅ tested with mcode 0.7.6 (2026-11-10) |
| Where to configure | CLI: `mcode provider add`, saved under `custom_provider` in `~/.minimax/config.yaml` (default data directory). Desktop: **Settings → Usage & model** → Custom model → Add model |
| API key | Your QCode key, `cr_xxx`. The CLI reads it from `MCODE_PROVIDER_API_KEY`, or from the variable named by `--api-key-env`, when you add the provider |
| MiniMax login | Not needed for your own key; `mcode login` is only for MiniMax's own models |
| Official docs | [Custom Models / BYOK](https://code.minimax.io/docs/code/account/byok) · [Configure BYOK Models with an Agent](https://code.minimax.io/docs/code/account/byok-agent-setup) · [CLI configuration](https://code.minimax.io/docs/cli/configuration) · [CLI quick start](https://code.minimax.io/docs/cli/quick-start) · [GitHub: MiniMax-AI/minimax-code](https://github.com/MiniMax-AI/minimax-code) |

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

| API format | Base URL shape in the official table | Request target | Fill in for QCode |
|---|---|---|---|
| `anthropic-messages` | `https://example.invalid`, or a provider-specified compatibility prefix | `<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` |

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](/docs/getting-started/endpoints-and-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:

| Models | `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 (e.g. `glm-5.3`, `kimi-k3`, `deepseek-v4-flash`, `qwen3.8-max`) | ✅ | ✅ | ❌ |

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](https://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](/docs/getting-started/endpoints-and-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:

```bash
# 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`:

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

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

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

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

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

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

| Field | Claude | GPT | GLM / Kimi / DeepSeek / Qwen |
|---|---|---|---|
| Provider name | `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 key | `cr_xxx` | `cr_xxx` | `cr_xxx` |
| API format | `anthropic-messages` | `openai-completions` (or `openai-responses`) | `openai-completions` (or `anthropic-messages` with `https://api.qcode.cc/api`) |
| Model ID | `claude-sonnet-5-5` | `gpt-6.1-sol` | `deepseek-v4-flash` |

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:

```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]
```

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:

```bash
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):

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

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:

| Symptom | What the official docs say to check | What to do with QCode |
|---|---|---|
| Saved model does not appear | Correct data directory, provider and model enabled, configuration under `custom_provider`, app loaded the change | Re-open the desktop app if you edited the file by hand |
| 401 / 403 | Key belongs to this provider; no mask or unexpanded placeholder; custom headers did not override authentication | Paste the full `cr_` key, not a masked value |
| 404 | "Matching API format and Base URL; required `/v1` and gateway prefix preserved; exact model ID exists" | `anthropic-messages` → `https://api.qcode.cc/api`; both OpenAI formats → `https://api.qcode.cc/openai/v1`; model ID copied from [qcode.cc/models](https://qcode.cc/models) |
| Failed test but model remains selectable | Test status is diagnostic only; fix the error the test reports instead of recording a success | Fix the error shown, then test again |
| `model_not_available_on_endpoint` | Not in the MiniMax docs; it is the QCode error for a Claude ID sent to an OpenAI format | Use `anthropic-messages` for `claude-*` |
| Text works but attachments or tools fail | The declared capability must be supported by the provider and protocol | Add only capabilities you have verified |
| New QCode key, but mcode still sends the old one | The key was copied into `config.yaml` when the provider was added | Add the provider again, or edit `options.apiKey` in `~/.minimax/config.yaml` |
| Log line `token counter endpoint missing; disabling remote counting for this base url` | Not in the MiniMax docs; seen in the 2026-11-10 test | Informational: mcode stops remote token counting for that Base URL, and the chat itself continues |

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](/docs/usage/model-selection). Errors outside this tool: [Troubleshooting](/docs/reference/troubleshooting).

## Related

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths): protocol against model family
- [Tool Compatibility](/docs/ide/tool-compatibility): which tools speak which protocol
- [Kimi Code CLI Setup](/docs/ide/kimi-code): another terminal agent, tested on the same three endpoints
- [Chinese Models](/docs/usage/cn-models): model IDs on the OpenAI Chat endpoint
- [Model Selection](/docs/usage/model-selection): matching model to task