DEV Community

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

Posted on • Originally published at apidog.com

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

#agents #ai #cli #spanish

Un agente de codificación CLI parece gratis hasta que llega la factura. Apuntas Claude Code o Codex a un repositorio, le pides refactorizar un módulo y, diez minutos después, leyó cuarenta archivos, ejecutó la suite de pruebas tres veces y consumió cientos de miles de tokens en contexto que nunca necesitaba. Multiplica eso por ocho ingenieros usando agentes todo el día: el gasto deja de ser marginal. La mayoría del costo de tokens en agentes CLI es desperdicio, y gran parte se puede corregir desde la línea de comandos sin cambiar de modelo ni empeorar la salida.

Prueba Apidog hoy

En resumen

Reduce el costo de tokens recortando el contexto antes de enviarlo al modelo:

  • Delimita archivos y carpetas antes de iniciar la tarea.
  • Mantén CLAUDE.md u otros archivos de memoria cortos.
  • Usa /compact o /clear entre tareas.
  • Activa caché de prompts para prefijos estables.
  • Envía tareas simples a modelos baratos.
  • Filtra la salida de herramientas.
  • Mide costo por ejecución para validar el impacto.

Introducción

El problema suele aparecer de dos formas: alcanzas un límite semanal a mitad de tarea, o llega la factura mensual de API y alguien pregunta por qué un “asistente de IA” cuesta más que un contratista junior.

La causa raíz es la misma: los agentes CLI consumen tokens por defecto. Leen archivos completos cuando necesitan diez líneas, reenvían el historial completo en cada turno, vuelcan logs enteros al contexto y mandan el mismo prompt del sistema y mapa del repositorio miles de veces.

Una refactorización que realmente necesita razonar sobre 2.000 tokens de código no debería requerir 180.000 tokens de contexto. La diferencia entre esos dos números es tu margen de ahorro.

Esta guía cubre tácticas concretas para reducir cada categoría de gasto:

  1. Higiene de contexto y archivos de memoria.
  2. Caché de prompts.
  3. Enrutamiento de modelos.
  4. Recorte de salida de herramientas.
  5. Medición de costo por ejecución.

Los ejemplos usan Claude Code y Codex, pero el patrón aplica a cualquier agente conectado a una API facturada por tokens.

También hay un costo indirecto importante: depuración. Si tu agente llama a una API interna inestable, reintentará, leerá errores, revisará documentos y entrará en bucles. Cada iteración cuesta tokens.

💡 Si tus agentes interactúan con APIs, tener esas APIs diseñadas, simuladas y probadas en Apidog antes de apuntarles un agente elimina una categoría completa de prueba y error costoso. El agente trabaja contra un contrato estable, no contra un endpoint en vivo que lo sorprende.

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

Antes de optimizar, necesitas entender qué se factura. En cada turno, el agente envía una carga de entrada al modelo y recibe una salida. Pagas por ambas.

En muchos proveedores, los tokens de salida cuestan bastante más que los de entrada. Por ejemplo, en una familia de modelos de frontera a mediados de 2026, la entrada puede rondar los $3 por millón de tokens y la salida alrededor de $15. Un modelo más barato puede estar cerca de $1 de entrada y $5 de salida. Usa estos números solo como referencia: consulta siempre la página de precios actual.

Lo importante es estructural:

  • La salida es cara.
  • La entrada se dispara con facilidad.
  • El historial se reenvía una y otra vez.

Una ejecución típica incluye:

  • Prompt del sistema y definiciones de herramientas. Instrucciones del agente más esquemas JSON de herramientas. Se reenvían en cada turno.
  • Archivos de memoria/proyecto. CLAUDE.md, convenciones del repositorio, instrucciones persistentes. Se cargan aunque no siempre sean relevantes.
  • Historial de conversación. Mensajes, respuestas, llamadas a herramientas y resultados anteriores. Crece sin límite.
  • Contenido de archivos leídos. Un Read sobre un archivo de 1.200 líneas puede costar miles de tokens.
  • Salida de herramientas. Logs de tests, npm install, git diff, stack traces y ruido de consola.

La carga de salida contiene razonamiento, ediciones y explicaciones. Suele ser menor que la entrada, pero más cara por token.

El punto crítico: el historial completo se reproduce en cada turno. Una sesión de 30 turnos no cuesta 30 veces un turno aislado. Se parece más a una suma acumulativa donde los turnos finales cargan todo lo anterior.

Si quieres profundizar en cómo se consumen ventanas y límites, este desglose sobre cómo se restablece la ventana de tokens de Claude Code complementa bien esta sección.

Higiene del contexto y archivos de memoria

El token más barato es el que nunca envías. La higiene de contexto reduce la carga de entrada en todos los turnos posteriores.

1. Delimita el conjunto de trabajo antes de empezar

No abras un agente en la raíz del repositorio con una instrucción vaga como:

claude "refactoriza la lógica de facturación"
Enter fullscreen mode Exit fullscreen mode

Eso invita al agente a explorar demasiado.

Usa prompts específicos:

claude "refactor the retry logic so it uses exponential backoff,
only in src/payments/retry.ts and its test file"
Enter fullscreen mode Exit fullscreen mode

Mejor aún, incluye límites explícitos:

claude "Actualiza solo estos archivos:
- src/payments/retry.ts
- src/payments/retry.test.ts

No leas otros módulos salvo que una importación falle.
No modifiques archivos de configuración."
Enter fullscreen mode Exit fullscreen mode

Nombrar archivos evita que el agente lea veinte candidatos para encontrar dos relevantes. Si necesita explorar, limítalo a un directorio:

claude "Busca la lógica de reintentos solo dentro de src/payments/.
No explores src/admin ni src/legacy."
Enter fullscreen mode Exit fullscreen mode

2. Mantén CLAUDE.md corto

Un archivo como CLAUDE.md se carga en cada turno. Si el equipo lo convierte en una wiki de onboarding, cada ejecución paga por ese texto una y otra vez.

Mide su tamaño aproximado:

wc -c CLAUDE.md | awk '{print "≈", int($1/4), "tokens por turno"}'
Enter fullscreen mode Exit fullscreen mode

Un buen archivo de memoria debería contener:

# Proyecto

## Comandos
- Test unitarios: npm test -- --runInBand
- Lint: npm run lint
- Typecheck: npm run typecheck

## Convenciones
- No usar `any` salvo en adaptadores externos.
- Mantener tests junto al archivo bajo prueba.
- No modificar archivos generados.

## Documentos bajo demanda
- Arquitectura de pagos: docs/payments.md
- Contrato API: docs/api-contract.md
Enter fullscreen mode Exit fullscreen mode

Evita incluir:

  • Historia del proyecto.
  • Guías largas de estilo.
  • Documentación completa de APIs.
  • Decisiones antiguas irrelevantes.
  • Texto que solo aplica a una tarea mensual.

Si el agente necesita un documento largo, que lo lea bajo demanda.

3. Compacta o limpia sesiones largas

Una tarea lógica debe tener una sesión lógica. Cuando termines una tarea, no sigas usando el mismo contexto para otra no relacionada.

En Claude Code:

/compact
Enter fullscreen mode Exit fullscreen mode

Esto resume el historial y elimina la transcripción original del contexto activo.

Para empezar limpio:

/clear
Enter fullscreen mode Exit fullscreen mode

Regla práctica:

  • Usa /compact si la tarea continúa, pero la conversación ya es larga.
  • Usa /clear si cambias de tarea.

Ejemplo:

# Tarea 1
claude "Corrige los tests fallidos en src/payments/retry.test.ts"

# Después de terminar:
/clear

# Tarea 2 no relacionada
claude "Revisa el componente src/ui/InvoiceTable.tsx"
Enter fullscreen mode Exit fullscreen mode

Los patrones en flujos de trabajo de Claude Code se apoyan en esta disciplina: delimitar, ejecutar, compactar o limpiar.

4. Excluye artefactos generados

Evita que el agente lea directorios que no aportan razonamiento:

node_modules/
dist/
build/
coverage/
.next/
.lock-cache/
vendor/
*.lock
Enter fullscreen mode Exit fullscreen mode

Si tu agente admite un archivo de exclusión propio, úsalo para bloquear:

node_modules/**
dist/**
coverage/**
package-lock.json
pnpm-lock.yaml
yarn.lock
Enter fullscreen mode Exit fullscreen mode

Esto evita gastos accidentales en:

  • Dependencias vendoreadas.
  • Archivos compilados.
  • Lockfiles enormes.
  • Salidas de coverage.
  • Builds generados.

Caché de prompts: deja de pagar precio completo por el mismo prefijo

La caché de prompts permite al proveedor almacenar un prefijo estable de tu solicitud —herramientas, prompt del sistema, convenciones del repositorio— y reutilizarlo con descuento en solicitudes posteriores.

Según la documentación de caché de prompts de Anthropic:

  • Una escritura en caché cuesta más que una entrada normal.
  • Una lectura desde caché cuesta alrededor de 0.1x la entrada base.
  • Eso equivale aproximadamente a un 90% de descuento sobre la parte cacheada.
  • La caché por defecto suele ser corta, alrededor de 5 minutos, con opción de 1 hora.
  • Hay un tamaño mínimo para que un prefijo sea cacheable.

La regla de implementación:

Pon primero el contenido estable y deja lo volátil al final.

Orden recomendado:

herramientas → sistema → convenciones estables → tarea del usuario → archivos recuperados
Enter fullscreen mode Exit fullscreen mode

No metas timestamps, IDs aleatorios o contenido cambiante antes del punto de caché.

Ejemplo con wrapper propio 

# Prefijo estable:
# - prompt del sistema
# - definiciones de herramientas
# - convenciones del repositorio
#
# La tarea del usuario queda fuera del prefijo cacheado.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {
            "role": "user",
            "content": user_task,
        }
    ],
)

u = response.usage

print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)
print("fresh input:", u.input_tokens)
Enter fullscreen mode Exit fullscreen mode

Si tienes un bloque de convenciones de 8.000 tokens y lo usas en 60 invocaciones diarias:

  • Sin caché: pagas 8.000 tokens completos 60 veces.
  • Con caché: pagas escritura una vez y lecturas con descuento en las siguientes llamadas.

Esto se acumula con las demás optimizaciones.

Checklist para que la caché funcione

  • Mantén el prefijo byte-estable.
  • No interpoles fechas ni UUIDs en el prompt del sistema.
  • No reordenes herramientas sin necesidad.
  • Agrupa ejecuciones relacionadas para mantener la caché caliente.
  • Revisa métricas de cache_read_input_tokens.

La API de OpenAI aplica descuentos similares de entrada cacheada en modelos compatibles, aunque los controles sean distintos.

Los trucos de nivel gratuito y enrutamiento en ejecutar GPT-5.5 gratis a través de Codex son útiles cuando la caché no basta.

Enrutamiento de modelos: modelo barato para trabajo barato

No todas las acciones del agente requieren un modelo de frontera.

Tareas que suelen poder ir a un modelo barato:

  • Escribir mensajes de commit.
  • Resumir un diff.
  • Generar changelog.
  • Explicar errores de lint.
  • Renombrar variables.
  • Crear tests boilerplate.
  • Formatear documentación.

Tareas que justifican un modelo más potente:

  • Diseñar arquitectura.
  • Resolver bugs ambiguos.
  • Refactorizaciones grandes.
  • Revisiones de seguridad.
  • Cambios con mucho contexto de negocio.

Desde la CLI:

# Tarea mecánica
claude --model haiku "write a conventional-commit message for the staged diff"

# Tarea compleja
claude --model sonnet "redesign the caching layer for the payments service"
Enter fullscreen mode Exit fullscreen mode

El patrón recomendado es invertir el default habitual:

# Default barato para tareas comunes
export CLAUDE_MODEL=haiku

# Escalar solo cuando sea necesario
claude --model sonnet "analiza este bug intermitente de concurrencia"
Enter fullscreen mode Exit fullscreen mode

Muchos equipos hacen lo contrario: usan el modelo caro para todo “por seguridad” y pagan varias veces más por tareas triviales.

Enrutamiento con subagentes

Si tu framework permite subagentes, delega trabajo mecánico a un agente hijo con contexto pequeño:

Agente padre:
- Modelo caro.
- Decide estrategia.
- Recibe resultados resumidos.

Agente hijo:
- Modelo barato.
- Busca archivos.
- Resume hallazgos.
- Devuelve 10 líneas, no 10.000 tokens.
Enter fullscreen mode Exit fullscreen mode

Ejemplo de prompt:

Usa un subagente barato para inspeccionar solo src/payments/.
Debe devolver:
1. Archivos relevantes.
2. Funciones candidatas.
3. Riesgos principales.

No debe proponer cambios todavía.
Enter fullscreen mode Exit fullscreen mode

Así el modelo caro no paga por exploración extensa.

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.

El enrutamiento también ayuda con límites de uso. Si tu plan tiene cuota semanal, gastar modelo premium en mensajes de commit es una forma rápida de agotar el presupuesto antes del viernes. El aumento del límite semanal de Claude Code ayuda, pero no reemplaza una buena estrategia de enrutamiento.

Recorte de salida de herramientas y recuperación

La salida de herramientas es uno de los gastos menos visibles. Todo lo que imprime un comando vuelve al contexto. Luego se reenvía en turnos posteriores.

Ejemplos comunes de desperdicio:

  • npm install con miles de líneas.
  • Tests en modo verbose.
  • Diffs completos de lockfiles.
  • Stack traces repetidos.
  • Logs con timestamps irrelevantes.

1. Haz los comandos silenciosos 

# Ruidoso
npm test

# Más conciso
npm test --silent -- --reporter=dot
Enter fullscreen mode Exit fullscreen mode 
# Ruidoso
npm install

# Más conciso
npm install --silent --no-audit --no-fund
Enter fullscreen mode Exit fullscreen mode 
# Ruidoso
pytest

# Más conciso
pytest -q
Enter fullscreen mode Exit fullscreen mode

2. Filtra antes de devolver al agente 

# Solo las últimas líneas relevantes
pytest -q 2>&1 | tail -n 30
Enter fullscreen mode Exit fullscreen mode 
# Resumen en vez de diff completo
git diff --stat
Enter fullscreen mode Exit fullscreen mode 
# Solo errores importantes
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20
Enter fullscreen mode Exit fullscreen mode 
# Evita lockfiles gigantes en el diff
git diff -- . ':!package-lock.json' ':!pnpm-lock.yaml' ':!yarn.lock'
Enter fullscreen mode Exit fullscreen mode

3. Pide lecturas dirigidas

Un archivo de 1.500 líneas no debería entrar completo al contexto para cambiar una función.

Prompt recomendado:

Encuentra la función que maneja los reintentos.
Lee solo esa función y 40 líneas alrededor.
No leas el archivo completo salvo que sea necesario.
Enter fullscreen mode Exit fullscreen mode

Flujo sugerido:

grep -R "retry" src/payments -n
sed -n '120,220p' src/payments/retry.ts
Enter fullscreen mode Exit fullscreen mode

Esto puede convertir una lectura de decenas de miles de tokens en unos cientos.

4. Limita recuperación/RAG

Si tu agente consulta documentación o usa RAG, ajusta:

  • Número máximo de fragmentos.
  • Tamaño de fragmento.
  • Directorios permitidos.
  • Tipos de archivo relevantes.

Mejor:

Devuelve máximo 5 fragmentos de 200 tokens.
Prioriza docs/api/*.md.
Ignora changelogs y documentos archivados.
Enter fullscreen mode Exit fullscreen mode

Peor:

Busca en toda la documentación y trae todo lo relevante.
Enter fullscreen mode Exit fullscreen mode

Pagas por cada token recuperado, aunque el modelo no lo use.

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

No puedes optimizar lo que no mides. “La factura bajó” no es suficiente. Necesitas costo por ejecución, idealmente por tipo de tarea.

Si usas API directamente, captura usage:

u = response.usage

# Sustituye por las tarifas actuales de tu modelo.
INPUT_RATE  = 3.00 / 1_000_000
OUTPUT_RATE = 15.00 / 1_000_000
CACHE_READ  = 0.30 / 1_000_000
CACHE_WRITE = 3.75 / 1_000_000

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} "
    f"out={u.output_tokens} "
    f"cr={u.cache_read_input_tokens} "
    f"cw={u.cache_creation_input_tokens})"
)
Enter fullscreen mode Exit fullscreen mode

Si usas CLI, aplica una de estas opciones:

# 1. Revisa costo/uso de la sesión si la CLI lo soporta
claude /cost
Enter fullscreen mode Exit fullscreen mode 
# 2. Usa claves de API por proyecto o agente
# Así puedes atribuir consumo desde la consola del proveedor.
Enter fullscreen mode Exit fullscreen mode 
# 3. Envuelve la CLI con un script que registre:
# - timestamp
# - tarea
# - modelo
# - costo reportado
# - tokens de entrada/salida
Enter fullscreen mode Exit fullscreen mode

Ejemplo simple de registro:

#!/usr/bin/env bash

TASK_LABEL="$1"
shift

START=$(date -Iseconds)

claude "$@"

END=$(date -Iseconds)

echo "$START,$END,$TASK_LABEL" >> agent-runs.csv
Enter fullscreen mode Exit fullscreen mode

Si tu CLI expone métricas en JSON, registra también tokens:

claude --json "$@" | tee last-run.json

jq -r '[
  now,
  .model,
  .usage.input_tokens,
  .usage.output_tokens,
  .usage.cache_read_input_tokens
] | @csv' last-run.json >> agent-costs.csv
Enter fullscreen mode Exit fullscreen mode

Antes de una ejecución grande, estima tokens:

  1. Pega prompt y archivos en un tokenizador.
  2. Compara “módulo completo” vs “función objetivo”.
  3. Si una opción son 90.000 tokens y otra 6.000, decide antes de pagar.

Mide tareas representativas:

  • Costo por refactorización diaria.
  • Costo por revisión de PR.
  • Costo por generación de tests.
  • Costo por depuración de fallo CI.

Cuando actives caché, cambies de modelo o filtres logs, esos números deberían moverse. Si no se mueven, la optimización no está funcionando.

Comparación de tácticas

Táctica Ahorro típico de tokens Esfuerzo
Delimitar el conjunto de trabajo 30–60% en entrada por ejecución Bajo
Archivo de memoria corto y estable 5–15% por turno Bajo
/compact o /clear entre tareas 40–80% en sesiones largas Bajo
Caché de prompts en prefijo estable ~90% en el prefijo cacheado Medio
Enrutamiento de modelos 50–80% en subtareas enrutadas Medio
Salida de herramienta silenciosa/filtrada 20–50% en ejecuciones con muchas herramientas Bajo
Lecturas dirigidas 70–95% en archivos grandes Bajo
Recuperación/RAG restringido 30–60% en agentes con mucho RAG Medio
Medición por ejecución 0% directo; habilita todo lo demás Bajo

Los rangos son ilustrativos. El ahorro real depende de tu desperdicio inicial y las tácticas se acumulan de forma multiplicativa.

Checklist de implementación rápida

Empieza por cambios de bajo esfuerzo:

[ ] Limitar prompts a archivos/directorios concretos.
[ ] Reducir CLAUDE.md a comandos, reglas y enlaces.
[ ] Usar /compact o /clear entre tareas.
[ ] Excluir dist/, node_modules/, coverage/ y lockfiles.
[ ] Ejecutar tests en modo silencioso.
[ ] Usar git diff --stat antes de pedir diffs completos.
[ ] Enviar commits, changelogs y resúmenes a modelo barato.
[ ] Medir costo por ejecución durante una semana.
Enter fullscreen mode Exit fullscreen mode

Luego añade optimizaciones de mayor impacto:

[ ] Configurar caché de prompts para prefijos estables.
[ ] Separar modelos por tipo de tarea.
[ ] Usar subagentes baratos para exploración.
[ ] Limitar fragmentos de recuperación/RAG.
[ ] Crear dashboards por clave de API, proyecto o agente.
Enter fullscreen mode Exit fullscreen mode

Conclusión

Los costos de tokens en agentes CLI suelen ser auto-infligidos. El desperdicio está en el contexto que reenvías, la salida que no lees y los modelos caros usados para tareas simples.

La solución no requiere abandonar agentes ni aceptar peores resultados. Requiere operar con disciplina:

  • Contexto mínimo.
  • Sesiones cortas.
  • Herramientas silenciosas.
  • Modelos adecuados por tarea.
  • Caché para prefijos repetidos.
  • Medición por ejecución.

Haz primero lo barato: delimitar, filtrar salida y adelgazar archivos de memoria. Después añade caché y enrutamiento. Ahí es donde el ahorro deja de ser marginal y empieza a notarse en el presupuesto.

Top comments (0)