Configurazione

Ricerca del file di configurazione

Claudex utilizza figment per la configurazione a livelli. Le fonti vengono unite in questo ordine (le fonti successive sovrascrivono quelle precedenti):

1. Valori predefiniti programmatici (fallback integrati)
2. Configurazione globale (~/.config/claudex/config.toml o config.yaml)
3. Configurazione di progetto (claudex.toml o claudex.yaml nella directory corrente o nelle directory genitore fino a 10 livelli, oppure $CLAUDEX_CONFIG)
4. Variabili d’ambiente (prefisso CLAUDEX_, separatore __)

Sono supportati sia il formato TOML che YAML. Il formato viene rilevato dall’estensione (.toml o .yaml/.yml).

Nota

Il percorso XDG (~/.config/claudex/config.toml) e la posizione predefinita. Se non esiste alcun file di configurazione, questo percorso viene utilizzato durante la creazione di una nuova configurazione.

# Mostra il percorso del config caricato e tutte le posizioni di ricerca
claudex config show

# Mostra solo il percorso del file di configurazione
claudex config path

# Crea un nuovo config nella directory corrente
claudex config init

# Ricrea il config da config.example.toml
claudex config recreate

# Apri il config nel tuo $EDITOR
claudex config edit

# Valida la sintassi del config e i riferimenti ai profili
claudex config validate

# Ottieni un valore specifico del config
claudex config get proxy_port

# Imposta un valore specifico del config
claudex config set proxy_port 8080

# Esporta il config corrente su stdout
claudex config export

Consiglio

La configurazione a livello di progetto (./claudex.toml) ha priorita sulla configurazione globale, permettendo di personalizzare i fornitori per ogni progetto.

Impostazioni globali

# Percorso del binario claude (predefinito: "claude" dal PATH)
# claude_binary = "/usr/local/bin/claude"

# Impostazioni proxy
proxy_port = 13456
proxy_host = "127.0.0.1"

# Livello di log: trace, debug, info, warn, error
log_level = "info"

# Hyperlink nel terminale (OSC 8): "auto" | true | false
# "auto" rileva il supporto del terminale; true/false forzano on/off
hyperlinks = "auto"

# Alias modelli (abbreviazione → nome completo del modello)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profili

Ogni profilo rappresenta una connessione a un fornitore AI. Esistono tre tipi di fornitore:

DirectAnthropic

Per i fornitori che supportano nativamente l’API Anthropic Messages. Le richieste vengono inoltrate con modifiche minime.

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

Fornitori compatibili: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Per i fornitori che utilizzano l’API OpenAI Chat Completions. Claudex traduce automaticamente tra i protocolli Anthropic e 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

Fornitori compatibili: 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

Per i fornitori che utilizzano l’API OpenAI Responses (ad es. abbonamenti ChatGPT/Codex). Claudex traduce tra l’API Anthropic Messages e 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"

Fornitori compatibili: abbonamenti ChatGPT/Codex (tramite Codex CLI)

Consiglio

Questo tipo di fornitore viene utilizzato principalmente con abbonamenti OAuth. Consulta la Guida alla configurazione dei fornitori per istruzioni dettagliate sulla configurazione di Codex CLI.

Campi del profilo

Campo	Predefinito	Descrizione
name	obbligatorio	Identificatore univoco del profilo
provider_type	DirectAnthropic	DirectAnthropic, OpenAICompatible o OpenAIResponses
base_url	obbligatorio	Endpoint API del fornitore
api_key	""	Chiave API (testo in chiaro)
api_key_keyring	—	Legge la chiave API dal portachiavi del sistema operativo
default_model	obbligatorio	Modello predefinito da utilizzare
auth_type	"api-key"	"api-key" o "oauth"
oauth_provider	—	Fornitore OAuth (claude, openai, google, qwen, kimi, github, gitlab). Obbligatorio quando auth_type = "oauth"
backup_providers	[]	Nomi dei profili di failover
custom_headers	{}	Header HTTP aggiuntivi
extra_env	{}	Variabili d’ambiente aggiuntive per Claude
priority	100	Priorita per il routing intelligente
enabled	true	Se il profilo e attivo
max_tokens	—	Limita i token di output massimi inviati al fornitore (opzionale)
strip_params	"auto"	"auto", "none" o ["temperature", "top_p"]. Rileva automaticamente i parametri non supportati (ad es. endpoint ChatGPT Codex)
[profiles.query_params]	{}	Parametri query URL (ad es. api-version per Azure)
[profiles.models]	—	Tabella di mappatura degli slot modello (campi haiku, sonnet, opus)

Configurazione interattiva

Il modo piu semplice per aggiungere un profilo e la procedura guidata interattiva:

claudex profile add

Ti guida attraverso la selezione del fornitore, l’inserimento della chiave API (con archiviazione opzionale nel portachiavi), la selezione del modello e il test di connettivita.

Integrazione con il portachiavi

Memorizza le chiavi API in modo sicuro nel portachiavi del sistema operativo invece che in testo in chiaro nel config:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # legge dal portachiavi del SO

Backend supportati:

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

Autenticazione OAuth con abbonamento

Invece delle chiavi API, puoi autenticarti con il tuo abbonamento esistente tramite OAuth. Utile se hai un piano Claude Pro/Team, ChatGPT Plus o altri abbonamenti.

Configurazione

1. Imposta auth_type del profilo su "oauth" e specifica 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. Effettua il login con il comando auth:

claudex auth login openai

3. Verifica lo stato dell’autenticazione:

claudex auth status

Fornitori supportati

Fornitore	oauth_provider	Origine del token
Claude	claude	Legge da ~/.claude/.credentials.json (configurazione nativa di Claude Code)
ChatGPT	openai	Browser PKCE o Device Code, fallback su ~/.codex/auth.json (Codex CLI)
Google	google	Legge dalle credenziali di Gemini CLI
Qwen	qwen	Device Code flow
Kimi	kimi	Legge dalle credenziali di Kimi CLI
GitHub	github	Device Code flow, fallback su ~/.config/github-copilot/
GitLab	gitlab	Variabile d’ambiente GITLAB_TOKEN

Per i dettagli sul flusso OAuth di ciascun fornitore, consulta Abbonamenti OAuth.

Modalita Gateway Auth

Quando si utilizzano profili OAuth, Claudex imposta ANTHROPIC_AUTH_TOKEN (non ANTHROPIC_API_KEY) durante l’avvio di Claude Code. Questo previene conflitti con il meccanismo di login dell’abbonamento nativo di Claude Code, che utilizza ANTHROPIC_API_KEY internamente.

Il proxy aggiorna automaticamente i token OAuth prima della scadenza. Puoi anche aggiornare manualmente con:

claudex auth refresh openai

Parametri query

Alcuni fornitori richiedono parametri query nell’URL (ad es. api-version di Azure OpenAI). Usa la tabella [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 aggiunge questi parametri a ogni URL di richiesta per il profilo. Azure OpenAI viene rilevato automaticamente quando base_url contiene openai.azure.com e utilizza l’header api-key per l’autenticazione al posto di Authorization: Bearer.

Rimozione dei parametri

Alcuni fornitori non supportano determinati parametri (ad es. l’endpoint ChatGPT Codex rifiuta temperature, top_p). Il campo strip_params controlla quali parametri vengono rimossi prima dell’invio:

strip_params = "auto"       # rileva e rimuove automaticamente i parametri non supportati (predefinito)
strip_params = "none"       # invia tutti i parametri cosi come sono
strip_params = ["temperature", "top_p", "top_k"]  # rimuove parametri specifici

Quando impostato su "auto", Claudex rileva gli endpoint noti (ad es. chatgpt.com) e rimuove i parametri che causerebbero errori.

Mappatura slot modello

Claude Code ha un selettore /model integrato con tre slot: haiku, sonnet e opus. Consulta Mappatura slot modello per i dettagli.

Compatibilita nomi tool

Alcuni fornitori (in particolare OpenAI) impongono un limite di 64 caratteri sui nomi dei tool (funzioni). Claude Code puo generare nomi di tool che superano questo limite.

Claudex tronca automaticamente i nomi dei tool superiori a 64 caratteri quando invia richieste a fornitori compatibili con OpenAI e ripristina trasparentemente i nomi originali durante l’elaborazione delle risposte. Questo processo bidirezionale e completamente trasparente.

Modalita non interattiva

Claudex supporta l’esecuzione one-shot (non interattiva) per l’uso in pipeline CI/CD, script e automazione:

# Stampa la risposta ed esci
claudex run grok "Explain this codebase" --print

# Salta tutti i prompt di autorizzazione (per pipeline completamente automatizzate)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

Attenzione

--dangerously-skip-permissions disabilita tutti i prompt di sicurezza. Usalo solo in ambienti automatizzati affidabili.

In modalita non interattiva, i log vengono scritti in file di log per istanza in ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log invece che su stderr, mantenendo l’output stdout pulito per il piping e l’automazione.

Hyperlink nel terminale

Claudex supporta gli hyperlink cliccabili OSC 8 nell’output del terminale. Consulta Hyperlink nel terminale per i dettagli.

# "auto" rileva il supporto del terminale; true/false forzano on/off
hyperlinks = "auto"

Set di configurazione

Installa pacchetti riutilizzabili di regole, skill e server MCP. Consulta Set di configurazione per i dettagli.

claudex sets add ./my-set
claudex sets list

Esempio completo

Consulta config.example.toml per un file di configurazione completo con tutti i fornitori e le opzioni.

Per istruzioni passo passo sulla configurazione di ciascun fornitore (inclusi link per le chiavi API e flussi OAuth), consulta la Guida alla configurazione dei fornitori.