Tutorial de OpenCode

¿Te suena esta situación? Llevas horas depurando un error, le pides ayuda a tu agente de IA favorito, te da una solución genial… y luego te das cuenta de que todo tu código ha salido de tu máquina hacia los servidores de alguien. O peor: el modelo que usabas deja de estar disponible, cambia de precio, o simplemente tu empresa decide que no puede enviar código propietario a la nube de otro.

Bienvenido al mundo del lock-in de modelos. Es el nuevo vendor locking, pero con IA.

Cada semana sale un agente nuevo. Cada mes un modelo diferente es el mejor. Cada trimestre tu herramienta favorita cambia de precio, de licencia o de política de privacidad. Y mientras tanto, tu código —tu propiedad intelectual— viaja por servidores que no controlas, alimentando modelos que no son tuyos.

OpenCode llega para romper ese círculo. Es un agente de IA para programar desde la terminal, completamente open source (MIT), que funciona con más de 75 proveedores de modelos —incluyendo modelos locales con Ollama— y que mantiene tu código en tu máquina. Siempre.

Este tutorial arranca desde lo básico. No necesitas saber de IA, ni de agentes, ni haber usado ninguna herramienta similar. Solo necesitas un equipo con Linux, macOS o Windows, una terminal y ganas de aprender a programar con inteligencia artificial sin ataduras.

¿Qué es OpenCode? (el resumen)

Antes de meternos en materia, necesitas tener claro de qué estamos hablando.

OpenCode es un agente de IA para programar desde la terminal. Corre en Linux, macOS y Windows como un único binario. Es open source (licencia MIT), lo que significa que puedes leerlo, modificarlo, redistribuirlo y usarlo sin restricciones.

Su característica más diferencial: no estás atado a ningún modelo. Puedes usar Claude, GPT, Gemini, DeepSeek, modelos locales con Ollama, o cualquiera de los más de 75 proveedores que soporta. Cambias de modelo con un cambio de configuración, sin migrar de herramienta.

Y lo más importante para muchos: tu código no sale de tu máquina. OpenCode envía los prompts necesarios al proveedor que elijas, pero el código fuente, los archivos y el historial de la sesión permanecen en tu equipo. Esto es fundamental para empresas con políticas de seguridad estrictas, sectores regulados o simplemente para quien no quiere que su código alimente modelos ajenos.

Si quieres una explicación más detallada de qué es OpenCode, de dónde viene y cómo se compara con otras herramientas, ese es precisamente el contenido del Capítulo 1. Aquí estamos poniendo los cimientos.

¿Por qué existe este tutorial?

Porque OpenCode tiene una curva de aprendizaje. No es difícil, pero tiene muchas piezas: proveedores, skills, subagentes, MCP, modos de trabajo, graphify, codegraph… Y la documentación oficial, aunque completa, está en inglés y está pensada como referencia, no como ruta de aprendizaje.

Este tutorial es exactamente lo contrario: una ruta progresiva. Cada capítulo se apoya en el anterior. Empiezas sin saber nada y terminas usando OpenCode en producción con skills personalizados, subagentes, integración con bases de datos y flujos de trabajo para tu equipo.

No hay saltos. No hay «asumiendo que sabes X». Cada concepto se introduce cuando toca, con ejemplos prácticos que puedes seguir en tu máquina.

Además, el tutorial está en español. Porque la tecnología no debería tener barreras idiomáticas.

Roadmap del tutorial: 20 capítulos en 7 bloques

Este tutorial tiene 20 capítulos organizados en bloques temáticos. Cada bloque construye sobre el anterior. Puedes saltarte capítulos si ya conoces algunos conceptos, pero la ruta está diseñada para seguirlos en orden.

Bloque 1 — Fundamentos (Capítulos 01–02)

Los cimientos. Aquí entiendes qué es OpenCode, de dónde viene, por qué es diferente, y lo instalas en tu sistema.

• 01 — ¿Qué es OpenCode? Del equipo SST a 165K estrellas. Origen, filosofía, comparativa con Claude Code, Codex CLI, Cline y Aider.
• 02 — Instalación y primeros pasos. Los cinco métodos de instalación, verificación, primer prompt, estructura de directorios y solución de problemas.

Bloque 2 — Interfaz y modelos (Capítulos 03–06)

Una vez que OpenCode está instalado, toca aprender a usarlo y a elegir con qué modelo trabajar.

• 03 — Interfaz TUI. Cómo moverse por la interfaz de terminal, paneles, atajos de teclado, historial, búsqueda.
• 04 — Modelos locales con Ollama. Ejecuta modelos de IA en tu propia máquina. Sin internet, sin enviar datos a ningún sitio.
• 05 — APIs cloud. Configura y usa proveedores cloud: Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral y más de 75 proveedores.
• 06 — Multi-modelo. Cómo usar diferentes modelos para diferentes tareas. Cambia de modelo en medio de una sesión sin perder contexto.

Bloque 3 — Flujo de trabajo (Capítulos 07–09)

Aquí es donde OpenCode empieza a mostrar su verdadero potencial como herramienta de desarrollo.

• 07 — Plan vs Build. Los dos modos fundamentales: análisis sin efectos y ejecución con acceso completo. Cómo combinarlos para proyectos complejos.
• 08 — Sesiones árbol. OpenCode organiza las conversaciones en árboles de decisión. Ramifica, explora alternativas, vuelve atrás sin perder trabajo.
• 09 — Modo headless. OpenCode sin interfaz interactiva, ideal para CI/CD, automatización y pipelines. Integración con scripts y herramientas.

Bloque 4 — Personalización (Capítulos 10–11)

OpenCode se adapta a tu forma de trabajar, no al revés.

• 10 — Skills. Instrucciones reutilizables para el agente. Codifica las convenciones de tu equipo, estilos de código, patrones de testing.
• 11 — System prompts. Personaliza el comportamiento del agente a nivel profundo. Cómo escribir prompts efectivos para cada tipo de tarea.

Bloque 5 — Herramientas (Capítulos 12–16)

El ecosistema que amplía las capacidades de OpenCode más allá del código.

• 12 — Graphify. Visualiza el grafo de llamadas y dependencias de tu código. Entiende proyectos grandes antes de modificarlos.
• 13 — CodeGraph. Construye un grafo de contexto que OpenCode usa para entender mejor proyectos complejos.
• 14 — Herramientas imprescindibles. El toolkit que todo usuario de OpenCode debería conocer: MCP servers, integraciones, utilidades.
• 15 — RAG en OpenCode. Recuperación aumentada de generación: cómo OpenCode busca y usa información de tu base de código y documentación interna.
• 16 — Bases de datos y APIs. Conecta OpenCode con PostgreSQL, MySQL, APIs REST, GraphQL. El agente consulta esquemas y entiende tus datos.

Bloque 6 — Avanzado (Capítulos 17–19)

Para cuando ya dominas lo básico y quieres exprimir OpenCode al máximo.

• 17 — Documentación legacy. Cómo integrar documentación existente (PDFs, wikis, Confluence, Notion) para que OpenCode la use como contexto.
• 18 — Subagentes. @explore, @scout, @build, @plan. Cómo delegar tareas a agentes especializados dentro de una misma sesión.
• 19 — Configuración definitiva. El archivo de configuración óptimo. Proveedores, modelos por defecto, skills globales, MCP servers, hooks.

Bloque 7 — Producción (Capítulo 20)

El capítulo que cierra el círculo: OpenCode en entornos reales, con equipos y en producción.

• 20 — Producción y seguridad. Buenas prácticas para equipos, integración con CI/CD, políticas de seguridad, auditoría de acciones, gestión de secrets, cumplimiento normativo.

¿Para quién es este tutorial?

Este tutorial está escrito para:

• Desarrolladores que quieren dejar de depender de un único proveedor de IA y recuperar el control sobre su código.
• Sysadmins y DevOps que necesitan integrar agentes de IA en sus pipelines sin comprometer la seguridad.
• Equipos de desarrollo que buscan una herramienta común que funcione para todos, independientemente del modelo que cada uno prefiera usar.
• Estudiantes y personas que empiezan con la programación asistida por IA y quieren hacerlo bien desde el principio.
• Cualquier persona que valore el software libre y quiera entender cómo funciona realmente su herramienta de IA, sin cajas negras.

No asumimos que sabes de inteligencia artificial, de agentes, ni de modelos de lenguaje. Sí asumimos que sabes usar la terminal, conoces los fundamentos de Linux (o macOS), has usado git alguna vez y tienes nociones básicas de desarrollo de software. Pero si alguna vez has abierto una terminal y has escrito cd, ls y git clone, estás dentro.

Requisitos

Los requisitos para seguir este tutorial son mínimos:

• Un ordenador con Linux, macOS o Windows. Cualquier sistema moderno vale. Si usas Linux, cualquier distribución reciente sirve. En macOS, desde Monterey (12) en adelante. En Windows, Windows 10 u 11 con PowerShell o Windows Terminal.
• Conexión a Internet. Necesaria para descargar OpenCode y para conectarte a los proveedores de IA (a menos que uses modelos locales con Ollama).
• Una terminal moderna. Cualquier terminal con soporte Unicode y truecolor. Recomendadas: Kitty, Alacritty, iTerm2, WezTerm, Windows Terminal, GNOME Terminal.
• Git (opcional pero muy recomendado). OpenCode lo usa para gestionar el historial de cambios. Sin Git funciona, pero pierdes capacidad de deshacer.

No necesitas:

• Conocimientos previos de IA. Todo se explica desde cero.
• Una GPU potente. Si usas modelos cloud, solo necesitas un navegador y conexión a Internet. Si usas modelos locales, un ordenador con 8 GB de RAM es suficiente para modelos pequeños y medianos.
• Node.js, Python ni ningún runtime. OpenCode se distribuye como binario compilado. No necesitas instalar nada más.
• Experiencia con otras herramientas de IA para código. Este tutorial parte de cero.

¿Y si vienes de otras herramientas?

Si ya has usado Claude Code, Cursor o GitHub Copilot, estás en buena posición. Muchos conceptos te resultarán familiares, pero hay diferencias que conviene señalar.

Si vienes de Claude Code

Claude Code es el agente oficial de Anthropic. Es excelente — probablemente la mejor calidad de razonamiento del mercado— pero tiene una limitación clave: solo funciona con modelos de Anthropic. Estás atado a su ecosistema, sus precios y su disponibilidad.

OpenCode te da exactamente la misma experiencia de agente en terminal, pero con la libertad de elegir cualquier modelo. Puedes seguir usando Claude (de hecho, es uno de los proveedores más populares en OpenCode), pero también puedes cambiar a GPT, Gemini, DeepSeek o un modelo local cuando quieras. Sin cambiar de herramienta, sin volver a aprender comandos.

Además, OpenCode es open source. Puedes auditar el código, contribuir, forkearlo. Con Claude Code, el código es cerrado. Dependes de Anthropic para cada actualización.

Si vienes de Cursor

Cursor es un IDE modificado con IA integrada. Es una experiencia diferente: tienes un editor completo con autocompletado, chat lateral, edición inline. Es cómodo, visual, y está muy pulido.

OpenCode no es un IDE. Es un agente que trabaja desde la terminal. La experiencia es más parecida a tener un compañero de programación que conversa contigo, entiende tu proyecto y ejecuta tareas. No escribes código tú — se lo pides al agente y él lo hace.

Si prefieres un IDE, Cursor es una gran opción. Si prefieres la terminal, el control total y no depender de un producto cerrado, OpenCode es tu herramienta. También puedes usar ambos: OpenCode para tareas pesadas de refactorización y Cursor para el día a día.

Otra diferencia fundamental: Cursor es propietario. OpenCode es MIT. Con Cursor, tus datos pasan por sus servidores. Con OpenCode, decides tú.

Si vienes de GitHub Copilot

GitHub Copilot revolucionó la programación asistida por IA. Su punto fuerte es el autocompletado en el editor: mientras escribes, te sugiere la siguiente línea. Es rápido, está integrado en todos los IDEs principales y funciona bien.

Pero Copilot es un asistente de autocompletado, no un agente. No ejecuta comandos, no modifica archivos, no mantiene una conversación contextual sobre tu proyecto. Es limitado por diseño.

OpenCode opera en una categoría diferente. Es un agente autónomo: entiende tu proyecto, ejecuta comandos, edita archivos, busca información, despliega. No solo completa líneas — construye funcionalidades completas.

Y al igual que con Cursor, Copilot es propietario. Tus fragmentos de código viajan a los servidores de GitHub/Microsoft. Con OpenCode, decides qué proveedor usas y qué datos compartes.

En resumen

Aspecto	OpenCode	Claude Code	Cursor	GitHub Copilot
Tipo	Agente CLI/TUI	Agente CLI/TUI	IDE con IA	Autocompletado
Código abierto	Sí (MIT)	No	No	No
Proveedores	75+	Solo Anthropic	Limitado	Solo OpenAI
Modelos locales	Sí (Ollama)	No	Limitado	No
Privacy-first	Sí	No	No	No
Skills/Hooks	Sí	Sí	No	No
Subagentes	Sí	Sí	No	No
Requiere IDE	No	No	Sí	Sí

Primeros pasos: un adelanto

Antes de instalar nada, puedes hacerte una idea de lo que es OpenCode. Si ya lo tienes instalado (viene por defecto en algunas distribuciones o lo has instalado por tu cuenta), abre un terminal y escribe:

opencode --version

Este comando te muestra la versión instalada. Algo como opencode version 1.18.0 o superior.

Si no lo tienes instalado, no te preocupes. En el capítulo 2 verás cómo hacerlo en los principales sistemas operativos.

Pero vamos a hacer un pequeño adelanto de lo que te espera. Cuando tengas OpenCode listo, puedes probar algo como esto:

opencode "Explica qué hace este proyecto en un párrafo"

O, si quieres algo más visual:

opencode

Sin argumentos, OpenCode arranca en modo TUI. Se abre una interfaz dentro de tu terminal con un panel de conversación, un panel de archivos y un área de entrada. Desde ahí puedes mantener una conversación completa con el agente, ver lo que hace en tiempo real y pedirle tareas complejas.

¿Ves? No hace falta registro, no hace cuenta en una plataforma, no hay un plan gratuito limitado. Solo tu terminal y OpenCode.

¿Qué ha ocurrido exactamente?

Cuando ejecutas opencode sin argumentos:

1. OpenCode lee su configuración de ~/.config/opencode/ para saber qué proveedor usar.
2. Si no hay configuración, te guía para configurar tu primer proveedor (puedes incluso usar modelos gratuitos).
3. Arranca la interfaz TUI con un panel de conversación vacío.
4. Escribes tu primer prompt y el agente empieza a trabajar: lee archivos, ejecuta comandos, edita código.
5. Todo el historial de la sesión se guarda localmente en ~/.local/share/opencode/sessions/.

En menos de un minuto tienes un agente de IA funcionando en tu máquina. Sin dependencias, sin demonios, sin servicios en segundo plano.

Lo que no cubre este tutorial

Para ser honesto desde el principio, hay cosas que este tutorial no va a cubrir:

• Uso de OpenCode como extensión de VS Code. El tutorial se centra en la experiencia desde la terminal (CLI y TUI). La extensión de VS Code es funcionalmente equivalente, pero la interfaz es diferente. Si usas VS Code, los conceptos de este tutorial te servirán igualmente, pero tendrás que adaptar los comandos a los menús y atajos del editor.
• OpenCode Desktop App. La aplicación de escritorio sigue en beta. Este tutorial cubre la versión estable de terminal. Si usas la app de escritorio, los conceptos son los mismos pero la navegación es gráfica.
• Programación de servidores MCP. Mencionamos MCP porque es parte del ecosistema, pero no vamos a enseñarte a programar tu propio servidor MCP desde cero. Eso es material para un tutorial aparte.
• Despliegue de modelos de IA. OpenCode se conecta a proveedores existentes. No vamos a enseñarte a entrenar, ajustar o desplegar tus propios modelos. Si quieres ejecutar modelos locales, usamos Ollama, que se encarga de todo eso.
• Historia de la IA. No vamos a repasar la historia de los modelos de lenguaje, ni las arquitecturas de transformers, ni los fundamentos del machine learning. Este tutorial es práctico: a usar OpenCode se aprende usando OpenCode.

Si alguno de estos temas te interesa, en la sección de referencias encontrarás enlaces a recursos más especializados.

Verificación

Antes de pasar al capítulo 1, asegúrate de que tienes claro lo que has aprendido aquí.

Conceptos clave

1. ¿Qué problema resuelve OpenCode? Explica por qué el lock-in de modelos es un problema real y cómo OpenCode lo aborda.
2. ¿Qué significa que OpenCode sea privacy-first? ¿Cómo gestiona tu código y qué implicaciones tiene para empresas con datos sensibles?
3. ¿Cómo se organiza el tutorial? Enumera los 7 bloques temáticos y di qué capítulos incluye cada uno.
4. ¿Cuál es la diferencia fundamental entre OpenCode y herramientas como Claude Code, Cursor o GitHub Copilot? No se trata de cuál es mejor, sino de qué filosofía y caso de uso tiene cada una.
5. ¿Qué necesitas para seguir el tutorial? ¿Y qué NO necesitas?

Comprobar que OpenCode está disponible

Si ya tienes OpenCode instalado:

opencode --version

Deberías ver algo como opencode version 1.18.0 o superior. Si el comando no se encuentra, no pasa nada. En el capítulo 2 lo instalaremos.

Batería de verificación rápida

Puedes copiar y pegar estas líneas en tu terminal para hacer una comprobación completa de tu preparación:

echo "=== Verificación para tutorial de OpenCode ==="
echo ""
echo "1. Sistema operativo:"
uname -a
echo ""
echo "2. Terminal:"
echo "$TERM - $(tput colors) colores"
echo ""
echo "3. Git disponible:"
git --version 2>/dev/null || echo "[NO INSTALADO - opcional]"
echo ""
echo "4. OpenCode instalado:"
opencode --version 2>/dev/null || echo "[NO INSTALADO - lo instalaremos en el capítulo 2]"
echo ""
echo "5. Espacio en disco:"
df -h ~ | tail -1 | awk '{print $4 " disponibles"}'
echo ""
echo "=== Todo listo para empezar ==="

Si todo está correcto, verás la información de tu sistema y sabrás si OpenCode está instalado o no. En cualquier caso, estás listo para el capítulo 1.

Marca tu progreso

Crea un archivo de progreso para llevar la cuenta de los capítulos que has completado:

mkdir -p ~/.tutorial-opencode
echo "00-introduccion: $(date)" >> ~/.tutorial-opencode/progreso.txt
cat ~/.tutorial-opencode/progreso.txt

Así puedes retomar el tutorial donde lo dejaste si tienes que interrumpirlo.

Conclusión

Los agentes de IA para programar van a cambiar la forma en que escribimos código. Pero esa transformación no tiene por qué venir acompañada de dependencia, pérdida de privacidad ni lock-in. OpenCode demuestra que se puede tener un agente potente, flexible y respetuoso con tu código y tu libertad.

En este capítulo introductorio has visto por qué OpenCode existe, qué problema resuelve, cómo se organiza el tutorial y si esto es para ti. También has visto un adelanto de lo que puedes hacer cuando lo tengas instalado.

Si algunos conceptos te parecen abstractos todavía, no te preocupes. El capítulo 1 te dará el contexto histórico y técnico, el capítulo 2 te pondrá OpenCode funcionando en tu máquina, y a partir del capítulo 3 empezarás a usarlo de verdad.

Lo importante ahora es que entiendas el para qué. OpenCode no es una herramienta más. Es una forma diferente de entender la relación entre el desarrollador y la IA: sin intermediarios, sin ataduras, sin comprometer tu código.

En el siguiente capítulo, Qué es OpenCode, te contaré la historia completa: cómo nació, quién está detrás, cómo ha evolucionado en menos de un año hasta convertirse en el agente de IA para código con más estrellas de GitHub, y cómo se compara con las alternativas del mercado.

Y recuerda: no necesitas saber nada de IA para seguir este tutorial. Todo está explicado desde cero. Pero si ya vienes de Claude Code, Cursor o Copilot, también encontrarás contenido útil, especialmente en los capítulos avanzados donde verás las diferencias y ventajas de OpenCode.

Nos vemos en el capítulo 1.

Referencias

• Web oficial de OpenCode — Página principal del proyecto, descargas, documentación.
• Documentación oficial de OpenCode — Guía de inicio rápido, referencia de comandos y configuración.
• Repositorio en GitHub — OpenCode — Código fuente, issues, pull requests y comunidad.
• Ollama — Modelos locales — La forma más sencilla de ejecutar modelos de IA en tu máquina para usarlos con OpenCode.
• Model Context Protocol (MCP) — Protocolo abierto de Anthropic para conectar agentes de IA con herramientas externas.
• Graphify — Visualización del grafo de llamadas y dependencias de tu código.
• CodeGraph — Grafo de contexto para que OpenCode entienda proyectos grandes.
• Tutorial de OpenCode en atareao.es — Índice completo del tutorial con todos los capítulos disponibles.
• Qué es OpenCode — atareao.es — Capítulo 1 del tutorial en atareao.es.
• Cómo instalar OpenCode — atareao.es — Capítulo 2 del tutorial en atareao.es.
• Tutorial de Podman en atareao.es — Tutorial complementario sobre contenedores con Podman.
• Tutorial de Docker en atareao.es — Tutorial sobre Docker, útil para entender el ecosistema de contenedores.
• Tutorial de IA en atareao.es — Conceptos generales sobre inteligencia artificial y modelos de lenguaje.
• Podcast: Agentes de IA para programar — atareao.es — Episodio del podcast sobre herramientas de IA para desarrollo de software.