Ver todos los artículos
Claude CodeOllamaIA LocalHerramientas de Desarrollo

Claude Code con un modelo local de Ollama: guía y límites

JG
Jacobo González Jaspe
|

Revisado:

Ilustración abstracta: un poliedro de cristal que refracta un haz de luz ámbar en rayos blancos. Modelos
Ilustración generada con IA en nuestra máquina.
Este artículo también está en inglés:Claude Code on a Local Ollama Model: Setup, Limits, Tests

Al terminar esta guía, Claude Code hablará con un modelo servido por Ollama en tu propia máquina. Sabrás qué variables hacen el trabajo, qué sigue saliendo de tu red y dónde se queda corto un modelo local.

Cada variable, opción y versión está comprobada con la documentación de Claude Code y de Ollama el 15 de noviembre de 2026. Las cifras son nuestras y enlazamos los archivos de resultados.

Para quién es, y cuándo no hacerlo

Te sirve si tienes código que no puede ir a una API externa, si trabajas sin conexión o si quieres entender cómo un agente de programación maneja un modelo.

No es buena idea en tres casos:

  • Necesitas el producto tal como lo cubre Anthropic. Su documentación de pasarelas dice que Anthropic no da soporte a enrutar Claude Code hacia modelos que no sean Claude a través de ninguna pasarela (LLM gateways, leído el 15 de noviembre de 2026). Si algo falla, lo arreglas tú.
  • Tienes menos de 16 GB de memoria para el modelo. Un agente de programación necesita un contexto largo, y el contexto cuesta memoria. Lo verás en el paso 2.
  • La tarea es un cambio largo en muchos archivos. Un modelo local de 26B pide más turnos y más supervisión que un modelo puntero alojado. Para eso mantenemos uno alojado.

Qué necesitas

  • Ollama v0.14.0 o posterior. Esa versión añadió el endpoint compatible con Anthropic, según el anuncio de Ollama del 16 de enero de 2026. Compruébalo con ollama --version. La última versión estable el 15 de noviembre de 2026 era la v0.40.16. Nuestras pruebas corrieron en la 0.34.0 y no hemos probado la 0.40.x.
  • Claude Code. Se instala con curl -fsSL https://claude.ai/install.sh | bash en macOS o Linux, o con irm https://claude.ai/install.ps1 | iex en PowerShell de Windows. Ambos comandos están en la página de integración de Ollama.
  • Un modelo con la capacidad tools. ollama show <modelo> la muestra. Si empiezas de cero, pasa antes por instalar Ollama y tu primer modelo.
  • Memoria para el modelo y su contexto. La tabla del paso 2 trae nuestros tamaños cargados.

Cómo funciona hoy la conexión

Claude Code habla el formato Messages de Anthropic. Su guía de compatibilidad de pasarelas lista los endpoints que necesita: /v1/messages y, de forma opcional, /v1/messages/count_tokens. Cualquier servidor que los atienda puede ir detrás de ANTHROPIC_BASE_URL.

Ollama atiende /v1/messages de forma nativa. Su página de compatibilidad con Anthropic da por soportados el streaming, los prompts de sistema, las llamadas a herramientas y sus resultados, las imágenes en base64 y los bloques de razonamiento. Da por no soportados count_tokens, tool_choice, la caché de prompts, los lotes, las citas y los PDF.

Por eso ya no hace falta un proxy que traduzca, como LiteLLM. Sigue teniendo sentido si quieres una sola dirección delante de varios servidores, claves por usuario o registro de uso, y LiteLLM lo documenta en su tutorial para Claude Code. Nosotros lo usamos por esos motivos, no para traducir formatos.

El endpoint de Ollama compatible con OpenAI no sirve aquí. La misma guía lista los formatos que habla Claude Code, y el de OpenAI no está entre ellos.

Paso 1: comprueba el endpoint antes de abrir Claude Code

Envía a mano una petición con una herramienta. Si falla aquí, fallará en Claude Code, con un mensaje menos claro.

bash
curl -s http://localhost:11434/v1/messages \
  -H "content-type: application/json" -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gemma4:26b", "max_tokens": 400,
    "tools": [{"name": "Read", "description": "Read a file from the repository.",
      "input_schema": {"type": "object",
        "properties": {"file_path": {"type": "string"}}, "required": ["file_path"]}}],
    "messages": [{"role": "user", "content": "Show me what is in the file src/parser.py."}]
  }'

Debes ver un bloque tool_use y "stop_reason": "tool_use". Nuestra ejecución del 15 de noviembre de 2026 devolvió esto, recortado a lo que importa:

JSON
{"type": "tool_use", "name": "Read", "input": {"file_path": "src/parser.py"}}

Si recibes texto, o un JSON escrito como texto, el modelo no llama bien a las herramientas. Elige otro.

Paso 2: dale al modelo un contexto de verdad

Es el paso que más se salta, y causa el peor fallo de esta guía.

La página de longitud de contexto de Ollama (leída el 15 de noviembre de 2026) dice que el valor por defecto depende de tu VRAM: 4k tokens por debajo de 24 GiB, 32k entre 24 y 48 GiB, y 256k a partir de 48 GiB. La misma página recomienda al menos 64.000 tokens para agentes y herramientas de programación. En 4k no caben el prompt de sistema y las definiciones de herramientas de un agente.

El endpoint de Anthropic no tiene campo num_ctx. La ventana la pone el servidor o el modelo:

bash
# Opción A: para todo el servidor
OLLAMA_CONTEXT_LENGTH=65536 ollama serve

# Opción B: fijarlo en una copia con nombre (lo que hacemos; mira la referencia de Modelfile de Ollama)
printf 'FROM gemma4:26b\nPARAMETER num_ctx 32768\n' > Modelfile
ollama create gemma4-32k -f Modelfile

ollama ps    # la columna CONTEXT enseña lo que hay cargado de verdad

Comprobamos que el valor fijado se respeta. Cargamos un modelo con 6.144 tokens, le enviamos doce peticiones por /v1/messages y ollama ps siguió marcando 6.144.

El contexto cuesta memoria, y las ranuras en paralelo lo multiplican. Son tamaños cargados según ollama ps en nuestras NVIDIA DGX Spark (GB10, 128 GB de memoria unificada), medidos el 2 de noviembre de 2026 (archivo de resultados):

Modelo (Q4_K_M)ArchivoContextoRanurasCargado
llama3.1:8b4,9 GB32.76819,21 GB
llama3.1:8b4,9 GB32.768422,38 GB
llama3.1:8b4,9 GB32.768839,27 GB
gemma4:26b18,0 GB32.768117,47 GB
gemma4:26b18,0 GB131.072118,36 GB
qwen3.6:35b23,9 GB32.768823,47 GB

El coste del contexto cambia mucho de un modelo a otro. El de 8B gana 13 GB al pasar de una ranura a cuatro. gemma4:26b gana menos de 1 GB al pasar de 32k a 131k. Ollama arranca su motor con un contexto total de num_ctx por el número de ranuras, como leímos en su registro de carga (recibo). En una máquina para una persona, deja OLLAMA_NUM_PARALLEL en 1 salvo que uses subagentes (paso 4).

Nuestras máquinas tienen 128 GB, y no tenemos datos de un portátil de 16 GB ni de una tarjeta de 24 GB. Haz tu cuenta con cuánta VRAM necesita un LLM local y qué cuantización GGUF elegir.

Paso 3: apunta Claude Code a Ollama

Hay dos caminos, y los dos los documenta Ollama, no Anthropic.

El lanzador. ollama launch claude --model gemma4:26b define las variables solo para ese proceso y arranca Claude Code. La referencia de la CLI documenta también --config, que configura sin arrancar.

A mano. Lo preferimos porque ves cada ajuste:

bash
export LOCAL_MODEL=gemma4-32k     # la copia del paso 2

# De la página de integración de Ollama
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""

# Manda todos los alias de modelo y todos los subagentes al modelo local
export ANTHROPIC_DEFAULT_OPUS_MODEL="$LOCAL_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$LOCAL_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$LOCAL_MODEL"
export CLAUDE_CODE_SUBAGENT_MODEL="$LOCAL_MODEL"

# Dile a Claude Code la ventana real y corta el tráfico de fondo
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=32768
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

claude --model "$LOCAL_MODEL"

Qué hace cada grupo y dónde está documentado:

  • Las tres primeras salen de la página de integración de Ollama. Ollama avisa de que el servidor local ignora el valor del token. La referencia de variables de Claude Code dice que ANTHROPIC_AUTH_TOKEN viaja como cabecera bearer y tiene prioridad sobre una sesión guardada.
  • Las cuatro de modelo son las que define el lanzador de Ollama, según leímos en su código fuente el 15 de noviembre de 2026. Cada una está documentada en la configuración de modelos de Claude Code. Sin ellas, un subagente que pida haiku solicita un nombre de modelo Claude que Ollama no tiene.
  • CLAUDE_CODE_MAX_CONTEXT_TOKENS es la que más importa. La página de configuración de modelos dice que Claude Code supone una ventana de 1M de tokens para un identificador que no reconoce, y compacta la conversación según esa suposición. Ponle la ventana que le diste a Ollama. El código del lanzador solo la define para los modelos en la nube de Ollama, así que con un modelo local la pones tú.
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC apaga las actualizaciones automáticas, la telemetría y los informes de errores. Es opcional. Si la activas, actualiza Claude Code a mano.

Después comprueba dentro de Claude Code con /status. La línea Anthropic base URL debe mostrar la dirección de tu Ollama.

No hemos ejecutado esta sesión de Claude Code para esta actualización. La máquina desde la que escribimos usa Claude Code en producción, y no cambiamos su configuración para una prueba. El paso 3 está montado con la documentación de los dos fabricantes. Lo que sí ejecutamos son los pasos 1 y 2 y las pruebas que siguen.

Lo que ejecutamos: llamadas a herramientas por el endpoint

El 15 de noviembre de 2026 enviamos a Ollama 0.34.0 seis peticiones por modelo a través de /v1/messages. Cada una llevaba un prompt de sistema corto y tres herramientas con la forma de las de un agente de programación (Read, Bash, Grep). Tres prompts pedían una herramienta, dos pedían una respuesta en texto y uno devolvía el resultado de una herramienta. Temperatura 0, una ejecución por caso y comprobación por script. Peticiones y respuestas completas: archivo de resultados.

Casollama3.1:8bgemma4:26b (32k)
Leer un archivoLlamada a Read, ruta correctaLlamada a Read, ruta correcta
Lanzar los tests con pytestBash: pytest && pytest --versionBash: ls -R | grep test
Buscar usos de una funciónLlamada a Grep, patrón correctoLlamada a Grep, patrón correcto
«Responde con tres palabras exactas»Bash: echo 'local model ready'Texto, correcto
«¿Qué significa JSON?»Bash: echo '...'Texto, correcto
Responder con el resultado de una herramientaCorrectoCorrecto

Todas las llamadas estaban bien formadas: herramienta conocida y argumentos válidos. La diferencia está en el criterio. El modelo de 8B recurrió a la shell en las dos preguntas que no pedían herramienta. En una sesión real, cada una es una petición de permiso y un turno perdido. El de 26B respondió en texto. También prefirió buscar los tests antes de lanzarlos: nuestro script lo marcó como fallo y una persona lo vería razonable.

Es una prueba pequeña, no una sesión de Claude Code, que envía un prompt de sistema mucho más largo y muchas más herramientas.

Dos resultados más de la misma ejecución:

  • tool_choice no tuvo efecto visible. Enviamos un mismo prompt de cuatro maneras: sin tool_choice, forzando Bash, forzando Read y con none. Las cuatro respuestas fueron idénticas. Coincide con la página de Ollama, que lo da por no soportado.
  • La salida estructurada apunta a lo mismo. En nuestra prueba aparte con 40 facturas en español, del 5 de noviembre de 2026, gemma4:26b acertó todos los campos en las 40. qwen2.5-coder:7b se quedó en el 85 % y llama3.1:8b en el 62,5 % (archivo de resultados y el método).

Qué modelo local, y a qué velocidad

Los cuatro modelos declaran la capacidad tools en Ollama. Son velocidades de una petición suelta, con 200 tokens de salida, en nuestras DGX Spark. No son sesiones de Claude Code.

Modelo (Q4_K_M)ArchivoGeneraciónMedido
qwen2.5-coder:7b4,68 GB42,1 tok/s17-10-2026, Ollama 0.30.10
llama3.1:8b4,92 GB40,2 tok/s17-10-2026, Ollama 0.30.10
gemma4:26b17,99 GB62,0 tok/s17-10-2026, Ollama 0.30.10
gemma4:26b17,99 GB68,2 tok/s2-11-2026, Ollama 0.34.0
qwen3.6:35b23,94 GB75,8 tok/s2-11-2026, Ollama 0.34.0

Fuentes: archivo de octubre y archivo de noviembre.

Nuestra lectura:

  • De 7B a 8B: valen para aprender la configuración y para preguntas sobre un solo archivo. Habrá llamadas que sobran.
  • En torno a 26B: el tamaño mínimo que usaríamos para trabajo de agente. Es el que usamos a diario.
  • qwen3-coder:30b: es el de los ejemplos de Ollama. Su página de la biblioteca indica 19 GB, ventana de 256K y herramientas. No lo hemos medido.

Paso 4: subagentes

Un subagente es una tarea aparte con su propio contexto. Devuelve un resumen, y la conversación principal se mantiene corta. La página de subagentes de Claude Code dice que funcionan con cualquier proveedor.

Con un modelo local cambian tres cosas:

  1. Fija el modelo de los subagentes. Un subagente puede pedir un alias como haiku. Las cuatro variables de modelo del paso 3 mandan esas peticiones a tu modelo local.
  2. Pídelos. El artículo de Ollama sobre subagentes (16 de febrero de 2026) nombra tres de sus modelos en la nube que los lanzan por su cuenta. No dice lo mismo de los modelos locales. Dilo en el prompt: «usa subagentes para revisar los tests y la documentación».
  3. El paralelo necesita ranuras. Con OLLAMA_NUM_PARALLEL=1, los subagentes en paralelo esperan en cola. Más ranuras cuestan memoria, como enseña la tabla del paso 2. En una sola GPU, además, se reparten su velocidad. Úsalos para mantener limpio el contexto, no para ir más rápido.

No hemos medido una ejecución con subagentes sobre un modelo local.

Qué se queda en tu máquina y qué no

TráficoAdónde vaCómo cortarlo
Prompts, código, llamadas a herramientas, subagentesTu servidor OllamaNada que cortar
Búsqueda webLa API de búsqueda alojada de OllamaDeniega la herramienta WebSearch
Descargas de páginas con WebFetchEl sitio que pidesDeniega la herramienta WebFetch
Comprobación de dominio de WebFetchapi.anthropic.com, solo el nombre del hostskipWebFetchPreflight: true en los ajustes
Métricas de uso y comprobación de actualizacionesAnthropic y sus proveedoresCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Las filas tres a cinco salen de la página de uso de datos de Claude Code. Da las métricas por activadas por defecto en la ruta de la API de Claude, que es como Claude Code trata una URL base propia. También dice que las métricas nunca incluyen código, prompts ni rutas de archivos.

La búsqueda web no es local. La herramienta WebSearch de Claude Code corre normalmente en los servidores de Anthropic. El artículo de Ollama dice que su capa de compatibilidad hace la búsqueda en su lugar y le pasa los resultados al modelo. La página de búsqueda web de Ollama documenta esa API en ollama.com y dice que requiere una cuenta gratuita de Ollama. La misma página de compatibilidad advierte de que la búsqueda web alojada no está soportada del todo. No la hemos probado con un modelo local.

Si tu norma es que no salga nada, no la uses. La referencia de herramientas de Claude Code dice que el motor de búsqueda no se puede cambiar, y propone un servidor MCP para añadir otro. Nosotros alojamos SearXNG para eso. Mira cómo conectar agentes a herramientas con MCP.

Fallos que te vas a encontrar

1. El modelo olvida el principio de la conversación. Enviamos un prompt de 64.507 caracteres a un modelo cargado con 6.144 tokens de contexto. La primera línea llevaba una palabra clave y la última, la pregunta. Ollama devolvió un HTTP 200, declaró 3.070 tokens de entrada y el modelo respondió que no veía ninguna palabra clave. Ni error ni aviso. Con un prompt corto respondió bien. Arreglo: el paso 2 y CLAUDE_CODE_MAX_CONTEXT_TOKENS en el paso 3. Si aun así se pierde, lanza /compact antes.

2. model 'claude-haiku-4-5' not found. Lo reprodujimos: Ollama responde un HTTP 404 con not_found_error cuando le piden un nombre de modelo Claude. Alguna parte de Claude Code sigue pidiendo un modelo Claude. Arreglo: las cuatro variables de modelo del paso 3. La página de compatibilidad de Ollama da otra salida: copiar tu modelo con un nombre de Claude mediante ollama cp.

3. Tus variables no se aplican. La página de conexión de Claude Code dice que un valor en el bloque env de un archivo de ajustes gana a un export de la shell. Lanza /status y lee la línea de la URL base.

4. El recuento de tokens es aproximado. En nuestro Ollama 0.34.0, /v1/messages/count_tokens respondió 404 page not found. La guía de pasarelas de Claude Code dice que entonces estima por caracteres, así que /context enseña cifras aproximadas. No hay nada que arreglar.

5. La primera respuesta tarda mucho. El modelo se está cargando desde el disco. En nuestra prueba de contexto, gemma4:26b tardó 32 segundos en su primera carga y de 9 a 10 segundos en las dos siguientes. Claude Code espera por defecto hasta 10 minutos a que empiece una respuesta (API_TIMEOUT_MS).

6. Errores 400 que nombran un campo desconocido. La tabla de problemas de Claude Code da CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 para servidores que rechazan campos en fase previa. No hemos visto este error.

Límites frente a los modelos alojados

  • Contexto. La página de modelos de Claude Code da a los modelos Claude alojados ventanas de 200K a 1M de tokens. Nuestro modelo local de diario trabaja con 32k. Las sesiones largas se compactan antes y pierden detalle.
  • Sin caché de prompts. Ollama da cache_control por no soportado. En nuestra prueba, Ollama sí declaró tokens de prompt reutilizados en prefijos repetidos, pero es un mecanismo propio.
  • Criterio. El modelo de 26B formó bien las llamadas a herramientas en nuestra prueba. No tenemos ninguna medida suya en trabajo largo sobre muchos archivos, y no afirmamos que iguale ahí a un modelo puntero.
  • Funciones ligadas a una sesión de Anthropic. Remote Control, el dictado por voz y los conectores de claude.ai no están disponibles con una URL base o un token propios, según la documentación de Claude Code.
  • Soporte. Ninguno por parte de Anthropic para esta configuración.

Lo que no probamos: una sesión completa de Claude Code con las versiones de hoy, Ollama 0.40.x, la búsqueda web con un modelo local, subagentes sobre un modelo local, una máquina de 16 o 24 GB, qwen3-coder, y si Claude Code acepta una ventana declarada de solo 32k (su documentación no da un mínimo). Una versión anterior de este artículo citaba tiempos de sesión de septiembre de 2026. No guardamos archivo de resultados de aquello, así que los hemos retirado.

Preguntas frecuentes

¿Sigo necesitando LiteLLM u otro proxy? No. Ollama sirve el formato de Anthropic desde la v0.14.0. Usa un proxy solo si quieres enrutado, claves o registros.

¿Lo cubre Anthropic? No. Su documentación lo dice sin rodeos. Ollama documenta y mantiene su parte.

¿Necesito una cuenta o una clave de Anthropic? La configuración de Ollama usa un token de relleno, y la documentación de Claude Code dice que ese token ocupa el lugar de la sesión. No lo hemos probado en una máquina que nunca haya iniciado sesión.

¿La búsqueda web funciona sin conexión? No. Llama a la API alojada de Ollama.

¿Puedo conservar mi sesión normal de Claude Code? Sí. Los export duran lo que ese terminal.

¿Con qué modelo empiezo? Con el mayor que tenga tools y quepa en tu memoria con una ventana de 32k. En nuestras máquinas es gemma4:26b.

Siguientes pasos

Trabaja con nosotros

Usamos agentes de programación sobre modelos locales a diario y reservamos un modelo alojado para los casos difíciles. Si quieres ese reparto diseñado para tu equipo, ajustado a las máquinas que ya tienes, escríbenos o mira cómo trabajamos en consultoría.

Diagrama
Compartir: LinkedIn X
Veredicto semanal

Recibe las guías nuevas antes que nadie

Suscríbete y te avisamos cuando publiquemos guías, plantillas y workflows nuevos. Un correo a la semana, sin spam.

Ya publicados: 101 guías y 25 plantillas. Todo gratis y sin registro.

Bonus: el kit de inicio de IA local en PDF al suscribirte
1x por semana Sin spam Cancela cuando quieras

Ver qué recibes