# Claude Code CLI — Configuration with OmniRoute (Deutsch)

🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇹 [am](../../../am/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇦 [bs](../../../bs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md)

---

Richte die **Claude Code**-CLI (`claude`) auf OmniRoute aus — lokal oder auf einem Remote-VPS —
mit modellspezifischen Profilen, analog zur Codex-Einrichtung.

---

## Schnellstart

```bash
# Claude Code mit einer lokalen OmniRoute-Instanz starten (erkennt den aktiven Kontext automatisch)
omniroute launch

# Mit einer Remote-OmniRoute-Instanz (nach `omniroute connect <host>` erfolgt dies automatisch)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Modellspezifische Profile generieren und anschließend eines davon starten
omniroute setup-claude            # schreibt ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code verwendet glm/glm-5.2 über OmniRoute
```

---

## So verbindet sich Claude Code mit einem Gateway

Claude Code kommuniziert über die **Anthropic Messages API** und wird mithilfe von
Umgebungsvariablen auf einen benutzerdefinierten Endpunkt ausgerichtet (es gibt kein
`--base-url`-Flag):

| Variable                                     | Zweck                                                                                              |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                         | Gateway-Basis-URL (Claude Code hängt `/v1/messages` an). **Kein `/v1`-Suffix.**                    |
| `ANTHROPIC_AUTH_TOKEN`                       | Wird als `Authorization: Bearer …` gesendet — verwende dein OmniRoute-Zugriffstoken/deinen API-Key |
| `ANTHROPIC_API_KEY`                          | Alternative: wird als `x-api-key` gesendet. Sind beide gesetzt, hat `ANTHROPIC_AUTH_TOKEN` Vorrang |
| `ANTHROPIC_MODEL`                            | Erzwingt ein bestimmtes Modell (überschreibt die Standardeinstellung der `/model`-Auswahl)         |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` → die native `/model`-Auswahl listet `claude*`-/`anthropic*`-Modelle aus `/v1/models` auf      |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS`              | Begrenzt die Ausgabe-Tokens pro Antwort (z. B. `65536`)                                            |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW`            | Token-Schwellenwert für die automatische Komprimierung                                             |

> Umgebungsvariablen werden **einmal beim Start** gelesen — starte Claude Code nach Änderungen neu.

`omniroute launch` setzt all diese Variablen für dich: Der Befehl ermittelt die Basis-URL und das Token
aus dem aktiven Kontext (sodass `omniroute connect <vps>` gefolgt von `omniroute launch`
direkt funktioniert), prüft den Serverzustand und führt `claude` aus.

---

## Discovery-Aliase — Nicht-Claude-Modelle in der `/model`-Auswahl sichtbar machen

Die Gateway-Modellerkennung von Claude Code listet nur IDs auf, die mit `claude`
oder `anthropic` beginnen. Mit `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` zeigt
die native `/model`-Auswahl daher normalerweise **nur** die Claude/Anthropic-Modelle
von OmniRoute — ein `kimi/kimi-k2.6` oder `glm/glm-5.2` erscheint nie, obwohl das
Routing einwandfrei funktioniert.

OmniRoute kann jedes aktivierte Modell (und jede Combo) unter einer `claude/…`-ID
spiegeln, sodass es den Filter passiert und in der Auswahl auftaucht:

```
kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado
```

Wenn du eines davon in Claude Code auswählst, entfernt OmniRoute den `claude/`-Wrapper
wieder und stellt die echte ID her, bevor das Routing erfolgt — eine echte
`claude/<real-claude-model>`-ID (der tatsächliche Claude-OAuth-Anbieter) bleibt immer
unverändert.

Standardmäßig werden nur Basis-IDs gespiegelt. Mit aktiviertem Opt-in-Feature-Flag
`CATALOG_MIRROR_REFINEMENTS_ENABLED` werden Reasoning-Effort-Varianten, die der Katalog
bereits auflistet (z. B. `codex/gpt-6-sol-high`), wie jede andere ID gespiegelt,
sodass Claude Code eine explizite Effort-Stufe wählen kann; eingebaute `auto/*`-IDs,
die der Request-Pfad nicht materialisieren kann, werden nicht gespiegelt. Ob
Effort-Varianten überhaupt aufgelistet werden, steuert weiterhin
`OMNIROUTE_DISABLE_THINKING_LEVEL_VARIANTS` — der Spiegel fügt nie eine Variante hinzu,
die der Basiskatalog nicht hat.

**Dies ist standardmäßig deaktiviert** und wird über ein dreistufiges Gate gesteuert
(die spezifischste Stufe gewinnt), sodass ein einfaches OmniRoute seinen Katalog für
Clients, die Claude Code nicht verwenden, niemals verdoppelt:

| Ebene    | Wo                                                                            |
| -------- | ----------------------------------------------------------------------------- |
| Modell   | Anbieter-Detailseite → Toggle „Expose in Claude Code" pro Modell              |
| Anbieter | Anbieter-Detailseite → Toggle auf Anbieterebene (deckt alle seine Modelle ab) |
| Global   | Einstellungen → Feature Flags → `EXPOSE_CC_DISCOVERY_ALIASES` (Standard: aus) |

Die Umgebungsvariable `EXPOSE_CC_DISCOVERY_ALIASES` erzwingt die globale Stufe und
hat Vorrang vor der Dashboard-Überschreibung (der Feature-Flags-Bildschirm zeigt in
diesem Fall den Hinweis „active via environment variable" an). Die Toggles pro
Anbieter und pro Modell verfeinern von dort aus — z. B. legt „global aus +
Kimi-Anbieter an" nur die Modelle von Kimi offen.

> ⚠️ **Fenster-Mismatch bei Nicht-Claude-Modellen.** Claude Code nimmt für jede ID,
> die es nicht erkennt, ein 200K-Kontextfenster an (es kann kein echtes Fenster aus
> `/v1/models` lesen). Bei einem Modell mit einem größeren Fenster (z. B. Kimi K2s
> 256K) setze `CLAUDE_CODE_AUTO_COMPACT_WINDOW` auf einen Wert unterhalb des echten
> Fensters des Modells, damit die Auto-Kompaktierung nicht vorzeitig auslöst. Die
> oben erzeugten Profile tun dies bereits pro Modell.

---

## Onboarding-Block im Dashboard

Die Claude-Tool-Karte (**Dashboard → CLI Code**) zeigt das exakte `settings.json`-Fragment
für diese Instanz neben dem Info-Button für den Discovery-Alias sowie einen Kopier-Button an:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<Ihre OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<Ihr OmniRoute-API-Schlüssel>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}
```

Die Basis-URL ist die von der Karte aufgelöste URL (einschließlich einer von Ihnen eingegebenen benutzerdefinierten Überschreibung) und bereits
normalisiert – ohne `/v1`-Suffix und ohne abschließenden Schrägstrich. **Der Schlüssel wird niemals angezeigt**: Der Block enthält einen
Platzhalter, sodass weder ein Screenshot noch ein eingefügtes Snippet einen Schlüssel preisgeben kann. Ersetzen Sie ihn durch Ihren Schlüssel.

Fügen Sie `CLAUDE_CODE_AUTO_COMPACT_WINDOW` für jedes Modell, dessen tatsächliches
Kontextfenster nicht 200K beträgt, demselben `env`-Block hinzu – Claude Code nimmt für jede nicht erkannte ID 200K an, sodass
die automatische Komprimierung andernfalls zum falschen Zeitpunkt ausgelöst wird (siehe Warnung im vorherigen Abschnitt).
Der Snippet-Builder akzeptiert diesen Wert ebenfalls, sodass ein Aufrufer, der die Kontextfenstergröße des Zielmodells kennt,
ihn direkt ausgeben kann.

Quelle: `src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet` (reiner,
durch Unit-Tests geprüfter Builder), dargestellt durch `ClaudeGatewayOnboardingBlock`.

### Ein Konto festlegen (optional)

Um jede Claude-Code-Anfrage über ein bestimmtes Anbieterkonto zu senden, fügen Sie den
`x-omniroute-connection`-Header über `ANTHROPIC_CUSTOM_HEADERS` demselben `env`-Block hinzu:

```jsonc
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>"
```

Kopieren Sie die ID aus dem `xxxxxxxx…`-Chip in der Verbindungszeile auf der Anbieterseite. Die Festlegung
gilt nur für Einzelmodell-IDs (`provider/model`), nicht für Kombinationen. Das genaue
Fallback-Verhalten finden Sie unter [Kontofestlegung pro Anfrage](../reference/API_REFERENCE.md#account-pinning-per-request).

---

## Profile (`CLAUDE_CONFIG_DIR`)

Claude Code verfügt über **keine nativen Profildateien** (anders als Codex mit `~/.codex/<name>.config.toml`).
Der idiomatische Mechanismus ist `CLAUDE_CONFIG_DIR` – ein separates Konfigurationsverzeichnis pro
Profil, jeweils mit eigenen `settings.json`, Anmeldedaten, eigenem Verlauf und Cache.

`omniroute setup-claude` ruft den aktuellen `/v1/models`-Katalog ab und schreibt für jedes
Modell ein Profil nach `~/.claude/profiles/<name>/settings.json`. Dabei werden die
**gleichen Namen wie bei `setup-codex`** verwendet (`glm52`, `kimi-k27`, `deepseek-pro`, …):

```jsonc
// ~/.claude/profiles/glm52/settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}
```

> **Das Authentifizierungstoken wird niemals in das Profil geschrieben.** Starten Sie mit
> `omniroute launch --profile <name>` (dadurch wird `ANTHROPIC_AUTH_TOKEN` aus dem
> aktiven Kontext eingefügt), oder exportieren Sie `ANTHROPIC_AUTH_TOKEN` selbst und führen Sie
> `CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude` aus.

**Automatische Synchronisierung nach der Modellerkennung (optional).** OmniRoute kann dieselben
`~/.claude/profiles/<name>/settings.json`-Dateien automatisch neu erzeugen, sobald eine
Modellsynchronisierung eines Anbieters den aktuellen Katalog ändert – dadurch erhalten neue oder
umbenannte Modelle Profile, ohne dass der Befehl erneut ausgeführt werden muss. Diese Funktion ist
**standardmäßig deaktiviert**: Aktivieren Sie sie im **CLI-Code-Dashboard** („Automatische
Synchronisierung von CLI-Profilen“ → Claude Code), oder setzen Sie
`OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true` (dabei wird auch `CLI_ALLOW_CONFIG_WRITES`
berücksichtigt, was standardmäßig aktiviert ist). Wenn diese Funktion aktiviert ist, schreibt sie
ausschließlich Profildateien; sie ändert niemals Ihre aktive bzw. standardmäßige Claude-Konfiguration,
die Authentifizierung oder die Datei `~/.claude/settings.json`.

### Profile erzeugen und verwenden

```bash
# Lokales OmniRoute
omniroute setup-claude

# Remote-VPS (bettet die VPS-URL in jedes Profil ein)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Nur einige Anbieter
omniroute setup-claude --only glm,kimi

# Auch Profile für lokale CLI-Anbieter (zcode, auggie, devin-cli-agentic,
# codex-app-server) schreiben, die auf diesem Host nicht erkannt wurden
# (bei einem lokalen Ziel standardmäßig übersprungen)
omniroute setup-claude --include-local

# Vorschau ohne Schreiben
omniroute setup-claude --dry-run

# Ein Profil starten
omniroute launch --profile kimi-k27
```

---

## Modellstufen (optional)

Claude Code leitet Anfragen an unterschiedliche Leistungsstufen weiter. Ordnen Sie jede davon über Umgebungsvariablen /
Einstellungen einem OmniRoute-Modell zu, wenn Sie je Stufe unterschiedliche Anbieter verwenden möchten:

```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"
```

Andernfalls wird ein einzelnes `ANTHROPIC_MODEL` (das von Profilen festgelegt wird) für alles verwendet.

---

## Remote-Modus

Nachdem Sie `omniroute connect <host>` ausgeführt haben (siehe
[Remote-Modus](./REMOTE-MODE.md)), richten sich `omniroute launch` und `omniroute setup-claude`
automatisch an diesen Remote-Server und verwenden dessen zugriffsbereichsgebundenes Token —
es sind keine zusätzlichen Flags erforderlich. Sie können dies pro Aufruf mit `--remote` / `--api-key` überschreiben.

---

## Fehlerbehebung

**Claude Code ignoriert das Gateway** — stellen Sie sicher, dass `ANTHROPIC_BASE_URL` **kein
`/v1`** enthält, und starten Sie `claude` neu (die Umgebungsvariablen werden beim Start nur einmal eingelesen). `omniroute launch`
übernimmt dies für Sie.

**Die `/model`-Auswahl ist leer / Gateway-Modelle fehlen** — hierfür sind Claude Code
v2.1.219+ und `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` erforderlich. In der Auswahl werden nur Modell-IDs angezeigt, die mit `claude*` /
`anthropic*` beginnen; erzwingen Sie jedes andere Modell mit
`ANTHROPIC_MODEL=<id>` (genau das tun Profile).

**`400 Ambiguous model 'claude-…'`** — Claude Code sendet Modell-IDs immer **ohne Präfix**
(z. B. `claude-opus-4-8`). Wenn daher sowohl der Claude-Code-Anbieter (`cc/…`) als auch
der Claude-Anbieter (`claude/…`) verbunden sind, stimmt die ID ohne Präfix mit zwei Routen überein und
OmniRoute verweigert eine automatische Auswahl. Sie können das Problem auf zwei Arten beheben: Legen Sie mit
`ANTHROPIC_MODEL=cc/claude-opus-4-8` eine ID mit Präfix fest oder aktivieren Sie **Claude Code für
Claude-Modelle ohne Präfix bevorzugen** — den Schalter auf der Claude-Anbieterseite oder
`OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true` (standardmäßig deaktiviert;
siehe [Umgebung](../reference/ENVIRONMENT.md)) — wodurch IDs ohne Präfix vom Typ `claude-*`
stattdessen an Claude Code weitergeleitet werden. Explizite Anbieterpräfixe haben immer Vorrang.

**Authentifizierungsfehler** — das Profil enthält kein Token. Verwenden Sie `omniroute launch --profile`
(dadurch wird es eingefügt) oder exportieren Sie `ANTHROPIC_AUTH_TOKEN`.

**Profile werden nicht isoliert** — jedes Profil verwendet ein eigenes `CLAUDE_CONFIG_DIR`;
überprüfen Sie innerhalb der Sitzung mit `echo $CLAUDE_CONFIG_DIR`, ob es auf
`~/.claude/profiles/<name>` verweist.