Claude Code: settings.json y variables de entorno: URL base, token de autenticación y modelo

Claude Code obtiene su configuración de archivos JSON y variables de entorno. Para usarlo a través de una puerta de enlace en lugar de la API de Anthropic, necesitas dos variables, ANTHROPIC_BASE_URL y un token, y normalmente también un modelo. Las variables son sencillas. Lo que confunde a la gente es dónde ponerlas, porque una misma variable puede estar en el perfil del shell, en varios archivos settings.json y en la configuración de VS Code.

Esta guía empieza con una configuración que funciona y luego explica dónde están los archivos, qué valor tiene prioridad y qué errores es probable que aparezcan. Se verificó con la documentación de Anthropic y se probó con AIHubMix en Claude Code 2.1.304 el 20 de octubre de 2026. Los ejemplos usan AIHubMix como puerta de enlace; cualquier endpoint compatible con Anthropic se configura del mismo modo.

En resumen

• Tu archivo de configuración personal es ~/.claude/settings.json o, en Windows, %USERPROFILE%\.claude\settings.json.
• Para una puerta de enlace, añade ANTHROPIC_BASE_URL (sin /v1) y ANTHROPIC_AUTH_TOKEN al bloque env de ese archivo.
• Un valor en el bloque env de un archivo de configuración prevalece sobre la misma variable exportada en el shell.
• Una vez configurado un token, las solicitudes dejan de usar tu suscripción a Claude y la puerta de enlace te las factura.
• La extensión de VS Code necesita las mismas variables en su propia opción claudeCode.environmentVariables.

Una configuración funcional de AIHubMix

1. Crea una clave en la consola de AIHubMix.
2. Añade esto a ~/.claude/settings.json. Crea el archivo si no existe.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

3. Haz una prueba rápida:

claude -p "1+1, output only the answer"

4. Inicia claude en un proyecto. El encabezado debajo del logotipo debería mostrar algo como Sonnet 5.5 · API Usage Billing, y /status muestra tu puerta de enlace en la línea Anthropic base URL.

Hay dos detalles importantes. La URL base es la dirección raíz: Claude Code añade /v1/messages, así que una URL que termine en /v1 hace que fallen todas las solicitudes. Además, AIHubMix usa los propios ID de modelo de Anthropic, como claude-sonnet-5-5, por lo que los accesos directos sonnet, opus y haiku funcionan sin configuración adicional.

La línea $schema es opcional. Permite que VS Code, Cursor y otros editores detecten errores en el archivo mientras escribes.

También puedes exportar las mismas dos variables en el shell, pero es mejor guardarlas en un archivo de configuración: todos los terminales, las extensiones del IDE y los agentes en segundo plano lo leen.

Dónde están los archivos de configuración

Nunca pongas un token en el archivo del proyecto .claude/settings.json, ya que se incluye en git. Usa tu archivo de usuario o .claude/settings.local.json.

Los archivos de configuración deben ser JSON válido. Un comentario // o una coma final hace que Claude Code ignore todo el archivo, incluido el token, y verás la pantalla de inicio de sesión en vez de tu puerta de enlace.

No los confundas con ~/.claude.json, un único archivo en tu carpeta personal. Ese archivo guarda el estado propio de Claude Code, como tu inicio de sesión y los servidores MCP, y rara vez necesitas editarlo.

Qué valor tiene prioridad

Cuando varios archivos definen lo mismo, se aplica la prioridad de configuración de Anthropic, en orden descendente:

1. Configuración administrada por tu organización
2. --settings en la línea de comandos, solo para esa sesión
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

Para las variables de entorno, hay una regla más: una variable del bloque env de un archivo de configuración reemplaza la misma variable del shell. Así que un export ANTHROPIC_BASE_URL=... en ~/.zshrc no hace nada si un archivo de configuración también la define. Las herramientas para cambiar de proveedor suelen escribir en ~/.claude/settings.json, por eso tienen prioridad sobre el shell.

Dentro de Claude Code, /status muestra los archivos que cargó en la línea Setting sources.

ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY

Usa la que lea tu puerta de enlace. AIHubMix acepta ambas, y su guía de Claude Code usa ANTHROPIC_AUTH_TOKEN, que también es la opción más sencilla. No dejes las dos configuradas. En ese caso, Claude Code envía ambos encabezados y AIHubMix comprueba primero x-api-key: en nuestra prueba, un token correcto en settings.json igualmente produjo un error 401 porque se había exportado una ANTHROPIC_API_KEY antigua en el shell. El bloque env solo reemplaza las variables que define, así que elimina la clave antigua del perfil del shell al cambiar.

¿Y tu suscripción a Claude? Según la guía de Anthropic sobre puertas de enlace, cuando se configura una variable de token o de clave de API, las solicitudes la usan en vez de tu inicio de sesión de claude.ai, y la puerta de enlace factura por token. Tu inicio de sesión sigue guardado y vuelve a usarse cuando eliminas la variable. Si solo configuras ANTHROPIC_BASE_URL, sin token, sigues usando tu suscripción.

Cómo elegir el modelo

La página de Anthropic sobre configuración de modelos establece este orden, de mayor a menor prioridad:

1. /model <name> durante una sesión
2. claude --model <name> al iniciar
3. La variable ANTHROPIC_MODEL
4. La clave model de un archivo de configuración

/model guarda tu elección como el nuevo valor predeterminado. Sin embargo, si ANTHROPIC_MODEL está configurada, cada sesión nueva vuelve a iniciarse con ese modelo. Si cambias de modelo con frecuencia, configura la clave model y deja sin definir ANTHROPIC_MODEL. Si no se especifica ningún modelo en ningún sitio, Claude Code usa Opus 5.5.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL y ANTHROPIC_DEFAULT_HAIKU_MODEL cambian el modelo al que apunta cada acceso directo. Solo las necesitas si quieres que un acceso directo apunte a otro modelo, por ejemplo, para mantener sonnet en una versión anterior.

AIHubMix también ofrece modelos de otros proveedores en la misma dirección, pero Anthropic no admite Claude Code con modelos que no sean de Claude, así que algunas funciones podrían no funcionar con ellos.

Cuándo surten efecto los cambios

Claude Code supervisa sus archivos de configuración, y la mayoría de los cambios guardados, incluido el bloque env, se aplican a la sesión en curso. La clave model, las variables eliminadas y las exportaciones del shell requieren reiniciar. Si tienes dudas, reinicia Claude Code.

La extensión de VS Code

La extensión lee los mismos archivos de configuración, pero comprueba si has iniciado sesión antes de arrancar, mediante su propia opción claudeCode.environmentVariables. Por eso VS Code puede pedirte que inicies sesión aunque la CLI funcione. Abre Preferences: Open User Settings (JSON) desde la paleta de comandos y añade:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
  ]
}

Después ejecuta Developer: Reload Window. Encontrarás más opciones en la documentación de VS Code de Anthropic. La aplicación Claude Desktop es independiente: no lee ni settings.json ni estas variables.

Otras variables útiles

Puedes añadirlas todas al bloque env. Encontrarás la lista completa en la referencia de variables de entorno de Anthropic.

Errores comunes y qué significan

Not logged in · Please run /login, o aparece la pantalla de inicio de sesión al iniciar por primera vez
Claude Code no encontró ningún token. Comprueba tres cosas: un error de JSON que hizo que ignorara el archivo, la ausencia de ANTHROPIC_AUTH_TOKEN o que el token solo esté en un archivo del proyecto. El paso de inicio de sesión se ejecuta antes de que se cargue la configuración del proyecto, así que mueve el token a ~/.claude/settings.json.

Invalid or malformed JSON
El archivo mencionado en el mensaje contiene un comentario, una coma final u otro error de sintaxis, por lo que no se aplicó ninguna de sus opciones.

There's an issue with the selected model (...)
El ID del modelo es incorrecto o la URL base termina en /v1 y la solicitud se envió a /v1/v1/messages. Si el ID del modelo parece correcto, comprueba primero la URL.

API Error: 400 con This model ID is incorrect
AIHubMix no tiene ningún modelo con ese ID, y el mensaje repite el ID recibido. Normalmente se trata de un error tipográfico. Vuelve a copiar el ID de la lista de modelos de AIHubMix.

Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix no acepta la clave. El mensaje termina con los últimos seis caracteres de la clave que recibió, así que compáralos con el final de tu token. PI_KEY significa que pegaste el marcador de posición AIHUBMIX_API_KEY en vez de una clave real. Cualquier otro valor suele indicar que se envió una ANTHROPIC_API_KEY antigua del shell. Si en cambio el mensaje dice this key is not enabled, comprueba en la consola de AIHubMix que la clave esté habilitada y tenga crédito.

auth may not work as expected
Hay una variable de token y un inicio de sesión guardado de claude.ai activos a la vez. Ejecuta /logout para seguir usando la puerta de enlace o elimina la variable para volver a tu suscripción.

Claude Code doesn't recognize the model ...
Es una advertencia, no un error: la solicitud se envía de todos modos, pero Claude Code presupone una ventana de contexto de 200K tokens. Si el ID corresponde a un modelo Claude más reciente, claude update lo soluciona.

Parece quedarse colgado con una clave incorrecta
Claude Code reintenta las solicitudes fallidas hasta 10 veces. En una prueba con una clave que siempre fallaba, claude -p siguió reintentando durante unos tres minutos. Reduce CLAUDE_CODE_MAX_RETRIES para ver el error antes.

Si quieres usar una sola clave para Claude en Claude Code y para OpenAI, Google y otros proveedores en tus demás herramientas, AIHubMix ofrece la API de Anthropic en https://aihubmix.com. El archivo de configuración de arriba es todo lo que necesita Claude Code.

Preguntas frecuentes

¿Dónde está el archivo settings.json de Claude Code?
Tu archivo personal es ~/.claude/settings.json o, en Windows, %USERPROFILE%.claude\settings.json. Un proyecto también puede tener .claude/settings.json, compartido mediante git, y .claude/settings.local.json, que solo es tuyo. Claude Code no los crea durante la instalación.

¿settings.json prevalece sobre las variables de entorno?
Sí. Un valor en el bloque env de un archivo de configuración sobrescribe la misma variable exportada en el shell. Las variables que el archivo no establece, como una ANTHROPIC_API_KEY antigua, siguen tomando su valor del shell.

¿Debería usar ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY?
Usa la que lea tu gateway. ANTHROPIC_AUTH_TOKEN envía un token Bearer y no requiere aprobación. Para AIHubMix, ANTHROPIC_AUTH_TOKEN es la opción documentada. No configures ambas: AIHubMix lee primero x-api-key, así que una ANTHROPIC_API_KEY obsoleta provoca un error 401.

¿ANTHROPIC_BASE_URL debería terminar en /v1?
No. Claude Code añade /v1/messages por su cuenta. Para AIHubMix, usa https://aihubmix.com.

¿Tengo que reiniciar Claude Code después de editar settings.json?
La mayoría de los cambios, incluidos los de env, se aplican al guardar. La clave del modelo y las exportaciones del shell requieren reiniciar. Reiniciar es la opción más segura.

¿Por qué VS Code me pide iniciar sesión si la CLI funciona?
Antes de iniciarse, la extensión comprueba si hay una sesión iniciada mediante su configuración claudeCode.environmentVariables, y los valores de ~/.claude/settings.json no llegan a esa comprobación. Añade allí la URL base y el token, y vuelve a cargar la ventana.

¿Configurar ANTHROPIC_BASE_URL utiliza mi suscripción a Claude?
Solo si no se configura ningún token. Si ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY está configurado, las solicitudes usan esa clave y el gateway factura por token.

Fuentes

• Archivos de configuración y precedencia, Anthropic
• Variables de entorno, Anthropic
• Conectar Claude Code a un gateway de LLM, Anthropic
• Configuración del modelo, Anthropic
• Guía de integración de Claude Code, AIHubMix