Guía de OpenCode

1. Introducción

OpenCode es un agente de código que utiliza inteligencia artificial para ayudarte a programar. A diferencia de otros agentes, OpenCode es flexible, extensible y está diseñado para integrarse perfectamente en tu flujo de trabajo de desarrollo. La idea principal de OpenCode es ser agnóstico a los modelos y utilizar un sistema estándar.

Recuerda que para trabajar en Windows, se recomienda utilizar WSL, que permite trabajar como si fuera un entorno Linux dentro de Windows, sin necesidad de máquinas virtuales o emuladores.

Características principales:

Modalidades: terminal, versión web y aplicación desktop
Modo plan: Planificar, analizar (no hace cambios)
Modo build: Construir e implementar (hace cambios)
Soporte para proveedores cloud de modelos de IA
Soporte para modelos locales de IA
Integración con MCP, CLI y skills
Medición de uso y costes

Iremos hablando de cada una de estas cosas en esta guía. Si lo prefieres en video:

2. Instalación

Para instalar OpenCode en tu sistema, ejecuta el siguiente comando:

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

Una vez instalado, para abrir opencode solo tienes que entrar a la carpeta donde vas a trabajar y escribir opencode:

cd ~/workspace/mi-proyecto
opencode

Ten en cuenta que a medida que vayan saliendo nuevas versiones, puedes actualizar OpenCode a la última versión con el siguiente comando:

opencode upgrade

Esta es la opción de terminal, que es la modalidad recomendada. Si no te sientes cómodo trabajando desde una terminal, tienes dos opciones: verte mi video de terminal (que te hará cambiar de opinión) o utilizar alguna de las otras dos modalidades:

Web: Desde una terminal puedes escribir opencode web y esto levantará un servidor, habilitando la posibilidad de trabajar desde una web con una interfaz similar a un editor o IDE. Se activa un servidor local (http://localhost:3000).
Desktop: OpenCode también tiene una aplicación de escritorio disponible para Windows, macOS y Linux. Puedes descargarla desde opencode.ai/download. La app de escritorio combina la potencia del agente con una interfaz nativa, pestañas, terminal integrada y gestión visual de proyectos.

3. Modos plan/build

OpenCode tiene dos modos de operación que controlan cómo el agente aborda tus tareas:

Modo plan

El modo plan es de solo lectura. El agente analiza tu solicitud, explora el código, pero no modifica archivos ni ejecuta comandos.

Ideal para:

Entender un código desconocido
Diseñar una arquitectura antes de implementar
Revisar posibles mejoras sin riesgo
Hacer preguntas sobre el proyecto

Modo build

El modo build permite al agente leer, escribir archivos y ejecutar comandos. Es el modo de ejecución completa.

Ideal para:

Implementar nuevas funcionalidades
Corregir bugs
Refactorizar código
Ejecutar tests y herramientas de build

Puedes cambiar entre modos en cualquier momento simplemente pulsando la tecla TAB.

4. Añadir modelos

OpenCode soporta múltiples proveedores de modelos. De hecho, suele tener modelos gratuitos para utilizar hasta un límite de tokens muy generoso. Para acceder al menú de modelos, puedes hacerlo escribiendo /models, o pulsando CTRL+X+M o pulsando CTRL+P y luego seleccionando Switch model.

Se mostrará una lista con los modelos disponibles. Selecciona el que quieras usar. También puedes verlos con el comando opencode models. En la sección Cloud tienes un listado de los mejores modelos cloud, con sus precios y características.

Configurar tus modelos

En tu fichero ~/.config/opencode/opencode.jsonc puedes añadir modelos personalizados que quieras utilizar, como por ejemplo modelos locales o específicos:

{
  "model": "nombre_modelo_por_defecto",
  "provider": {
    "llamacpp": {
      "models": {
        "Qwen 3.6 35B A3B MTP IQ2_XSS": {
          "name": "qwen3.6-35b-a3b-mtp-iq2_xxs"
        }
      },
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1",
        "api-key": "llama.cpp"
      }
    }
  }
}

Si no sabes la IP de tu servidor, consulta la guía de llama.cpp.

5. Uso de OpenCode

Existen múltiples formas de trabajar con OpenCode, pero su núcleo se basa en detalles que no son propios de OpenCode, sino genéricos. Te los resumo con enlaces a otras secciones de la página donde hablo de ello:

Característica	Descripción	Link
✨ Prompting	Cómo escribir prompts efectivos	Crear buenos prompts
📃 Instrucciones	Ficheros markdown con instrucciones personalizadas.	Instrucciones
📜 Skills	Ficheros markdown adicionales cargables bajo demanda.	Instrucciones

Puedes ejecutar /init desde OpenCode para generar un AGENTS.md automáticamente y partir de ahí.

Los skills permiten cargar sólo un índice y descripciones de cada skill, y el agente decide cuándo leerlos completamente según la tarea que realiza. Esto permite tener documentación rica sin sobrecargar el contexto del agente.

6. Comandos útiles

En OpenCode muchas características se pueden realizar mediante comandos. Simplemente escribiendo el prefijo / comprobarás que hay muchos comandos. Los comandos más habituales de OpenCode son los siguientes:

Comando	Descripción
`/init`	Genera un `AGENTS.md` analizando tu proyecto
`/connect`	Conecta con un proveedor externo (OpenAI, Copilot, planes de OpenCode...)
`/models`	Muestra lista de modelos y permite cambiar a otro
`/copy`	Copia al portapapeles una transcripción de la sesión
`/diff`	Muestra el programa para ver diferencias de implementación
`/mcps`	Muestra la lista de MCPs de OpenCode. Ver más adelante
`/skills`	Muestra una lista de las skills que tenemos instaladas
`/thinking`	Despliega u oculta los razonamientos del modelo. Ideal si te agobia
`/new`	Crea una sesión nueva vacía. Ideal para nuevas tareas
`/undo`	Deshace el último mensaje (para gestionar esto, mejor usa `git`)
`/compact`	Hace un resumen y compacta el contexto

Comandos personalizados

Puedes crear tus propios comandos personalizados creando un fichero markdown en ~/.opencode/commands/mi-comando.md:

---
description: "Refactoriza el código para hacerlo más legible"
agent: build
---

# Instrucciones

- Refactoriza el código con el objetivo de simplificar y reducir líneas
- Hazlo más compacto, si gana en legibilidad
- Si es posible, crea funciones reutilizables para partes que se repiten
- Además, sigue las instrucciones: $@

El nombre del fichero será el nombre del comando: /mi-comando, y con $@ puedes hacer referencia a lo que escriba el usuario después del comando.

7. MCP / CLI

Los MCP servers (Model Context Protocol) permiten extender las capacidades de OpenCode conectándolo a herramientas y servicios externos, a través de URL remotas o locales.
Los CLI (Command Line Interface) son comandos de terminal que realizan tareas o acciones, y que un agente también puede ejecutar.

Configuración de MCP

Para configurar un servidor MCP, añade la sección mcp en tu ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "nombre-de-mcp-remoto": {
      "enabled": true,
      "type": "remote",
      "url": "https://dominio.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    },
    "nombre-de-mcp-local": {
      "enabled": false,
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "environment": {
        "ENV_VAR": "value"
      }
    }
  }
}

En el interior de mcp se colocan todos los servidores MCP que se deseen. Pueden ser tanto locales como remotos. Si el servidor MCP requiere autenticación, es necesario indicar la clave oauth (si no, no hace falta).

Intenta siempre tener los MCP apagados siempre que sea posible, ya que suelen consumir contexto. Tienes un campo enabled que conviene tenerlo en false por defecto. Desde OpenCode, puedes activarlos con el comando /mcps.

CLI vs MCP: Por qué preferir CLI

Los MCP servers son útiles, pero cuando una herramienta ya existe como CLI, usarla directamente suele ser mejor. OpenCode tiene acceso a la terminal, así que puede ejecutar cualquier comando sin pasar por un servidor MCP intermedio.

MCP:

🟩 Cómodo: Funciona sin necesidad de preocuparse por aspectos técnicos.
🟩 Schema: Si se necesita un esquema estructurado y validado, MCP ahorra parseos.
🟥 Consume contexto siempre: Los tool schemas de cada MCP conectado se cargan en el contexto en cada turno, se usen o no. Con varios MCP activos, esto puede comerse una parte significativa de la ventana de contexto antes de escribir una sola palabra.
🟥 Latencia: Cada llamada pasa por un proceso intermedio.
🟥 Punto de fallo extra: Si el servidor MCP cae o tiene un bug, se pierde esa funcionalidad aunque la herramienta subyacente funcione bien.

CLI:

🟩 Barato en contexto: Junto a skills, la documentación de la herramienta solo se carga cuando hace falta, en vez de ocupar contexto de forma permanente como los MCP.
🟩 Directo y fiable: Se ejecuta sin intermediarios, menos probabilidad de fallos.
🟩 Disponibilidad: cualquier herramienta con CLI ya es usable, sin necesidad de un wrapper MCP.
🟥 Requiere skill previa: Si no hay skill para esa CLI, el modelo puede necesitar más intentos para descubrir la sintaxis correcta.

En resumen. Si algo tiene una CLI disponible, intenta antes usar el CLI que el MCP. Si es posible, añade skills para mejorar su utilización y descubrimiento.

Ejemplo: Git/GitHub con CLI

En lugar de usar un MCP server para GitHub, OpenCode puede usar directamente gh cli:

# Crear un issue
gh issue create --title "Bug: login error" --body "Descripción problema"

# Crear un PR
gh pr create --title "feat: nueva feature" --body "Descripción de cambios"

# Ver pull requests abiertos
gh pr list

8. Permisos

OpenCode tiene acceso a tu sistema de archivos y terminal, por lo que es importante configurar correctamente los permisos. Ejecuta siempre en la carpeta del proyecto que quieres utilizar. OpenCode podrá cambiar archivos en ese proyecto, pero te pedirá permiso si necesita acceder a un archivo o carpeta fuera de ese proyecto.

Buenas prácticas

Revisa siempre qué archivos va a modificar antes de confirmar
No des permisos automáticos a menos que confíes completamente en la tarea
Usa el modo plan para explorar antes de ejecutar cambios
Mantén backups o usa git antes de hacer cambios grandes
Sé selectivo con los MCP servers que instalas o CLI que ejecutas

Si trabajas en un entorno sensible, considera usar contenedores de Docker para aislar el funcionamiento de OpenCode.

9. Medir uso

OpenCode incluye herramientas para monitorizar tu uso y costes. Por ejemplo, de serie puedes ejecutar el comando opencode stats. Esto mostrará información como:

Tokens utilizados por sesión
Coste estimado por modelo
Historial de uso
Herramientas usadas (tools)

tokscale

Para una medición más detallada, puedes usar pnpx tokscale. Esta herramienta analiza el consumo de tokens y te ayuda a optimizar el uso de modelos, especialmente útil cuando trabajas con modelos cloud que tienen coste por token.

Revisa periódicamente tus estadísticas para identificar oportunidades de optimización, como usar el modelo pequeño para tareas simples.

10. Costes/planes

OpenCode ofrece diferentes opciones según tus necesidades: Modelos cloud y Modelos abiertos (locales). Los más comunes suelen ser los primeros, pero los segundos son más interesantes en ciertos casos.

Modelos cloud

En esta modalidad, conectamos nuestro agente OpenCode, con modelos de IA como Claude, GPT, Gemini, DeepSeek, etc... Generalmente, requiere una API-key de ese proveedor (coste por uso, tokens) o conectar con una suscripción.

Plan	Descripción
BYOK (Bring Your Own Key)	Usas tus propias API keys de los proveedores
OpenCode Go	Plan «tarifa plana», 10$ al mes y acceso a varios modelos
OpenCode Zen	Plan estilo «monedero», pagas lo que usas
OpenCode Free	Modelos gratuitos con límite. Van ciclando cada cierto tiempo

Modelos locales

Si tienes un hardware potente en tu equipo, puedes utilizar llama.cpp para ejecutar modelos en local. Es especialmente útil con modelos para casos específicos y tiene grandes beneficios:

Coste cero, una vez tengas el hardware
Privacidad total: tus datos no salen de tu máquina
Sin dependencia de internet: puedes trabajar hasta offline