Usar Ollama con un agente de programación

Qué está conectando

Puede usar Ollama con su agente de programación. La conexión requiere menos cambios de lo que suele esperarse. Cambie una URL base y seleccione un nombre de modelo. El campo de clave de API sigue requiriendo un valor, pero el servidor local lo ignora. Por tanto, puede usar cualquier cadena.

Ollama escucha en el puerto 11434 y ofrece dos formatos de solicitud al mismo tiempo. /v1/chat/completions es el formato compatible con OpenAI. La documentación de Ollama indica que la clave es obligatoria, pero se ignora. /v1/messages es el formato compatible con Anthropic, que es el que usa Claude Code. Su agente ya usa uno de los dos formatos. No necesita cambiar nada más.

Esta parte requiere cinco minutos. La utilidad del resultado depende de dos ajustes que casi nadie cambia: la longitud de contexto y el keep-alive. También depende de asignar al modelo el tipo de trabajo que realiza 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 consiste en 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 las herramientas que se consideran agentes de programación en agosto de 2026. No todas usan el mismo formato, y ahí es donde fallan las configuraciones.

• La mayoría de los agentes requieren un endpoint compatible con OpenAI. Indíqueles la URL base http://localhost:11434/v1 y cualquier cadena no vacía como clave de 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 que no permita configurar una 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 que pueda llamar 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í 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 prosa en lugar de realizarla, 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 agosto de 2026, esa etiqueta requiere una descarga de 19 GB y ofrece una ventana de contexto de 256K. Si su servidor sólo usa CPU o tiene poca RAM, la aritmética 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 ocuparán el disco raíz del servidor, que es la parte de un VPS con menos espacio disponible, por lo que conviene leer dónde guarda Ollama sus archivos de modelos y cómo moverlos a otra ubicación antes de que se llene 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. Comprobarlas primero resuelve la mayoría de los errores de modelo no encontrado. Si todavía no ha instalado Ollama, consulte la guía más extensa sobre cómo 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 incoherentes

Esta es la sección importante. Ollama elige una longitud de contexto predeterminada a partir de 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 consume 4096 tokens antes de empezar a trabajar. El prompt del sistema, las definiciones de las herramientas, el listado del repositorio y el primer archivo que abre ya superan ese límite. Ahí está todo el problema: no aparece 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 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 memoria de caché KV para cada tamaño 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

ollama ps es la comprobación. Imprime una columna CONTEXT, y ese número es el que el modelo recibió realmente. 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 en lugar de hacerlo 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 específica del servidor, así que todos los agentes que apuntes a ese equipo la heredarán. El lado de salida tiene su propio límite 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 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 pasa a la CPU, la tasa 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. Cuánta RAM y CPU necesita un VPS para un agente de programación explica cómo dimensionar la máquina antes de comprarla.

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 textos 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 indica que el modelo no existe. El nombre de la configuración no coincide con ningún nombre que ofrezca 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 descargó falla aunque haya un modelo similar instalado.

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

Hay un silencio prolongado antes del primer token y después la velocidad es normal. El tiempo de permanencia expiró 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 truncó el contexto. ollama ps suele mostrar un valor de CONTEXT menor del que cree haber configurado, porque la variable de entorno se estableció en su shell en lugar de en la unidad de systemd.

Todo funciona, pero lentamente, y PROCESSOR no es 100% GPU. El modelo y su contexto no caben en la VRAM. Reduzca la longitud del contexto o cambie a un modelo más pequeño o a una cuantización menor. Antes de volver a descargarlo, qué coste de memoria tienen q4_K_M, q8_0 y fp16, y dónde se pierde realmente calidad explica cuánto espacio se obtiene al bajar un nivel y qué se sacrifica a cambio.

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.