Riferimento configurazione

Posizione del file di configurazione

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

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

Sono supportati sia il formato TOML che YAML.

Consulta Configurazione per i dettagli di setup.

Impostazioni globali

# Percorso del binario claude (predefinito: "claude" dal PATH)
claude_binary = "claude"

# Porta di bind del server proxy
proxy_port = 13456

# Indirizzo di bind del server proxy
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
hyperlinks = "auto"

Campo	Tipo	Predefinito	Descrizione
claude_binary	string	"claude"	Percorso del binario CLI di Claude Code
proxy_port	integer	13456	Porta su cui il proxy di traduzione e in ascolto
proxy_host	string	"127.0.0.1"	Indirizzo a cui si lega il proxy
log_level	string	"info"	Livello minimo di log
hyperlinks	string/bool	"auto"	Hyperlink nel terminale: "auto" (rileva), true (forza on), false (forza off)

Alias modello

Definisci nomi abbreviati per gli identificatori dei modelli:

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

Usa gli alias con -m:

claudex run grok -m grok3

Configurazione del profilo

[[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" (predefinito) o "oauth"
# oauth_provider = "openai"        # obbligatorio quando auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # opzionale: limita i token di output
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# Parametri query URL (ad es. api-version per Azure)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Mappatura slot modello (opzionale)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Campo	Tipo	Predefinito	Descrizione
name	string	obbligatorio	Identificatore univoco del profilo
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" o "OpenAIResponses"
base_url	string	obbligatorio	URL dell’endpoint API del fornitore
api_key	string	""	Chiave API in testo in chiaro
api_key_keyring	string	—	Nome della voce nel portachiavi del SO (sovrascrive api_key)
default_model	string	obbligatorio	Identificatore del modello da usare per impostazione predefinita
auth_type	string	"api-key"	Metodo di autenticazione: "api-key" o "oauth"
oauth_provider	string	—	Nome del fornitore OAuth. Uno tra: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Nomi dei profili per il failover, provati in ordine
custom_headers	map	{}	Header HTTP aggiuntivi inviati con ogni richiesta
extra_env	map	{}	Variabili d’ambiente impostate all’avvio di Claude
priority	integer	100	Peso di priorita per il routing intelligente (maggiore = preferito)
enabled	boolean	true	Se questo profilo e attivo
max_tokens	integer	—	Limita i token di output massimi inviati al fornitore. Quando impostato, sovrascrive il max_tokens nelle richieste
strip_params	string/array	"auto"	Parametri da rimuovere dalle richieste. "auto" rileva gli endpoint noti; "none" invia tutto; array rimuove parametri specifici

Parametri query

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

Campo	Tipo	Descrizione
query_params	map	Coppie chiave-valore aggiunte come parametri query URL a ogni richiesta

Usato principalmente per Azure OpenAI (api-version), ma funziona con qualsiasi fornitore.

Mappatura slot modello

La tabella opzionale [profiles.models] mappa gli slot del selettore /model di Claude Code sui nomi dei modelli specifici del fornitore. Quando cambi modello in Claude Code (ad es. /model opus), Claudex traduce la richiesta sul modello mappato.

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

Campo	Tipo	Descrizione
haiku	string	Modello da usare quando Claude Code seleziona haiku
sonnet	string	Modello da usare quando Claude Code seleziona sonnet
opus	string	Modello da usare quando Claude Code seleziona opus

Consiglio

Se uno slot non e definito, viene usato default_model del profilo come fallback. Gli slot sono anche esposti come variabili d’ambiente: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Esempi di fornitori

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

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

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

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

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

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

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

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

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

# Azure OpenAI (OpenAICompatible — header 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 (locale, nessuna chiave API necessaria)
[[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 (locale)
[[profiles]]
name = "local-llama"
provider_type = "OpenAICompatible"
base_url = "http://localhost:8000/v1"
api_key = ""
default_model = "llama-3.3-70b"
enabled = false

Esempi di profili OAuth

# Claude Max (salta il proxy, usa OAuth nativo di Claude da ~/.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"

# Abbonamento 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 tramite 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 tramite 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 tramite 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 tramite 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 tramite 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"

Attenzione

Per il fornitore OAuth claude, Claudex salta il proxy e lascia che Claude Code usi il proprio OAuth direttamente. Per tutti gli altri fornitori OAuth, il proxy gestisce i token e il loro aggiornamento.

Router intelligente

[router]
enabled = false
profile = "local-qwen"    # riutilizza base_url + api_key di un profilo
model = "qwen2.5:3b"      # override modello (opzionale)

Campo	Tipo	Predefinito	Descrizione
enabled	boolean	false	Abilita il routing intelligente
profile	string	""	Nome del profilo da riutilizzare per la classificazione (usa il suo base_url + api_key)
model	string	""	Override del modello per la classificazione (predefinito: default_model del profilo)

Regole di routing

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

Chiave	Descrizione
code	Profilo per le attivita di codice
analysis	Profilo per l’analisi e il ragionamento
creative	Profilo per la scrittura creativa
search	Profilo per la ricerca e la consultazione
math	Profilo per la matematica e la logica
default	Fallback quando l’intento non e classificato

Motore di contesto

Compressione

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # riutilizza base_url + api_key di un profilo
model = "qwen2.5:3b"      # override modello (opzionale)

Campo	Tipo	Predefinito	Descrizione
enabled	boolean	false	Abilita la compressione delle conversazioni
threshold_tokens	integer	50000	Comprimi quando il conteggio dei token supera questo valore
keep_recent	integer	10	Mantieni sempre gli ultimi N messaggi non compressi
profile	string	""	Nome del profilo da riutilizzare per la riepilogazione
model	string	""	Override del modello per la riepilogazione

Condivisione tra profili

[context.sharing]
enabled = false
max_context_size = 2000

Campo	Tipo	Predefinito	Descrizione
enabled	boolean	false	Abilita la condivisione del contesto tra profili
max_context_size	integer	2000	Token massimi da iniettare da altri profili

RAG locale

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # riutilizza base_url + api_key di un profilo
model = "nomic-embed-text"           # modello di embedding
chunk_size = 512
top_k = 5

Campo	Tipo	Predefinito	Descrizione
enabled	boolean	false	Abilita il RAG locale
index_paths	string[]	[]	Directory da indicizzare
profile	string	""	Nome del profilo da riutilizzare per gli embedding
model	string	""	Nome del modello di embedding
chunk_size	integer	512	Dimensione del chunk di testo in token
top_k	integer	5	Numero di risultati da iniettare