¿Qué es OpenCode?
OpenCode es un agente de código de Inteligencia Artificial (IA) open source que se despliega en local. Está diseñado para acompañar al desarrollador en la elaboración de código y en otras cuestiones relacionadas con el trabajo del día a día. OpenCode integra diversos modelos de lenguaje grande (LLMs), tanto locales como a través de APIs, algunos de los cuales se analizarán en este post.
Instalación de OpenCode y primeros pasos
Para empezar a utilizar OpenCode, se puede ejecutar el script de instalación proporcionado por la propia herramienta:
curl -fsSL https://opencode.ai/install | bashUna vez instalado, es posible modificar la configuración global a través de un json situado en la ruta ~/.config/opencode/opencode.json. Además, este json también se puede configurar a nivel de proyecto situándolo en la ruta base del mismo. Más adelante en el post se usará para añadir modelos locales.
Cuando esta parte esté lista, ya se puede lanzar la herramienta en la terminal o como aplicación web para el navegador utilizando los siguientes comandos, respectivamente:
opencode
opencode web
En este artículo se utilizará la versión web por ser más familiar y parecida a otros servicios de IA. Para empezar a trabajar sobre un proyecto se debe hacer click en el icono + en la barra izquierda o pulsar Ctrl+O.
Una vez dentro del proyecto deseado, se puede empezar a hablar con el agente. El cuadro de texto también permite lanzar una serie de comandos empezando por el carácter /. Si es un proyecto ya existente, al ejecutar el comando /init se generará un fichero AGENTS.md en el proyecto según su contenido. Más adelante, se ejemplificará en el post cómo funciona este fichero.
Además, justo debajo del cuadro de texto, se encuentran dos selectores rápidos. El primero permite cambiar la modalidad del agente entre planificar acciones según la entrada del usuario (plan) o hacer la ejecución directamente (build). El segundo selector permite cambiar de modelo fácilmente. A continuación, se explorarán algunas opciones de modelos.
Configuración de modelos en OpenCode
OpenCode permite una gran variedad de modelos de lenguaje LLM a los cuales conectarse ya que se integra con plataformas como AI SDK y Models.dev. En la documentación se puede encontrar una larga lista de proveedores a los cuales conectarse. En esta sección se explorarán algunas opciones gratuitas de las que el usuario puede disponer para probar esta herramienta.
Modelos Zen de OpenCode
OpenCode Zen es una plataforma creada por el propio OpenCode. Dicha plataforma está dotada de múltiples modelos que han sido verificados y testeados para funcionar con OpenCode. Además, ofrece una API a la cual conectarse. No obstante, hay una serie de modelos que se ofrecen de manera gratuita y están directamente disponibles en la instalación de la herramienta. Estos modelos se ofrecen de manera temporal con el propósito de testearlos y verificar su funcionamiento, por lo que a veces puede haber más o menos modelos disponibles.
Por otro lado, si se desea usar los modelos de pago disponibles a través de la API, hay que logearse en la web de OpenCode Zen. Seguidamente, se debe copiar la clave API:
A continuación, se debe lanzar el siguiente comando desde terminal, seleccionar OpenCode Zen y pegar la clave API:
opencode auth loginDespués de añadir el modelo, se debe reiniciar OpenCode, si estaba abierto.
Integración de Gemini en OpenCode
La integración de los modelos Gemini de Google en OpenCode proporciona acceso a una de las IAs más potentes, además de modelos de acceso gratuito. Para tener acceso a estos modelos, hay que loguearse en la plataforma de AI Studio de Google e ir al panel para obtener una clave API.
Una vez ahí, se debe crear una clave, asignarle un nombre identificativo y también un proyecto de Google Cloud. Si no se desea utilizar modelos de pago y, por tanto, requerir de una cuenta de facturación, se puede utilizar el proyecto por defecto de Gemini, como se muestra en la siguiente captura de pantalla:
Cuando ya se ha obtenido la clave API, hay que seguir los mismos pasos que con Zen: ejecutar el siguiente comando desde terminal, seleccionar el proveedor de Google y pegar la clave API:
opencode auth login
Esto activa el acceso a los modelos desde la UI después de reiniciar OpenCode, si estaba abierto:
Modelos locales con Ollama
Los proveedores y sus APIs no son la única manera de configurar un modelo para OpenCode. Si se dispone de una máquina potente, el usuario puede optar por utilizar un modelo alojado localmente. Esto permite ahorrar gastos, sobre todo si se dispone de infraestructura para hospedar modelos LLM muy grandes.
Instalación y configuración de Ollama
Una manera de enlazar OpenCode con modelos locales es con Ollama. Esta herramienta se puede instalar de la siguiente manera:
curl -fsSL https://ollama.com/install.sh | shConfigurar un modelo de Ollama para ser utilizado en OpenCode no es tan sencillo como las otras opciones. En primer lugar, se debe descargar el modelo deseado. Ollama dispone de una librería grande de modelos que provienen de diferentes proveedores y tienen requerimientos de máquina. En este ejemplo, se empieza con el modelo qwen3.5:4b y se puede descargar con el siguiente comando:
ollama pull qwen3.5:4bSi el modelo no requiere más configuración, se puede incorporar a OpenCode modificando el fichero de configuración ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3.5:4b": {
"name": "Qwen3.5 4B"
}
}
}
}
}
Dependiendo del modelo y de la máquina, es posible que se requiera modificar el contexto máximo permitido. Ollama establece unos valores de contexto dependiendo de la capacidad de VRAM de tu sistema. Estos límites están para asegurar que ejecutar un modelo no requiera de volcado a RAM (o disco) y que se realice de manera fluida y rápida. No obstante, el límite inferior para gráficas con menos de 24GB de VRAM sitúa a muchos sistemas para usuarios corrientes en un contexto de 4k. Para realizar pruebas con OpenCode, esta longitud ventana de contexto no es lo suficientemente grande.
Para modificar el tamaño del contexto, hay que cambiar la variable de entorno OLLAMA_CONTEXT_LENGTH. Si el usuario lanza el servidor de Ollama manualmente, esto se puede hacer con el siguiente comando:
OLLAMA_CONTEXT_LENGTH=16384 ollama servePor otro lado, si el usuario decide lanzar el servidor en segundo plano a través de un servicio, se puede añadir al fichero /etc/systemd/system/ollama.service la siguiente línea en el bloque de [Service]:
Environment="OLLAMA_CONTEXT_LENGTH=16384"Y, a continuación, reiniciar el servicio:
sudo systemctl daemon-reload
sudo systemctl restart ollama.serviceConfiguración del proyecto
El comportamiento central y la arquitectura del agente OpenCode en un proyecto o repositorio se definen a través del archivo de configuración AGENTS.md. En este fichero el usuario (o el propio agente) puede definir reglas o instrucciones que se pasarán al contexto del agente. Además, estos ficheros se pueden incluir en cualquier subcarpeta del proyecto, personalizando el agente jerárquicamente.
Para crear un fichero AGENTS.md, simplemente hay que redactar en el fichero markdown algunas reglas de funcionamiento. No tiene ninguna estructura estricta. Si se parte de un proyecto ya existente, se puede ejecutar el comando /init dentro de la sesión con el agente. En el siguiente ejemplo, se han creado dos ficheros de código Python para mover 2 entidades aleatoriamente:
En la siguiente imagen se puede observar el resultado de ejecutar el comando /init. El agente ha hecho un resumen breve del contenido del código. En consultas futuras, se incluirá este contexto para facilitar las acciones del agente.
Como se ha dicho anteriormente, estos ficheros de configuración se pueden incluir en las subcarpetas del proyecto con diferentes instrucciones. En el siguiente ejemplo, se han creado dos subcarpetas con instrucciones diferentes: en una el estilo de código es funcional y en la otra está orientado a objetos.
Se han creado dos sesiones diferentes donde se le ha pedido al agente crear código para leer y deduplicar un csv, pero en cada sesión se le ha solicitado escribir el código en una carpeta diferente. El resultado es más o menos el esperado. En la carpeta de funciones ha escrito funciones y en la carpeta de objetos ha programado orientado a objetos.
Configuración de Skills de OpenCode
La funcionalidad de OpenCode puede expandirse considerablemente mediante la configuración de habilidades o skills. Las skills son herramientas o funciones personalizadas que el agente puede ejecutar de manera automática o manual usando el comando /nombre_skill dentro de la sesión. Configurar estas habilidades permite al usuario dotar al agente de capacidades especializadas, mejorando su eficacia y precisión en tareas nicho o recurrentes.
Para configurar una skill con nombre <skill_name> a nivel de proyecto es necesario crear un fichero en la ruta .opencode/skills/<skill_name>/SKILL.md. Al igual que AGENTS.md, también se puede describir la skill que deseamos directamente al agente y este intentará crearla. El fichero SKILL.md es un fichero markdown que debe tener un bloque de metadatos en formato YAML al inicio. Estos metadatos deben incluir obligatoriamente los siguientes pares clave-valor:
- name: nombre de la skill formado por letras minúsculas, números y guiones. Debe ser igual a
<skill_name>marcado por la ruta del fichero. - description: un resumen de la skill que debe indicar qué hace y cuándo usarla.
A partir de aquí, se pueden redactar los detalles en el cuerpo del fichero markdown. Se recomienda usar un lenguaje conciso pero con todo lo necesario para que no llene el contexto del agente. Algunos ejemplos de skills incluyen plantillas que el agente deba usar o fragmentos de código a utilizar.
En el siguiente ejemplo, se crea una skill create-transformer con una plantilla para crear clases que transforman datos.
Después de reiniciar OpenCode para cargar las skills, se le pide al agente que cree una transformación con el siguiente prompt:
I have sales data and i would like to aggregate it by date, client_country and product_category. I want to see the aggregated total_sales_eur and number of sales. Can you write me the code in the root folder of the project?Pese a no nombrar la palabra “transform” ni decirle que ejecute la skill, el agente ha sabido detectar automáticamente que debía utilizar la nueva skill:
Conclusión
OpenCode es un agente de código abierto diseñado para acompañar al desarrollador en su elaboración de código y otras tareas diarias, desplegándose en local. En este post se ha abordado cómo esta herramienta es capaz de integrarse con múltiples proveedores como Zen, Google y Ollama, para dar acceso a diversos modelos LLM (y algunos de ellos de forma gratuita).
A continuación, se ha visto como configurar OpenCode a nivel de proyecto a través del fichero AGENTS.md. En él se pueden determinar las reglas e instrucciones que el agente incluirá en su contexto. Además, se puede configurar carpeta a carpeta para crear unas reglas más personalizadas.
Finalmente, la funcionalidad de OpenCode se expande considerablemente mediante la configuración de habilidades o skills. Estas se definen a través del archivo SKILL.md y permiten dotar al agente de capacidades especializadas para mejorar su eficacia en tareas específicas o recurrentes.
Hasta aquí nuestro post de hoy. Si te ha parecido interesante, te animamos a visitar la categoría Software para ver artículos similares y a compartirlo en redes con tus contactos. ¡Hasta pronto!
