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 ahí es donde fallan las configuraciones.

• La mayoría de los agentes requieren 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 ofrece /v1/messages.
• Codex usa la API OpenAI Responses. Ollama también ofrece /v1/responses, disponible desde la versión 0.13.3.
• Un agente sin opción para configurar la URL base no se puede redirigir, porque el endpoint está integrado en el cliente. Coloque delante una capa de traducción, como una puerta de enlace LiteLLM autohospedada, y vuelva a exponer el 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 que elija, 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.

Apunta Claude Code a 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. Si dejas una clave real en el entorno, tus solicitudes se envían a la API alojada, por lo que recibes una factura y no ejecutas inferencia local. ollama launch claude configura todo esto automáticamente.

Debes conocer las funciones que la capa de compatibilidad no incluye. No implementa tool_choice ni la caché de prompts, y no tiene un endpoint para contar tokens. Por eso, las cifras de tokens que ves 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 general de qué funciones se conservan y cuáles no se trata en si puedes alojar Claude por tu 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/. También permite fijar la ventana de contexto de cada modelo en .aider.model.settings.yml. Esto 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 según la VRAM (memoria de vídeo de la GPU) que puede detectar, y esos valores predeterminados están publicados:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB 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. Sólo una GPU grande obtiene los 262,144 tokens de la última fila.

Un agente envía 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 ese tamaño. A partir de ahí aparece el problema principal: no se produce 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 u olvida una instrucción que recibió dos pasos antes. Este mecanismo explica la mayoría de los informes según los cuales un modelo local es demasiado limitado para escribir código. Elegir el número también es una decisión independiente, y conviene leer cuánto cuesta num_ctx en la memoria de caché KV para cada tamaño antes de fijar un valor.

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

ollama ps es la comprobación. Muestra una columna CONTEXT, y ese número es el contexto que recibió realmente el modelo. Tus valores de ID y SIZE serán distintos:

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

Configúralo en el servidor y 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, el ajuste se aplica por servidor, así que todos los agentes que dirijas a ese equipo lo heredan. El límite de salida es independiente y, a diferencia de la longitud de contexto, sí se transmite mediante el endpoint compatible. Por tanto, num_predict y el campo max_tokens que se asigna a él son los parámetros que debes usar cuando una respuesta se interrumpe a mitad de un parche. Si un modelo necesita una ventana diferente, intégrala 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 debes vigilar. Cuando parte del modelo pasa a la CPU, la velocidad de generación de tokens disminuye tanto que el bucle de un agente se vuelve 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 contratarla 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 lectura de un diff, agotarse el temporizador y la siguiente solicitud volverá a cargar decenas de gigabytes de pesos desde el disco antes de mostrar el primer token. El resultado parece un bloqueo.

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. Establézcalo junto a la longitud de contexto:

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

El campo de solicitud keep_alive sólo existe en los endpoints nativos de Ollama /api/generate y /api/chat, no en los endpoints de compatibilidad, por lo que un agente no puede establecerlo por solicitud. La variable de entorno es la única opción disponible. Cuando necesite recuperar la memoria, ollama stop qwen3-coder:30b descarga el modelo sin detener el servidor. Si quiere conservar esta 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 en ambos casos.

Ejecutar Ollama en un servidor independiente

Ollama se enlaza a localhost. Para acceder desde otra máquina, establezca OLLAMA_HOST=0.0.0.0:11434 en el mismo override 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 tanto, si el puerto 11434 está abierto a Internet, cualquiera puede usar su hardware y leer todo lo que envíe su agente. 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 sigue apuntando a http://localhost:11434/v1 y no detecta ninguna diferencia. La otra opción es 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 mismo equipo, el planificador de Ollama no está diseñado para esa carga. la comparación entre Ollama y vLLM muestra a partir de qué punto la diferencia de rendimiento empieza a ser problemática.

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 la misma 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 los recuentos mostrados son aproximados.

¿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 según la VRAM detectada y, por debajo de 24 GiB, ese valor predeterminado es de 4,096 tokens. El prompt del sistema y las definiciones de herramientas de un agente ya superan ese límite por sí solos. 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 con la etiqueta tools que aún quepa en la memoria con una ventana de contexto de 64k, y prefiera uno ajustado 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 son una comparación útil 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 en ediciones de varios pasos, porque el trabajo de agente penaliza los pequeños errores de formato en las llamadas a herramientas. Pruebe una tarea real de su propio repositorio en lugar de 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 vuelve a leer un historial largo en cada una. Por eso, una tasa baja de tokens puede convertir una tarea de dos minutos en una hora. Compruebe la columna PROCESSOR en 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.