Usar Ollama en Claude Code y Cursor (modelos locaux)

#¿Por qué usar Ollama en Claude Code o Cursor?

Tres razones que siempre se repiten. Primero, la confidencialidad: un proyecto de un cliente bajo NDA, código propietario, secretos en texto plano en los archivos —nada de esto debería enviarse a un tercero. Después, el costo: Cursor Pro cuesta 20 $/mes, y Claude Code consume tokens de Anthropic cuyo costo alcanza rápidamente los 50-100 $/mes con un uso sostenido. Con Ollama, es cero después de comprar la GPU. Por último, la resiliencia: tu asistente no se detiene cuando hay un incidente en la API de Anthropic ni cuando se corta tu conexión ADSL.

El equilibrio entre ventajas y limitaciones es razonable: un Qwen3-Coder 30B en local no iguala a Claude Sonnet 4.6 o GPT-5 en tareas complejas de agentes que abarcan varios archivos. Pero para el 80 % de los usos diarios —completar, refactorizar, escribir un test, explicar un bloque, generar un commit— un modelo de programación de 9 a 30B en Q4 cumple de sobra. Y siempre puedes seguir usando la nube en paralelo para las tareas más exigentes.

#El endpoint compatible con OpenAI de Ollama

Desde la versión 0.1.24, Ollama expone, además de su API nativa, un endpoint compatible con la API ChatCompletions de OpenAI. Esto es lo que hace posible todo lo demás: cualquier cliente de OpenAI (SDK de Python, SDK de Node, Cursor, Cline, Aider, Continue, etc.) puede enviar solicitudes a Ollama sin modificaciones, simplemente cambiando la URL base.

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder:30b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

El formato de respuesta es idéntico al de OpenAI: choices[0].message.content, usage con prompt_tokens y completion_tokens, y compatibilidad con streaming mediante stream: true. La clave de API se ignora: puedes enviar cualquier cosa en la cabecera Authorization y Ollama la acepta. Sin embargo, muchos clientes rechazan un campo vacío: pon ollama o anything para complacerlos.

#Prerrequisitos

Ollama 0.5+

ollama --version debe responder. En Windows, el icono del sistema debe estar activo. Si empiezas desde cero, consulta la guía de instalación Ollama para tu sistema operativo.

GPU con 12 GB de VRAM o Mac de la serie M con 16 GB o más

Un Qwen 3.5 9B Q4 = ~6,6 GB, un Devstral 24B Q4 = ~14 GB, un Qwen3-Coder 30B-A3B Q4 = ~19 GB. RTX 3060 12 GB = mínimo útil (Qwen 3.5 9B); RTX 4070/4080 16 GB o Mac M3/M4 = Devstral 24B y Qwen3-Coder 30B completos.

Cursor 0.40+ o Claude Code CLI

Cursor desde cursor.com (modo personalizado de OpenAI integrado). Claude Code mediante npm install -g @anthropic-ai/claude-code.

Conocimiento mínimo sobre las variables de entorno

Para Claude Code, se utilizarán ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN.

#1. Conectar Cursor con Ollama

Cursor tiene una opción oficial para apuntar a un endpoint compatible con OpenAI. Funciona muy bien para el chat (Ctrl+L) y la edición en línea (Ctrl+K). El agente Composer y el autocompletado Tab, en cambio, siguen restringidos a los modelos de Cursor en la nube: es una limitación del producto asumida por Anthysphere.

1. 01
   Descargar un modelo de código

   Con 12 GB de VRAM, Qwen 3.5 9B (qwen3.5:9b) es un excelente punto de partida: se maneja razonablemente bien en francés, permite llamadas a herramientas y ofrece 256k de contexto. Con 16 GB, pasa a Devstral 24B (devstral:24b); con 24 GB, a Qwen3-Coder 30B-A3B (qwen3-coder:30b), el MoE de código de referencia.
2. 02
   Abrir los ajustes de Cursor

   Ctrl+Shift+J (Cmd+, en Mac) → pestaña Models. Ves la lista de modelos de Cursor (claude-3.5-sonnet, gpt-5, etc.) con interruptores.
3. 03
   Añadir un modelo personalizado

   Haz clic en Add Model en la parte inferior. Escribe el nombre exacto del modelo Ollama: qwen3-coder:30b. Marca la casilla para activarlo.
4. 04
   Configurar la URL base

   En la sección OpenAI API Key, despliega Override OpenAI Base URL. Introduce http://localhost:11434/v1 y luego haz clic en Save. En API Key, introduce cualquier valor (ollama basta); Cursor no acepta un campo vacío.
5. 05
   Comprobar la conexión

   Haz clic en Verify. Cursor envía una solicitud de prueba a tu Ollama. Si responde con 200, el botón se pone verde y el modelo aparece en el selector del chat.

ollama pull qwen3-coder:30b

Una vez configurado, el chat de Cursor (Ctrl+L) y la edición en línea (Ctrl+K) funcionan con tu modelo local. El selector de modelos en la parte superior del panel de chat muestra qwen3-coder:30b; los modelos de Cursor en la nube siguen disponibles si quieres cambiar a ellos de vez en cuando.

#2. Conectar Claude Code a Ollama

Claude Code (la CLI de Anthropic) utiliza de forma nativa la API Messages de Anthropic, no la API Chat Completions de OpenAI. Los dos protocolos difieren (roles, formato de las llamadas a herramientas, streaming). Para que Claude Code se comunique con Ollama, hace falta un pequeño traductor: un proxy que recibe solicitudes en el formato Anthropic Messages por un lado y las emite en el formato OpenAI Chat Completions por el otro.

El proyecto de referencia para esto se llama claude-code-router (musistudio/claude-code-router en GitHub). Se instala con un solo comando, se ejecuta en local en un puerto y acepta reglas de enrutamiento por modelo (por ejemplo: enviar haiku a Ollama y sonnet al verdadero Claude).

1. 01
   Instalar Claude Code

   npm install -g @anthropic-ai/claude-code si ce n'est pas déjà fait. claude --version doit répondre.
2. 02
   Instalar claude-code-router

   npm install -g @musistudio/claude-code-router. Le binaire ccr est ajouté au PATH.
3. 03
   Descargar el modelo en Ollama

   Elige preferentemente un modelo que admita llamadas a herramientas: qwen3-coder:30b, devstral:24b o glm-4.7-flash. Sin soporte para llamadas a herramientas, Claude Code no podrá llamar a sus herramientas internas (Read, Edit, Bash, etc.) y perderá el 90 % de su utilidad.
4. 04
   Configurar el router

   Crea ~/.claude-code-router/config.json con una entrada Providers que apunte a Ollama y una regla Router que asocie los modelos Claude con tu modelo local.
5. 05
   Iniciar mediante ccr

   ccr code en lugar de claude. El wrapper inicia el proxy en segundo plano, exporta ANTHROPIC_BASE_URL para que apunte a él y luego inicia Claude Code. Dentro, /model permite cambiar entre rutas.

ollama pull qwen3-coder:30b
# ou pour du pur agent de code
ollama pull devstral:24b

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "devstral:24b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,qwen3-coder:30b",
    "think": "ollama,devstral:24b",
    "longContext": "ollama,qwen3-coder:30b"
  }
}

ccr code
# Claude Code démarre, mais les requêtes filent vers Ollama
# Vérifier : /model affiche qwen3-coder:30b

Enfoque minimalista sin router: también puedes exportar directamente ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN para apuntar a un proxy compatible con Anthropic (como LiteLLM en modo --anthropic o y-router). Más ligero, pero sin la flexibilidad de las reglas por tarea.

#3. Qué modelo de código elegir: Qwen3-Coder vs Devstral en local

En Ollama, algunas familias destacan para la programación en el verano de 2026: Qwen3-Coder (Alibaba), Devstral (Mistral AI) y los modelos MoE polivalentes como GLM 4.7 Flash (Z.ai) o gpt-oss (OpenAI). Todas son de pesos abiertos y funcionan en Q4 en hardware de consumo.

Qwen3-Coder 30B-A3B (Alibaba, Apache 2.0)

La referencia polivalente en 2026. Soporte sólido para llamadas a herramientas, multilingüe (francés correcto), bueno en Python/JS/Go/Rust, 256k de contexto. Es un MoE con 3B activos: rápido como un modelo denso de 14B, con la calidad de uno de 30B. ≈ 19 GB en Q4. Pull: qwen3-coder:30b.

Devstral 24B (Mistral AI, Apache 2.0)

Diseñado específicamente para agentes SWE (edición de varios archivos, navegación por la base de código). Excelente en Aider, OpenHands y —por extensión— Claude Code. 24B denso ≈ 14 GB en Q4, cabe en 16 GB. Pull: devstral:24b.

GLM 4.7 Flash (Z.ai, MIT) / gpt-oss 20B (OpenAI)

Dos modelos MoE muy adecuados en modo agente. GLM 4.7 Flash (30B-A3B, ≈ 19 GB) es un excelente gestor de llamadas a herramientas; gpt-oss 20B (≈ 14 GB, MXFP4, 131k de contexto) es más rápido y cabe en 16 GB. Pull: glm-4.7-flash o gpt-oss:20b.

Qwen 3.5 9B (alternativa para GPU de 8-12 GB)

Solo 6,6 GB, un modelo generalista sólido en programación, con 256k de contexto y visión. Una buena alternativa cuando la VRAM es escasa, antes de pasar a los modelos de 24B+. Pull: qwen3.5:9b.

VRAM por tamaño en Q4_K_M (la cuantización recomendada): 7B ≈ 5 GB, 14B ≈ 9 GB, 24B ≈ 14 GB, 32B ≈ 19 GB, 70B ≈ 40 GB. El contexto consume memoria adicional: calcula entre 2 y 4 GB más para 32k tokens de contexto, según el modelo.

#Limitaciones frente a la nube: dónde la IA local se queda atrás

Seamos honestos sobre lo que los modelos locales no hacen tan bien como Claude Sonnet 4.6 o GPT-5:

Ventana de contexto

Ollama limita por defecto num_ctx a 4096 tokens; se puede aumentar a 32k o incluso 128k según el modelo, pero a costa de la VRAM. Cursor con Sonnet en la nube maneja 200k tokens sin problemas. En un monorepo grande, la nube lo lee todo; el modelo local debe elegir.

Razonamiento en múltiples pasos

Un modelo de 9-14B pierde el hilo cuando el agente encadena 10 llamadas a herramientas con dependencias entre ellas. Sonnet mantiene el hilo. Para una orquestación de agentes realmente compleja, la nube sigue por delante, y con mucha diferencia.

Conocimiento de las API recientes

Los modelos con pesos abiertos tienen una fecha límite de conocimiento (a menudo, 2025) y no conocen las API publicadas después. Cursor en la nube se beneficia de las actualizaciones continuas y de las herramientas de búsqueda web.

Latencia del primer token

Paradójicamente, la nube puede ser más rápida al iniciar (no hay que cargar el modelo). En local, el modelo permanece cargado y listo entre llamadas: tras el primer prompt, la ventaja vuelve a estar del lado de la ejecución local.

Costo eléctrico

Una RTX 4090 bajo carga consume 350 W. 8 horas al día de programación intensiva = ~70 kWh/mes = ~15 € en Francia. Sigue siendo muy inferior a 20 $/mes con Cursor + 50 $/mes con Claude, pero no es gratis.

#Consejos y solución de problemas

Cursor devuelve "OpenAI API key invalid"

El campo API Key debe contener un valor no vacío. Coloca ollama, sk-anything o cualquier cosa plausible. Es estético: Ollama ignora la cabecera.

Cursor no ve el modelo

El nombre del modelo en Cursor (Add Model) debe ser EXACTAMENTE el devuelto por ollama list (etiqueta incluida, por ejemplo qwen3-coder:30b). No solo qwen3-coder, ni Qwen3 Coder.

Claude Code entra en bucle o vuelve a pedir lo mismo

A menudo, el modelo local falla al llamar a herramientas. Comprueba que el modelo admita llamadas a funciones (ollama show qwen3-coder:30b → busca la mención tools en las capacidades). Cambia a un modelo más grande o simplifica la tarea.

Respuestas truncadas después de 2-3 frases

num_ctx por defecto = 4096. Para Claude Code y Cursor con un contexto de base de código, sube el valor a 16384 o 32768. Con Ollama: crea un Modelfile personalizado con PARAMETER num_ctx 32768 y ejecuta ollama create coder-32k -f Modelfile. El consumo adicional de memoria es real (+ 2-4 GB para la caché KV).

VRAM saturada, OOM

Revisa ollama ps durante el uso. Si ves >100% loaded en GPU/CPU split, parte del modelo pasa a la RAM y se vuelve muy lento. Soluciones: cuantización más agresiva (Q3_K_M), modelo más pequeño o reducir num_ctx.

Latencia > 5 s por respuesta

O bien el modelo se ejecuta parcialmente en la CPU (ver el punto anterior), o bien Ollama recarga el modelo en cada solicitud. Comprueba OLLAMA_KEEP_ALIVE (por defecto, 5 min). Establece OLLAMA_KEEP_ALIVE=2h para mantener el modelo cargado y listo.

#Para ir más allá

Ya tienes Ollama sirviendo un modelo de código a Cursor o Claude Code. Los siguientes pasos naturales:

Completar en el editor (FIM inline)

La guía «Copilot gratuito en local» explica cómo instalar Continue.dev / Tabby / CodeGeeX para el autocompletado en línea al estilo de Copilot, un complemento natural del chat en Cursor.

Elegir la cuantización adecuada

Q4_K_M, Q5_K_M, Q8_0: la guía Elegir la cuantización compara la pérdida real de calidad en los modelos de código y explica cuándo un Q3 sigue siendo utilizable.

Personalizar un modelo de código

La guía Personalizar un modelo con Ollama Modelfile muestra cómo fijar num_ctx, el prompt de sistema y la temperatura para tener un modelo de programación adaptado a tu stack.