Konfigurationsreferenz

Speicherort der Konfigurationsdatei

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

1. Programmatische Standardwerte
2. Globale Konfiguration (~/.config/claudex/config.toml oder .yaml)
3. Projektkonfiguration (claudex.toml/.claudex/config.toml im CWD oder uebergeordneten Verzeichnissen, oder $CLAUDEX_CONFIG)
4. Umgebungsvariablen (CLAUDEX_-Praefix, __-Trennzeichen)

Sowohl TOML- als auch YAML-Formate werden unterstuetzt.

Siehe Konfiguration fuer Einrichtungsdetails.

Globale Einstellungen

# Pfad zur claude-Binaerdatei (Standard: "claude" aus PATH)
claude_binary = "claude"

# Proxy-Server-Bind-Port
proxy_port = 13456

# Proxy-Server-Bind-Adresse
proxy_host = "127.0.0.1"

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

# Terminal-Hyperlinks (OSC 8): "auto" | true | false
hyperlinks = "auto"

Feld	Typ	Standard	Beschreibung
claude_binary	string	"claude"	Pfad zur Claude Code CLI-Binaerdatei
proxy_port	integer	13456	Port, auf dem der Uebersetzungsproxy lauscht
proxy_host	string	"127.0.0.1"	Adresse, an die der Proxy gebunden ist
log_level	string	"info"	Minimaler Log-Level
hyperlinks	string/bool	"auto"	Terminal-Hyperlinks: "auto" (erkennen), true (erzwingen ein), false (erzwingen aus)

Modell-Aliase

Kurzformen fuer Modellbezeichner definieren:

[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"
claude = "claude-sonnet-4-20250514"

Aliase mit -m verwenden:

claudex run grok -m grok3

Profilkonfiguration

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
# api_key_keyring = "grok-api-key"
default_model = "grok-3-beta"
auth_type = "api-key"              # "api-key" (Standard) oder "oauth"
# oauth_provider = "openai"        # erforderlich wenn auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # optional: Ausgabe-Token begrenzen
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# URL-Abfrageparameter (z.B. Azure api-version)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Modell-Slot-Zuordnung (optional)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Feld	Typ	Standard	Beschreibung
name	string	erforderlich	Eindeutiger Profilbezeichner
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" oder "OpenAIResponses"
base_url	string	erforderlich	API-Endpunkt-URL des Anbieters
api_key	string	""	API-Schluessel im Klartext
api_key_keyring	string	—	Name des OS-Schluesselbundeintrags (ueberschreibt api_key)
default_model	string	erforderlich	Standardmaessig verwendeter Modellbezeichner
auth_type	string	"api-key"	Authentifizierungsmethode: "api-key" oder "oauth"
oauth_provider	string	—	OAuth-Anbietername. Eines von: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Profilnamen fuer Failover, in Reihenfolge versucht
custom_headers	map	{}	Zusaetzliche HTTP-Header, die mit jeder Anfrage gesendet werden
extra_env	map	{}	Umgebungsvariablen, die beim Starten von Claude gesetzt werden
priority	integer	100	Prioritaetsgewicht fuer intelligentes Routing (hoeher = bevorzugt)
enabled	boolean	true	Ob dieses Profil aktiv ist
max_tokens	integer	—	Maximale Ausgabe-Token begrenzen. Wenn gesetzt, ueberschreibt max_tokens in Anfragen
strip_params	string/array	"auto"	Parameter, die aus Anfragen entfernt werden. "auto" erkennt bekannte Endpunkte; "none" sendet alle; Array entfernt bestimmte Parameter

Abfrageparameter

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

Feld	Typ	Beschreibung
query_params	map	Schluessel-Wert-Paare, die als URL-Abfrageparameter an jede Anfrage angehaengt werden

Wird hauptsaechlich fuer Azure OpenAI (api-version) verwendet, funktioniert aber mit jedem Anbieter.

Modell-Slot-Zuordnung

Die optionale [profiles.models]-Tabelle ordnet die /model-Umschalter-Slots von Claude Code anbieterspezifischen Modellnamen zu. Beim Wechseln von Modellen in Claude Code (z.B. /model opus) uebersetzt Claudex die Anfrage zum zugeordneten Modell.

[profiles.models]
haiku = "grok-3-mini-beta"    # ordnet /model haiku zu
sonnet = "grok-3-beta"        # ordnet /model sonnet zu
opus = "grok-3-beta"          # ordnet /model opus zu

Feld	Typ	Beschreibung
haiku	string	Zu verwendendes Modell, wenn Claude Code haiku auswaehlt
sonnet	string	Zu verwendendes Modell, wenn Claude Code sonnet auswaehlt
opus	string	Zu verwendendes Modell, wenn Claude Code opus auswaehlt

Tipp

Wenn ein Slot nicht definiert ist, wird das default_model des Profils als Fallback verwendet. Slots werden auch als Umgebungsvariablen bereitgestellt: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Anbieterbeispiele

# Anthropic (DirectAnthropic -- keine Uebersetzung)
[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"

# MiniMax (DirectAnthropic -- keine Uebersetzung)
[[profiles]]
name = "minimax"
provider_type = "DirectAnthropic"
base_url = "https://api.minimax.io/anthropic"
api_key = "..."
default_model = "claude-sonnet-4-20250514"
backup_providers = ["anthropic"]

# OpenRouter (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]

# OpenAI (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

# DeepSeek (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "deepseek"
provider_type = "OpenAICompatible"
base_url = "https://api.deepseek.com"
api_key = "..."
default_model = "deepseek-chat"
backup_providers = ["grok"]

# Kimi / Moonshot (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "kimi"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.ai/v1"
api_key = "..."
default_model = "kimi-k2-0905-preview"

# GLM / Zhipu (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq (OpenAICompatible -- schnelle Inferenz)
[[profiles]]
name = "groq"
provider_type = "OpenAICompatible"
base_url = "https://api.groq.com/openai/v1"
api_key = "gsk_..."
default_model = "llama-3.3-70b-versatile"

# Mistral AI (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI (OpenAICompatible -- Uebersetzung erforderlich)
[[profiles]]
name = "together"
provider_type = "OpenAICompatible"
base_url = "https://api.together.xyz/v1"
api_key = "..."
default_model = "meta-llama/Llama-3.3-70B-Instruct-Turbo"

# Perplexity (OpenAICompatible -- Online-Suche + LLM)
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

# Cerebras (OpenAICompatible -- schnelle Inferenz)
[[profiles]]
name = "cerebras"
provider_type = "OpenAICompatible"
base_url = "https://api.cerebras.ai/v1"
api_key = "..."
default_model = "llama-3.3-70b"

# Azure OpenAI (OpenAICompatible -- api-key-Header + query_params)
[[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"

# Google Vertex AI (DirectAnthropic)
[[profiles]]
name = "vertex-ai"
provider_type = "DirectAnthropic"
base_url = "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models"
api_key = "YOUR_GCLOUD_TOKEN"
default_model = "claude-sonnet-4@20250514"

# Ollama (lokal, kein API-Schluessel erforderlich)
[[profiles]]
name = "local-qwen"
provider_type = "OpenAICompatible"
base_url = "http://localhost:11434/v1"
api_key = ""
default_model = "qwen2.5:72b"
enabled = false

# vLLM / LM Studio (lokal)
[[profiles]]
name = "local-llama"
provider_type = "OpenAICompatible"
base_url = "http://localhost:8000/v1"
api_key = ""
default_model = "llama-3.3-70b"
enabled = false

OAuth-Profilbeispiele

# Claude Max (ueberspringt Proxy, verwendet natives OAuth von Claude aus ~/.claude)
[[profiles]]
name = "claude-max"
provider_type = "DirectAnthropic"
base_url = "https://api.claude.ai"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "claude"

[profiles.models]
haiku = "claude-haiku-4-20250514"
sonnet = "claude-sonnet-4-20250514"
opus = "claude-opus-4-20250514"

# ChatGPT/Codex-Abonnement (OpenAIResponses)
[[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"

[profiles.models]
haiku = "codex-mini-latest"
sonnet = "gpt-5.3-codex"
opus = "gpt-5.3-codex"

# Google Gemini ueber OAuth
[[profiles]]
name = "gemini-sub"
provider_type = "OpenAICompatible"
base_url = "https://generativelanguage.googleapis.com/v1beta/openai"
default_model = "gemini-2.5-pro"
auth_type = "oauth"
oauth_provider = "google"

# Kimi ueber OAuth
[[profiles]]
name = "kimi-oauth"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.cn/v1"
default_model = "moonshot-v1-128k"
auth_type = "oauth"
oauth_provider = "kimi"

# Qwen ueber OAuth
[[profiles]]
name = "qwen-oauth"
provider_type = "OpenAICompatible"
base_url = "https://chat.qwen.ai/api"
default_model = "qwen3-235b-a22b"
auth_type = "oauth"
oauth_provider = "qwen"

# GitHub Copilot ueber OAuth
[[profiles]]
name = "copilot"
provider_type = "OpenAICompatible"
base_url = "https://api.githubcopilot.com"
default_model = "gpt-4o"
auth_type = "oauth"
oauth_provider = "github"

# GitLab Duo ueber GITLAB_TOKEN
[[profiles]]
name = "gitlab-duo"
provider_type = "OpenAICompatible"
base_url = "https://gitlab.com/api/v4/ai/llm/proxy"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "gitlab"

Achtung

Fuer den claude OAuth-Anbieter ueberspringt Claudex den Proxy und laesst Claude Code sein eigenes OAuth direkt verwenden. Fuer alle anderen OAuth-Anbieter uebernimmt der Proxy die Token-Verwaltung und -Aktualisierung.

Intelligenter Router

[router]
enabled = false
profile = "local-qwen"    # base_url + api_key eines Profils wiederverwenden
model = "qwen2.5:3b"      # Modell ueberschreiben (optional)

Feld	Typ	Standard	Beschreibung
enabled	boolean	false	Intelligentes Routing aktivieren
profile	string	""	Profilname fuer Klassifikation (verwendet dessen base_url + api_key)
model	string	""	Modellueberschreibung fuer Klassifikation (Standard ist default_model des Profils)

Routing-Regeln

[router.rules]
code = "deepseek"
analysis = "grok"
creative = "chatgpt"
search = "kimi"
math = "deepseek"
default = "grok"

Schluessel	Beschreibung
code	Profil fuer Programmieraufgaben
analysis	Profil fuer Analyse und Schlussfolgern
creative	Profil fuer kreatives Schreiben
search	Profil fuer Suche und Recherche
math	Profil fuer Mathematik und Logik
default	Fallback, wenn Absicht nicht klassifiziert

Kontext-Engine

Komprimierung

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # base_url + api_key eines Profils wiederverwenden
model = "qwen2.5:3b"      # Modell ueberschreiben (optional)

Feld	Typ	Standard	Beschreibung
enabled	boolean	false	Konversationskomprimierung aktivieren
threshold_tokens	integer	50000	Komprimieren, wenn Token-Anzahl diesen Wert ueberschreitet
keep_recent	integer	10	Immer die letzten N Nachrichten unkomprimiert behalten
profile	string	""	Profilname fuer Zusammenfassung
model	string	""	Modellueberschreibung fuer Zusammenfassung

Profiluebergreifende Freigabe

[context.sharing]
enabled = false
max_context_size = 2000

Feld	Typ	Standard	Beschreibung
enabled	boolean	false	Profiluebergreifende Kontextfreigabe aktivieren
max_context_size	integer	2000	Maximale Token, die aus anderen Profilen injiziert werden

Lokales RAG

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # base_url + api_key eines Profils wiederverwenden
model = "nomic-embed-text"           # Einbettungsmodell
chunk_size = 512
top_k = 5

Feld	Typ	Standard	Beschreibung
enabled	boolean	false	Lokales RAG aktivieren
index_paths	string[]	[]	Zu indizierende Verzeichnisse
profile	string	""	Profilname fuer Einbettungen
model	string	""	Einbettungsmodellname
chunk_size	integer	512	Textchunk-Groesse in Token
top_k	integer	5	Anzahl der zu injizierenden Ergebnisse