# Crush-Einrichtung

> **Zuletzt überprüft**: 2026-09-18 · 📄 Laut offizieller Dokumentation (Crush v0.95.0, veröffentlicht 2026-09-16)

## Auf einen Blick

| Punkt | Details |
|---|---|
| Verfügbare Modelle | Claude ✅ (`type: anthropic`) · GPT ✅ · Chinesische Modelle ✅ (`openai-compat`) · Gemini ❌ (hier ist keine Gemini-Route dokumentiert) |
| Protokoll & Basis-URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Konfiguration | Auf Projektebene `crush.json` / auf Benutzerebene `~/.config/crush/crush.json` |
| Offizielle Dokumentation | [charmbracelet/crush](https://github.com/charmbracelet/crush)
[Crush](https://github.com/charmbracelet/crush) ist Charms terminalorientierter KI-Coding-Agent (in Go geschrieben). Er unterstützt **benutzerdefinierte Anbieter**, sodass QCode.cc als Upstream dienen kann.

> **Hinweis zur Namensgebung**: Das Repository hieß ursprünglich `charmbracelet/opencode` und heißt nun `crush` (die alte URL leitet per 301 weiter; der Grund wurde vom Upstream nie genannt). Es handelt sich um ein **anderes Projekt** als [OpenCode](/docs/ide/opencode) (opencode.ai) – beachten Sie außerdem, dass Crush auch einen integrierten Modell-Upstream namens `opencode` mitbringt, noch eine weitere Charm-Komponente, die nicht verwechselt werden sollte.

## Welches Protokoll

Crush benutzerdefinierte Anbieter akzeptieren `anthropic` und `openai-compat` als `type`. **Für Claude verwenden Sie `anthropic`** – der OpenAI-Endpunkt von QCode akzeptiert keine Claude-Modelle (siehe [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths)).

| Gewünschtes Modell | `type` | `base_url` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / die vier chinesischen Modellfamilien | `openai-compat` | `https://api.qcode.cc/openai/v1` |

## Installation

```bash
# Homebrew
brew install charmbracelet/tap/crush

# or download a prebuilt binary from Releases
# https://github.com/charmbracelet/crush/releases
```

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

```bash
crush --version
```

## Konfiguration

Erstellen Sie `crush.json` im Projektstamm oder auf Benutzerebene unter `~/.config/crush/crush.json` (= `$XDG_CONFIG_HOME/crush/crush.json`; beachten Sie, dass `~/.local/share/crush/` Zustandsdateien enthält, die laut offizieller Dokumentation nicht bearbeitet werden sollten). Neuere Upstream-Versionen empfehlen auch ein `crushrc`-Format (Bash-DSL); JSON-Konfiguration wird weiterhin gelesen:

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "qcode": {
      "type": "anthropic",
      "base_url": "https://api.qcode.cc/api",
      "api_key": "$QCODE_KEY",
      "extra_headers": { "anthropic-version": "2023-06-01" },
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "QCode Sonnet 5",
          "cost_per_1m_in": 2,
          "cost_per_1m_out": 10,
          "context_window": 1000000,
          "default_max_tokens": 8192,
          "cost_per_1m_in_cached": 0.2,
          "cost_per_1m_out_cached": 2.5,
          "can_reason": true,
          "supports_attachments": true
        },
        {
          "id": "claude-haiku-4-5",
          "name": "QCode Haiku 4.5",
          "cost_per_1m_in": 1,
          "cost_per_1m_out": 5,
          "context_window": 200000,
          "default_max_tokens": 4096,
          "cost_per_1m_in_cached": 0.1,
          "cost_per_1m_out_cached": 1.25,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}
```

Übergeben Sie den API-Key über die Umgebung, anstatt ihn in die Datei zu schreiben:

```bash
export QCODE_KEY="cr_your_qcode_key"
```

| Feld | Bedeutung |
|-------|---------|
| `type` | `anthropic` wählt das native Messages-Protokoll aus |
| `base_url` | Endet auf `/api` – **Crush fügt `/v1/messages` selbst an** |
| `api_key` | Unterstützt `$VAR`-Umgebungsvariablen-Expansion |
| `extra_headers` | Das Anthropic-Protokoll erfordert `anthropic-version` |
| `models[]` | Das Auflisten von Modellen ermöglicht das Überschreiben von Kosten-/Kontextparametern; wenn Sie es weglassen, erkennt Crush die Modelle automatisch über `<base>/v1/models` (`discover_models` ist standardmäßig aktiviert). Jede `id` muss mit [qcode.cc/models](https://qcode.cc/models) übereinstimmen – Zeichen für Zeichen |

> **Festlandchina**: Ersetzen Sie den Host durch `https://asia.qcode.cc/api` (Asien-Knoten, nächstliegender von Korea / Taiwan / Hongkong); der API-Key bleibt unverändert.
> `cost_per_1m_*` (einschließlich der beiden `*_cached`-Schlüssel, die das offizielle Schema erfordert) beeinflusst nur die Nutzungsanzeige in Crush, nicht die tatsächliche Abrechnung; die Beispielwerte folgen einem typischen Cache-Verhältnis – passen Sie diese an die tatsächlichen Cache-Preise auf [qcode.cc/models](https://qcode.cc/models) an.
## Überprüfen

```bash
crush run "reply with exactly: OK"
```

`OK` bedeutet, dass die Verbindung steht.

**Um zu belegen, dass der Datenverkehr tatsächlich an QCode geht**, setzen Sie `base_url` gezielt auf einen nicht existierenden Pfad und führen den Befehl erneut aus. Sie sollten einen eindeutigen 404-Fehler sehen, der die vollständige URL wiedergibt:

```text
404 Not Found {"error":"Not Found","message":"Route /api/xxx/v1/messages not found"}
```

Dieser Fehler belegt, dass Crush `base_url + /v1/messages` zusammensetzt und Ihre Konfiguration wirksam ist. (Das ist eine Negativkontrolle: Ein Erfolg allein beweist nicht, dass Ihr Anbieter verwendet wurde – Crush könnte auf einen anderen zurückgefallen sein.)

## Alltägliche Nutzung

```bash
# interactive
crush

# non-interactive
crush run "make this function async"

# pipes
cat README.md | crush run "make this clearer" > README.new.md

# specific directory with debug logging
crush --debug --cwd /path/to/project

# auto-accept every permission (use with care)
crush --yolo
```

## Fehlerbehebung

### `model_not_available_on_endpoint`

`type` steht auf `openai-compat`, während das Modell ein Claude-Modell ist. Wechseln Sie zu `type: "anthropic"` mit `base_url` = `https://api.qcode.cc/api`.

### 401 Invalid API key

Die Umgebungsvariable wurde nicht übergeben, oder der Key enthält überflüssige Leerzeichen. Prüfen Sie, ob `echo $QCODE_KEY` mit `cr_` beginnt.

### Das Modell erscheint nicht in der Auswahl

Crush zeigt nur Modelle an, die explizit in `models[]` aufgeführt sind. Fügen Sie einen Eintrag hinzu und starten Sie Crush neu.

## Verwandte Themen

- [Endpunkte & API-Pfade](/docs/getting-started/endpoints-and-api-paths) — Tabelle Protokoll × Modellfamilie
- [OpenCode-Integration](/docs/ide/opencode) — ein anderer Terminal-Agent (nicht dasselbe Projekt)
- [Chinesische Modelle](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen