# CodeBuddy: eigene Modelle mit QCode

> **Zuletzt überprüft**: 2026-11-10 · 📄 Laut offizieller Dokumentation (CodeBuddy IDE 4.12.4, veröffentlicht am 2026-11-06; CLI-Dokumentation zu v2.182.0) · ✅ QCode-Anbindung mit CodeBuddy Code CLI 2.182.0 getestet (2026-11-10)

Ja, CodeBuddy kann Ihren eigenen Schlüssel nutzen: Eigene Modelle stehen in `models.json` (auf Benutzerebene `~/.codebuddy/models.json`), und die offizielle Dokumentation sagt „Currently only supports OpenAI interface format API“. Stand 2026-11-10, getestet mit CodeBuddy Code CLI 2.182.0: QCode funktioniert über OpenAI Chat Completions (`url` ist der vollständige Pfad) und OpenAI Responses (`url` ist die Basis), und die CLI nutzt diese Modelle ohne Anmeldung bei einem Tencent-Konto. Die Schritte für die IDE folgen der offiziellen Dokumentation.

## Auf einen Blick

| Punkt | Details |
|---|---|
| Eigener Schlüssel möglich? | Ja. IDE und CLI lesen `models.json`; die CLI braucht dafür keine Anmeldung (✅ getestet) |
| Nutzbare Modelle | Claude ❌ (dieses Protokoll ist nicht der Anthropic-Endpunkt) · GPT ✅ · chinesische Modelle ✅ · Gemini ❌ (QCode bietet derzeit kein Gemini an) |
| Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` (vollständiger Pfad) · ✅ in der CLI getestet |
| Responses (CLI) | `"api": "openai-responses"`, `url`: `https://api.qcode.cc/openai/v1` · ✅ in der CLI getestet |
| Umgebungsvariablen (CLI) | `CODEBUDDY_BASE_URL=https://api.qcode.cc/openai/v1` (OpenAI Chat) · ✅ in der CLI getestet |
| Konfigurationsdateien | Benutzerebene `~/.codebuddy/models.json`; Projektebene `<project-root>/.codebuddy/models.json` |
| Offizielle Doku | [IDE models.json](https://www.codebuddy.ai/docs/ide/Features/models) · [CLI models.json](https://www.codebuddy.ai/docs/cli/models) · [CLI-Umgebungsvariablen](https://www.codebuddy.ai/docs/cli/env-vars) |

CodeBuddy ist das KI-Programmierwerkzeug von Tencent Cloud. Es gibt drei Formen: ein Plugin für VS Code und JetBrains-IDEs, die eigenständige CodeBuddy IDE und CodeBuddy Code, ein Kommandozeilenwerkzeug mit dem Befehl `codebuddy`. Die Websites sind [codebuddy.cn](https://www.codebuddy.cn) (Festland-China) und [codebuddy.ai](https://www.codebuddy.ai) (international); der Dateipfad für eigene Modelle ist in beiden Dokumentationen gleich. WorkBuddy, der Office-Agent desselben Teams, nutzt dieselbe Basis; siehe [eigenes Modell in WorkBuddy](/docs/ide/workbuddy).

QCode.cc ist nicht mit Tencent oder CodeBuddy verbunden. Oberfläche und Felder richten sich nach Ihrer installierten Version.

## Welches Protokoll

| Einstieg | Protokoll | Wert für QCode | Modelle |
|---|---|---|---|
| `models.json` (IDE und CLI) | OpenAI Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` | GPT, DeepSeek / GLM / Kimi / Qwen |
| `models.json` mit `"api": "openai-responses"` (CLI) | OpenAI Responses | `url`: `https://api.qcode.cc/openai/v1` | GPT |
| `CODEBUDDY_BASE_URL` (CLI) | OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT, DeepSeek / GLM / Kimi / Qwen |

Über diese Protokolle stehen bei QCode GPT und die chinesischen Modelle bereit. Claude-Modelle laufen über den Anthropic-Endpunkt, und die eigenen Modelle von CodeBuddy nutzen dieses Protokoll nicht. Wenn Sie Claude brauchen, verwenden Sie ein Werkzeug mit Anthropic-Endpunkt, etwa [Claude Code](/docs/getting-started/installation), [ZCode](/docs/ide/zcode) oder [Qoder](/docs/ide/qoder). Die drei Protokolle vergleicht [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths). Aus Festland-China können Sie `asia.qcode.cc` statt `api.qcode.cc` verwenden; Pfad und Schlüssel bleiben gleich.

## CodeBuddy Code CLI installieren

Die offizielle Installationsanleitung nennt diesen Weg (Voraussetzung: Node.js 18.20 oder neuer); er wurde auch im Test vom 2026-11-10 verwendet:

```bash
npm install -g @tencent-ai/codebuddy-code
```

Ohne Node.js bietet die Anleitung auch Homebrew und eine native Binärdatei (Beta):

```bash
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

In Windows PowerShell verwenden Sie `irm https://www.codebuddy.cn/cli/install.ps1 | iex`. Prüfen Sie die Installation mit `codebuddy --version` (im Test 2.182.0). Die eigenen Modelle unten funktionieren ohne Anmeldung bei einem Tencent-Konto. Die IDE oder das Plugin laden Sie auf [codebuddy.ai](https://www.codebuddy.ai) herunter; wenn Sie nur die IDE nutzen, können Sie diesen Abschnitt überspringen.

## models.json konfigurieren

### Speicherorte

Die Dokumentation beschreibt zwei Ebenen:

- Benutzerebene: `~/.codebuddy/models.json`, global, gilt für alle Projekte
- Projektebene: `<project-root>/.codebuddy/models.json`, hat Vorrang vor der Benutzerebene

Zusammengeführt wird in der Reihenfolge Projektebene, Benutzerebene, eingebaute Standardwerte. Ein Modell mit gleicher `id` wird überschrieben, eines mit anderer `id` wird ergänzt. IDE und CLI lesen dieselben Pfade.

### CLI: minimale models.json (✅ getestet)

Speichern Sie Folgendes als `~/.codebuddy/models.json`. Der erste Eintrag nutzt Chat Completions, der zweite Responses; der Schlüssel kommt aus einer Umgebungsvariable:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}
```

Exportieren Sie dann den Schlüssel und senden Sie jedem Modell einen einzeiligen Test:

```bash
export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra
```

Die Antwort `OK` bedeutet, dass das Modell funktioniert. Die `id` geht als Modellname an QCode und muss daher eine aktuelle ID von [qcode.cc/models](https://qcode.cc/models) sein, Zeichen für Zeichen. Für Chat-Einträge eignen sich auch `gpt-6.1-sol`, `deepseek-v4-pro`, `glm-5.3`, `kimi-k3` oder `qwen3.8-max` (siehe [Chinesische Modelle](/docs/usage/cn-models)); Responses-Einträge nehmen GPT-IDs. Die Preise pro Modell stehen auf https://qcode.cc/models. Setzen Sie `maxInputTokens`, `maxOutputTokens` und die Bild- oder Reasoning-Flags passend zum gewählten Modell.

### Zwei Regeln für `url`

Für Chat Completions (Standard) lautet die offizielle Formulierung: „url field must be the complete interface path, typically ending with /chat/completions“, mit diesen falschen Beispielen:

```text
❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434
```

Mit `api` auf `openai-responses` kehrt sich die Regel um. Offizielle Formulierung: „With api set to openai-responses, the model uses the OpenAI Responses API: requests go to {url}/responses“ und „url takes the base URL; a trailing /responses is optional.“

| Wert für `url` | Ergebnis |
|---|---|
| `https://api.qcode.cc/openai/v1/chat/completions` | ✅ Chat Completions (getestet) |
| `https://api.qcode.cc/openai/v1` | ✅ mit `"api": "openai-responses"` (getestet); für Chat kein vollständiger Pfad |
| `https://api.qcode.cc/api` | ❌ das Präfix für Anthropic Messages, kein OpenAI-Pfad |

Für Responses hat auch `https://api.qcode.cc/openai` den Test bestanden; diese Seite verwendet `/openai/v1`, damit beide Einträge dieselbe Basis haben. Laut Dokumentation schaltet nur ein im Modelleintrag ausdrücklich gesetztes `api` das Protokoll um.

### CodeBuddy IDE (📄 laut offizieller Dokumentation)

Die IDE-Dokumentation nennt dieselben Dateipfade und die Chat-Felder. Die IDE-Seite beschreibt `apiKey` als „actual key value, not environment variable name“; tragen Sie daher den Schlüssel selbst ein. Ein Chat-Eintrag für die IDE:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}
```

Die Feldtabelle der IDE enthält kein `api`-Feld; Responses-Einträge sind daher für die CLI gedacht. Wenn IDE und CLI dieselbe `~/.codebuddy/models.json` nutzen, tragen Sie den Schlüssel in jedem Eintrag direkt ein; auch die CLI akzeptiert einen direkt eingetragenen Schlüssel. Der offizielle Rat: Committen Sie keine `models.json` mit echtem Schlüssel in die Versionsverwaltung, und setzen Sie die Dateirechte auf 600 (nur der Eigentümer darf lesen und schreiben).

### Feldtabelle

| Feld | Typ | Beschreibung (offizielle Formulierung) |
|---|---|---|
| `id` | string | Pflicht. Eindeutige Modellkennung |
| `name` | string | Anzeigename des Modells |
| `vendor` | string | Modellanbieter (z. B. OpenAI, Google) |
| `apiKey` | string | API-Schlüssel. Die IDE-Seite sagt „actual key value, not environment variable name“; die CLI-Seite sagt, er „supports environment variable references“ |
| `maxInputTokens` | number | Maximale Eingabe-Token |
| `maxOutputTokens` | number | Maximale Ausgabe-Token |
| `url` | string | URL des API-Endpunkts (muss der vollständige Schnittstellenpfad sein, endet meist auf /chat/completions) |
| `supportsToolCall` | boolean | Ob Tool-Aufrufe unterstützt werden |
| `supportsImages` | boolean | Ob Bildeingaben unterstützt werden |
| `supportsReasoning` | boolean | Ob der Reasoning-Modus unterstützt wird |

Die CLI-Seite ergänzt drei Felder: `api` (Anfrageprotokoll; `openai-responses` schaltet auf die Responses API um), `temperature` (Sampling-Temperatur, 0-2) und `relatedModels` (welche Modell-ID für Szenarien wie lite und reasoning dient). Das Feld `availableModels` auf oberster Ebene ist ein String-Array; nur die dort aufgeführten IDs erscheinen in der Auswahlliste, ein leeres oder fehlendes Array zeigt alle Modelle.

### Umgebungsvariablen mit `${VAR_NAME}` referenzieren (CLI)

Laut CLI-Seite unterstützen die Felder `apiKey` und `url` die Referenzsyntax `${VAR_NAME}`; die `apiKey`-Referenz im Block oben hat den Test bestanden. Offizielle Hinweise: Umgebungsvariablen werden beim Start der CLI aufgelöst; existiert eine Variable nicht, bleibt der ursprüngliche Platzhalter stehen, und der API-Aufruf schlägt fehl.

### Hot Reload

Laut Dokumentation unterstützen die Konfigurationsdateien Hot Reload: Änderungen an beiden `models.json` oben werden automatisch mit 1 Sekunde Entprellung erkannt.

## Umgebungsvariablen der CLI

Die offizielle Seite zu Umgebungsvariablen nennt drei Variablen, die für Drittanbietermodelle relevant sind:

| Variable | Offizielle Beschreibung |
|---|---|
| `CODEBUDDY_API_KEY` | API-Schlüssel für Modell-API-Aufrufe. Im nicht interaktiven Modus (-p) wird immer dieser Schlüssel verwendet |
| `CODEBUDDY_BASE_URL` | Überschreibt die Adresse des API-Endpunkts, meist zusammen mit `CODEBUDDY_API_KEY` |
| `CODEBUDDY_MODEL` | Überschreibt das Standard-Agentenmodell |

Stand 2026-11-10, getestet mit CodeBuddy Code CLI 2.182.0: `CODEBUDDY_BASE_URL` erwartet eine Basis für OpenAI Chat Completions, und die CLI hängt `/chat/completions` an. Setzen Sie `https://api.qcode.cc/openai/v1` und wählen Sie ein GPT- oder chinesisches Modell; dieser Weg braucht keine `models.json`:

```bash
export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
```

Lassen Sie `CODEBUDDY_BASE_URL` auf `/openai/v1`: Mit `https://api.qcode.cc/api` geht die Anfrage an `/api/chat/completions`, und QCode antwortet mit HTTP 400.

## Prüfen

Prüfen Sie zuerst, ob der OpenAI-Pfad von QCode aus Ihrem Netz erreichbar ist (derselbe Test wie in [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths)):

```bash
KEY="cr_xxx"

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix
```

Danach:

1. CLI: Führen Sie die `codebuddy -p`-Tests oben aus; `OK` bedeutet Erfolg. Für eine interaktive Sitzung starten Sie `codebuddy --model deepseek-v4-flash`.
2. IDE: Öffnen Sie die Modellauswahl. Laut Dokumentation erhalten Modelle aus `models.json` automatisch das Tag `custom`, damit Sie sie leicht finden und filtern können. Senden Sie dem neuen Modell eine kurze Nachricht.
3. Geben Sie Ihren Schlüssel auf [probe.qcode.cc](https://probe.qcode.cc) ein, um die Anfrage und das antwortende Modell zu sehen.

## Fehlerbehebung

### Die Konfiguration greift nicht

Die offizielle Checkliste: Prüfen Sie, ob das JSON gültig ist; prüfen Sie den Dateipfad; sehen Sie in den Logs nach, ob die Konfiguration geladen wurde; prüfen Sie, ob der API-Schlüssel in der Umgebungsvariable gesetzt ist. Hot Reload entprellt mit 1 Sekunde, achten Sie also darauf, dass die Datei wirklich gespeichert ist.

### Das Modell fehlt in der Auswahlliste

Laut Dokumentation: Prüfen Sie, ob die Modell-ID in `availableModels` steht und ob die `models`-Konfiguration stimmt. Ein `availableModels` auf Projektebene ersetzt das der Benutzerebene vollständig, ohne Zusammenführung. Der offizielle Abschnitt zur Fehlerbehebung nennt „id, name, provider“ als Pflichtfelder, die Feldtabelle markiert nur `id` als Pflicht und nennt das Feld `vendor`; mit `id`, `name` und `vendor` sind beide Angaben erfüllt.

### HTTP 404

Die `url` eines Chat-Eintrags reicht nicht bis `/chat/completions` oder lautet `https://api.qcode.cc/api`. Chat-Einträge verwenden immer den vollständigen Pfad `https://api.qcode.cc/openai/v1/chat/completions`; nur Einträge mit `"api": "openai-responses"` enden bei `/openai/v1`.

### HTTP 400 `model_not_available_on_endpoint`

Eine `claude-…`-ID wurde an einen OpenAI-Pfad geschickt, etwa über einen Eintrag in `models.json` oder über `CODEBUDDY_BASE_URL` mit `https://api.qcode.cc/api`. Claude-Modelle gibt es nur über den Anthropic-Endpunkt; verwenden Sie hier ein GPT- oder chinesisches Modell oder wechseln Sie zu einem Werkzeug wie [Claude Code](/docs/getting-started/installation). Dieser Fehler bedeutet nicht, dass der Schlüssel ungültig ist.

### HTTP 401

Der Schlüssel muss mit `cr_` beginnen und darf keine Leerzeichen enthalten. Bei einer Umgebungsvariablen-Referenz prüfen Sie, ob die Variable wirklich exportiert ist: Laut Dokumentation bleibt bei einer fehlenden Variable der ursprüngliche Platzhalter stehen, sodass die Zeichenkette `${QCODE_API_KEY}` als Schlüssel gesendet wird.

### Muss ich mich bei einem Tencent-Konto anmelden?

Für diese Modelle nicht. Im Test mit 2.182.0 hat `codebuddy -p` sowohl über `models.json` als auch über `CODEBUDDY_BASE_URL` ohne Anmeldung geantwortet.

### Sendet ein eigenes Modell Identitäts-Header der Tencent-Plattform?

Laut den offiziellen Versionshinweisen zu CLI v2.180.0 tragen eigene Modelle keine Identitäts-Header der Plattform mehr: Verbindet sich ein eigenes Modell direkt mit einem Drittanbieter-Endpunkt, werden keine Identitätsdaten mehr an den von Ihnen konfigurierten Dienst gesendet.

## Verwandte Seiten

- [WorkBuddy-Modell einrichten](/docs/ide/workbuddy) — der Office-Agent desselben Teams, ebenfalls über OpenAI Chat Completions
- [ZCode: eigener Anbieter](/docs/ide/zcode) — eigene Anbieter über die Protokolle Anthropic und OpenAI, auch mit Claude
- [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths) — drei Protokolle, drei Domains, `BASE_URL`-Übersicht
- [Chinesische Modelle](/docs/usage/cn-models) — Modell-IDs für GLM / Kimi / DeepSeek / Qwen
- [Übersicht der Tool-Kompatibilität](/docs/ide/tool-compatibility) — Protokolle pro Werkzeug und ob Claude funktioniert
- Aktuelle IDs und Preise: [qcode.cc/models](https://qcode.cc/models)