Referencia de configuracion

Ubicacion del archivo de configuracion

Claudex usa configuracion por capas via figment. Las fuentes se combinan en este orden (las posteriores sobreescriben a las anteriores):

1. Valores por defecto programaticos
2. Configuracion global (~/.config/claudex/config.toml o .yaml)
3. Configuracion de proyecto (claudex.toml/.claudex/config.toml en el directorio actual o directorios padre, o $CLAUDEX_CONFIG)
4. Variables de entorno (prefijo CLAUDEX_, separador __)

Se soportan formatos TOML y YAML.

Consulta Configuracion para detalles de configuracion.

Ajustes globales

# Ruta al binario de claude (por defecto: "claude" del PATH)
claude_binary = "claude"

# Puerto de escucha del servidor proxy
proxy_port = 13456

# Direccion de enlace del servidor proxy
proxy_host = "127.0.0.1"

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

# Hipervinculos en terminal (OSC 8): "auto" | true | false
hyperlinks = "auto"

Campo	Tipo	Por defecto	Descripcion
claude_binary	string	"claude"	Ruta al binario de la CLI de Claude Code
proxy_port	entero	13456	Puerto en el que escucha el proxy de traduccion
proxy_host	string	"127.0.0.1"	Direccion a la que se enlaza el proxy
log_level	string	"info"	Nivel minimo de log
hyperlinks	string/bool	"auto"	Hipervinculos en terminal: "auto" (detectar), true (forzar activar), false (forzar desactivar)

Alias de modelos

Define nombres abreviados para identificadores de modelos:

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

Usa alias con -m:

claudex run grok -m grok3

Configuracion de perfiles

[[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" (por defecto) o "oauth"
# oauth_provider = "openai"        # requerido cuando auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # opcional: limitar tokens de salida
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# Parametros de consulta URL (por ejemplo, api-version de Azure)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Mapeo de slots de modelo (opcional)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Campo	Tipo	Por defecto	Descripcion
name	string	requerido	Identificador unico del perfil
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" u "OpenAIResponses"
base_url	string	requerido	URL del endpoint de la API del proveedor
api_key	string	""	Clave API en texto plano
api_key_keyring	string	—	Nombre de entrada en el llavero del SO (sobreescribe api_key)
default_model	string	requerido	Identificador del modelo a usar por defecto
auth_type	string	"api-key"	Metodo de autenticacion: "api-key" u "oauth"
oauth_provider	string	—	Nombre del proveedor OAuth. Uno de: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Nombres de perfiles para failover, probados en orden
custom_headers	mapa	{}	Cabeceras HTTP adicionales enviadas con cada solicitud
extra_env	mapa	{}	Variables de entorno establecidas al lanzar Claude
priority	entero	100	Peso de prioridad para el enrutamiento inteligente (mayor = preferido)
enabled	booleano	true	Si este perfil esta activo
max_tokens	entero	—	Limitar tokens de salida maximos enviados al proveedor. Cuando se establece, sobreescribe el max_tokens de las solicitudes
strip_params	string/array	"auto"	Parametros a eliminar de las solicitudes. "auto" detecta endpoints conocidos; "none" envia todo; array elimina parametros especificos

Parametros de consulta

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

Campo	Tipo	Descripcion
query_params	mapa	Pares clave-valor agregados como parametros de consulta URL a cada solicitud

Usado principalmente para Azure OpenAI (api-version), pero funciona con cualquier proveedor.

Mapeo de slots de modelo

La tabla opcional [profiles.models] mapea los slots del selector /model de Claude Code a nombres de modelos especificos del proveedor. Cuando cambias de modelo dentro de Claude Code (por ejemplo, /model opus), Claudex traduce la solicitud al modelo mapeado.

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

Campo	Tipo	Descripcion
haiku	string	Modelo a usar cuando Claude Code selecciona haiku
sonnet	string	Modelo a usar cuando Claude Code selecciona sonnet
opus	string	Modelo a usar cuando Claude Code selecciona opus

Consejo

Si un slot no esta definido, se usa el default_model del perfil como fallback. Los slots tambien se exponen como variables de entorno: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Ejemplos de proveedores

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

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

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

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

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

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

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

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

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

# Azure OpenAI (OpenAICompatible — cabecera 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, sin clave API)
[[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

Ejemplos de perfiles OAuth

# Claude Max (omite el proxy, usa OAuth nativo de Claude desde ~/.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"

# Suscripcion 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"

Precaución

Para el proveedor OAuth claude, Claudex omite el proxy y deja que Claude Code use su propio OAuth directamente. Para todos los demas proveedores OAuth, el proxy gestiona los tokens y su refresco.

Enrutador inteligente

[router]
enabled = false
profile = "local-qwen"    # reutilizar la base_url + api_key de un perfil
model = "qwen2.5:3b"      # sobreescribir modelo (opcional)

Campo	Tipo	Por defecto	Descripcion
enabled	booleano	false	Habilitar el enrutamiento inteligente
profile	string	""	Nombre del perfil a reutilizar para clasificacion (usa su base_url + api_key)
model	string	""	Sobreescritura del modelo para clasificacion (por defecto es el default_model del perfil)

Reglas de enrutamiento

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

Clave	Descripcion
code	Perfil para tareas de codigo
analysis	Perfil para analisis y razonamiento
creative	Perfil para escritura creativa
search	Perfil para busqueda e investigacion
math	Perfil para matematicas y logica
default	Respaldo cuando la intencion no esta clasificada

Motor de contexto

Compresion

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # reutilizar la base_url + api_key de un perfil
model = "qwen2.5:3b"      # sobreescribir modelo (opcional)

Campo	Tipo	Por defecto	Descripcion
enabled	booleano	false	Habilitar la compresion de conversaciones
threshold_tokens	entero	50000	Comprimir cuando el recuento de tokens supere esto
keep_recent	entero	10	Mantener siempre los ultimos N mensajes sin comprimir
profile	string	""	Nombre del perfil a reutilizar para la generacion de resumenes
model	string	""	Sobreescritura del modelo para la generacion de resumenes

Comparticion entre perfiles

[context.sharing]
enabled = false
max_context_size = 2000

Campo	Tipo	Por defecto	Descripcion
enabled	booleano	false	Habilitar la comparticion de contexto entre perfiles
max_context_size	entero	2000	Tokens maximos a inyectar desde otros perfiles

RAG local

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # reutilizar la base_url + api_key de un perfil
model = "nomic-embed-text"           # modelo de embedding
chunk_size = 512
top_k = 5

Campo	Tipo	Por defecto	Descripcion
enabled	booleano	false	Habilitar RAG local
index_paths	string[]	[]	Directorios a indexar
profile	string	""	Nombre del perfil a reutilizar para embeddings
model	string	""	Nombre del modelo de embedding
chunk_size	entero	512	Tamano del fragmento de texto en tokens
top_k	entero	5	Numero de resultados a inyectar