Konfiguration

Auffindung der Konfigurationsdatei

Claudex verwendet figment fuer geschichtete Konfiguration. Quellen werden in dieser Reihenfolge zusammengefuehrt (spaetere ueberschreiben fruehere):

Programmatische Standardwerte (eingebaute Rueckfallwerte)
Globale Konfiguration (~/.config/claudex/config.toml oder config.yaml)
Projektkonfiguration (claudex.toml oder claudex.yaml im aktuellen Verzeichnis oder uebergeordneten Verzeichnissen bis zu 10 Ebenen, oder $CLAUDEX_CONFIG)
Umgebungsvariablen (CLAUDEX_-Praefix, __ als Trennzeichen)

Sowohl TOML- als auch YAML-Formate werden unterstuetzt. Das Dateiformat wird anhand der Endung erkannt (.toml oder .yaml/.yml).

# Geladenen Konfigurationspfad und alle Suchpfade anzeigen
claudex config show

# Nur den Konfigurationsdateipfad anzeigen
claudex config path

# Neue Konfiguration im aktuellen Verzeichnis erstellen
claudex config init

# Konfiguration aus config.example.toml neu erstellen
claudex config recreate

# Konfiguration im $EDITOR oeffnen
claudex config edit

# Konfigurationssyntax und Profilverweise validieren
claudex config validate

# Einen bestimmten Konfigurationswert abfragen
claudex config get proxy_port

# Einen bestimmten Konfigurationswert setzen
claudex config set proxy_port 8080

# Aktuelle Konfiguration nach stdout exportieren
claudex config export

Globale Einstellungen

# Pfad zur claude-Binaerdatei (Standard: "claude" aus PATH)
# claude_binary = "/usr/local/bin/claude"

# Proxy-Einstellungen
proxy_port = 13456
proxy_host = "127.0.0.1"

# Log-Level: trace, debug, info, warn, error
log_level = "info"

# Terminal-Hyperlinks (OSC 8): "auto" | true | false
# "auto" erkennt die Terminalunterstuetzung; true/false erzwingt ein/aus
hyperlinks = "auto"

# Modell-Aliase (Kurzform → vollstaendiger Modellname)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profile

Jedes Profil repraesentiert eine Verbindung zu einem KI-Anbieter. Es gibt drei Anbietertypen:

DirectAnthropic

Fuer Anbieter, die die Anthropic Messages API nativ unterstuetzen. Anfragen werden mit minimalen Aenderungen weitergeleitet.

[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"
priority = 100
enabled = true

Kompatible Anbieter: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Fuer Anbieter, die die OpenAI Chat Completions API verwenden. Claudex uebersetzt automatisch zwischen den Anthropic- und OpenAI-Protokollen.

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]
priority = 100
enabled = true

Kompatible Anbieter: Grok (xAI), OpenAI, DeepSeek, Kimi/Moonshot, GLM (Zhipu), OpenRouter, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, GitHub Copilot, GitLab Duo, Ollama, vLLM, LM Studio

OpenAIResponses

Fuer Anbieter, die die OpenAI Responses API verwenden (z.B. ChatGPT/Codex-Abonnements). Claudex uebersetzt zwischen der Anthropic Messages API und der OpenAI Responses API.

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

Kompatible Anbieter: ChatGPT/Codex-Abonnements (ueber Codex CLI)

Profilfelder

Feld	Standard	Beschreibung
`name`	erforderlich	Eindeutiger Profilbezeichner
`provider_type`	`DirectAnthropic`	`DirectAnthropic`, `OpenAICompatible` oder `OpenAIResponses`
`base_url`	erforderlich	API-Endpunkt des Anbieters
`api_key`	`""`	API-Schluessel (Klartext)
`api_key_keyring`	—	API-Schluessel stattdessen aus dem OS-Schluesselbund lesen
`default_model`	erforderlich	Standardmaessig verwendetes Modell
`auth_type`	`"api-key"`	`"api-key"` oder `"oauth"`
`oauth_provider`	—	OAuth-Anbieter (`claude`, `openai`, `google`, `qwen`, `kimi`, `github`, `gitlab`). Erforderlich wenn `auth_type = "oauth"`
`backup_providers`	`[]`	Failover-Profilnamen
`custom_headers`	`{}`	Zusaetzliche HTTP-Header
`extra_env`	`{}`	Zusaetzliche Umgebungsvariablen fuer Claude
`priority`	`100`	Prioritaet fuer Smart Routing
`enabled`	`true`	Ob dieses Profil aktiv ist
`max_tokens`	—	Maximale Ausgabe-Token begrenzen (optional)
`strip_params`	`"auto"`	`"auto"`, `"none"` oder `["temperature", "top_p"]`. Erkennt automatisch nicht unterstuetzte Parameter (z.B. ChatGPT-Codex-Endpunkt)
`[profiles.query_params]`	`{}`	URL-Abfrageparameter (z.B. Azure `api-version`)
`[profiles.models]`	—	Modell-Slot-Zuordnungstabelle (`haiku`, `sonnet`, `opus`-Felder)

Interaktive Einrichtung

Der einfachste Weg, ein Profil hinzuzufuegen, ist der interaktive Assistent:

claudex profile add

Er fuehrt Sie durch Anbieterauswahl, API-Schluessel-Eingabe (mit optionaler Schluesselbund-Speicherung), Modellauswahl und Konnektivitaetstests.

Schluesselbund-Integration

API-Schluessel sicher im OS-Schluesselbund statt im Klartext speichern:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # liest aus dem OS-Schluesselbund

Unterstuetzte Backends:

macOS: Keychain
Linux: Secret Service (GNOME Keyring / KDE Wallet)

OAuth-Abonnement-Authentifizierung

Anstelle von API-Schluesseln koennen Sie sich mit Ihrem bestehenden Anbieter-Abonnement ueber OAuth authentifizieren. Das ist nuetzlich, wenn Sie ein Claude Pro/Team-, ChatGPT Plus- oder anderes Abonnement haben.

Einrichtung

Setzen Sie auth_type des Profils auf "oauth" und geben Sie den oauth_provider an:

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

Melden Sie sich mit dem auth-Befehl an:

claudex auth login openai

Pruefen Sie Ihren Authentifizierungsstatus:

claudex auth status

Unterstuetzte Anbieter

Anbieter	`oauth_provider`	Token-Quelle
Claude	`claude`	Liest aus `~/.claude/.credentials.json` (native Claude Code-Konfiguration)
ChatGPT	`openai`	Browser-PKCE oder Device Code, Fallback auf `~/.codex/auth.json` (Codex CLI)
Google	`google`	Liest aus Gemini CLI-Anmeldedaten
Qwen	`qwen`	Device Code Flow
Kimi	`kimi`	Liest aus Kimi CLI-Anmeldedaten
GitHub	`github`	Device Code Flow, Fallback auf `~/.config/github-copilot/`
GitLab	`gitlab`	`GITLAB_TOKEN`-Umgebungsvariable

Fuer Details zu den OAuth-Flows der einzelnen Anbieter siehe OAuth-Abonnements.

Gateway-Auth-Modus

Bei OAuth-Profilen setzt Claudex ANTHROPIC_AUTH_TOKEN (nicht ANTHROPIC_API_KEY) beim Starten von Claude Code. Dies verhindert Konflikte mit dem eigenen Abonnement-Login-Mechanismus von Claude Code, der ANTHROPIC_API_KEY intern verwendet.

Der Proxy aktualisiert OAuth-Token automatisch vor ihrem Ablauf. Sie koennen auch manuell aktualisieren mit:

claudex auth refresh openai

Abfrageparameter

Einige Anbieter erfordern URL-Abfrageparameter (z.B. api-version von Azure OpenAI). Verwenden Sie die [profiles.query_params]-Tabelle:

[[profiles]]
name = "azure-openai"
provider_type = "OpenAICompatible"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT"
api_key = "YOUR_AZURE_KEY"
default_model = "gpt-4o"

[profiles.query_params]
api-version = "2024-12-01-preview"

Claudex haengt diese Parameter an jede Anfrage-URL fuer das Profil an. Azure OpenAI wird automatisch erkannt, wenn base_url den String openai.azure.com enthaelt, und verwendet den api-key-Header zur Authentifizierung anstelle von Authorization: Bearer.

Parameter-Bereinigung

Einige Anbieter unterstuetzen bestimmte Parameter nicht (z.B. lehnt der ChatGPT-Codex-Endpunkt temperature, top_p ab). Das Feld strip_params steuert, welche Parameter vor dem Senden entfernt werden:

strip_params = "auto"       # automatisch erkennen und nicht unterstuetzte Parameter entfernen (Standard)
strip_params = "none"       # alle Parameter unveraendert senden
strip_params = ["temperature", "top_p", "top_k"]  # bestimmte Parameter entfernen

Bei "auto" erkennt Claudex bekannte Endpunkte (z.B. chatgpt.com) und entfernt Parameter, die Fehler verursachen wuerden.

Modell-Slot-Zuordnung

Claude Code hat einen eingebauten /model-Umschalter mit drei Slots: haiku, sonnet und opus. Siehe Modell-Slot-Zuordnung fuer Details.

Werkzeugname-Kompatibilitaet

Einige Anbieter (insbesondere OpenAI) erzwingen ein 64-Zeichen-Limit fuer Werkzeug-(Funktions-)namen. Claude Code kann Werkzeugnamen generieren, die dieses Limit ueberschreiten.

Claudex kuerzt automatisch Werkzeugnamen, die laenger als 64 Zeichen sind, beim Senden von Anfragen an OpenAI-kompatible Anbieter und stellt die urspruenglichen Namen bei der Verarbeitung von Antworten transparent wieder her. Dieser Roundtrip ist vollstaendig transparent.

Nicht-interaktiver Modus

Claudex unterstuetzt einmalige (nicht-interaktive) Ausfuehrung fuer CI/CD-Pipelines, Skripte und Automatisierung:

# Antwort ausgeben und beenden
claudex run grok "Explain this codebase" --print

# Alle Berechtigungsabfragen ueberspringen (fuer vollautomatisierte Pipelines)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

Im nicht-interaktiven Modus werden Protokolle in instanzspezifische Logdateien unter ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log geschrieben statt nach stderr, wodurch die stdout-Ausgabe sauber fuer Piping und Automatisierung bleibt.

Terminal-Hyperlinks

Claudex unterstuetzt OSC-8-klickbare Hyperlinks in der Terminalausgabe. Siehe Terminal-Hyperlinks fuer Details.

# "auto" erkennt Terminalunterstuetzung; true/false erzwingt ein/aus
hyperlinks = "auto"

Konfigurationssets

Wiederverwendbare Pakete aus Regeln, Skills und MCP-Servern installieren. Siehe Konfigurationssets fuer Details.

claudex sets add ./my-set
claudex sets list

Vollstaendiges Beispiel

Siehe config.example.toml fuer eine vollstaendige Konfigurationsdatei mit allen Anbietern und Optionen.

Fuer Schritt-fuer-Schritt-Einrichtungsanleitungen fuer jeden Anbieter (einschliesslich API-Schluessel-Links und OAuth-Flows) siehe die Anbieter-Einrichtungsanleitung.