Image for post Claude Code con Modelos Locales: Reduce el Coste de API

Claude Code con Modelos Locales: Reduce el Coste de API

Escrito por Sergio Márquez

Los costes de API en Claude Code se acumulan más rápido de lo que parece. Un desarrollador que usa el agente de forma intensiva puede gastar entre 15€ y 50€ al mes solo en tokens de Anthropic, y eso antes de llegar a proyectos con contextos largos o workflows multi-agente. El ciclo de revisión cruzada entre agentes puede multiplicar ese consumo por tres sin que te des cuenta.

La buena noticia: Claude Code admite redirigir sus llamadas de modelo con una sola variable de entorno. Esto permite usar Qwen3-Coder-Next, un modelo open-weight con arquitectura MoE que ofrece rendimiento comparable a Claude Sonnet en la mayoría de tareas de código, a una fracción del coste, tanto en APIs externas como en inferencia local.

TL;DR

Claude Code puede redirigirse a modelos alternativos usando la variable ANTHROPIC_BASE_URL junto con un proxy como LiteLLM o la herramienta claude-code-router. El ahorro potencial oscila entre el 70% y el 85% en llamadas a API dependiendo del modelo y la mezcla de tareas. La configuración tarda menos de 30 minutos y funciona tanto con modelos cloud (OpenRouter) como con inferencia local (Ollama, vLLM).

El problema real: tokens que no ves llegar

Claude Code factura por tokens consumidos en cada sesión. Una sesión de trabajo con contexto de repositorio mediano puede usar entre 200.000 y 500.000 tokens de entrada. A los precios actuales de Claude Sonnet 4.6 (aproximadamente 2,80€ por millón de tokens de entrada), eso equivale a 0,56€ - 1,40€ por sesión. Aparentemente poco, pero en una semana de trabajo intensivo se convierte en 15€-40€ al mes, sin contar los tokens de salida, que son bastante más caros.

El control de tokens en tiempo real con Statusline ayuda a ser consciente del consumo, pero no lo reduce. Para reducirlo de verdad, hay que cambiar el modelo backend.

Cómo funciona el routing de modelos en Claude Code

Claude Code usa la Anthropic Messages API para comunicarse con el modelo. Esa comunicación pasa por una URL configurable mediante la variable de entorno ANTHROPIC_BASE_URL. Si apuntas esa URL a un proxy que traduzca las peticiones al formato del modelo que quieres usar, Claude Code nunca se entera del cambio: sigue pensando que habla con Anthropic.

El problema es que los modelos locales (Ollama, LM Studio) hablan el formato OpenAI chat completions, no Anthropic Messages API. Son protocolos incompatibles. Necesitas una capa de traducción. Hay dos herramientas principales para esto:

Herramienta Mejor para Complejidad Coste
claude-code-router Desarrollador individual, configuración rápida Baja Gratis (open source)
LiteLLM proxy Equipos, auditoría de uso, múltiples modelos Media Gratis (self-hosted)

El modelo: Qwen3-Coder-Next

Qwen3-Coder-Next, publicado por el equipo de Alibaba en febrero de 2026, es el modelo open-weight más competitivo para tareas de coding agente disponible a fecha de este artículo. Su arquitectura MoE (Mixture of Experts) tiene 80B parámetros totales, pero solo activa 3B por token durante la inferencia, lo que lo hace significativamente más barato de ejecutar que modelos densos de tamaño equivalente.

Donde Qwen3-Coder rinde de forma equiparable a Sonnet: edición de ficheros, generación de tests, debugging de funciones aisladas, refactorizaciones acotadas. Donde Sonnet sigue siendo claramente superior: razonamiento de arquitectura complejo, instrucciones de sistema muy precisas y contextos con más de 100k tokens de código interdependiente.

Precios orientativos en OpenRouter (marzo 2026):

  • Qwen3-Coder-Next: ~0,73€/M tokens entrada, ~3,65€/M tokens salida
  • Claude Sonnet 4.6: ~2,80€/M tokens entrada, ~14€/M tokens salida

La diferencia en coste por token de salida es de aproximadamente 3,8x. Con 200.000 tokens de salida al mes, eso supone pasar de ~2,80€ a ~0,73€ solo en ese concepto.

Configuración paso a paso: claude-code-router

Este es el enfoque más directo para un desarrollador individual. claude-code-router actúa como proxy local entre Claude Code y el modelo de tu elección, con configuración declarativa en JSON.

Paso 1: Instalar claude-code-router

npm install -g @musistudio/claude-code-router

Paso 2: Crear el archivo de configuración

{
  "Router": {
    "default": "openrouter,qwen/qwen3-coder-next",
    "background": "openrouter,qwen/qwen3-coder-next"
  },
  "Providers": {
    "openrouter": {
      "api_base": "https://openrouter.ai/api/v1",
      "api_key": "${OPENROUTER_API_KEY}"
    }
  }
}

Guarda este archivo en ~/.claude-code-router/config.json.

Paso 3: Arrancar el proxy y lanzar Claude Code

# Terminal 1: arranca el router
claude-code-router start

# Terminal 2: apunta Claude Code al proxy
export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_API_KEY="sk-local"  # Valor no vacío, el router lo ignora
export OPENROUTER_API_KEY="sk-or-..."  # Tu key de OpenRouter

claude

Si la conexión funciona, Claude Code arranca normalmente y las peticiones se enrutan a Qwen3-Coder-Next sin ningún cambio en tu flujo de trabajo habitual.

Alternativa con inferencia 100% local: LiteLLM + Ollama

Si prefieres que ningún token salga de tu máquina, la combinación LiteLLM + Ollama elimina el coste de API por completo. Requiere hardware suficiente: Qwen3-Coder-Next con cuantización Q4_K_M necesita aproximadamente 24 GB de VRAM para funcionar con fluidez.

Paso 1: Descargar el modelo en Ollama

ollama pull qwen3-coder-next

Paso 2: Configurar LiteLLM

# litellm_config.yaml
model_list:
  - model_name: "claude-3-5-sonnet-20241022"  # Alias que Claude Code espera
    litellm_params:
      model: "ollama/qwen3-coder-next"
      api_base: "http://localhost:11434"

litellm_settings:
  drop_params: true  # Ignora parámetros no soportados por Ollama

Paso 3: Arrancar LiteLLM y conectar Claude Code

# Instalar LiteLLM
pip install "litellm[proxy]"

# Arrancar el proxy
litellm --config litellm_config.yaml --port 4000

# En otra terminal
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-local"

claude

Puedes combinar este setup con el patrón de fallback entre modelos para tener Qwen3 local como primario y la API de Anthropic como respaldo cuando el modelo local no dé abasto.

Aplicación práctica: workflow híbrido por tipo de tarea

El patrón más útil no es sustituir Claude completamente, sino enrutar según el tipo de tarea. claude-code-router admite configuración granular por tipo de operación:

{
  "Router": {
    "default": "openrouter,qwen/qwen3-coder-next",
    "background": "ollama,qwen3-coder-next"
  },
  "TaskRouting": {
    "file_edit": "default",
    "test_generation": "default",
    "code_review": "default",
    "architecture": "anthropic,claude-sonnet-4-6"
  },
  "Providers": {
    "anthropic": {
      "api_key": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "api_base": "https://openrouter.ai/api/v1",
      "api_key": "${OPENROUTER_API_KEY}"
    }
  }
}

Con este enfoque, las ediciones de ficheros, generación de tests y code review rutinario van a Qwen3-Coder, mientras que las decisiones de arquitectura o los contextos muy largos van al modelo de Anthropic. En equipos con flujos de revisión multi-agente, este routing puede reducir el coste mensual total de forma significativa sin comprometer la calidad en las tareas que más importan.

En producción

Hay diferencias que el tutorial no muestra y que aparecen con el uso real:

Latencia: La inferencia local con Qwen3-Coder-Next en hardware de consumo es notablemente más lenta que la API de Anthropic. Sobre una RTX 4090 con cuantización Q4_K_M, la velocidad de generación ronda los 15-25 tokens/segundo. La API de Claude genera entre 80-120 tokens/segundo. Para sesiones interactivas, la diferencia es perceptible en operaciones largas.

Ventana de contexto: Qwen3-Coder-Next tiene una ventana nativa de 256k tokens. Con Ollama, el límite efectivo suele ser menor dependiendo de la VRAM disponible, porque el modelo reserva memoria para el KV cache.

Coste de hardware frente a coste de API: Si ya dispones de una GPU con 24+ GB de VRAM, el coste marginal de ejecutar el modelo localmente es prácticamente cero. Si necesitas adquirir el hardware, el break-even con el coste de la API depende del consumo mensual. Para la mayoría de desarrolladores individuales, el cálculo rara vez favorece la compra de hardware solo para esto.

Cuándo no usar modelos locales: Tareas que requieren seguir instrucciones de sistema complejas con alta precisión, razonamiento arquitectónico en sistemas grandes o contextos con interdependencias entre muchos ficheros. En estos casos, el ahorro de coste no compensa la pérdida de calidad.

Para entornos con múltiples agentes y modelos en paralelo, el routing por tipo de tarea es especialmente valioso porque los agentes de background pueden resolverse con modelos baratos mientras los agentes principales usan Sonnet.

Errores comunes y depuración

Error: Connection refused al arrancar Claude Code
Causa: El proxy no está activo cuando arrancas el agente.
Solución: Comprueba que el proxy está corriendo antes de abrir Claude Code. Valida con curl http://localhost:4000/health.

Error: 401 Unauthorized
Causa: ANTHROPIC_API_KEY está vacío o sin definir.
Solución: Establece cualquier valor no vacío: export ANTHROPIC_API_KEY="sk-local". El proxy ignora este valor, pero Claude Code lo requiere para iniciar.

Error: Model does not support tool use
Causa: El modelo local o la versión de Ollama no soporta function calling de forma nativa.
Solución: Usa Qwen3-Coder-Next en lugar de modelos de propósito general. Si el error persiste, añade drop_params: true en la configuración de LiteLLM.

Preguntas frecuentes

¿Qwen3-Coder-Next puede sustituir completamente a Claude Sonnet 4.6 en Claude Code?

Para la mayoría de tareas cotidianas (edición de código, generación de tests, debugging de funciones aisladas) el rendimiento es comparable. Para decisiones de arquitectura, refactorizaciones que afectan a múltiples capas o instrucciones de sistema muy precisas, Sonnet sigue siendo más fiable. El enfoque híbrido con routing por tarea es lo más pragmático en la práctica.

¿Funciona esta configuración con VS Code y el modo agente?

El routing vía ANTHROPIC_BASE_URL afecta al CLI de Claude Code, no al plugin de VS Code. Para el modo agente de VS Code, el hub multi-agente de VS Code tiene sus propias opciones de configuración de backend.

¿Es seguro enviar código privado por OpenRouter?

OpenRouter actúa como intermediario hacia los proveedores del modelo. El código que incluyes en el contexto pasa por sus servidores. Para repositorios con información sensible, la opción más segura es la inferencia local con Ollama, donde ningún dato sale de tu máquina.

Routing inteligente, no sustitución ciega

Cambiar el backend de Claude Code no es una decisión de todo o nada. La arquitectura de routing permite delegar tareas rutinarias a modelos más baratos sin abandonar la herramienta ni cambiar el flujo de trabajo. El verdadero ahorro viene de ser selectivo: Qwen3-Coder para el 80% de las operaciones del día a día, Sonnet para el 20% que lo requiere.

La decisión entre claude-code-router y LiteLLM depende del contexto. Para uso individual, el router está operativo en menos de 10 minutos. LiteLLM tiene sentido cuando necesitas control de acceso por usuario, límites de gasto o auditoría de llamadas en un equipo.

¿Ya has probado a conectar Claude Code con un backend alternativo? ¿Qué modelo has encontrado más equilibrado para código del día a día? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. El próximo artículo explorará cómo estructurar el routing automático según la complejidad estimada de cada tarea.

Volver al blog