Usar Ollama con un agente de programación

A qué se conecta

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 admite simultáneamente dos formatos de solicitud. /v1/chat/completions es el formato compatible con OpenAI. La documentación de Ollama describe la clave como obligatoria, aunque se ignora. /v1/messages es el formato compatible con Anthropic, que es el que utiliza Claude Code. Su agente ya utiliza uno de los dos formatos. No es necesario cambiar nada más.

Esta parte requiere cinco minutos. Que el resultado sea utilizable depende de dos ajustes que casi nadie modifica: la longitud del contexto y el tiempo de mantenimiento de la conexión. 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 expone una opción para configurar la URL base? Si la expone, 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 los casos a los que se refiere la expresión agente de programación en agosto 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 necesita un endpoint compatible con OpenAI. Indique 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 sirve /v1/messages.
• Codex usa la API OpenAI Responses. Ollama también sirve /v1/responses, disponible desde la versión 0.13.3.
• Un agente que no tenga una 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 insertada 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.

Instale Ollama y descargue un modelo que pueda invocar 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 la invocación de herramientas, porque así es como funciona un agente. Lee un archivo, escribe un parche, ejecuta la prueba, lee el fallo y vuelve a intentarlo. Un modelo que no puede emitir una invocación de herramienta describirá la modificación en texto en lugar de realizarla, y el agente entrará en un bucle o se detendrá. Antes de descargarlo, busque la etiqueta tools en la página del modelo en ollama.com. qwen3-coder:30b la incluye y, en agosto de 2026, esa etiqueta corresponde a una descarga de 19 GB con una ventana de contexto de 256K.

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 la guía más extensa sobre alojar un LLM en un VPS con Ollama.

Configurar OpenCode para usar 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.

Configurar Claude Code para usar 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 deliberadamente como una cadena vacía. Si deja una clave real en el entorno, las solicitudes se envían a la API alojada, lo que genera un coste y evita la inferencia local. ollama launch claude configura todo esto automáticamente.

Debe conocer las funciones que la capa de compatibilidad no incluye. No implementa tool_choice ni el almacenamiento en caché de prompts, y no ofrece un endpoint para contar tokens. Por eso, las cantidades de tokens que se muestran 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é funciones se mantienen y cuáles no se trata en si puede alojar Claude por su cuenta.

Apuntar 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 para cada 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 incoherentes

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 consume 4096 tokens antes de realizar 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. A partir de ahí aparece el problema: 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 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.

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úrelo en el servidor:

sudo systemctl edit ollama.service

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

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Después, vuelva a cargar la configuración y reinicie:

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 lo que el modelo recibió realmente. Los 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úrelo en el servidor y no en el agente por dos motivos. El esquema de OpenAI chat completions 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 se aplica por servidor, de modo que todos los agentes que apunten a ese equipo la heredarán. Si un modelo necesita una ventana diferente, incorpórela 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, por lo que debe supervisar la columna PROCESSOR. 100% GPU es el valor que necesita. Cuando parte del modelo pasa a la CPU, la velocidad de generación de tokens disminuye tanto que el bucle de un agente deja de ser utilizable. Medir los tokens por segundo en un LLM local permite encontrar el límite real de su 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 un agente. Puede pausar la ejecución para revisar un diff, el temporizador termina 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. Defínalo junto con la longitud del 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 /api/generate y /api/chat de Ollama, no en los endpoints de compatibilidad, por lo que un agente no puede definirlo 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.

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 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 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 redirija 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 nota la 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 un problema.

Dónde destaca un modelo de código local y dónde no

Un agente impulsado por un modelo que aloja usted no sustituye a una API de frontera en todas las tareas. Destaca claramente en cuatro tipos de trabajo.

• Ediciones mecánicas masivas, donde cada cambio es pequeño y puede comprobarlo. Cambiar nombres en un repositorio, añadir sugerencias de tipos, escribir docstrings o traducir comentarios. El modelo puede ejecutarse durante horas sin aumentar la factura.
• Trabajo que no debe salir de su hardware. Por ejemplo, código de cliente sujeto a un acuerdo de confidencialidad o un repositorio interno que no puede 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 GPU VPS alcanza el punto de equilibrio frente a los tokens de una API contiene los cálculos.

Pierde eficacia en tareas largas con varios pasos. «Averigua por qué falla esta prueba, corrige la causa y actualiza las llamadas» requiere muchas llamadas correctas a herramientas seguidas, con todo el historial todavía en el contexto. Un modelo del rango de 8B a 14B en un servidor modesto generará una llamada a una herramienta con un formato incorrecto o perderá el plan después de unos turnos. Entonces dedicará más tiempo a orientarlo que el 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 eficacia 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 un modelo alojado para el trabajo que no revisarí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 su 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 tanto, 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 y sus definiciones de herramientas ya ocupan toda la ventana de contexto. Compruebe la etiqueta tools en la página del modelo y después la columna CONTEXT de ollama ps.

Hay una espera larga antes del primer token y después la velocidad es normal. El tiempo de mantenimiento de la conexión 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 ha truncado el contexto. ollama ps suele mostrar un valor CONTEXT menor del que cree haber configurado porque la variable de entorno se definió 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.

FAQ

¿Puedo conectar Claude Code a Ollama?

Sí, pero no con 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 la 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 disponible. Por debajo de 24 GiB, ese valor predeterminado es de 4,096 tokens, una cantidad que el prompt del sistema y las definiciones de herramientas de un agente superan 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 debo ejecutar para un agente de programación en un VPS?

Elija el modelo más grande que tenga la etiqueta tools y que aún quepa 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. 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 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 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 usando sólo la 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 velocidad baja de generación de tokens puede convertir una tarea de dos minutos en una tarea de 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 velocidad de generación de tokens disminuye considerablemente.