# Настройка MiniMax Code с QCode (BYOK)

> **Последняя проверка**: 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-ключ? Да. По официальным страницам BYOK («bring your own key») на 2026-11-10, в десктопном приложении свой провайдер моделей добавляется в **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` отвечала во всех трёх форматах.

## Кратко

| Пункт | Что важно |
|---|---|
| Что это | 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 |
| Официальная документация | [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) |

## Какой протокол выбрать

От выбранного `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-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`.» Иначе говоря, в форматах OpenAI /v1 сам не добавится, а в формате Messages хвосты вроде /v1 нормализуются и дописывать их второй раз не нужно. Для QCode это значит:

- **`anthropic-messages`**: точка доступа Anthropic в QCode — это префикс `/api`, а `/v1/messages` MiniMax Code добавляет сам, поэтому запрос уходит на `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`) | ✅ | ✅ | ❌ |

ID модели должен в точности совпадать с ID в QCode; официальная страница формулирует это так: «The model ID must match the ID in the provider's documentation.» Актуальные ID и цены по моделям — на [qcode.cc/models](https://qcode.cc/models). Модели Claude доступны только через точку доступа Anthropic Messages, поэтому ID `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`); на macOS можно поставить через Homebrew:

```bash
# Версия для материкового Китая
brew install --cask minimax-ai/tap/minimax-code

# Международная версия
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

# или npm: Node.js 22.19.0 и новее (ветка 22.x) либо Node.js 24, 25, 26
npm install -g @minimax-ai/code
```

Откройте терминал заново и проверьте установку (в проверке 2026-11-10 CLI ставился через npm, `mcode --version` вывел `0.7.6`):

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

Для работы со своим ключом входить в MiniMax не нужно. В README репозитория сказано: «BYOK does not require a MiniMax login.», и проверка 2026-11-10 шла без `mcode login`. Вход через `mcode login` (аккаунт для материкового Китая) или `mcode login --region global` (аккаунт Global) понадобится, только если вы хотите ещё и собственные модели MiniMax.

## Настройка CLI mcode

Положите ключ в `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 и китайские модели
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`. ID провайдера — это `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** и выберите **Add model** в разделе Custom model.
2. Найдите готового провайдера или выберите **Others** и введите имя провайдера, Base URL, API-ключ и формат API.
3. Введите ID модели или нажмите **Fetch**, чтобы выбрать из списка провайдера. ID должен совпадать с указанным в документации провайдера.
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`) |
| ID модели | `claude-sonnet-5-5` | `gpt-6.1-sol` | `deepseek-v4-flash` |

По официальной странице, «Fetch» только читает список моделей провайдера и ничего не сохраняет, а «Save» не запускает тест и не меняет модель текущей задачи. Прежде чем работать, нажмите кнопку проверки рядом с моделью (проверка соединения).

**Где лежит файл.** Пользовательские провайдеры хранятся в `<dataDir>/config.yaml` на macOS и в `<dataDir>\config.yaml` на Windows, в ключе `custom_provider`. Официальное руководство предупреждает, что особая установка или параметры запуска могут сменить каталог данных, поэтому единого пути для десктопа оно не даёт — и эта страница тоже. Руководство рассчитано на то, что файл правит агент; через экран настроек выше проще. Если всё же правите файл вручную, сначала сделайте резервную копию, добавьте в существующее содержимое запись вроде этой и не сохраняйте в это время настройки в приложении:

```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 | «Matching API format and Base URL; required `/v1` and gateway prefix preserved; exact model ID exists» | `anthropic-messages` → `https://api.qcode.cc/api`; оба формата OpenAI → `https://api.qcode.cc/openai/v1`; ID модели скопируйте с [qcode.cc/models](https://qcode.cc/models) |
| Тест не прошёл, но модель можно выбрать | Статус теста — только диагностика; исправляйте ошибку, о которой сообщает тест, а не записывайте успех | Исправьте показанную ошибку и повторите тест |
| `model_not_available_on_endpoint` | В документации MiniMax нет; это ошибка QCode, когда ID Claude отправлен в формате OpenAI | Для `claude-*` используйте `anthropic-messages` |
| Текст работает, вложения или инструменты — нет | Заявленная возможность должна поддерживаться провайдером и протоколом | Указывайте только проверенные возможности |
| Ключ 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 отключает удалённый подсчёт токенов для этого Base URL, а диалог продолжается как обычно |

Ещё несколько моментов:

- При неудачном BYOK-запросе выбранный провайдер сохраняется и показывается ошибка; MiniMax Code не переключается молча на управляемую модель или другого провайдера.
- В CLI есть и четвёртый формат API — `google-generative-ai` для 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 и предупреждают, что форматы «may differ between app versions».
- Какую модель брать под задачу — в разделе [Выбор модели](/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): ID моделей на точке доступа OpenAI Chat
- [Выбор модели](/docs/usage/model-selection): модель под задачу