Modelos, tokens y ventana de contexto

Modelos disponibles

Claude Code permite elegir entre distintos modelos de la familia Claude para cada sesión. Cada modelo ofrece un equilibrio diferente entre velocidad, coste y capacidad de razonamiento.

Los principales modelos disponibles son:

• Sonnet: modelo equilibrado entre velocidad y calidad. Es la opción por defecto y la más adecuada para la mayoría de tareas de desarrollo: edición de código, búsqueda de archivos, ejecución de comandos y generación de tests.

• Opus: modelo de mayor capacidad de razonamiento. Tarda más en responder y consume más tokens, pero produce resultados de mayor calidad en tareas que requieren razonamiento complejo, como refactorizaciones arquitectónicas, depuración de problemas sutiles o análisis de seguridad.

• Haiku: modelo rápido y económico, orientado a tareas de lectura y exploración. Claude Code lo utiliza internamente para subagentes como Explore, que analizan el código base sin realizar modificaciones. También se puede seleccionar de forma manual para consultas rápidas donde la velocidad es prioritaria frente a la profundidad.

La elección del modelo depende de la complejidad de la tarea. Sonnet cubre la gran mayoría de escenarios del día a día. Opus se reserva para tareas donde la profundidad de análisis justifica el coste y tiempo adicional. Haiku es útil para consultas rápidas y es el modelo que Claude Code asigna automáticamente a sus subagentes de exploración.

Cambiar de modelo

Existen varias formas de seleccionar el modelo:

• Durante una sesión: el comando /model abre un selector interactivo. También se puede pulsar Alt+P para cambiar de modelo sin borrar el prompt.

• Al iniciar sesión: el flag --model establece el modelo desde la línea de comandos:

claude --model opus

• En settings.json: la propiedad model fija el modelo por defecto para todas las sesiones:

{
  "model": "claude-sonnet-4-6"
}

• Variable de entorno: ANTHROPIC_MODEL permite establecer el modelo sin modificar archivos de configuración:

export ANTHROPIC_MODEL=opus

Los alias sonnet y opus apuntan siempre a la versión más reciente del modelo correspondiente. Para fijar una versión concreta, se utiliza el nombre completo (por ejemplo, claude-sonnet-4-6).

Modelo de respaldo

En modo print (-p), el flag --fallback-model permite definir un modelo alternativo que se usa automáticamente si el modelo principal está sobrecargado:

claude -p --fallback-model sonnet "analiza este archivo"

Restringir modelos disponibles

En entornos de equipo o empresariales, la propiedad availableModels en settings.json permite limitar qué modelos pueden seleccionar los usuarios:

{
  "availableModels": ["sonnet", "haiku"]
}

Esta restricción aplica al selector /model, al flag --model y a la variable de entorno ANTHROPIC_MODEL.

Tokens y ventana de contexto

Qué son los tokens

Los modelos de lenguaje no procesan texto directamente, sino que lo convierten en tokens: unidades de texto que pueden ser palabras completas, fragmentos de palabras o caracteres individuales. Como referencia aproximada, 1 token equivale a unas 3-4 letras en inglés.

Cada interacción con Claude Code consume tokens de dos formas:

• Tokens de entrada: el prompt del sistema, el contenido de CLAUDE.md, los mensajes de la conversación, los archivos leídos y las salidas de comandos que se acumulan en el contexto.
• Tokens de salida: la respuesta que genera Claude, incluyendo el razonamiento interno (extended thinking) y el texto visible.

La ventana de contexto

La ventana de contexto es la cantidad total de texto que el modelo puede manejar en una sola conversación. Claude Code trabaja con una ventana de 200.000 tokens (200K). Todo lo que ocurre en una sesión se acumula dentro de esta ventana:

• El prompt del sistema de Claude Code
• El contenido de los archivos CLAUDE.md
• Cada mensaje enviado por el usuario
• Cada respuesta de Claude
• El contenido de cada archivo leído
• La salida de cada comando ejecutado
• Los resultados de búsquedas y herramientas

flowchart LR
    A["Prompt sistema<br>+ CLAUDE.md"] --> B["Conversación"]
    B --> C["Archivos leídos"]
    C --> D["Salidas de comandos"]
    D --> E["200K tokens<br>(ventana de contexto)"]

La ventana de contexto se llena con rapidez. Una sola sesión de depuración o exploración de código puede consumir decenas de miles de tokens. A medida que la ventana se llena, la precisión y la capacidad de recordar instrucciones anteriores se degradan.

Monitorizar el uso de contexto

El comando /context dentro de una sesión muestra una cuadrícula visual del uso de la ventana de contexto. Permite ver de un vistazo cuánto espacio queda disponible.

El comando /cost muestra estadísticas de consumo de tokens de la sesión actual, incluyendo tokens de entrada, tokens de salida y el coste estimado.

Para un seguimiento continuo, se puede configurar una línea de estado personalizada en settings.json que muestre el porcentaje de contexto utilizado en todo momento:

{
  "statusLine": {
    "type": "command",
    "command": "echo \"Contexto: ${context_window.used_percentage}%\""
  }
}

Nivel de esfuerzo

Claude Code permite ajustar el nivel de esfuerzo del modelo, lo que controla la profundidad del razonamiento y el tiempo que dedica a pensar antes de responder. Existen tres niveles:

• low: respuestas rápidas con razonamiento mínimo. Adecuado para tareas simples como renombrar variables, añadir líneas de log o consultas de documentación.
• medium: nivel de razonamiento estándar. Cubre la mayoría de tareas de desarrollo habituales.
• high: razonamiento profundo y extendido. Recomendado para tareas complejas como refactorizaciones arquitectónicas, depuración de errores difíciles o análisis de seguridad.

El nivel de esfuerzo se puede ajustar de varias formas:

• Durante la sesión: dentro del selector /model, las flechas izquierda y derecha ajustan el nivel de esfuerzo.

• Variable de entorno: CLAUDE_CODE_EFFORT_LEVEL establece el nivel para la sesión:

export CLAUDE_CODE_EFFORT_LEVEL=high

• Atajo de teclado: Alt+T activa o desactiva el modo de pensamiento extendido (extended thinking), que equivale al nivel de esfuerzo alto.

Un nivel de esfuerzo más alto consume más tokens de salida y tarda más en responder, pero produce resultados más reflexivos y menos propensos a errores en tareas complejas.

Extended thinking

El pensamiento extendido (extended thinking) es un mecanismo que permite al modelo razonar internamente antes de producir una respuesta visible. Claude Code habilita extended thinking de forma predeterminada con un presupuesto de tokens asignado automáticamente.

La variable MAX_THINKING_TOKENS permite controlar el presupuesto de tokens de pensamiento:

export MAX_THINKING_TOKENS=10000

Para desactivar el pensamiento extendido por completo:

export MAX_THINKING_TOKENS=0

El ajuste alwaysThinkingEnabled en settings.json habilita el pensamiento extendido por defecto para todas las sesiones:

{
  "alwaysThinkingEnabled": true
}

Extended thinking no se muestra en la respuesta visible, pero se refleja en el consumo de tokens de salida. En tareas simples, desactivarlo reduce el coste sin afectar la calidad. En tareas complejas, activarlo mejora la precisión del razonamiento.

Gestión de costes

El consumo de tokens se traduce directamente en coste económico. Varias estrategias ayudan a mantener los costes bajo control:

Limitar el presupuesto

En modo print, el flag --max-budget-usd establece un tope de gasto en dólares:

claude -p --max-budget-usd 2.00 "genera tests para todo el proyecto"

Limitar los turnos

El flag --max-turns limita el número de ciclos de razonamiento y acción:

claude -p --max-turns 5 "refactoriza este módulo"

Prompt caching

Claude Code utiliza prompt caching por defecto, que permite reutilizar fragmentos de contexto entre turnos consecutivos y reduce significativamente el consumo de tokens de entrada. El prompt del sistema, CLAUDE.md y los mensajes anteriores de la conversación se almacenan en cache y no se reenvían completamente en cada turno.

El caching se puede desactivar de forma global o por modelo mediante variables de entorno:

export DISABLE_PROMPT_CACHING=1

Tokens de salida

La variable CLAUDE_CODE_MAX_OUTPUT_TOKENS controla el máximo de tokens por respuesta. El valor por defecto es 32.000 y el máximo es 64.000. Aumentar este valor reduce el espacio disponible antes de que la autocompactación se active:

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

Para la mayoría de tareas de desarrollo, el valor por defecto de 32.000 tokens de salida es más que suficiente. Reducirlo puede ahorrar costes en tareas que generan respuestas cortas.