Configuracion

Descubrimiento de archivos de configuracion

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

Valores por defecto programaticos (fallbacks integrados)
Configuracion global (~/.config/claudex/config.toml o config.yaml)
Configuracion de proyecto (claudex.toml o claudex.yaml en el directorio actual o directorios padre hasta 10 niveles, o $CLAUDEX_CONFIG)
Variables de entorno (prefijo CLAUDEX_, separador __)

Se soportan formatos TOML y YAML. El formato se detecta por la extension (.toml o .yaml/.yml).

# Mostrar la ruta de configuracion cargada y todas las ubicaciones de busqueda
claudex config show

# Mostrar solo la ruta del archivo de configuracion
claudex config path

# Crear una nueva configuracion en el directorio actual
claudex config init

# Recrear la configuracion desde config.example.toml
claudex config recreate

# Abrir la configuracion en tu $EDITOR
claudex config edit

# Validar la sintaxis de configuracion y las referencias de perfiles
claudex config validate

# Obtener un valor especifico de configuracion
claudex config get proxy_port

# Establecer un valor especifico de configuracion
claudex config set proxy_port 8080

# Exportar la configuracion actual a stdout
claudex config export

Ajustes globales

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

# Ajustes del proxy
proxy_port = 13456
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
# "auto" detecta el soporte del terminal; true/false fuerzan activar/desactivar
hyperlinks = "auto"

# Alias de modelos (abreviatura → nombre completo del modelo)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Perfiles

Cada perfil representa una conexion a un proveedor de IA. Hay tres tipos de proveedor:

DirectAnthropic

Para proveedores que soportan nativamente la API de Mensajes de Anthropic. Las solicitudes se reenvian con modificaciones minimas.

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

Proveedores compatibles: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Para proveedores que usan la API de Chat Completions de OpenAI. Claudex traduce automaticamente entre los protocolos Anthropic y 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

Proveedores 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

Para proveedores que usan la API de Responses de OpenAI (por ejemplo, suscripciones ChatGPT/Codex). Claudex traduce entre la API de Mensajes de Anthropic y la API de Responses de OpenAI.

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

Proveedores compatibles: suscripciones ChatGPT/Codex (via Codex CLI)

Campos de perfil

Campo	Valor por defecto	Descripcion
`name`	requerido	Identificador unico del perfil
`provider_type`	`DirectAnthropic`	`DirectAnthropic`, `OpenAICompatible` u `OpenAIResponses`
`base_url`	requerido	Endpoint de la API del proveedor
`api_key`	`""`	Clave API (texto plano)
`api_key_keyring`	—	Leer la clave API del llavero del SO
`default_model`	requerido	Modelo a usar por defecto
`auth_type`	`"api-key"`	`"api-key"` u `"oauth"`
`oauth_provider`	—	Proveedor OAuth (`claude`, `openai`, `google`, `qwen`, `kimi`, `github`, `gitlab`). Requerido cuando `auth_type = "oauth"`
`backup_providers`	`[]`	Nombres de perfiles de failover
`custom_headers`	`{}`	Cabeceras HTTP adicionales
`extra_env`	`{}`	Variables de entorno adicionales para Claude
`priority`	`100`	Prioridad para enrutamiento inteligente
`enabled`	`true`	Si el perfil esta activo
`max_tokens`	—	Limitar los tokens de salida maximos enviados al proveedor (opcional)
`strip_params`	`"auto"`	`"auto"`, `"none"` o `["temperature", "top_p"]`. Detecta automaticamente parametros no soportados (por ejemplo, endpoint ChatGPT Codex)
`[profiles.query_params]`	`{}`	Parametros de consulta URL (por ejemplo, `api-version` de Azure)
`[profiles.models]`	—	Tabla de mapeo de slots de modelo (campos `haiku`, `sonnet`, `opus`)

Configuracion interactiva

La forma mas facil de agregar un perfil es el asistente interactivo:

claudex profile add

Te guia a traves de la seleccion del proveedor, entrada de clave API (con almacenamiento opcional en el llavero), seleccion de modelo y prueba de conectividad.

Integracion con llavero

Almacena las claves API de forma segura en el llavero de tu SO en lugar de texto plano en la configuracion:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # lee del llavero del SO

Backends soportados:

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

Autenticacion OAuth por suscripcion

En lugar de claves API, puedes autenticarte con tu suscripcion existente del proveedor via OAuth. Esto es util si tienes un plan Claude Pro/Team, ChatGPT Plus u otra suscripcion.

Configuracion

Establece el auth_type del perfil como "oauth" y especifica el 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"

Inicia sesion con el comando auth:

claudex auth login openai

Verifica el estado de autenticacion:

claudex auth status

Proveedores soportados

Proveedor	`oauth_provider`	Fuente del token
Claude	`claude`	Lee de `~/.claude/.credentials.json` (configuracion nativa de Claude Code)
ChatGPT	`openai`	PKCE en navegador o Device Code, con fallback a `~/.codex/auth.json` (Codex CLI)
Google	`google`	Lee de las credenciales de Gemini CLI
Qwen	`qwen`	Flujo Device Code
Kimi	`kimi`	Lee de las credenciales de Kimi CLI
GitHub	`github`	Flujo Device Code, con fallback a `~/.config/github-copilot/`
GitLab	`gitlab`	Variable de entorno `GITLAB_TOKEN`

Para detalles sobre el flujo OAuth de cada proveedor, consulta Suscripciones OAuth.

Modo Gateway Auth

Al usar perfiles OAuth, Claudex establece ANTHROPIC_AUTH_TOKEN (y no ANTHROPIC_API_KEY) al lanzar Claude Code. Esto previene conflictos con el mecanismo de inicio de sesion por suscripcion propio de Claude Code, que usa ANTHROPIC_API_KEY internamente.

El proxy refresca automaticamente los tokens OAuth antes de que expiren. Tambien puedes refrescar manualmente con:

claudex auth refresh openai

Parametros de consulta

Algunos proveedores requieren parametros de consulta en la URL (por ejemplo, api-version de Azure OpenAI). Usa la tabla [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 agrega estos parametros a cada URL de solicitud del perfil. Azure OpenAI se detecta automaticamente por base_url que contenga openai.azure.com y usa la cabecera api-key para autenticacion en lugar de Authorization: Bearer.

Eliminacion de parametros

Algunos proveedores no soportan ciertos parametros (por ejemplo, el endpoint ChatGPT Codex rechaza temperature, top_p). El campo strip_params controla que parametros se eliminan antes de enviar:

strip_params = "auto"       # detectar y eliminar automaticamente parametros no soportados (por defecto)
strip_params = "none"       # enviar todos los parametros tal cual
strip_params = ["temperature", "top_p", "top_k"]  # eliminar parametros especificos

Cuando se establece en "auto", Claudex detecta endpoints conocidos (por ejemplo, chatgpt.com) y elimina parametros que causarian errores.

Mapeo de slots de modelo

Claude Code tiene un selector /model integrado con tres slots: haiku, sonnet y opus. Consulta Mapeo de slots de modelo para mas detalles.

Compatibilidad de nombres de herramientas

Algunos proveedores (notablemente OpenAI) imponen un limite de 64 caracteres en los nombres de herramientas (funciones). Claude Code puede generar nombres de herramientas que exceden este limite.

Claudex trunca automaticamente los nombres de herramientas que superan 64 caracteres al enviar solicitudes a proveedores compatibles con OpenAI y restaura transparentemente los nombres originales al procesar las respuestas. Este viaje de ida y vuelta es completamente transparente.

Modo no interactivo

Claudex soporta ejecucion de un solo uso (no interactiva) para pipelines CI/CD, scripts y automatizacion:

# Imprimir respuesta y salir
claudex run grok "Explain this codebase" --print

# Omitir todas las solicitudes de permisos (para pipelines completamente automatizados)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

En modo no interactivo, los logs se escriben en archivos de log por instancia en ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log en lugar de stderr, manteniendo la salida stdout limpia para redireccion y automatizacion.

Hipervinculos en terminal

Claudex soporta hipervinculos clicables OSC 8 en la salida del terminal. Consulta Hipervinculos en terminal para mas detalles.

# "auto" detecta el soporte del terminal; true/false fuerzan activar/desactivar
hyperlinks = "auto"

Conjuntos de configuracion

Instala paquetes reutilizables de reglas, habilidades y servidores MCP. Consulta Conjuntos de configuracion para mas detalles.

claudex sets add ./my-set
claudex sets list

Ejemplo completo

Consulta config.example.toml para un archivo de configuracion completo con todos los proveedores y opciones.

Para instrucciones paso a paso de configuracion de cada proveedor (incluyendo enlaces de claves API y flujos OAuth), consulta la Guia de configuracion de proveedores.