# CodeWhale (ehemals DeepSeek-TUI) Integration

> **Zuletzt überprüft**: 2026-09-18 · 📄 Gemäß offizieller Dokumentation (CodeWhale v0.9.13, veröffentlicht am 2026-09-14, ehemals DeepSeek-TUI)

## Auf einen Blick

| Eintrag | Details |
|---|---|
| Verfügbare Modelle | Claude ✅ (anthropic-Provider, hängt `/v1/messages` selbst an) · GPT ✅ · Chinesische Modelle ✅ (openai-Provider) · Gemini ⚠️ nicht verifiziert — der offizielle `google`-Provider nutzt Geminis OpenAI-kompatible Route, und die Dokumentation besagt, dass eine `google`-Zeile, die auf ein anderes Gateway zeigt, auf einfache OpenAI-Semantik zurückfällt; wir haben nicht verifiziert, dass QCodes OpenAI-Chat-Zweig Gemini-Modell-IDs akzeptiert |
| Protokoll & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Wo konfigurieren | `~/.codewhale/config.toml` (das frühere `~/.deepseek/` dient nur als Fallback, wenn das neue Verzeichnis nicht existiert) |
| Offizielle Dokumentation | [Hmbown/Codewhale](https://github.com/Hmbown/Codewhale) |

> **⚠️ Das Projekt wurde umbenannt.** Aus `DeepSeek-TUI` wurde **CodeWhale**. Die Binary änderte sich von
> `deepseek` zu `codewhale` und die Konfigurationsdatei zog von `~/.deepseek/config.toml` nach
> `~/.codewhale/config.toml` um. Der Fallback ist bedingt: Das offizielle Migrationsverhalten ist
> **Lesen mit Fallback, Schreiben in neues Verzeichnis** — Lesezugriffe schauen zuerst in `~/.codewhale/` und
> fallen auf `~/.deepseek/` zurück, **nur wenn dieses Verzeichnis das einzig vorhandene ist**, während alle
> Schreibzugriffe in das neue Verzeichnis gehen. Außerdem wurden seit **v0.9.0** die Befehle `deepseek` und
> `deepseek-tui` entfernt; die Einstiegspunkte sind `codewhale`, `codew` (eine praktische Kurzform) und
> `codewhale-tui`. Die alte Website `deepseek-tui.com` leitet nun per 301-Redirect auf [codewhale.net](https://codewhale.net) weiter.
> Die URL dieser Seite ist unverändert.

[CodeWhale](https://codewhale.net) ist ein Terminal-Coding-Agent mit Dutzenden erstklassigen
Anbietern (`anthropic`, `openai`, `deepseek`, `ollama`, `vllm`, `openrouter` und weitere; die Dokumentation
verweist auf `ProviderKind::ALL` im Quellcode als die maßgebliche Liste, die sich zwischen Versionen vergrößert und verkleinert —
führen Sie `/provider` aus, um die in Ihrem Build verfügbare Auswahl zu sehen). Das Tool spricht sowohl das
**native Anthropic-Messages-Protokoll** als auch das **OpenAI-Chat-Completions-Protokoll**, und jeder der beiden
Protokolltypen kann auf QCode.cc zeigen.

## 🔴 Zuerst lesen: Claude erfordert den anthropic-Provider

QCodes OpenAI-kompatibler Endpunkt **akzeptiert keine Claude-Modelle** — `claude-…` in
`[providers.openai]` einzutragen, führt zu `model_not_available_on_endpoint`. Siehe die Kompatibilitätstabelle unter
[Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths).

| Gewünschtes Modell | CodeWhale-Provider | QCode `base_url` |
|---|---|---|
| Claude (`claude-opus-5` / `claude-sonnet-5` …) | `anthropic` | `https://api.qcode.cc/api` |
| GPT (`gpt-6-sol` / `gpt-6-luna` …) | `openai` | `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen | beide möglich | siehe die beiden Zeilen oben |

## Warum CodeWhale mit QCode verwenden

- **Vertraute TUI**: Modi Plan / Work / Operate, mit den Berechtigungsstufen Ask / Auto-Review / Full Access (`Shift+Tab`) sowie integrierter MCP / Shell / Git / Subagenten-Unterstützung
- **Ein API-Key**: nutzt das Kontingent Ihres QCode-Tarifs gemeinsam mit Claude Code und Codex CLI
- **Anbieterwechsel**: Wechseln Sie innerhalb desselben Tools zwischen anthropic / openai / ollama / vllm
- **Gut vom chinesischen Festland aus nutzbar**: `asia.qcode.cc` (Asien-Knoten, in der Nähe von Korea / Taiwan / Hongkong) bietet die niedrigste Latenz
- **Vollständig Open Source**: unter MIT-Lizenz, die Konfigurationsdatei ist auditierbar

## 1. Installation

Die offizielle erste Wahl ist das Installationsskript aus den GitHub Releases; npm und Cargo werden in der Dokumentation als
**sekundäre** Paketierungswege bezeichnet:

```bash
# Officially recommended (macOS / Linux): installs the release binary
curl -fsSL https://codewhale.net/install.sh | sh

# npm - the official docs call this a secondary packaging route (Node 18+)
npm install -g codewhale

# Homebrew - add the tap first, otherwise a fresh machine cannot find the formula
brew tap Hmbown/deepseek-tui
brew install codewhale

# Cargo - source build; the crate is codewhale-cli, the command it installs is codewhale
cargo install codewhale-cli --locked
```

Plattformbeschränkungen und Details: [offizielle Installationsdokumentation](https://codewhale.net/en/install).

Überprüfen Sie die Installation (**verlassen Sie sich auf die tatsächliche Ausgabe, nicht auf eine in irgendeiner Dokumentation genannte Versionsnummer**):

```bash
codewhale --version
```

## 2. Claude konfigurieren (Anbieter anthropic)

Bearbeiten Sie `~/.codewhale/config.toml`:

```toml
# ~/.codewhale/config.toml

provider = "anthropic"

[providers.anthropic]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/api"
model    = "claude-sonnet-5"
```

| Feld | Bedeutung |
|------|---------|
| `provider` | Auf oberster Ebene auf `"anthropic"` setzen, damit standardmäßig das native Messages-Protokoll verwendet wird |
| `api_key` | Aus der QCode.cc-Konsole, beginnt mit `cr_`. CodeWhale sendet ihn als `x-api-key` |
| `base_url` | Enden Sie bei `/api`; CodeWhale hängt `/v1/messages` an (laut offizieller Dokumentation). Fügen Sie kein abschließendes `/` hinzu und schreiben Sie nicht selbst `/v1/messages` |
| `model` | Eine Claude-Modell-ID, die QCode anbietet – siehe [qcode.cc/models](https://qcode.cc/models). Die Dokumentation behandelt `[providers.<table>].model` als **Override auf Anbieterebene**; das Standardmodell gehört in `default_text_model` auf oberster Ebene |

> **Vom chinesischen Festland aus** ersetzen Sie den Host durch `https://asia.qcode.cc/api` (Asien-Knoten, nahe Korea / Taiwan / Hongkong).
> Der Key bleibt unverändert.

Statt der Konfigurationsdatei funktionieren auch Umgebungsvariablen; die Dokumentation bevorzugt inzwischen die generischen `CODEWHALE_*`-Variablen:

```bash
export CODEWHALE_PROVIDER="anthropic"
export CODEWHALE_BASE_URL="https://api.qcode.cc/api"
export CODEWHALE_MODEL="claude-sonnet-5"
export ANTHROPIC_API_KEY="cr_your_qcode_key"

codewhale
```

Die anbieterspezifischen Variablen (`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`) werden weiterhin akzeptiert, ebenso
das Flag `codewhale --provider anthropic`.

## 3. GPT und chinesische Modelle konfigurieren (Anbieter openai)

Mehrere Anbieter können in einer Konfiguration nebeneinander bestehen; wechseln Sie mit `codewhale --provider <id>`:

```toml
[providers.openai]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/openai/v1"
model    = "gpt-6-sol"
```

Enden Sie bei `base_url` mit `/openai/v1`; CodeWhale hängt `/chat/completions` an. Falls ein Build
ein anderes Suffix benötigt, ist der offizielle Schlüssel dafür `path_suffix` innerhalb von `[providers.openai]` – schmuggeln Sie es nicht
in `base_url`.

Die vier chinesischen Modellfamilien (`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` …) funktionieren auf
**beiden** Strecken, sodass Sie jeden der beiden Anbieter verwenden können. Die IDs finden Sie unter
[Chinesische Modelle](/docs/usage/cn-models).

## 4. Verfügbare Modelle

| Modell-ID | Anbieter | Geeignet für |
|---------|----------|----------|
| `claude-opus-5` | `anthropic` | Aufwendige Planung / komplexe Architektur |
| `claude-sonnet-5` | `anthropic` | Alltägliches Programmieren (**empfohlen**) |
| `claude-haiku-4-5` | `anthropic` | Schnelle kleine Aufgaben / niedrige Kosten |
| `gpt-6-sol` | `openai` | Flaggschiff von OpenAI |
| `gpt-6-luna` | `openai` | Schnell, niedrige Kosten |
| `glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` | beide | Günstigere chinesische Optionen |

> Modelle der Version 4.x wie `claude-sonnet-4-6` und `claude-opus-4-8` werden weiterhin angeboten. Die vollständige Liste und
> die aktuellen Preise finden Sie unter [qcode.cc/models](https://qcode.cc/models).

Lassen Sie sich anzeigen, was Sie aktuell aufrufen können – beachten Sie, dass die beiden Strecken **unterschiedliche** Listen zurückgeben:

```bash
# Claude and Chinese models (Anthropic leg)
curl https://api.qcode.cc/v1/models -H "Authorization: Bearer cr_your_qcode_key"

# GPT (OpenAI leg)
curl https://api.qcode.cc/openai/v1/models -H "Authorization: Bearer cr_your_qcode_key"
```
## 5. Verbindung überprüfen

```bash
KEY="cr_your_qcode_key"

# Claude (Anthropic protocol) — should return JSON containing content
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# GPT (OpenAI protocol) — should return JSON containing choices
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

Dann starten:

```bash
codewhale
```

## 6. Fehlerbehebung

| Symptom | Ursache | Lösung |
|---------|-------|-----|
| `model_not_available_on_endpoint` | Ein Claude-Modell wurde in `[providers.openai]` eingetragen | `[providers.anthropic]` verwenden mit `base_url` = `https://api.qcode.cc/api` |
| `Invalid API key` | Falscher Key oder überflüssige Leerzeichen | Prüfen, ob der Key mit `cr_` beginnt und keine führenden oder abschließenden Leerzeichen enthält |
| 404 | Schrägstrich am Ende von `base_url` oder falscher Pfadpräfix | Vergleich mit [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths) |
| Konfigurationsänderungen zeigen keine Wirkung | Der offizielle Vertrag greift nur auf das Legacy-Verzeichnis zurück, wenn es das einzige vorhandene ist; daher ist eine veraltete `~/.deepseek/config.toml` selten die Ursache. Viel häufiger liegt es an der Priorisierung von Anmeldedaten (gespeicherte Konfiguration / Schlüsselbund schlägt Umgebungsvariablen) oder einer projektbezogenen `.codewhale/config.toml`, die über der globalen liegt | `codewhale auth status` ausführen (zeigt, welche Quelle Vorrang hat) und `/config audit` nutzen; bei geänderter Anbieter-Base-URL muss der Modell-Client neu gestartet werden |

## Weiterführende Links

- [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths) — Tabelle Protokoll × Modellfamilie
- [Chinesische Modelle](/docs/usage/cn-models) — GLM- / Kimi- / DeepSeek- / Qwen-IDs und Pfade
- [Modellauswahl](/docs/usage/model-selection) — welches Modell für welche Aufgabe