Inteligencia artificial · Tecnología · Recursos

Tutorial

OpenCode V2 desde cero: manual básico de instalación, TUI, plugins y MCP

OpenCode es un agente de código abierto que trabaja dentro de tu proyecto. No se limita a responder en un chat: lee archivos, busca en el código, ejecuta comandos y propone cambios.

OpenCode V2 desde cero: manual básico de instalación, TUI, plugins y MCP

Tú decides qué acepta y qué no.

Este manual está pensado para alguien que nunca ha usado un agente de este tipo. Vamos de cero: elegir la interfaz, instalar, conectar un modelo, abrir el primer proyecto, entender la TUI y añadir plugins y servidores MCP con criterio. Al final tienes una lista de comprobación para tu primera hora.

Aviso de versión: aquí hablamos de OpenCode V2. Si ves tutoriales con la URL /install a secas, con provider en singular o con los servidores MCP directamente bajo mcp, son de V1. No mezcles configuraciones de las dos versiones.

1. Qué necesitas antes de empezar

  • Un ordenador con Windows 10/11, macOS o Linux.
  • Una carpeta de proyecto. Si solo quieres probar, crea una carpeta vacía.
  • Una cuenta o una clave de API de un proveedor de modelos. La forma más rápida de empezar es una cuenta de OpenCode, que da acceso a modelos gratuitos por tiempo limitado.
  • Si vas a usar la terminal: saber moverte con pwd, ls y cd. No hace falta más.

No necesitas saber programar para seguir este manual, pero OpenCode está pensado para trabajar sobre código. Si es tu primera vez, empieza en un proyecto pequeño o en una copia.

2. Instalar OpenCode V2

Windows: la app de escritorio (la vía más fácil)

Si no quieres tocar la terminal, descarga la aplicación de escritorio desde opencode.ai/download. Elige el instalador de Windows x64 o ARM64, ejecútalo y abre la app.

En el primer arranque, la aplicación te pedirá conectar un proveedor de modelos. Puedes usar tu cuenta de OpenCode o una clave de API. La app es una interfaz gráfica del mismo agente: sirve para trabajar sin WSL y sin comandos.

Windows: WSL2 + terminal (la vía recomendada para la TUI)

Si quieres usar la TUI, la interfaz de terminal que veremos más adelante, instala WSL2. Abre PowerShell como administrador y ejecuta:

ice-tech
wsl --install -d Ubuntu

Reinicia el equipo cuando termine. Abre Ubuntu desde el menú de inicio, crea tu usuario y tu contraseña. Dentro de Ubuntu, instala OpenCode:

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

Dos consejos para Windows:

  • Guarda los proyectos en /home/tu-usuario/, no en /mnt/c/. WSL puede acceder a los discos de Windows, pero es mucho más lento.
  • Si usas VS Code, instala la extensión WSL, abre la carpeta desde Ubuntu o escribe code . dentro de la carpeta del proyecto.

La CLI nativa de Windows también existe como binario ZIP, pero la documentación de V2 indica que los gestores de paquetes de Windows no están soportados. Para empezar, usa la app de escritorio o WSL.

macOS y Linux

La instalación oficial es la misma para macOS y Linux:

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

Si prefieres un gestor de paquetes, elige una sola vía:

ice-tech

brew install anomalyco/tap/opencode-v2

# Si ya tienes Node.js
npm install -g @opencode/cli

También hay app de escritorio para macOS y Linux en la página de descargas.

Comprobar que todo está en su sitio

ice-tech
opencode --version
opencode auth list
opencode mcp list
opencode service status

Es normal que auth list y mcp list estén vacíos al principio. Lo importante es que opencode --version responda y que service status no dé error.

Si el comando opencode no aparece, cierra y vuelve a abrir la terminal. Si sigue igual, comprueba que la carpeta donde se instaló esté en el PATH; el instalador te indica la ruta.

3. Conectar un modelo

OpenCode es el motor; el modelo lo pones tú. Arranca OpenCode en cualquier carpeta:

ice-tech
opencode

Dentro de la TUI, escribe:

ice-tech
/connect

Elige OpenCode si quieres usar tu cuenta de OpenCode y sus modelos gratuitos. Si prefieres otro proveedor, elige Anthropic, OpenAI, Google, OpenRouter o el que uses, y pega tu clave de API o completa el inicio de sesión.

Después elige el modelo:

ice-tech
/models

Los modelos que llevan free en el nombre no cobran tokens, pero son promociones que pueden cambiar y tienen límites de uso. Si necesitas más estabilidad, usa un modelo de pago con tu propia clave.

Puedes comprobar las cuentas conectadas con:

ice-tech
opencode auth list

Si usas modelos locales con Ollama, OpenCode los detecta en http://127.0.0.1:11434 y aparecen como ollama/... en /models. No hace falta configurar nada para empezar. Tienes una guía completa en Entorno de desarrollo IA local.

OpenCode Console es pago por uso y OpenCode Go es una suscripción de 10 $/mes con modelos incluidos. Ninguno de los dos es obligatorio para probar OpenCode.

4. Tu primera sesión en un proyecto

Abre la carpeta donde está tu proyecto y arranca OpenCode:

ice-tech
cd ~/proyectos/tienda
opencode

Si la carpeta no existe, créala antes:

ice-tech
mkdir -p ~/proyectos/tienda
cd ~/proyectos/tienda

La primera petición no debería ser «escríbeme una app». Pide un mapa:

ice-tech
Explora este proyecto y explícame qué hace,
cómo está organizado y cómo se arranca.
No modifiques nada.

OpenCode leerá el README, el package.json o el archivo de dependencias, buscará en el código y te devolverá un resumen. Si algo no te cuadra, pídele que cite los archivos concretos en los que se basa.

Después pide un plan antes de tocar nada:

ice-tech
Hazme un plan para añadir un formulario de contacto.
No escribas código todavía.

Plan y Build: los dos modos que más vas a usar

  • Plan explora, lee y propone. No edita los archivos normales del proyecto.
  • Build es el agente por defecto para ejecutar cambios.

Cambia de agente con Shift+Tab o con Ctrl+X y luego A. Para una tarea nueva, empieza en Plan. Cuando el plan te convenza, pasa a Build y pide la implementación por pasos.

Adjuntar archivos y ejecutar comandos

Dentro del prompt:

  • @ busca un archivo y lo adjunta. Puedes indicar líneas: @src/auth.ts#20-45.
  • ! al principio de una línea vacía entra en modo shell. Por ejemplo, !git status.
  • Shift+Enter (o Ctrl+J) añade una línea nueva sin enviar.

Crear un AGENTS.md

AGENTS.md es el archivo de instrucciones del proyecto. OpenCode lo lee al empezar y lo tiene en cuenta en todas las sesiones. Un ejemplo sencillo:

ice-tech
# Instrucciones del proyecto

- Ejecuta `npm test` antes de dar una tarea por terminada.
- No modifiques los archivos de `dist/` ni los `.env`.
- Sigue el estilo de los componentes que ya están en `src/components`.

Colócalo en la raíz del proyecto. OpenCode V2 lee AGENTS.md; no usa CLAUDE.md como respaldo. Si vienes de otra herramienta, renombra el archivo.

Si no quieres escribirlo a mano, pide:

ice-tech
Crea un AGENTS.md con las convenciones
que hayas detectado en este proyecto.

Tareas de una sola vez

Para scripts o tareas rápidas no hace falta abrir la TUI:

ice-tech
opencode run "Resume los cambios de los últimos commits"

5. La TUI: cómo se usa

La TUI es la interfaz de pantalla completa que se abre con opencode. Es la forma más cómoda de trabajar en sesiones largas.

OpenCode funciona con un servidor local en segundo plano. La TUI, la app de escritorio y la interfaz web son clientes de ese servidor. Por eso puedes cerrar la TUI y recuperar la sesión más tarde.

Las zonas de la pantalla

ice-tech
┌─ sesiones ──────┬─ conversación ─────────────────────────┐
│ ● proyecto      │ tú: explica este proyecto              │
│ ○ otra sesión   │ opencode: leyendo README.md...          │
│ + nueva         │ ✓ read  ✓ glob  ✓ grep                 │
│                 │                                          │
│                 │ > escribe aquí                          │
└─────────────────┴──────────────────────────────────────────┘
  • Barra superior: proyecto, agente, modelo y estado de los MCP.
  • Barra lateral: sesiones, pestañas y archivos del proyecto.
  • Conversación: mensajes, llamadas a herramientas y diferencias de código.
  • Compositor: aquí escribes. Debajo verás el modelo, el contexto usado y el estado.
  • Pestañas: puedes tener varias sesiones abiertas a la vez.

Atajos que merece la pena aprender

Atajo Acción
Ctrl+P Paleta de comandos: todo lo que puedes hacer
Ctrl+X Tecla líder; se combina con la siguiente tecla
Ctrl+X M Elegir modelo
Ctrl+X A Elegir agente
Ctrl+X N Nueva sesión
Ctrl+X L Listar sesiones
Ctrl+X B Mostrar u ocultar la barra lateral
Ctrl+X T Abrir o cerrar la terminal integrada
Ctrl+X E Editar el prompt en tu editor externo
Ctrl+X U / R Deshacer / rehacer
Ctrl+X C Compactar la conversación
Shift+Tab Cambiar de agente
F2 Cambiar al modelo usado recientemente
Ctrl+O Sesiones y proyectos recientes
Ctrl+Tab Cambiar de pestaña
Esc Interrumpir la generación
Ctrl+D Salir

El líder por defecto es Ctrl+X. Si no responde, abre Ctrl+P y busca la acción por su nombre. Puedes cambiar el líder en cli.json, como veremos al final.

Comandos con barra

Escribe / y aparece la lista. No hace falta memorizarlos todos:

Comando Para qué
/connect Conectar un proveedor de modelos
/models Cambiar de modelo
/agents Cambiar de agente
/new Empezar una sesión nueva
/sessions Ver y recuperar sesiones
/undo y /redo Deshacer o rehacer el último trabajo
/diff Revisar los cambios
/mcps Ver, conectar y autenticar servidores MCP
/editor Abrir el prompt en tu editor
/btw Hacer una pregunta lateral sin ensuciar la conversación
/highlights Ver las novedades de la versión instalada

El compositor: lo que de verdad se usa

  • @archivo adjunta un archivo. @src/auth.ts#20-45 adjunta solo ese rango.
  • !comando ejecuta un comando de shell y deja la salida en la sesión.
  • Mientras OpenCode trabaja, Enter dirige la sesión activa. Si quieres guardar una instrucción para después, pulsa Ctrl+X y luego Enter.
  • Esc interrumpe. Ctrl+D sale.
  • /btw responde con el contexto de la conversación, pero no añade la respuesta al historial.

Sesiones, diffs y deshacer

  • Ctrl+X N crea una sesión. Ctrl+X L las lista. Ctrl+O abre sesiones y proyectos recientes.
  • Ctrl+Tab y Ctrl+Shift+Tab cambian de pestaña. Ctrl+Shift+T reabre la última pestaña cerrada.
  • /undo revierte el último mensaje y el trabajo que vino después. /redo lo restaura.
  • /diff abre el visor de cambios. Dentro, d cambia el ámbito (todo, confirmado, sin confirmar o último turno), m marca un archivo como revisado y v alterna entre vista dividida y unificada.
  • Ctrl+X C compacta la conversación cuando se hace muy larga. No borra la sesión: resume el contexto para seguir trabajando.

Mini y web

Si la pantalla es pequeña, estás por SSH o compartes terminal con otro programa:

ice-tech
opencode mini

La interfaz mini solo muestra la conversación y el prompt. Ctrl+L limpia la pantalla visible.

Para abrir la interfaz web desde otro dispositivo:

ice-tech
opencode pair

OpenCode imprime un enlace y un QR. El enlace caduca a los cinco minutos y la sesión web dura 30 días. La interfaz web está protegida con contraseña. opencode pair --remote expone el servidor a internet; úsalo solo si entiendes el riesgo.

Tema y ajustes de la TUI

Pulsa Ctrl+P y elige Open settings. Los ajustes de terminal se guardan en ~/.config/opencode/cli.json, no en la configuración del proyecto. Un ejemplo mínimo:

ice-tech
{
  "$schema": "https://opencode.ai/v2/cli.json",
  "theme": {
    "name": "tokyonight",
    "mode": "dark"
  },
  "attention": {
    "notifications": true,
    "sound": true
  }
}

cli.json controla temas, atajos, notificaciones, pestañas y el modo mini. No mezclarlo con opencode.json, que es la configuración del agente y del proyecto.

6. Plugins: qué son y cuáles merecen la pena

Un plugin extiende OpenCode: añade memoria, protege archivos, mejora la interfaz, gestiona sesiones o conecta servicios. Es código que se ejecuta con tus permisos, así que instala solo plugins de repositorios que conozcas.

Se gestionan desde la CLI:

ice-tech
opencode plugin add opencode-mem
opencode plugin list
opencode plugin update
opencode plugin remove opencode-mem

También puedes declararlos en la lista plugins de opencode.json. En V2 la API de plugins cambió respecto a V1: antes de instalar, comprueba que el README del plugin mencione V2 o que su última versión sea reciente. Si un plugin no aparece o da errores, retíralo y prueba otro.

Plugin Para qué sirve Instalación
opencode-mem Memoria persistente entre sesiones con búsqueda local opencode plugin add opencode-mem
@tarquinen/opencode-dcp Poda contexto antiguo para gastar menos tokens opencode plugin add @tarquinen/opencode-dcp
envsitter-guard Evita que el agente lea o edite archivos .env opencode plugin add envsitter-guard@latest
opencode-handoff Genera un resumen para continuar en otra sesión opencode plugin add opencode-handoff
opencode-token-tracker Muestra tokens, coste y latencia por petición opencode plugin add opencode-token-tracker
opencode-synced Sincroniza la configuración global entre equipos opencode plugin add opencode-synced
oh-my-opencode-slim Orquestación ligera con subagentes y tareas en segundo plano bunx oh-my-opencode-slim@latest install
@daytona/opencode Ejecuta las sesiones en un sandbox aislado opencode plugin add @daytona/opencode

Para empezar, no instales la tabla entera. Una combinación razonable es envsitter-guard para proteger secretos y @tarquinen/opencode-dcp si trabajas en sesiones largas. Añade opencode-mem solo si repites el mismo proyecto todos los días.

Las notificaciones de escritorio no necesitan plugin: se activan con attention.notifications en cli.json, como hemos visto arriba. El consumo de tokens también aparece en la barra inferior de la TUI; opencode-token-tracker añade un desglose más detallado.

7. MCP: conectar OpenCode con el mundo

MCP (Model Context Protocol) es un estándar para que el agente use herramientas externas: documentación, navegador, repositorios, bases de datos o servicios de tu empresa. Un servidor MCP puede ser local (un comando que arranca en tu máquina) o remoto (una URL con OAuth).

La diferencia con un plugin es simple: el plugin extiende OpenCode; el MCP le da acceso a un sistema externo.

Añadir un servidor

ice-tech
opencode mcp add context7 --global --url https://mcp.context7.com/mcp
opencode mcp list

--global lo deja disponible en todos los proyectos. Si omites la opción, se guarda en la configuración del proyecto actual.

Los servidores remotos usan OAuth por defecto. Si mcp list dice needs authentication, abre /mcps, selecciona el servidor y completa el inicio de sesión.

Un servidor local se añade con -- delante del comando:

ice-tech
opencode mcp add playwright --global -- npx @playwright/mcp@latest

Los MCP que más se usan

Servidor Para qué sirve Alta
Context7 Documentación actualizada de librerías y frameworks opencode mcp add context7 --global --url https://mcp.context7.com/mcp
GitHub Repositorios, issues, pull requests y búsqueda de código opencode mcp add github --global --url https://api.githubcopilot.com/mcp/
Playwright Abrir un navegador real, rellenar formularios y probar la web opencode mcp add playwright --global -- npx @playwright/mcp@latest
Sentry Traer errores y trazas de producción a la conversación opencode mcp add sentry --global --url https://mcp.sentry.dev/mcp
Supabase Consultar tablas y esquema de un proyecto Supabase opencode mcp add supabase --global --url https://mcp.supabase.com/mcp
Filesystem Leer y escribir archivos en carpetas que tú autorices opencode mcp add files --global -- npx -y @modelcontextprotocol/server-filesystem ~/proyectos

Context7 suele ser el primero que merece la pena: evita que el modelo invente APIs que ya no existen. GitHub es el siguiente si trabajas con repositorios. Playwright solo si haces desarrollo web y necesitas probar la interfaz. Sentry y Supabase tienen sentido cuando ya usas esos servicios.

La configuración, si prefieres editarla a mano

ice-tech
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp"
      },
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp@latest"]
      }
    }
  }
}

En V2 los servidores van dentro de mcp.servers. Si ves un archivo con mcp y los nombres directamente debajo, es de V1.

No lo conectes todo

Cada servidor MCP añade descripciones de herramientas al contexto del modelo. Con veinte servidores conectados, el agente gasta contexto antes de empezar y elige peor las herramientas. La recomendación práctica es tener entre tres y cinco activos y dejar el resto configurados pero desconectados:

ice-tech
{
  "mcp": {
    "servers": {
      "supabase": {
        "type": "remote",
        "url": "https://mcp.supabase.com/mcp",
        "disabled": true
      }
    }
  }
}

Para eliminar un servidor, borra su entrada de la configuración. Para desconectarlo sin borrarlo, usa disabled: true o el interruptor de /mcps.

Seguridad con MCP

  • Instala servidores publicados por el proveedor del servicio (GitHub, Sentry, Supabase) o por proyectos con mantenimiento visible.
  • Revisa los permisos que pides: un MCP con escritura en tu base de datos o en tu repositorio puede hacer cambios reales.
  • Usa modo de solo lectura cuando estés explorando datos de producción.
  • No escribas claves en opencode.json. Usa {env:VARIABLE} o el flujo de OAuth.

8. Configuración mínima sin romper nada

OpenCode usa dos archivos distintos:

  • opencode.json o opencode.jsonc: configuración del agente, modelos, permisos, MCP y plugins. Puede ser global (~/.config/opencode/opencode.json) o de proyecto (opencode.json en la raíz).
  • cli.json: solo ajustes de la interfaz de terminal (tema, atajos, notificaciones).

La configuración del proyecto tiene prioridad sobre la global. Los cambios se recargan solos; si algo no se refresca, ejecuta opencode reload en otra terminal.

Un ejemplo seguro para empezar

ice-tech
{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/deepseek-v4.1-flash-free",
  "permissions": [
    {
      "action": "external_directory",
      "resource": "*",
      "effect": "ask"
    },
    {
      "action": "shell",
      "resource": "*",
      "effect": "ask"
    },
    {
      "action": "edit",
      "resource": "*.env",
      "effect": "deny"
    }
  ]
}

Tres cosas importantes de este ejemplo:

  1. external_directory hace que te pregunte antes de tocar archivos fuera del proyecto.
  2. shell hace que te pregunte antes de ejecutar comandos. Es más lento, pero es lo que quieres al principio.
  3. edit bloquea la escritura en archivos .env. La lectura de .env ya pide permiso por defecto en V2.

La política por defecto de V2 es bastante permisiva: permite casi todo y solo pregunta al leer .env. Si vienes de V1 y esperabas confirmaciones por cada comando, añade reglas como las de arriba.

Lo que no debes copiar de un tutorial de V1

V1 V2
provider providers
mcp con servidores dentro mcp.servers
plugin plugins
permission permissions
bash shell
task subagent

No mezcles las dos formas en el mismo archivo. Si algo falla después de copiar una configuración, revisa primero esto.

Claves y secretos

No escribas claves de API en opencode.json. Lo más limpio es usar /connect, que las guarda fuera de la configuración. Si necesitas una variable de entorno:

ice-tech
{
  "providers": {
    "openrouter": {
      "settings": {
        "apiKey": "{env:OPENROUTER_API_KEY}"
      }
    }
  }
}

Y defines OPENROUTER_API_KEY en tu shell o en el entorno del servicio.

9. Seguridad y buenas costumbres

OpenCode puede leer, escribir y ejecutar. Eso es lo que lo hace útil, y también lo que exige un poco de disciplina.

  • Haz commit antes de una tarea grande. Si el agente se equivoca, git diff y git restore son tu red de seguridad. Si no usas Git, haz una copia de la carpeta. Tienes una guía en Git y GitHub desde cero.
  • Lee los diffs antes de aceptar. No hace falta revisar cada línea, pero sí saber qué archivos se tocan.
  • No aceptes permisos a ciegas. «Allow always» guarda una regla permanente en el proyecto. Si no estás seguro, elige «once».
  • No pegues secretos en el chat. Ni claves, ni tokens, ni datos de clientes. Usa variables de entorno y el plugin envsitter-guard.
  • No conectes veinte MCP. Tres o cinco bien elegidos rinden más que una lista enorme.
  • Cuida los modelos gratuitos. Son una gran forma de probar, pero tienen límites y condiciones de privacidad distintas. No les envíes información confidencial.
  • Revisa los plugins y MCP como revisarías una dependencia. Son código de terceros con acceso a tu máquina.

10. Problemas comunes

Síntoma Qué hacer
opencode: command not found Cierra y abre la terminal. Revisa el PATH o vuelve a ejecutar el instalador.
No aparece ningún modelo Ejecuta /connect, elige un proveedor y comprueba opencode auth list. Después /models.
Un MCP dice needs authentication Abre /mcps, selecciona el servidor y completa el OAuth.
Un plugin no carga Comprueba que su README indique compatibilidad con V2. Quítalo con opencode plugin remove, reinicia el servicio y vuelve a probar.
WSL va lento Mueve el proyecto a /home/tu-usuario/. No lo dejes en /mnt/c/.
El agente pide demasiados permisos Es normal si añadiste reglas ask. Revisa cada petición y guarda solo las que repitas.
Se ha equivocado en un cambio /undo o Ctrl+X U. Si ya hiciste commit, usa Git.
Algo está raro y no sabes qué opencode service status, luego opencode --standalone para aislar el problema. Los logs están en ~/.local/share/opencode/log/opencode.log.
La app de escritorio no conecta Actualiza la app y vuelve a iniciar sesión con el proveedor. Si usas la CLI, comprueba opencode service status.

11. Tu primera hora con OpenCode

Si haces esto en orden, tendrás una base sólida:

  1. Instala OpenCode (app de escritorio o WSL/terminal).
  2. Conecta un proveedor con /connect y elige un modelo con /models.
  3. Abre una carpeta de proyecto y pide el tour: «explícame qué hace este proyecto, sin modificar nada».
  4. Cambia a Plan con Shift+Tab y pide un plan para una tarea pequeña.
  5. Crea un AGENTS.md con las reglas del proyecto.
  6. Añade Context7 como primer MCP y comprueba que aparece en /mcps.
  7. Instala envsitter-guard si el proyecto tiene archivos .env.
  8. Aprende cinco atajos: Ctrl+P, Ctrl+X M, Ctrl+X N, Ctrl+X L y Esc.
  9. Haz una tarea real en una rama de Git y revisa el diff antes de aceptar.
  10. Cuando termines, cierra con Ctrl+D. La sesión queda guardada.

A partir de aquí, lo demás se aprende sobre la marcha: memoria persistente, subagentes, worktrees, sandboxes y automatización con opencode run.

Recursos

Manual actualizado en octubre de 2026 para OpenCode V2.

Volver a artículos ←