Reference de configuration

Emplacement du fichier de configuration

Claudex utilise une configuration par couches via figment. Les sources sont fusionnees dans cet ordre (les sources ulterieures ecrasent les precedentes) :

1. Valeurs par defaut programmatiques
2. Configuration globale (~/.config/claudex/config.toml ou .yaml)
3. Configuration projet (claudex.toml/.claudex/config.toml dans le CWD ou parents, ou $CLAUDEX_CONFIG)
4. Variables d’environnement (prefixe CLAUDEX_, separateur __)

Les formats TOML et YAML sont tous deux supportes.

Consultez Configuration pour les details de mise en place.

Parametres globaux

# Chemin vers le binaire claude (defaut : "claude" depuis PATH)
claude_binary = "claude"

# Port d'ecoute du serveur proxy
proxy_port = 13456

# Adresse d'ecoute du serveur proxy
proxy_host = "127.0.0.1"

# Niveau de log : trace, debug, info, warn, error
log_level = "info"

# Hyperliens terminaux (OSC 8) : "auto" | true | false
hyperlinks = "auto"

Champ	Type	Defaut	Description
claude_binary	string	"claude"	Chemin vers le binaire CLI Claude Code
proxy_port	integer	13456	Port sur lequel le proxy de traduction ecoute
proxy_host	string	"127.0.0.1"	Adresse a laquelle le proxy se lie
log_level	string	"info"	Niveau de log minimum
hyperlinks	string/bool	"auto"	Hyperliens terminaux : "auto" (detecter), true (forcer), false (desactiver)

Alias de modeles

Definissez des noms abreges pour les identifiants de modeles :

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

Utilisez les alias avec -m :

claudex run grok -m grok3

Configuration des profils

[[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" (defaut) ou "oauth"
# oauth_provider = "openai"        # requis quand auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # optionnel : plafonner les tokens de sortie
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# Parametres de requete URL (par ex. Azure api-version)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Mapping des slots de modele (optionnel)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Champ	Type	Defaut	Description
name	string	requis	Identifiant unique du profil
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" ou "OpenAIResponses"
base_url	string	requis	URL de l’endpoint API du fournisseur
api_key	string	""	Cle API en texte brut
api_key_keyring	string	—	Nom de l’entree du trousseau OS (surcharge api_key)
default_model	string	requis	Identifiant du modele a utiliser par defaut
auth_type	string	"api-key"	Methode d’authentification : "api-key" ou "oauth"
oauth_provider	string	—	Nom du fournisseur OAuth. Un parmi : claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Noms de profils pour le basculement, essayes dans l’ordre
custom_headers	map	{}	En-tetes HTTP supplementaires envoyes avec chaque requete
extra_env	map	{}	Variables d’environnement definies au lancement de Claude
priority	integer	100	Poids de priorite pour le routage intelligent (plus eleve = prefere)
enabled	boolean	true	Si ce profil est actif
max_tokens	integer	—	Plafonner les tokens de sortie max envoyes au fournisseur. Quand defini, surcharge le max_tokens des requetes
strip_params	string/array	"auto"	Parametres a supprimer des requetes. "auto" detecte les endpoints connus ; "none" envoie tout ; un tableau supprime des parametres specifiques

Parametres de requete

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

Champ	Type	Description
query_params	map	Paires cle-valeur ajoutees comme parametres de requete URL a chaque requete

Utilise principalement pour Azure OpenAI (api-version), mais fonctionne avec tout fournisseur.

Mapping des slots de modele

La table optionnelle [profiles.models] associe les slots du selecteur /model de Claude Code aux noms de modeles specifiques au fournisseur. Quand vous changez de modele dans Claude Code (par ex. /model opus), Claudex traduit la requete vers le modele associe.

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

Champ	Type	Description
haiku	string	Modele a utiliser quand Claude Code selectionne haiku
sonnet	string	Modele a utiliser quand Claude Code selectionne sonnet
opus	string	Modele a utiliser quand Claude Code selectionne opus

Astuce

Si un slot n’est pas defini, le default_model du profil est utilise comme repli. Les slots sont aussi exposes en tant que variables d’environnement : ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Exemples de fournisseurs

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

# MiniMax (DirectAnthropic — pas de traduction)
[[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 — traduction necessaire)
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok (OpenAICompatible — traduction necessaire)
[[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 — traduction necessaire)
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

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

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

# GLM / 智谱 (OpenAICompatible — traduction necessaire)
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq (OpenAICompatible — inference rapide)
[[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 — traduction necessaire)
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI (OpenAICompatible — traduction necessaire)
[[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 — recherche en ligne + LLM)
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

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

# Azure OpenAI (OpenAICompatible — en-tete api-key + 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 (local, pas de cle API requise)
[[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 (local)
[[profiles]]
name = "local-llama"
provider_type = "OpenAICompatible"
base_url = "http://localhost:8000/v1"
api_key = ""
default_model = "llama-3.3-70b"
enabled = false

Exemples de profils OAuth

# Claude Max (contourne le proxy, utilise l'OAuth natif de Claude depuis ~/.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"

# Abonnement ChatGPT/Codex (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 via 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 via 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 via 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 via 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 via 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"

Attention

Pour le fournisseur OAuth claude, Claudex contourne le proxy et laisse Claude Code utiliser son propre OAuth directement. Pour tous les autres fournisseurs OAuth, le proxy gere la gestion et le rafraichissement des tokens.

Routeur intelligent

[router]
enabled = false
profile = "local-qwen"    # reutiliser le base_url + api_key d'un profil
model = "qwen2.5:3b"      # surcharger le modele (optionnel)

Champ	Type	Defaut	Description
enabled	boolean	false	Activer le routage intelligent
profile	string	""	Nom du profil a reutiliser pour la classification (utilise son base_url + api_key)
model	string	""	Surcharge du modele pour la classification (par defaut le default_model du profil)

Regles de routage

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

Cle	Description
code	Profil pour les taches de codage
analysis	Profil pour l’analyse et le raisonnement
creative	Profil pour l’ecriture creative
search	Profil pour la recherche et la documentation
math	Profil pour les mathematiques et la logique
default	Repli quand l’intention n’est pas classifiee

Moteur de contexte

Compression

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # reutiliser le base_url + api_key d'un profil
model = "qwen2.5:3b"      # surcharger le modele (optionnel)

Champ	Type	Defaut	Description
enabled	boolean	false	Activer la compression de conversation
threshold_tokens	integer	50000	Compresser quand le nombre de tokens depasse ce seuil
keep_recent	integer	10	Toujours garder les N derniers messages non compresses
profile	string	""	Nom du profil a reutiliser pour la synthese
model	string	""	Surcharge du modele pour la synthese

Partage inter-profils

[context.sharing]
enabled = false
max_context_size = 2000

Champ	Type	Defaut	Description
enabled	boolean	false	Activer le partage de contexte inter-profils
max_context_size	integer	2000	Nombre max de tokens a injecter depuis d’autres profils

RAG local

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # reutiliser le base_url + api_key d'un profil
model = "nomic-embed-text"           # modele d'embedding
chunk_size = 512
top_k = 5

Champ	Type	Defaut	Description
enabled	boolean	false	Activer le RAG local
index_paths	string[]	[]	Repertoires a indexer
profile	string	""	Nom du profil a reutiliser pour les embeddings
model	string	""	Nom du modele d’embedding
chunk_size	integer	512	Taille des chunks de texte en tokens
top_k	integer	5	Nombre de resultats a injecter