Configuration

Decouverte du fichier de configuration

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

1. Valeurs par defaut programmatiques (replis integres)
2. Configuration globale (~/.config/claudex/config.toml ou config.yaml)
3. Configuration projet (claudex.toml ou claudex.yaml dans le repertoire courant ou les repertoires parents jusqu’a 10 niveaux, ou $CLAUDEX_CONFIG)
4. Variables d’environnement (prefixe CLAUDEX_, __ comme separateur)

Les formats TOML et YAML sont tous deux supportes. Le format du fichier est detecte par l’extension (.toml ou .yaml/.yml).

Note

Le chemin XDG (~/.config/claudex/config.toml) est l’emplacement par defaut. Si aucun fichier de configuration n’existe nulle part, ce chemin est utilise lors de la creation d’une nouvelle configuration.

# Afficher le chemin du config charge et tous les emplacements de recherche
claudex config show

# Afficher uniquement le chemin du fichier de config
claudex config path

# Creer un nouveau config dans le repertoire courant
claudex config init

# Recreer le config depuis config.example.toml
claudex config recreate

# Ouvrir le config dans votre $EDITOR
claudex config edit

# Valider la syntaxe du config et les references de profils
claudex config validate

# Obtenir une valeur specifique du config
claudex config get proxy_port

# Definir une valeur specifique du config
claudex config set proxy_port 8080

# Exporter le config actuel vers stdout
claudex config export

Astuce

La configuration au niveau projet (./claudex.toml) a priorite sur la configuration globale, vous pouvez donc personnaliser les fournisseurs par projet.

Parametres globaux

# Chemin vers le binaire claude (defaut : "claude" depuis PATH)
# claude_binary = "/usr/local/bin/claude"

# Parametres du proxy
proxy_port = 13456
proxy_host = "127.0.0.1"

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

# Hyperliens terminaux (OSC 8) : "auto" | true | false
# "auto" detecte le support du terminal ; true/false forcent l'activation/desactivation
hyperlinks = "auto"

# Alias de modeles (raccourci → nom complet du modele)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profils

Chaque profil represente une connexion a un fournisseur IA. Il existe trois types de fournisseur :

DirectAnthropic

Pour les fournisseurs qui supportent nativement l’API Anthropic Messages. Les requetes sont transmises avec un minimum de modifications.

[[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

Fournisseurs compatibles : Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Pour les fournisseurs utilisant l’API OpenAI Chat Completions. Claudex traduit automatiquement entre les protocoles Anthropic et OpenAI.

[[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

Fournisseurs compatibles : 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

Pour les fournisseurs utilisant l’API OpenAI Responses (par ex. abonnements ChatGPT/Codex). Claudex traduit entre l’API Anthropic Messages et l’API OpenAI Responses.

[[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"

Fournisseurs compatibles : Abonnements ChatGPT/Codex (via Codex CLI)

Astuce

Ce type de fournisseur est principalement utilise avec les abonnements OAuth. Consultez le Guide de configuration des fournisseurs pour des instructions detaillees sur la configuration du Codex CLI.

Champs du profil

Champ	Defaut	Description
name	requis	Identifiant unique du profil
provider_type	DirectAnthropic	DirectAnthropic, OpenAICompatible ou OpenAIResponses
base_url	requis	Endpoint API du fournisseur
api_key	""	Cle API (texte brut)
api_key_keyring	—	Lire la cle API depuis le trousseau OS
default_model	requis	Modele par defaut a utiliser
auth_type	"api-key"	"api-key" ou "oauth"
oauth_provider	—	Fournisseur OAuth (claude, openai, google, qwen, kimi, github, gitlab). Requis quand auth_type = "oauth"
backup_providers	[]	Noms des profils de basculement
custom_headers	{}	En-tetes HTTP supplementaires
extra_env	{}	Variables d’environnement supplementaires pour Claude
priority	100	Priorite pour le routage intelligent
enabled	true	Si ce profil est actif
max_tokens	—	Plafonner le nombre max de tokens de sortie envoyes au fournisseur (optionnel)
strip_params	"auto"	"auto", "none", ou ["temperature", "top_p"]. Detecte automatiquement les parametres non supportes (par ex. endpoint ChatGPT Codex)
[profiles.query_params]	{}	Parametres de requete URL (par ex. api-version Azure)
[profiles.models]	—	Table de mapping des slots de modele (champs haiku, sonnet, opus)

Configuration interactive

Le moyen le plus simple d’ajouter un profil est l’assistant interactif :

claudex profile add

Il vous guide a travers la selection du fournisseur, la saisie de la cle API (avec stockage optionnel dans le trousseau), la selection du modele, et le test de connectivite.

Integration du trousseau

Stockez les cles API de maniere securisee dans le trousseau de votre OS au lieu du texte brut dans le config :

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # lit depuis le trousseau OS

Backends supportes :

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

Authentification par abonnement OAuth

Au lieu de cles API, vous pouvez vous authentifier avec votre abonnement fournisseur existant via OAuth. Utile si vous avez un abonnement Claude Pro/Team, ChatGPT Plus, ou un autre plan.

Configuration

1. Definissez le auth_type du profil a "oauth" et specifiez le oauth_provider :

[[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"

2. Connectez-vous avec la commande auth :

claudex auth login openai

3. Verifiez votre statut d’authentification :

claudex auth status

Fournisseurs supportes

Fournisseur	oauth_provider	Source du token
Claude	claude	Lit depuis ~/.claude/.credentials.json (config native de Claude Code)
ChatGPT	openai	PKCE navigateur ou Device Code, se rabat sur ~/.codex/auth.json (Codex CLI)
Google	google	Lit depuis les credentials du Gemini CLI
Qwen	qwen	Flux Device Code
Kimi	kimi	Lit depuis les credentials du Kimi CLI
GitHub	github	Flux Device Code, se rabat sur ~/.config/github-copilot/
GitLab	gitlab	Variable d’environnement GITLAB_TOKEN

Pour les details sur le flux OAuth de chaque fournisseur, consultez Abonnements OAuth.

Mode Gateway Auth

Lors de l’utilisation de profils OAuth, Claudex definit ANTHROPIC_AUTH_TOKEN (et non ANTHROPIC_API_KEY) au lancement de Claude Code. Cela empeche les conflits avec le mecanisme de connexion par abonnement propre a Claude Code, qui utilise ANTHROPIC_API_KEY en interne.

Le proxy rafraichit automatiquement les tokens OAuth avant leur expiration. Vous pouvez aussi rafraichir manuellement avec :

claudex auth refresh openai

Parametres de requete

Certains fournisseurs necessitent des parametres de requete URL (par ex. api-version d’Azure OpenAI). Utilisez la table [profiles.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"

Claudex ajoute ces parametres a chaque URL de requete pour le profil. Azure OpenAI est auto-detecte par la presence de openai.azure.com dans la base_url et utilise l’en-tete api-key pour l’authentification au lieu de Authorization: Bearer.

Filtrage des parametres

Certains fournisseurs ne supportent pas certains parametres (par ex. l’endpoint ChatGPT Codex rejette temperature, top_p). Le champ strip_params controle quels parametres sont supprimes avant l’envoi :

strip_params = "auto"       # auto-detecte et supprime les params non supportes (defaut)
strip_params = "none"       # envoie tous les params tels quels
strip_params = ["temperature", "top_p", "top_k"]  # supprime des params specifiques

Quand la valeur est "auto", Claudex detecte les endpoints connus (par ex. chatgpt.com) et supprime les parametres qui provoqueraient des erreurs.

Mapping des slots de modele

Claude Code dispose d’un selecteur /model integre avec trois slots : haiku, sonnet et opus. Consultez Mapping des slots de modele pour les details.

Compatibilite des noms d’outils

Certains fournisseurs (notamment OpenAI) imposent une limite de 64 caracteres sur les noms d’outils (fonctions). Claude Code peut generer des noms d’outils depassant cette limite.

Claudex tronque automatiquement les noms d’outils de plus de 64 caracteres lors de l’envoi de requetes aux fournisseurs compatibles OpenAI et restaure de maniere transparente les noms originaux lors du traitement des reponses. Cet aller-retour est entierement transparent.

Mode non interactif

Claudex supporte l’execution ponctuelle (non interactive) pour une utilisation dans les pipelines CI/CD, les scripts et l’automatisation :

# Afficher la reponse et quitter
claudex run grok "Explain this codebase" --print

# Ignorer toutes les demandes de permission (pour les pipelines entierement automatises)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

Attention

--dangerously-skip-permissions desactive toutes les demandes de securite. N’utilisez ceci que dans des environnements automatises de confiance.

En mode non interactif, les logs sont ecrits dans des fichiers de log par instance a ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log au lieu de stderr, gardant la sortie stdout propre pour le piping et l’automatisation.

Hyperliens terminaux

Claudex supporte les hyperliens cliquables OSC 8 dans la sortie du terminal. Consultez Hyperliens terminaux pour les details.

# "auto" detecte le support du terminal ; true/false forcent l'activation/desactivation
hyperlinks = "auto"

Jeux de configuration

Installez des ensembles reutilisables de regles, skills et serveurs MCP. Consultez Jeux de configuration pour les details.

claudex sets add ./my-set
claudex sets list

Exemple complet

Consultez config.example.toml pour un fichier de configuration complet avec tous les fournisseurs et options.

Pour des instructions de configuration etape par etape pour chaque fournisseur (incluant les liens de cles API et les flux OAuth), consultez le Guide de configuration des fournisseurs.