OpenCode + Ollama: un agente de código en tu terminal

#OpenCode con Ollama: quién hace qué

OpenCode es un agente de programación de código abierto que se ejecuta en el terminal: lee tu proyecto, modifica archivos y ejecuta comandos. No proporciona un modelo por sí mismo. Ollama, por su parte, descarga y ejecuta modelos en tu máquina y expone una API local. Los dos se complementan: OpenCode envía sus solicitudes a Ollama, que responde con un modelo local. Por tanto, no se trata de elegir entre «OpenCode u Ollama»: se utilizan los dos.

El interés del uso local no es ideológico. Un agente de código ve todo: la estructura de directorios, los archivos de configuración, la lógica de negocio. Con un modelo local, este contexto permanece en la máquina, sin facturación por token ni dependencia de la red. El precio a pagar es la capacidad: un modelo local de unas pocas decenas de miles de millones de parámetros no iguala a los mayores modelos alojados en servidores, y las tareas largas se ejecutan más lentamente.

#Requisitos: máquina, terminal y Ollama

Ollama en funcionamiento

Verifica que un modelo responda antes de configurar nada: ollama list, luego ollama run con un modelo de código. Si funciona, solo queda la configuración de OpenCode.

Un terminal moderno

La documentación de OpenCode menciona WezTerm, Alacritty, Ghostty y Kitty. En Windows, recomienda usar WSL para obtener un mejor rendimiento y una compatibilidad completa.

Memoria para el contexto

Un agente lee archivos y acumula el historial. Ollama indica que OpenCode exige una longitud de contexto de al menos 64 000 tokens, lo que aumenta la memoria necesaria más allá de los pesos del modelo.

Un repositorio git

No obligatorio, pero recomendado: un git diff o un git restore anula correctamente una sesión fallida.

#Instalar OpenCode y conectarlo a Ollama

OpenCode se instala mediante un script o mediante gestores de paquetes. La documentación lista el script oficial, npm, bun, pnpm, yarn, Homebrew, Arch, Chocolatey, Scoop, Mise y Docker. Para macOS y Linux con Homebrew, recomienda el tap oficial en lugar de la fórmula base, que se actualiza menos frecuentemente.

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#Método rápido: ollama launch opencode

Ollama sabe lanzar OpenCode con un modelo seleccionado. El comando ollama launch opencode arranca OpenCode con una configuración pasada por línea de comandos, sin sobrescribir tu archivo ~/.config/opencode/opencode.json; tus ajustes existentes de OpenCode siguen aplicándose. Con la opción --config, Ollama configura OpenCode sin abrir una sesión interactiva. Los modelos definidos solo en opencode.json no aparecen en el selector de ollama launch.

ollama launch opencode

#Método manual: declarar Ollama como proveedor

Si prefieres mantener el control, añade un proveedor al archivo opencode.json, ya sea el global (~/.config/opencode/opencode.json) o el situado en la raíz del proyecto. El endpoint de Ollama compatible con OpenAI es http://localhost:11434/v1. Cada clave bajo models debe coincidir exactamente con el nombre del modelo tal como aparece en ollama list.

{
  "$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" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

Reinicia OpenCode: el selector de modelo muestra los modelos declarados bajo el proveedor Ollama.

#La trampa número uno: la longitud del contexto

Muchos de los primeros intentos fallan porque el contexto es demasiado corto: el agente pierde el comienzo de la tarea, repite sus lecturas de archivos o produce modificaciones incoherentes. Ollama no fija un contexto único: la documentación indica 4k tokens por debajo de 24 GB de VRAM, 32k entre 24 y 48 GB y 256k a partir de 48 GB. Especifica que las tareas que requieren un gran contexto, como los agentes y las herramientas de código, deben configurarse con al menos 64.000 tokens.

Para cambiar el valor, existen dos opciones. En la aplicación Ollama, un control deslizante en los ajustes fija el contexto. En la línea de comandos, la variable OLLAMA_CONTEXT_LENGTH se aplica al iniciar el servidor. Un contexto más grande consume más memoria: comprueba con ollama ps que el modelo cabe por completo en la GPU, ya que un modelo que pasa a ejecutarse parcialmente en la CPU se vuelve muy lento.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#¿Qué modelo local para un agente de código?

Un agente debe llamar a herramientas de forma fiable: leer, escribir, ejecutar. Elige un modelo que muestre la capacidad tools en la biblioteca de Ollama. Estos son algunos candidatos cuyas etiquetas y tamaños se han registrado en ollama.com.

Estos tamaños corresponden a los archivos; añade la caché de contexto, que crece con los 64.000 tokens solicitados. El modelo de 15 GB (Devstral Small 2) es el más accesible en una máquina de 24 GB; el de 19 GB (Qwen3-Coder 30B) requiere más margen. En una máquina más modesta, un modelo más pequeño ejecuta tareas sencillas y específicas, pero pierde eficacia antes al refactorizar código que afecta a varios archivos.

#Un flujo de trabajo real: añadir una ruta y su prueba

Caso concreto: añadir una ruta GET /health a una pequeña API Express y cubrirla con un test. La documentación de OpenCode recomienda comenzar por /init, que analiza el proyecto y crea un archivo AGENTS.md en la raíz, que debes incluir en un commit de git para ayudar al agente a entender la estructura.

1. 01
   Abrir el proyecto

   Sitúate en la raíz del repositorio, ejecuta opencode y, la primera vez, ejecuta después /init. Comprueba en la parte inferior que el modelo seleccionado sea realmente un modelo de Ollama.
2. 02
   Cambiar al modo Plan

   La tecla Tab cambia entre los modos Plan y Build. El modo Plan desactiva las modificaciones: el agente solo sugiere cómo procedería. Pídele un plan antes de cualquier cambio.
3. 03
   Describir la tarea

   Da el contexto como a un desarrollador junior: «Agrega una ruta GET /health en src/server.js que devuelva status ok, luego un test en test/health.test.js». El carácter @ permite buscar un archivo en el proyecto.
4. 04
   Cambiar al modo Build

   Cuando el plan te satisfaga, presiona nuevamente Tab y pide aplicar los cambios.
5. 05
   Ejecutar e iterar

   El agente puede ejecutar npm test, leer la salida y corregir. Este ciclo de ejecutar, observar y corregir es el núcleo del funcionamiento de los agentes de IA.
6. 06
   Verificar y hacer commit

   Revisa git diff antes de hacer un commit. Si la sesión se ha desviado, git restore devuelve los archivos al estado anterior.

Con un modelo local, cada paso es más lento que con un modelo alojado, y una instrucción ambigua a veces requiere reformulación. La ventaja es el control: el código y el contexto permanecen en tu máquina, y tú eliges el modelo, su cuantización y su tamaño de contexto según tu hardware.

#Permisos: lo que el agente puede hacer sin pedirte permiso

Una idea extendida es que el agente no modifica nada sin tu consentimiento. Ese no es el comportamiento por defecto. La documentación de OpenCode indica que, sin configuración, la mayoría de los permisos tienen el valor allow, es decir, las acciones correspondientes se ejecutan sin preguntar; solo algunos, como external_directory y doom_loop, tienen el valor ask. Por defecto, se deniega la lectura de los archivos .env, salvo .env.example.

Para un agente que controla un modelo local menos confiable, es prudente aplicar un ajuste más estricto. El archivo opencode.json admite una sección permission en la que cada acción tiene el valor allow, ask o deny, incluida una regla global * con el valor ask.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode, Cline o Aider: ¿cuál elegir?

Los tres utilizan la API de Ollama; probar los dos más cercanos a tus hábitos tarda una hora y es mejor que un comparativo. Para autocompletado en línea en lugar de un agente, mira Tabby.

#Solución de problemas

El modelo no aparece

El nombre en opencode.json no coincide con ollama list. Copia el nombre exacto, incluyendo el tag. Al usar ollama launch, un modelo definido solo en opencode.json no aparece en su selector.

El agente olvida lo que acaba de leer

El contexto es demasiado corto: pasa a 64 000 tokens (OLLAMA_CONTEXT_LENGTH) y verifica con ollama ps.

Conexión rechazada

El servidor Ollama no está funcionando o no está escuchando en el puerto predeterminado 11434. Prueba ollama list, luego la URL de baseURL.

Llamadas a herramientas que fallan

El modelo no maneja bien las herramientas. Elige un modelo marcado como tools en la biblioteca Ollama.

Respuestas muy lentas

El modelo y su contexto superan la capacidad de la VRAM y parte de la ejecución se realiza en el procesador. Reduce el contexto, el tamaño del modelo o la cuantización.

#Para ir más allá

• Cline + Ollama en VS Code
• Aider + Ollama en el terminal
• Tabby: autocompletado local de código
• Elegir tu cuantización
• Comprender la ventana de contexto
• Instalar Ollama en 5 minutos

• Fuente: Ollama, integración OpenCode
• Fuente: Ollama, longitud de contexto
• Fuente: documentación de OpenCode
• Fuente: permisos de OpenCode