Claude Code CLI — Configuration with OmniRoute

Schnellstart

# 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-Aliasse — Nicht-Claude-Modelle in der /model-Auswahl anzeigen

Die Gateway-Modellerkennung von Claude Code listet nur IDs auf, die mit claude oder anthropic beginnen. Daher zeigt die native /model-Auswahl bei gesetztem CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 normalerweise nur die Claude-/Anthropic-Modelle von OmniRoute an — kimi/kimi-k2.6 oder glm/glm-5.2 erscheinen nie, obwohl das Routing problemlos funktioniert.

OmniRoute kann jedes aktivierte Modell (und jede Kombination) unter einer claude/…-ID spiegeln, damit es diesen Filter passiert und in der Auswahl erscheint:

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 vor dem Routing die claude/-Umschließung und stellt die echte ID wieder her — eine echte claude/<real-claude-model>-ID (der tatsächliche Claude-OAuth-Anbieter) bleibt immer unverändert.

Dies ist standardmäßig deaktiviert und wird über eine dreistufige Konfiguration gesteuert (die spezifischste Einstellung hat Vorrang), sodass eine unveränderte OmniRoute-Instanz ihren Katalog für Clients, die Claude Code nicht verwenden, nicht verdoppelt:

Ebene	Ort
Modell	Anbieterdetailseite → modellspezifischer Schalter „In Claude Code anzeigen“
Anbieter	Anbieterdetailseite → anbieterspezifischer Schalter (gilt für alle Modelle)
Global	Einstellungen → Feature Flags → EXPOSE_CC_DISCOVERY_ALIASES (standardmäßig aus)

Die Umgebungsvariable EXPOSE_CC_DISCOVERY_ALIASES erzwingt die Aktivierung auf globaler Ebene und hat Vorrang vor der Einstellung im Dashboard (der Bildschirm „Feature Flags“ zeigt in diesem Fall den Hinweis „über Umgebungsvariable aktiv“ an). Anbieter- und modellspezifische Schalter verfeinern die Konfiguration anschließend weiter — beispielsweise werden bei global deaktivierter Einstellung und aktiviertem Kimi-Anbieter nur die Modelle von Kimi angezeigt.

⚠️ Abweichende Kontextfenster bei Nicht-Claude-Modellen. Claude Code nimmt für jede nicht erkannte ID ein Kontextfenster von 200K an (das tatsächliche Fenster kann nicht aus /v1/models gelesen werden). Setze bei einem Modell mit größerem Fenster (z. B. 256K bei Kimi K2) CLAUDE_CODE_AUTO_COMPACT_WINDOW auf einen Wert unterhalb des tatsächlichen Modellfensters, damit die automatische Komprimierung nicht zu früh ausgelöst wird. Die oben generierten Profile erledigen dies bereits modellspezifisch.

---

Onboarding-Block im Dashboard

Die Claude-Tool-Karte (Dashboard → CLI Code) zeigt das exakte settings.json-Fragment für diese Instanz neben der Info-Schaltfläche für Discovery-Aliasse sowie eine Kopierschaltfläche an:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<Ihr 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 ermittelte URL (einschließlich einer von Ihnen eingegebenen benutzerdefinierten Überschreibung) und bereits normalisiert — kein /v1-Suffix und kein abschließender 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 den Platzhalter durch Ihren Schlüssel.

Fügen Sie CLAUDE_CODE_AUTO_COMPACT_WINDOW für jedes Modell, dessen tatsächliches Kontextfenster nicht 200K beträgt, im selben env-Block hinzu — Claude Code geht bei jeder nicht erkannten ID von 200K aus, 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 das Kontextfenster des Zielmodells kennt, ihn direkt ausgeben kann.

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

---

Profile (CLAUDE_CONFIG_DIR)

Claude Code verfügt über keine nativen Profildateien (anders als Codex mit ~/.codex/<name>.config.toml). Der übliche Mechanismus ist CLAUDE_CONFIG_DIR — ein separates Konfigurationsverzeichnis pro Profil, jeweils mit eigenen settings.json, Anmeldedaten, 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, wobei dieselben Namen wie bei setup-codex verwendet werden (glm52, kimi-k27, deepseek-pro, …):

~/.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 generieren, sobald eine Synchronisierung der Anbietermodelle 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 (auch CLI_ALLOW_CONFIG_WRITES wird berücksichtigt; standardmäßig aktiviert). Ist die Funktion aktiviert, schreibt sie ausschließlich Profildateien; sie ändert niemals Ihre aktive oder standardmäßige Claude-Konfiguration, Authentifizierung oder ~/.claude/settings.json.

Profile generieren und verwenden

# 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

# Vorschau ohne zu 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:

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), 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) — 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.

---

undefined (a58000c7685f)