# MiniMax Code mit QCode einrichten (BYOK)

> **Zuletzt geprüft**: 2026-11-10 · 📄 Laut offizieller Dokumentation (Desktop-BYOK-Seiten, aktualisiert 2026-09-16; mcode-CLI-Dokumentation, npm `@minimax-ai/code` 0.7.6) · ✅ QCode-Anbindung mit mcode 0.7.6 getestet (2026-11-10)

Kann MiniMax Code einen eigenen API-Schlüssel verwenden? Ja. Laut den offiziellen BYOK-Seiten („bring your own key“, Stand 2026-11-10) fügen Sie in der Desktop-App unter **Settings → Usage & model** einen eigenen Modellanbieter hinzu, und die `mcode`-CLI erledigt dasselbe mit `mcode provider add`. Beide unterstützen drei API-Formate, `anthropic-messages`, `openai-completions` und `openai-responses`, und QCode bedient alle drei: Mit einem QCode-Schlüssel nutzen Sie Claude, GPT und die chinesischen Modellfamilien im selben Werkzeug. Getestet am 2026-11-10 mit mcode 0.7.6: Ohne MiniMax-Anmeldung lieferte `mcode exec` nach `mcode provider add … --use` in allen drei Formaten eine Antwort.

## Auf einen Blick

| Punkt | Details |
|---|---|
| Was es ist | MiniMax Code ist eine Desktop-App (AI Agent) für macOS und Windows; `mcode` ist die zugehörige Terminal-CLI (interaktives TUI, Headless-Modus `mcode exec`, `mcode acp`). Der CLI-Quellcode liegt unter MIT-Lizenz auf GitHub; laut Repository ist der Quellcode der Desktop-App nicht enthalten |
| Nutzbare Modelle | Claude ✅ (`anthropic-messages`) · GPT ✅ (`openai-completions` oder `openai-responses`) · GLM / Kimi / DeepSeek / Qwen ✅ (`anthropic-messages` oder `openai-completions`) · Gemini ❌ (QCode bietet die Gemini-Familie nicht an; nutzen Sie Claude, GPT oder ein chinesisches Modell) |
| Base URL je Format | `anthropic-messages`: `https://api.qcode.cc/api` · `openai-completions`: `https://api.qcode.cc/openai/v1` · `openai-responses`: `https://api.qcode.cc/openai/v1` · alle drei ✅ mit mcode 0.7.6 getestet (2026-11-10) |
| Wo eingerichtet wird | CLI: `mcode provider add`, gespeichert unter `custom_provider` in `~/.minimax/config.yaml` (Standard-Datenverzeichnis). Desktop: **Settings → Usage & model** → Custom model → Add model |
| API-Schlüssel | Ihr QCode-Schlüssel, `cr_xxx`. Die CLI liest ihn beim Hinzufügen des Anbieters aus `MCODE_PROVIDER_API_KEY` oder aus der Variable, die Sie mit `--api-key-env` angeben |
| MiniMax-Anmeldung | Für den eigenen Schlüssel nicht nötig; `mcode login` brauchen Sie nur für die eigenen Modelle von MiniMax |
| Offizielle Dokumentation | [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) |

## Welches Protokoll

Das gewählte `API format` bestimmt, welchen QCode-Endpunkt MiniMax Code aufruft. Der offizielle Konfigurationsleitfaden zeigt in einer Tabelle, wie aus der Base URL die Anfrageadresse wird:

| API-Format | Base URL laut offizieller Tabelle | Ziel der Anfrage | Für QCode eintragen |
|---|---|---|---|
| `anthropic-messages` | `https://example.invalid` oder ein vom Anbieter vorgegebenes Kompatibilitätspräfix | `<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` |

Die Erläuterung im Leitfaden lautet wörtlich: „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`.“ Bei den OpenAI-Formaten wird /v1 also nicht automatisch ergänzt, beim Messages-Format werden Endungen wie /v1 normalisiert und sollen nicht doppelt angehängt werden. Für QCode heißt das:

- **`anthropic-messages`**: Der Anthropic-Endpunkt von QCode ist das Präfix `/api`, und MiniMax Code hängt `/v1/messages` selbst an; die Anfrage landet also bei `https://api.qcode.cc/api/v1/messages`. Behalten Sie `/api` bei und tippen Sie `/v1/messages` nicht selbst ein.
- **`openai-completions`**: Die Base URL muss `/v1` bereits enthalten, weil das Werkzeug nur `/chat/completions` anhängt. Aus `https://api.qcode.cc/openai/v1` wird `https://api.qcode.cc/openai/v1/chat/completions`.
- **`openai-responses`**: Gleiche Regel, die Base URL enthält `/v1`, das Werkzeug hängt `/responses` an. Aus `https://api.qcode.cc/openai/v1` wird `https://api.qcode.cc/openai/v1/responses` – genau der Responses-Pfad aus [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths).

Alle drei Werte der letzten Spalte wurden am 2026-11-10 mit mcode 0.7.6 getestet, je Format mit einem Modell (`claude-haiku-5-5`, `deepseek-v4-flash`, `gpt-6.1-terra`).

Welche Modelle zu welchem Format passen:

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

Die Modell-ID muss exakt der QCode-ID entsprechen; die offizielle Seite schreibt: „The model ID must match the ID in the provider's documentation.“ Aktuelle IDs und die Preise je Modell finden Sie unter [qcode.cc/models](https://qcode.cc/models). Claude-Modelle gibt es nur am Anthropic-Messages-Endpunkt; eine `claude-*`-ID unter `openai-completions` oder `openai-responses` liefert daher `model_not_available_on_endpoint` (siehe [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths)).

Laut den offiziellen CLI-Hinweisen richtet sich die Authentifizierung nach dem Format: `openai-completions` und `openai-responses` senden `Authorization: Bearer <key>`, `anthropic-messages` sendet den Schlüssel als `x-api-key`. Beide Header-Varianten verwenden auch die curl-Beispiele auf der QCode-Endpunktseite.

## Installation

**Desktop.** MiniMax Code läuft ab macOS 12 und ab Windows 10. Laden Sie es von der internationalen Seite (`code.minimax.io/about`) oder der China-Seite (`code.minimax.cn/about`) herunter; unter macOS geht es auch per Homebrew:

```bash
# Version für Festlandchina
brew install --cask minimax-ai/tap/minimax-code

# Internationale Version
brew install --cask minimax-ai/tap/minimax-code --language=en
```

**CLI (`mcode`).** Der offizielle Installer braucht kein `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

# oder npm: Node.js 22.19.0 oder neuer (22.x) bzw. Node.js 24, 25, 26
npm install -g @minimax-ai/code
```

Öffnen Sie das Terminal neu und prüfen Sie die Installation (beim Test am 2026-11-10 wurde per npm installiert, `mcode --version` gab `0.7.6` aus):

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

Für den eigenen Schlüssel brauchen Sie keine MiniMax-Anmeldung. Das README im Repository sagt: „BYOK does not require a MiniMax login.“, und der Test am 2026-11-10 lief ohne `mcode login`. Melden Sie sich mit `mcode login` (Konto für Festlandchina) oder `mcode login --region global` (Global-Konto) nur an, wenn Sie zusätzlich die eigenen Modelle von MiniMax nutzen möchten.

## mcode-CLI konfigurieren

Legen Sie den Schlüssel in `MCODE_PROVIDER_API_KEY` ab und fügen Sie je Format einen Anbieter hinzu. Das sind genau die Befehle, die am 2026-11-10 mit mcode 0.7.6 getestet wurden; nur der Schlüssel ist ein Platzhalter:

```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 und chinesische Modelle
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
```

Jeder erfolgreiche Befehl meldet `Provider added and selected: <name>`. Starten Sie danach eine Aufgabe mit dem ausgewählten Modell; für einen einzelnen Lauf wählen Sie ein Modell mit `--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"
```

Was Sie zu diesen Befehlen wissen sollten:

- **Wo der Schlüssel landet.** `MCODE_PROVIDER_API_KEY` und `--api-key-env <name>` werden nur in dem Moment gelesen, in dem Sie den Anbieter hinzufügen; danach speichert mcode den Schlüssel im Klartext als `options.apiKey` in `~/.minimax/config.yaml`. Halten Sie diese Datei privat. Für einen neuen Schlüssel fügen Sie den Anbieter erneut hinzu oder ändern diesen Wert.
- **Eigener Variablenname.** Mit `--api-key-env QCODE_API_KEY` liest mcode den Schlüssel stattdessen aus `QCODE_API_KEY` (getestet beim Eintrag `openai-completions`).
- **`--use`** testet das erste angegebene Modell, speichert dann den Anbieter und setzt dieses Modell als Standard; scheitert der Verbindungstest, endet der Befehl mit einem Exit-Code ungleich 0 und speichert nichts. Der Test ist eine echte Modellanfrage. Jedes `--use` verschiebt den Standard – fügen Sie den gewünschten Standardanbieter daher zuletzt hinzu oder wechseln Sie später mit `/model`.
- **Mehrere Modelle.** Geben Sie `--model` mehrfach an, um einem Anbieter mehrere Modelle zuzuordnen, etwa `--model claude-haiku-5-5 --model claude-sonnet-5-5`. Die Anbieter-ID ist `custom_provider:` plus der Wert von `--name`, zum Beispiel `custom_provider:qcode-a`.
- **Grenzwerte.** Für eigene Modelle lassen sich `--context-limit` und `--output-limit` setzen (positive Ganzzahlen, gelten für jedes wiederholte `--model`). Ohne diese Angaben fallen unbekannte eigene Modelle auf 200.000 Kontext-Token und 16.384 Ausgabe-Token zurück.
- **Regionale Hosts.** In Asien, einschließlich Festlandchina, können Sie `asia.qcode.cc` verwenden, in Nordamerika und Europa `us.qcode.cc`. Der Pfad bleibt gleich, zum Beispiel `https://asia.qcode.cc/api`.

Im TUI wählen Sie ein Modell mit `/model [filter]` und verwalten gespeicherte Anbieter mit `/provider`.

## Desktop-App konfigurieren

Die offiziellen Schritte (Settings → Usage & model; die China-Version zeigt denselben Pfad mit chinesischen Bezeichnungen):

1. Öffnen Sie **Settings → Usage & model** und wählen Sie unter Custom model **Add model**.
2. Suchen Sie einen vordefinierten Anbieter oder wählen Sie **Others** und geben Sie Anbietername, Base URL, API-Schlüssel und API-Format ein.
3. Geben Sie eine Modell-ID ein oder wählen Sie mit **Fetch** aus der Liste des Anbieters. Die Modell-ID muss der ID in der Dokumentation des Anbieters entsprechen.
4. Wählen Sie **Save**, kehren Sie zum Eingabefeld zurück und wählen Sie das neue Modell im Modellmenü.

Werte für das Formular „Others“. Es sind dieselben drei Base URLs, die oben mit der CLI getestet wurden; die Desktop-App selbst war nicht Teil des Tests vom 2026-11-10, maßgeblich ist daher der Verbindungstest in der App. Legen Sie je Format einen Eintrag an; ein QCode-Schlüssel reicht für alle:

| Feld | Claude | GPT | GLM / Kimi / DeepSeek / Qwen |
|---|---|---|---|
| Anbietername | `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-Schlüssel | `cr_xxx` | `cr_xxx` | `cr_xxx` |
| API-Format | `anthropic-messages` | `openai-completions` (oder `openai-responses`) | `openai-completions` (oder `anthropic-messages` mit `https://api.qcode.cc/api`) |
| Modell-ID | `claude-sonnet-5-5` | `gpt-6.1-sol` | `deepseek-v4-flash` |

Laut offizieller Seite liest „Fetch“ nur die Modellliste des Anbieters und speichert nichts; „Save“ führt keinen Test aus und wechselt nicht das Modell der laufenden Aufgabe. Nutzen Sie vor dem Einsatz die Testschaltfläche neben dem Modell (Verbindungstest).

**Wo die Datei liegt.** Eigene Anbieter stehen unter macOS in `<dataDir>/config.yaml` und unter Windows in `<dataDir>\config.yaml`, jeweils unter dem Schlüssel `custom_provider`. Der offizielle Leitfaden warnt, dass eine angepasste Installation oder Startkonfiguration das Datenverzeichnis ändern kann; er nennt deshalb keinen festen Pfad für die Desktop-App, und diese Seite tut es auch nicht. Der Leitfaden ist dafür gedacht, dass ein Agent die Datei bearbeitet; über den Einstellungsbildschirm oben geht es einfacher. Wenn Sie die Datei doch von Hand bearbeiten, legen Sie zuerst eine Sicherung an, ergänzen Sie einen Eintrag wie diesen im vorhandenen Inhalt und speichern Sie währenddessen keine Einstellungen in der App:

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

Die Zahlen bei `context` und `output` sind Platzhalter: Laut Leitfaden sind Formular-Standardwerte kein Beleg für Modellfähigkeiten, und `limit`-Werte sind positive Ganzzahlen, keine Zeichenketten wie `128K`. Tragen Sie die Grenzwerte ein, die Sie für das Modell bestätigt haben. `${API_KEY}` wird nicht aufgelöst; in `apiKey` gehört der echte Schlüssel.

## Überprüfen

Zuerst die CLI, denn `provider test` sendet eine echte Anfrage:

```bash
mcode provider list
mcode provider test custom_provider:qcode-a
```

Die vollständige Form lautet `mcode provider test <provider-id> [--model <id>] [--json]`. Im Test am 2026-11-10 gab der Befehl `Provider available: custom_provider:qcode-a` aus und endete mit Exit-Code 0. `mcode provider list` zeigt Schlüssel maskiert und listet zusätzlich den eingebauten Eintrag `minimax_oauth` (verwaltete Anmeldung); Ihre eigenen Anbieter beeinflusst er nicht. Im TUI zeigt `/status` Konto und Modell, `/doctor` prüft die Konfiguration.

Desktop: Starten Sie den Verbindungstest neben dem Modell, wählen Sie das Modell dann im Modellmenü und senden Sie eine kurze Nachricht. Die offizielle Seite ergänzt, dass ein bestandener Test nur zeigt, dass die Testanfrage durchging; Bilder, Video und andere Eingaben prüfen Sie mit eigenen Beispielen.

Für eine Prüfung außerhalb des Werkzeugs senden Sie eine Anfrage an den Endpunkt Ihres Formats (Schlüssel und Modell ersetzen):

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

Kommt ein JSON mit Modellantwort zurück, stimmen Schlüssel und Pfad. Andernfalls lesen Sie den JSON-Fehlertext: Er unterscheidet einen falschen Pfad oder Schlüssel von einem Modell, das an diesem Endpunkt nicht angeboten wird.

## Fehlerbehebung und bekannte Einschränkungen

Die ersten vier Zeilen stammen aus der offiziellen Fehlerbehebungstabelle für eigene Modelle:

| Symptom | Was die offizielle Dokumentation prüfen lässt | Vorgehen mit QCode |
|---|---|---|
| Gespeichertes Modell erscheint nicht | Richtiges Datenverzeichnis; Anbieter und Modell aktiviert; Konfiguration unter `custom_provider`; Änderung von der App geladen | Nach einer Bearbeitung von Hand die Desktop-App neu öffnen |
| 401 / 403 | Schlüssel gehört zu diesem Anbieter; keine Maske und kein nicht aufgelöster Platzhalter; eigene Header überschreiben die Authentifizierung nicht | Den vollständigen `cr_`-Schlüssel einfügen, keinen maskierten Wert |
| 404 | „Matching API format and Base URL; required `/v1` and gateway prefix preserved; exact model ID exists“ | `anthropic-messages` → `https://api.qcode.cc/api`; beide OpenAI-Formate → `https://api.qcode.cc/openai/v1`; Modell-ID von [qcode.cc/models](https://qcode.cc/models) kopieren |
| Test gescheitert, Modell aber weiter auswählbar | Der Teststatus dient nur der Diagnose; beheben Sie den gemeldeten Fehler, statt einen Erfolg einzutragen | Gemeldeten Fehler beheben, dann erneut testen |
| `model_not_available_on_endpoint` | Nicht in der MiniMax-Dokumentation; das ist der QCode-Fehler, wenn eine Claude-ID an ein OpenAI-Format geht | Für `claude-*` das Format `anthropic-messages` verwenden |
| Text klappt, Anhänge oder Tools scheitern | Die angegebene Fähigkeit muss von Anbieter und Protokoll unterstützt werden | Nur geprüfte Fähigkeiten angeben |
| Neuer QCode-Schlüssel, aber mcode sendet den alten | Der Schlüssel wurde beim Hinzufügen des Anbieters in `config.yaml` kopiert | Anbieter erneut hinzufügen oder `options.apiKey` in `~/.minimax/config.yaml` ändern |
| Logzeile `token counter endpoint missing; disabling remote counting for this base url` | Nicht in der MiniMax-Dokumentation; im Test am 2026-11-10 aufgetreten | Nur ein Hinweis: mcode schaltet die entfernte Token-Zählung für diese Base URL ab, der Chat läuft normal weiter |

Weitere Punkte:

- Eine fehlgeschlagene BYOK-Anfrage behält den gewählten Anbieter bei und meldet den Fehler; MiniMax Code wechselt nicht stillschweigend zu einem verwalteten Modell oder einem anderen Anbieter.
- Die CLI führt mit `google-generative-ai` ein viertes API-Format für Google Gemini. QCode bietet die Gemini-Familie nicht an, daher gibt es dafür keine QCode-Einrichtung.
- QCode bietet `gpt-6-luna` und `gpt-5.6-luna` nicht an; verwenden Sie `gpt-6.1-sol` oder `gpt-6.1-terra`.
- Versionen am 2026-11-10: Diese Seite wurde mit mcode 0.7.6 getestet, der `latest`-Version von npm `@minimax-ai/code`; die GitHub-Releases-Seite führt weiterhin das Tag v0.7.2 als neuestes Release. Ihre Version zeigt `mcode --version`. Die Desktop-BYOK-Seiten tragen das Datum 2026-09-16 und weisen darauf hin, dass Formate „may differ between app versions“.
- Welches Modell zu welcher Aufgabe passt: [Modellauswahl](/docs/usage/model-selection). Fehler außerhalb dieses Werkzeugs: [Fehlerbehebungsleitfaden](/docs/reference/troubleshooting).

## Verwandte Dokumente

- [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths): Protokoll und Modellfamilie
- [Übersicht der Tool-Kompatibilität](/docs/ide/tool-compatibility): welches Werkzeug welches Protokoll spricht
- [Kimi Code CLI einrichten](/docs/ide/kimi-code): ein weiterer Terminal-Agent, an denselben drei Endpunkten getestet
- [Chinesische Modelle](/docs/usage/cn-models): Modell-IDs am OpenAI-Chat-Endpunkt
- [Modellauswahl](/docs/usage/model-selection): das passende Modell zur Aufgabe