Usar Ollama con un agente de programación

Qué está conectando

Puede usar Ollama con su agente de programación. La conexión es más sencilla de lo que suele pensarse. Cambie una URL base y elija un nombre de modelo. El campo de clave de API sigue requiriendo un valor, pero el servidor local lo ignora, por lo que puede usar cualquier cadena.

Ollama escucha en el puerto 11434 y ofrece tres superficies de API al mismo tiempo. /api es la API nativa de Ollama. /v1 es la capa compatible con OpenAI, que a su vez cubre varios formatos: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models y /v1/embeddings. La documentación de Ollama indica que la clave es obligatoria, pero se ignora. La tercera superficie es compatible con Anthropic: el cliente usa http://localhost:11434 como URL base y añade /v1/messages, que es el formato que usa Claude Code. La mayoría de los agentes usan /v1/chat/completions, Codex usa /v1/responses y Claude Code usa /v1/messages. Su agente ya es compatible con uno de estos formatos, por lo que no tiene que cambiar nada más.

Esta parte lleva cinco minutos. La utilidad real del resultado depende de dos ajustes que casi nadie cambia: la longitud del contexto y el keep-alive. También depende de asignar al modelo el tipo de trabajo que puede realizar bien. Cada ajuste tiene su propia sección. Las limitaciones reales se explican al final.

Qué agentes de programación aceptan una URL base local

La prueba consta de una pregunta: ¿la herramienta permite configurar una URL base? Si la permite, puede comunicarse con su servidor.

Ollama publica páginas de integración para Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs y VS Code. Aider documenta por separado su compatibilidad con Ollama. Esto cubre la mayoría de lo que se entiende por agente de programación en octubre de 2026. No todos usan el mismo formato, y esa diferencia es la causa de muchos fallos de configuración.

• La mayoría de los agentes necesitan un endpoint compatible con OpenAI. Proporcióneles la URL base http://localhost:11434/v1 y cualquier cadena no vacía como clave API.
• Claude Code no acepta una URL base de OpenAI. Usa la API Anthropic Messages, por lo que necesita que ANTHROPIC_BASE_URL se establezca en http://localhost:11434, donde Ollama expone /v1/messages.
• Codex usa la API OpenAI Responses. Ollama también expone /v1/responses, disponible desde la versión 0.13.3.
• Un agente que no tenga una opción de URL base no se puede redirigir, porque el endpoint está integrado en el cliente. Si el agente acepta una URL personalizada, pero necesita un formato de API diferente, coloque delante una capa de traducción, como una gateway LiteLLM autogestionada, y vuelva a exponer su modelo con el formato que requiera el cliente.

Ollama puede escribir estas configuraciones por usted. ollama launch opencode inicia OpenCode con una configuración en línea para el modelo elegido, ollama launch claude hace lo mismo con Claude Code y ollama launch droid --config escribe la configuración sin iniciar la herramienta.

Instalar Ollama y descargar un modelo compatible con llamadas a herramientas

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

El instalador añade una unidad de systemd y la inicia, por lo que systemctl status ollama debería mostrar active (running). Si no lo hace, journalctl -e -u ollama muestra el motivo.

El modelo debe admitir llamadas a herramientas, porque así es como funciona un agente. Lee un archivo, escribe un parche, ejecuta la prueba, lee el error y vuelve a intentarlo. Un modelo que no puede emitir una llamada a una herramienta describirá la modificación en texto en lugar de aplicarla, y el agente entrará en un bucle o se detendrá. Busque la etiqueta tools en la página del modelo en ollama.com antes de descargarlo. qwen3-coder:30b la incluye y, en octubre de 2026, esa etiqueta requiere una descarga de 19 GB y ofrece una ventana de contexto de 256K. Si el servidor sólo usa CPU o tiene poca RAM, la estimación de memoria para la etiqueta Qwen 27B en un VPS muestra qué configuración cabe realmente en 8 a 64 GB antes de iniciar la descarga. Después de descargarlo, esos gigabytes se almacenan en el disco root del servidor, que es la parte del VPS con menos espacio disponible. Por eso conviene leer dónde guarda Ollama los archivos de modelo y cómo moverlos a otra ubicación antes de llenar el disco.

Ahora confirme qué nombres ofrece realmente el servidor:

curl http://localhost:11434/v1/models

Las cadenas de esa respuesta son las que debe contener la configuración del agente, carácter por carácter. Comprobarlo primero resuelve la mayoría de los errores de modelo no encontrado. Si Ollama aún no está instalado, consulte el tutorial más extenso sobre alojar un LLM en un VPS con Ollama.

Apunte OpenCode a Ollama

Edite ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

La clave de models es el nombre del modelo que se envía a Ollama, por lo que debe coincidir exactamente con ollama ls. El campo name sólo es la etiqueta que aparece en el selector de modelos. Inicie opencode, cambie al proveedor Ollama y supervise journalctl -e -u ollama para confirmar que la solicitud llegó a su servidor y no a otro destino. La configuración del agente se explica en ejecutar OpenCode en un VPS.

Indique a Claude Code que use Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY se establece intencionadamente como una cadena vacía. La URL base controla adónde se envían las solicitudes; al borrar la clave, se evita que las credenciales de un servicio alojado se usen en esta configuración local. ollama launch claude configura todo esto automáticamente.

Tenga en cuenta qué elementos no incluye la capa de compatibilidad. No implementa tool_choice ni la caché de prompts, y no tiene un endpoint para contar tokens. Por eso, las cifras de tokens que ve son aproximaciones basadas en el tokenizador del propio modelo. Claude Code también incluye un prompt de sistema grande y un conjunto amplio de herramientas, por lo que necesita más contexto que un cliente de chat. La cuestión más amplia de qué elementos se conservan y cuáles no se trata en si puede alojar Claude por su cuenta.

Dirija Aider a Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

La documentación de Aider recomienda el prefijo ollama_chat/ en lugar de ollama/. De forma predeterminada, Aider solicita suficiente contexto para cada petición, además de 8k tokens para la respuesta. También permite fijar la ventana de contexto por modelo en .aider.model.settings.yml, lo que resulta útil cuando un modelo necesita una ventana distinta de la predeterminada del servidor:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Por qué una configuración funcional sigue produciendo resultados absurdos

Esta es la sección importante. Ollama elige una longitud de contexto predeterminada a partir de la VRAM agregada (memoria de video de las GPU) que puede detectar, restando OLLAMA_GPU_OVERHEAD por cada GPU detectada. La implementación usa estos umbrales:

[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

La mayoría de los planes VPS, y todos los servidores que sólo usan CPU, quedan en la primera fila: 4,096 tokens. Varias GPU pequeñas pueden alcanzar juntas el umbral de 47 GiB necesario para los 262,144 tokens de la última fila.

Un agente consume 4096 tokens antes de hacer cualquier trabajo. El prompt del sistema, las definiciones de las herramientas, el listado del repositorio y el primer archivo que abre ya superan esa cantidad. Después ocurre el problema principal: no se muestra ningún error. La documentación de Aider indica que Ollama descarta silenciosamente el contexto que supera la ventana. Los tokens más antiguos desaparecen, por lo que el modelo responde con seguridad sobre un archivo que ya no puede ver o olvida una instrucción que recibió dos pasos antes. Este mecanismo explica la mayoría de los informes que describen un modelo local como demasiado limitado para escribir código. Elegir el número también requiere una decisión independiente, y conviene leer cuánto cuesta cada valor de num_ctx en memoria de caché KV antes de fijarlo.

La documentación de Ollama indica que las tareas como los agentes y las herramientas de programación deben configurarse con al menos 64000 tokens. Configúralo en el servidor:

sudo systemctl edit ollama.service

Añade estas líneas al archivo de override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Después recarga y reinicia:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

Envía una petición desde tu agente después del reinicio y ejecuta ollama ps de nuevo para que haya un modelo cargado que se pueda inspeccionar. ollama ps es la comprobación. Muestra una columna CONTEXT, y ese número indica lo que recibió realmente el modelo. Tus valores de ID y SIZE serán diferentes:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Configúralo en el servidor, no en el agente, por dos motivos. El esquema de completions de chat de OpenAI no tiene ningún campo para la longitud de contexto, por lo que un cliente compatible con OpenAI no puede solicitarla. Además, la configuración es por servidor, así que todos los agentes que dirijas a ese equipo la heredarán. La salida tiene su propio límite y, a diferencia de la longitud de contexto, sí se transmite mediante el endpoint de compatibilidad. Por eso, num_predict y el campo max_tokens que se asigna a este valor son las opciones que debes usar cuando una respuesta se detiene a mitad de un parche. Si un modelo necesita una ventana diferente, incorpórala en una copia mediante un Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

El contexto no es gratuito. Una ventana más larga consume más memoria, así que supervisa la columna PROCESSOR. 100% GPU es el valor que necesitas. Cuando parte del modelo se desborda a la CPU, la velocidad de generación de tokens disminuye lo suficiente como para que un bucle de agente resulte inutilizable. Medir los tokens por segundo en un LLM local permite encontrar el límite real de tu equipo. El dimensionamiento de la máquina antes de comprarla se explica en cuánta RAM y CPU necesita un VPS para un agente de programación.

Mantener el modelo cargado entre solicitudes

De forma predeterminada, Ollama descarga un modelo 5 minutos después de su última solicitud. Esto es adecuado para un cuadro de chat, pero no para el trabajo de agentes. Puede pausar la ejecución para leer un diff, el temporizador puede agotarse y la siguiente solicitud vuelve a cargar decenas de gigabytes de pesos desde el disco antes de mostrar el primer token. Parece que el proceso se ha bloqueado.

OLLAMA_KEEP_ALIVE acepta una cadena de duración como 10m o 24h, un número simple de segundos, -1 para mantener el modelo cargado indefinidamente o 0 para descargarlo de inmediato. Configúrelo junto a la longitud del contexto:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

El campo de solicitud keep_alive existe en los endpoints nativos /api/generate y /api/chat de Ollama, y como extensión de Ollama en /v1/chat/completions. Un agente que exponga campos de solicitud adicionales puede enviarlo allí; de lo contrario, use la variable de entorno. Cuando necesite recuperar la memoria, ollama stop qwen3-coder:30b descarga el modelo sin detener el servidor. Si quiere conservar la configuración tras un reinicio, o comparar mantener los pesos en memoria todo el día con recuperar esa memoria, mantener un modelo de Ollama cargado en memoria funciona con ambas opciones.

Ejecutar Ollama en un servidor independiente

Ollama se enlaza a localhost. Para acceder a él desde otra máquina, establezca OLLAMA_HOST=0.0.0.0:11434 en la misma anulación de systemd y reinicie el servicio.

Hágalo sólo en una red privada. La documentación de Ollama indica que la API local no requiere autenticación, por lo que dejar abierto el puerto 11434 a Internet permite que cualquiera use su hardware. Hay dos opciones seguras. Mantenga el enlace en localhost y reenvíe el puerto mediante SSH desde su portátil:

ssh -N -L 11434:localhost:11434 you@your-vps

Su agente seguirá apuntando a http://localhost:11434/v1 y no notará la diferencia. La otra opción es usar una VPN, con Ollama enlazado a la dirección de la VPN en lugar de 0.0.0.0. Si varias personas o varios agentes van a compartir un equipo, Ollama admite solicitudes en paralelo cuando hay memoria suficiente, y la comparación entre Ollama y vLLM muestra a partir de qué punto la diferencia de rendimiento empieza a ser un problema.

Cuándo gana un modelo de código local y cuándo no

Un agente basado en un modelo que aloja usted no sustituye a una API de vanguardia en todas las tareas. Gana claramente en cuatro tipos de trabajo.

• Ediciones mecánicas masivas, cuando cada cambio es pequeño y se puede comprobar. Cambiar nombres en un repositorio, añadir sugerencias de tipos, escribir docstrings o traducir comentarios. El modelo se ejecuta durante horas y la factura no aumenta.
• Trabajo que no debe salir de su hardware. Código de cliente sujeto a un acuerdo de confidencialidad o un repositorio interno que no tiene permiso para enviar a terceros.
• Máquinas sin conexión o aisladas, donde no existe ninguna API alojada a la que llamar.
• Coste predecible. Una vez pagado el servidor, un agente que consume tokens en un bucle no genera ningún coste adicional. Esto es lo contrario de una API con tarificación por uso. Cuándo un VPS con GPU alcanza el punto de equilibrio frente a los tokens de una API contiene los cálculos.

Pierde en tareas largas de varios pasos. «Averigua por qué falla esta prueba, corrige la causa y actualiza los llamadores» requiere muchas llamadas correctas a las herramientas seguidas, con todo el historial todavía disponible en el contexto. Un modelo del rango de 8B a 14B en un servidor modesto generará una llamada incorrecta a una herramienta o perderá el plan después de unos pocos turnos, y usted dedicará más tiempo a dirigirlo del que habría requerido la tarea. No es un problema de prompts que pueda resolver redactándolos de otra forma. Es un problema de capacidad.

También pierde cuando equivocarse resulta costoso y usted no va a leer cada línea. Asigne al modelo local tareas acotadas cuyo resultado pueda verificar y reserve el modelo alojado para el trabajo que no comprobaría paso a paso.

Modos de fallo y cadenas que verá

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. El servidor no está en ejecución o el agente apunta a otro host. Ejecute systemctl status ollama y después journalctl -e -u ollama.

El agente informa de que el modelo no existe. El nombre de la configuración no coincide con ningún nombre que sirva el servidor. Compárelo con curl http://localhost:11434/v1/models y copie la cadena que aparece allí. La etiqueta forma parte del nombre, por lo que una configuración que indique una etiqueta que nunca ha descargado falla aunque haya instalado un modelo similar.

El agente responde con texto y nunca edita un archivo. El modelo no admite herramientas o la solicitud, junto con las definiciones de sus herramientas, ya ocupa toda la ventana de contexto. Compruebe la etiqueta tools en la página del modelo y después la columna CONTEXT en ollama ps.

Hay una espera larga antes del primer token y después la velocidad es normal. Ha caducado el keep-alive y los pesos se están leyendo de nuevo desde el disco. Configure OLLAMA_KEEP_ALIVE.

El modelo contradice un archivo que acaba de leer. Se ha truncado el contexto. ollama ps suele mostrar un valor CONTEXT inferior al que cree haber configurado, porque la variable de entorno se aplicó al shell en lugar de a la unidad de systemd.

Todo funciona, pero despacio, y PROCESSOR no es 100% GPU. Normalmente, el modelo y su contexto no caben en la VRAM. Si PROCESSOR muestra 100% CPU en un equipo que tiene una GPU, descarte primero la otra causa: es posible que Ollama no haya detectado la GPU. La documentación de Ollama indica que, en Linux, después de suspender y reanudar el sistema, a veces no detecta una GPU NVIDIA y cambia a la CPU; volver a cargar el controlador con sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm evita el problema. Si se detecta la GPU y el reparto se mantiene, reduzca la longitud del contexto o cambie a un modelo más pequeño o a una cuantización más pequeña. Antes de volver a descargar el modelo, qué coste de memoria tienen q4_K_M, q8_0 y fp16, y dónde se produce realmente la pérdida de calidad explica cuánto espacio obtiene al reducir un nivel y qué debe sacrificar.

FAQ

¿Puedo conectar Claude Code a Ollama?

Sí, pero no mediante una URL compatible con OpenAI. Claude Code usa la API Anthropic Messages, y Ollama ofrece ese formato en /v1/messages, en el mismo puerto 11434. Exporte ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama y un ANTHROPIC_API_KEY vacío; después, inícielo con claude --model qwen3-coder:30b. ollama launch claude escribe esta configuración por usted. La capa de compatibilidad no implementa tool_choice ni el almacenamiento en caché de prompts, y no tiene un endpoint para contar tokens, por lo que las cantidades de tokens indicadas son aproximadas.

¿Por qué mi modelo local responde sobre código que no puede ver?

Porque la solicitud ya no cabe en la ventana de contexto y la parte más antigua se descartó sin mostrar ningún error. Ollama establece el contexto predeterminado a partir de la VRAM total detectada, después de restar la sobrecarga configurada por GPU: por debajo de 23 GiB, el valor predeterminado es de 4,096 tokens; entre 23 y menos de 47 GiB, es de 32,768 tokens; y con 47 GiB o más, es de 262,144 tokens. Establezca OLLAMA_CONTEXT_LENGTH=64000 en la unidad de systemd, reinicie Ollama y confirme que la columna CONTEXT de ollama ps muestra el nuevo valor.

¿Qué modelo debería ejecutar para un agente de programación en un VPS?

Elija el modelo más grande que tenga la etiqueta tools y que siga cabiendo en la memoria con una ventana de contexto de 64k. Dé preferencia a un modelo optimizado para código. qwen3-coder:30b es la opción habitual en un servidor con GPU y suficiente VRAM. Si esa etiqueta es demasiado grande para su servidor, las cifras de RAM y las velocidades con CPU de Nemotron 3.5 Lightning sirven como comparación antes de iniciar la descarga. Por debajo de aproximadamente 14B parámetros, un modelo todavía puede responder bien a preguntas sobre código y fallar al realizar ediciones en varios pasos, porque el trabajo de un agente penaliza los pequeños errores de formato en las llamadas a herramientas. Pruebe una tarea real de su propio repositorio en lugar de usar un prompt de ejemplo.

¿Necesito una GPU para ejecutar un agente de programación con mi propio modelo?

En la práctica, sí. La inferencia sólo con CPU funciona y es suficiente para preguntas individuales, pero un agente envía muchas solicitudes por tarea y cada una vuelve a leer un historial largo. Por eso, una tasa baja de tokens puede convertir una tarea de dos minutos en una hora. Compruebe la columna PROCESSOR de ollama ps: cualquier valor distinto de 100% GPU significa que parte del modelo se está ejecutando en la CPU y que la tasa de tokens disminuye considerablemente.