Cómo Reducir Costos de Tokens de Agentes Desde la CLI (Guía 2026)

Un agente de codificación CLI se siente libre hasta que llega la factura. Apuntas Claude Code o Codex a un repositorio, le pides que refactorice un módulo, y diez minutos después ha leído cuarenta archivos, ejecutado la suite de pruebas tres veces y quemado seis cifras de tokens en contexto que nunca necesitaste que viera. Multiplica eso por un equipo de ocho ingenieros ejecutando agentes todo el día, y la factura deja de ser un error de redondeo. El gasto de tokens en agentes de codificación es en su mayoría un desperdicio, y la mayor parte de ese desperdicio es corregible desde la línea de comandos sin cambiar modelos ni aceptar una peor salida.

En resumen

Reduce los costos de tokens del agente recortando el contexto antes de que llegue al modelo: delimita el conjunto de trabajo, mantén los archivos de memoria cortos y compacta las sesiones largas. Activa el almacenamiento en caché de prompts para prefijos estables (aproximadamente un 90% de descuento en lecturas repetidas). Dirige las subtareas baratas a un modelo pequeño. Limita la salida de la herramienta. Mide el costo por ejecución para saber qué cambió realmente.

Introducción

El problema se manifiesta de dos maneras. O te encuentras con un muro a mitad de tarea porque superaste un límite semanal o de sesión, o llega la factura mensual de la API y alguien pregunta por qué un “asistente de IA” cuesta más que un contratista junior. Ambos provienen de la misma causa raíz: los agentes CLI son "tragones" de tokens por defecto. Leen archivos enteros cuando necesitan diez líneas, reproducen la conversación completa en cada turno, vuelcan la salida bruta de comandos al contexto y reenvían el mismo prompt del sistema y mapa del repositorio miles de veces al día.

Nada de eso es inherente al trabajo. Una refactorización que realmente necesita razonar sobre 2.000 tokens de código no necesita 180.000 tokens de contexto para hacerlo. La brecha entre esos dos números es tu ahorro, y casi todo es recuperable con banderas, archivos de configuración y hábitos que puedes adoptar hoy.

Esta guía explica dónde van realmente los tokens en una ejecución de agente CLI, y luego te ofrece tácticas concretas para reducir cada categoría: higiene del contexto y archivos de memoria, almacenamiento en caché de prompts, enrutamiento de modelos, recorte de la salida y recuperación de herramientas, y medición del costo por ejecución para que los ahorros sean reales y no una suposición. Los ejemplos asumen Claude Code y Codex, pero la mecánica se aplica a cualquier agente que se comunique con una API facturada por tokens.

Un costo adyacente que vale la pena mencionar temprano: gran parte del gasto de tokens del agente es en depuración. Un agente que llama a una API interna inestable reintentará, leerá cuerpos de error, releerá documentos y hará bucles, pagando en tokens el costo total en cada iteración.

Dónde van realmente los tokens en una ejecución de agente CLI

Antes de optimizar, necesitas un modelo mental de la factura. Un solo "turno" del agente envía una carga útil de entrada al modelo y recibe una carga útil de salida. Pagas por ambas, y en la mayoría de los proveedores, la salida cuesta de tres a seis veces más por token que la entrada. Para una familia de modelos de frontera a mediados de 2026, la entrada ronda los $3 por millón de tokens y la salida alrededor de $15; un modelo más barato de la misma familia es aproximadamente $1 de entrada y $5 de salida. Tómalos como ejemplos, no como cotizaciones; consulta las páginas de precios en vivo, porque los proveedores los revisan. El punto estructural se mantiene independientemente de los números exactos: la salida es cara, y el volumen de entrada es lo que se dispara.

Aquí tienes lo que llena la carga útil de entrada en una ejecución típica:

• Prompt del sistema y definiciones de herramientas. Las instrucciones del agente más el esquema JSON de cada herramienta. Fijo por turno, a menudo de 5.000 a 15.000 tokens, reenviado en cada turno.
• Archivos de memoria y de proyecto. Cosas como CLAUDE.md, convenciones del repositorio e instrucciones persistentes. Cargados en cada turno, sean relevantes o no.
• Historial de conversación. Cada mensaje de usuario anterior, respuesta del modelo, llamada a herramienta y resultado de herramienta, reproducido en su totalidad en cada turno. Esto crece sin límite y suele ser el elemento más grande en una sesión larga.
• Contenido de archivo recuperado. Archivos que el agente leyó. Una sola lectura (Read) en un archivo de 1.200 líneas es aproximadamente de 12.000 a 18.000 tokens, y a los agentes les encanta leer archivos completos.
• Salida de la herramienta. Registros del ejecutor de pruebas, ruido de npm install, git diff de un archivo de bloqueo generado, rastreos de pila. Bruto y verboso por defecto.

La carga útil de salida es el razonamiento del modelo, las ediciones de código y las explicaciones. Más pequeña que la entrada en la mayoría de las ejecuciones, pero con el precio más alto por token, por lo que un comportamiento verboso como "déjame explicar mi plan en seis párrafos" es costoso.

El hecho más importante: el historial de conversación se reproduce en cada turno. Una sesión de 30 turnos no cuesta 30 veces un turno. Está más cerca de la suma de un prefijo creciente, por lo que los turnos posteriores cargan con el peso total de todo lo anterior. Por eso, una sesión larga y sin rumbo es lo más caro que puedes hacer, y por qué las tácticas a continuación se centran desproporcionadamente en el contexto que se reenvía.

Si deseas una visión más profunda de cómo funciona la contabilidad de sesiones y límites en la práctica, el desglose en cómo se restablece la ventana de tokens de Claude Code es un compañero útil para esta sección; explica por qué una sesión que “parece corta” aún puede agotar un presupuesto.

Higiene del contexto y archivos de memoria

El token más barato es el que nunca envías. La higiene del contexto es el hábito de mayor impacto porque reduce la carga útil de entrada en cada turno durante el resto de la sesión.

Delimita el conjunto de trabajo antes de empezar. No abras un agente en la raíz del repositorio y digas “refactoriza la lógica de facturación”. Se arrastrará. En su lugar, dile exactamente qué archivos importan:

# En lugar de un prompt vago que desencadena una exploración amplia:
claude "refactor the retry logic so it uses exponential backoff,
only in src/payments/retry.ts and its test file"

Nombrar los archivos evita que el agente lea veinte candidatos para encontrar los dos que importan. Si debes permitirle explorar, apúntalo a un directorio, no a la raíz.

Mantén los archivos de memoria cortos y estables. Un CLAUDE.md (o archivo de memoria de proyecto equivalente) se carga en el contexto en cada turno. Los equipos lo tratan como una wiki y dejan que crezca hasta 4.000 tokens de prosa de incorporación. A, digamos, 50 turnos al día entre 8 ingenieros, un archivo de memoria inflado se reenvía cientos de veces al día sin ningún beneficio marginal. Audítalo:

# Comprobación aproximada de tokens en tu archivo de memoria (caracteres / 4 es una estimación decente):
wc -c CLAUDE.md | awk '{print "≈", int($1/4), "tokens per turn"}'

Busca un archivo conciso: comandos de compilación/prueba, convenciones estrictas y punteros a donde se encuentran los documentos más profundos, no los documentos en sí. Si una sección solo es relevante para una tarea al mes, no debe estar en el archivo siempre cargado. Muévelo a un documento que el agente lea bajo demanda.

Compacta o reinicia sesiones largas. Cuando una sesión ha cumplido su propósito y te mueves a una tarea no relacionada, no sigas escribiendo en el mismo contexto. Cada nuevo turno ahora arrastra toda la transcripción antigua. Usa el comando de compactación o limpieza del agente:

# En Claude Code, cuando la conversación se alarga:
/compact     # resume el historial en un breve resumen, elimina la transcripción original
# o, para un corte limpio en una nueva tarea:
/clear       # empieza de nuevo; el contexto antiguo ya no se reenvía

/compact típicamente reemplaza decenas de miles de tokens de historial bruto con un resumen de una décima parte del tamaño, y ese prefijo más pequeño es lo que lleva cada turno subsiguiente. La disciplina es simple: una tarea lógica por sesión, compactar o limpiar entre tareas. Los patrones de flujo de trabajo en flujos de trabajo de Claude Code se apoyan en gran medida en este hábito de delimitación, y vale la pena adoptarlo por completo.

Usa un archivo de exclusión del proyecto. Mantén los artefactos generados, archivos de bloqueo, salida de compilación y dependencias vendoreadas fuera del alcance del agente. Si el agente nunca ve dist/ o node_modules/, nunca gastará tokens leyéndolos o comparándolos. La mayoría de los agentes respetan un archivo de exclusión; configúralo una vez y los ahorros serán permanentes.

Almacenamiento en caché de prompts: deja de pagar el precio completo por el mismo prefijo

Esta es la palanca más grande para las ejecuciones repetidas, y es mecánica en lugar de conductual. El almacenamiento en caché de prompts permite al proveedor almacenar un prefijo de tu solicitud (herramientas, prompt del sistema, contexto estable) para que las solicitudes subsiguientes que compartan ese prefijo lo lean con un gran descuento en lugar de reprocesarlo.

La economía, según la documentación de almacenamiento en caché de prompts de Anthropic: una escritura en caché cuesta más que un token de entrada normal (aproximadamente 1.25x la entrada base para la caché predeterminada de 5 minutos, aproximadamente 2x para una caché de 1 hora), pero una lectura de caché cuesta aproximadamente 0.1x la entrada base; eso es aproximadamente un 90% de descuento en la porción almacenada en caché. Debido a que la prima de escritura es pequeña y el descuento de lectura es grande, el almacenamiento en caché se amortiza después de un solo acierto en la caché de corta duración, y después de unos dos aciertos en la de larga duración. La vida útil predeterminada de la caché es corta (alrededor de 5 minutos, se actualiza cada vez que se acierta), con una opción de 1 hora disponible. Existe un tamaño mínimo almacenable en caché; los modelos pequeños y los modelos más grandes necesitan unos pocos miles de tokens antes de que un prefijo sea elegible, por lo que el almacenamiento en caché ayuda más exactamente donde importa: prefijos estables grandes.

La regla estructural es colocar el contenido estable primero y el contenido volátil al final, y luego almacenar en caché el límite. El orden es herramientas → sistema → mensajes, y cambiar cualquier cosa invalida ese nivel y todo lo que le sigue. Por lo tanto, quieres que las marcas de tiempo, el mensaje entrante del usuario y el contenido de archivo recién recuperado vengan después de tu punto de interrupción de caché, no antes.

Si diriges un modelo directamente desde tu propio wrapper CLI, lo configuras explícitamente:

# Almacena en caché el prefijo estable (sistema + definiciones de herramientas + convenciones del repositorio).
# El turno volátil del usuario viene después y NO forma parte del prefijo almacenado en caché.
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,   # estable en todas las ejecuciones
            "cache_control": {"type": "ephemeral"},       # punto de interrupción de caché aquí
        }
    ],
    messages=[{"role": "user", "content": user_task}],     # cambia en cada ejecución
)

# Inspecciona lo que realmente se almacenó en caché:
u = response.usage
print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)   # estos tokens se facturan al ~10%
print("fresh input:", u.input_tokens)

Un agente de refactorización diario que ejecuta el mismo prompt del sistema y el mismo bloque de convenciones del repositorio de 8.000 tokens en 60 invocaciones al día es el caso de estudio. Sin caché, pagas el precio de entrada completo por ese bloque de 8.000 tokens 60 veces. Con caché, pagas la prima de escritura una vez (o una vez por caducidad de caché) y el precio de lectura de aproximadamente el 10% las otras veces. Solo en el bloque de convenciones, eso es casi una reducción del 90%, y se acumula con todas las demás tácticas aquí.

Dos notas operativas. Primero, mantén tu prefijo byte-estable; un solo carácter cambiado antes del punto de interrupción rompe la caché y pagas una escritura de nuevo. Fija tu prompt del sistema y tus convenciones; no interpoles una marca de tiempo en ellos. Segundo, la caché tiene una vida útil corta por defecto, por lo que agrupar las ejecuciones relacionadas (en lugar de dispersarlas a lo largo del día) te permite acceder a una caché "caliente". La API de OpenAI aplica un descuento similar a la entrada en caché automáticamente en los modelos compatibles; el principio es idéntico aunque los controles difieran. Los trucos de nivel gratuito y enrutamiento en ejecutar GPT-5.5 gratis a través de Codex son un complemento útil cuando el almacenamiento en caché por sí solo no es suficiente.

Enrutamiento de modelos: modelo barato para trabajo barato

No toda acción del agente necesita un modelo de frontera. Renombrar una variable en tres archivos, escribir un mensaje de commit, resumir un diff o generar una prueba boilerplate no requiere el mismo modelo que diseña una arquitectura. Sin embargo, el comportamiento predeterminado de la mayoría de los agentes CLI es ejecutar todo a través de un modelo costoso durante toda la sesión.

El enrutamiento significa enviar deliberadamente subtareas de bajo riesgo a un modelo más pequeño y barato, y reservar el costoso para el razonamiento genuino. La brecha de precios es grande: un modelo pequeño en una familia determinada puede ser de tres a cinco veces más barato por token que el modelo insignia, y para tareas mecánicas, la diferencia en la calidad de la salida es insignificante.

Formas prácticas de enrutar desde la CLI:

# 1. Elige el modelo por invocación según la tarea.
claude --model haiku   "write a conventional-commit message for the staged diff"
claude --model sonnet  "redesign the caching layer for the payments service"

# 2. Usa un modelo barato para el bucle de alta frecuencia y bajo riesgo
#    (mensajes de commit, entradas de changelog, explicaciones rápidas de lint)
#    y un modelo potente solo cuando invoques explícitamente la tarea difícil.

Establece el modelo más barato como predeterminado y escala conscientemente, en lugar de predeterminar el modelo caro y nunca reducirlo. La mayoría de los equipos tienen la polaridad invertida: ejecutan el modelo insignia para todo “para estar seguros” y pagan cinco veces más por los mensajes de commit.

Un segundo eje de enrutamiento son los sub-agentes. Si tu framework de agente permite delegar una subtarea específica a un agente hijo, dale a ese hijo un modelo barato y un contexto minúsculo. El hijo hace el trabajo pesado (buscar, resumir, redactar) por unos centavos y reporta un resultado corto al padre costoso, en lugar de que el padre costoso haga el trabajo pesado por sí mismo a precio completo con contexto completo. Los patrones de bucle autónomo en el comando goal a través de Codex y Claude Code muestran cómo estructurar esa delegación para que el modelo costoso solo vea resultados destilados.

Una nota sobre los límites, no solo los dólares. Si tienes un plan con límite de uso en lugar de un pago por uso puro, el enrutamiento también extiende cuánto dura tu asignación. Gastar tu presupuesto de modelo premium en mensajes de commit es cómo los equipos se topan con un muro el jueves. El reciente aumento del límite semanal de Claude Code ayuda, pero el enrutamiento sigue siendo lo que hace que la asignación dure.

Recorte de salida de herramientas y recuperación

La salida de herramientas es el asesino silencioso del presupuesto porque es invisible hasta que la miras. Cada comando que ejecuta un agente devuelve texto, y ese texto vuelve directamente al contexto, donde luego se reproduce en cada turno subsiguiente. Un solo npm install puede devolver miles de líneas. Una ejecución de prueba con registro verboso puede devolver decenas de miles de tokens. Un git diff que incluye un archivo de bloqueo regenerado puede ser enorme. El agente rara vez necesita todo; necesita el aprobado/fallo y el fallo relevante.

Tácticas que lo reducen de forma limpia:

Haz que los comandos sean silenciosos en el origen. El agente paga por todo lo que imprime el comando. Configura las herramientas para que sean concisas:

# Ruidoso (el agente paga por cada línea):
npm test

# Silencioso (solo los fallos y un resumen regresan):
npm test --silent -- --reporter=dot

# Ruidoso:
npm install

# Silencioso:
npm install --silent --no-audit --no-fund

Filtra antes de que el agente lo vea. Cuando controlas el comando que ejecuta el agente, elimina el ruido para que solo regrese la señal:

# Solo las líneas que importan vuelven al contexto:
pytest -q 2>&1 | tail -n 30

# Estadísticas de diff en lugar de un diff completo de 4,000 líneas:
git diff --stat

# Busca el fallo con grep en lugar de volcar todo el registro:
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20

Prefiere lecturas dirigidas sobre lecturas de archivos completos. Leer un archivo de 1.500 líneas para cambiar una función es un puro desperdicio. Anima al agente a buscar el símbolo con grep y leer una ventana alrededor, no el archivo completo. Muchos agentes hacen esto cuando el prompt los incita (“encuentra y lee solo la función que maneja los reintentos, no el archivo completo”). En un archivo grande, esa es la diferencia entre ~18.000 tokens y ~800.

Restringe el ámbito de recuperación. Si tu agente realiza búsquedas en el código base o RAG sobre documentos, limita cuántos fragmentos recupera y qué tan grandes son. Diez fragmentos de 200 tokens que responden a la pregunta son mejores que cincuenta fragmentos de 800 tokens que la entierran; pagas por cada token recuperado, lo use el modelo o no.

Estos cambios son en su mayoría una configuración única (informes de prueba, flags de instalación, un archivo de exclusión) y rinden frutos en cada ejecución para siempre, lo que los convierte en algunos de los mejores retornos de esfuerzo de toda esta lista.

Medición y atribución del costo por ejecución

No puedes gestionar lo que no mides, y “la factura bajó” no es una medición. Para saber si una táctica funcionó, necesitas el costo atribuido a una ejecución, idealmente a una tarea.

Empieza con los datos que ya te proporciona la API. Cada respuesta incluye un objeto de uso. Captúralo:

u = response.usage
# Costo aproximado en dólares; sustituye las tasas en vivo para tu modelo.
INPUT_RATE  = 3.00 / 1_000_000     # entrada base $/token (ilustrativo)
OUTPUT_RATE = 15.00 / 1_000_100    # salida $/token (ilustrativo)
CACHE_READ  = 0.30 / 1_000_000     # ~10% de la entrada base
CACHE_WRITE = 3.75 / 1_000_000     # ~1.25x entrada base (caché de 5 min)

cost = (
    u.input_tokens          * INPUT_RATE  +
    u.output_tokens         * OUTPUT_RATE +
    u.cache_read_input_tokens  * CACHE_READ +
    u.cache_creation_input_tokens * CACHE_WRITE
)
print(f"run cost ≈ ${cost:.4f}  "
      f"(in={u.input_tokens} out={u.output_tokens} "
      f"cr={u.cache_read_input_tokens})")

Si usas la CLI del agente en lugar de tu propio wrapper, funcionan tres enfoques:

# 1. La mayoría de las CLI de agentes exponen un comando de uso/costo para la sesión.
#    Compruébalo después de una tarea representativa y anota el número.
claude /cost

# 2. Las consolas del proveedor informan el gasto por clave de API. Emite una clave
#    de API dedicada por agente o por proyecto para que el gasto sea atribuible
#    en lugar de agruparse en un total no rastreable.

# 3. Etiqueta las ejecuciones. Envuelve la invocación del agente en un script que registre
#    la marca de tiempo, la etiqueta de la tarea y el recuento de tokens reportado en un CSV.
#    Una semana de ese CSV te dirá qué tareas son costosas.

Estima antes de ejecutar cualquier cosa grande. Pega el prompt y los archivos que pretendes incluir en un tokenizador (el tokenizador público de OpenAI es una forma rápida de verificar el tamaño) y mira el recuento. Si “incluir el módulo completo” son 90.000 tokens y la versión dirigida son 6.000, acabas de ver la decisión antes de pagarla.

Rastrea un número por tarea representativa a lo largo del tiempo: costo por “ejecución de refactorización diaria”, costo por “ejecución de revisión de PR”. Cuando activas el almacenamiento en caché o cambias una subtarea a un modelo barato, ese número debería moverse. Si no lo hace, la táctica no está funcionando como crees, y lo aprendiste por el precio de una ejecución en lugar de un mes de facturas.

Comparación de tácticas

Los rangos de ahorro son ilustrativos y se acumulan multiplicativamente; la ganancia de cualquier táctica depende de tu desperdicio inicial.

Conclusión

Los costos de tokens del agente son en su mayoría auto-infligidos, y la línea de comandos es donde los solucionas. El desperdicio reside en el contexto que reenvías, la salida que no lees y los modelos que son demasiado caros para la tarea en cuestión. Aborda eso y la factura bajará sin afectar la calidad del trabajo.

Haz primero los elementos de bajo esfuerzo; la delimitación, la salida silenciosa y un archivo de memoria esbelto no cuestan nada y rinden frutos en cada ejecución de ahora en adelante. Añade el almacenamiento en caché y el enrutamiento y la diferencia es el tipo de ahorro que puedes incluir en un presupuesto.