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
/installa secas, conprovideren singular o con los servidores MCP directamente bajomcp, 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,lsycd. 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:
wsl --install -d UbuntuReinicia el equipo cuando termine. Abre Ubuntu desde el menú de inicio, crea tu usuario y tu contraseña. Dentro de Ubuntu, instala OpenCode:
curl -fsSL https://opencode.ai/v2/install | bash
opencode --versionDos 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:
curl -fsSL https://opencode.ai/v2/install | bashSi prefieres un gestor de paquetes, elige una sola vía:
brew install anomalyco/tap/opencode-v2
# Si ya tienes Node.js
npm install -g @opencode/cliTambién hay app de escritorio para macOS y Linux en la página de descargas.
Comprobar que todo está en su sitio
opencode --version
opencode auth list
opencode mcp list
opencode service statusEs 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:
opencodeDentro de la TUI, escribe:
/connectElige 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:
/modelsLos 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:
opencode auth listSi 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:
cd ~/proyectos/tienda
opencodeSi la carpeta no existe, créala antes:
mkdir -p ~/proyectos/tienda
cd ~/proyectos/tiendaLa primera petición no debería ser «escríbeme una app». Pide un mapa:
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:
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(oCtrl+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:
# 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:
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:
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
┌─ 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
@archivoadjunta un archivo.@src/auth.ts#20-45adjunta solo ese rango.!comandoejecuta un comando de shell y deja la salida en la sesión.- Mientras OpenCode trabaja,
Enterdirige la sesión activa. Si quieres guardar una instrucción para después, pulsaCtrl+Xy luegoEnter. Escinterrumpe.Ctrl+Dsale./btwresponde con el contexto de la conversación, pero no añade la respuesta al historial.
Sesiones, diffs y deshacer
Ctrl+XNcrea una sesión.Ctrl+XLlas lista.Ctrl+Oabre sesiones y proyectos recientes.Ctrl+TabyCtrl+Shift+Tabcambian de pestaña.Ctrl+Shift+Treabre la última pestaña cerrada./undorevierte el último mensaje y el trabajo que vino después./redolo restaura./diffabre el visor de cambios. Dentro,dcambia el ámbito (todo, confirmado, sin confirmar o último turno),mmarca un archivo como revisado yvalterna entre vista dividida y unificada.Ctrl+XCcompacta 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:
opencode miniLa interfaz mini solo muestra la conversación y el prompt. Ctrl+L limpia la pantalla visible.
Para abrir la interfaz web desde otro dispositivo:
opencode pairOpenCode 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:
{
"$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:
opencode plugin add opencode-mem
opencode plugin list
opencode plugin update
opencode plugin remove opencode-memTambié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
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:
opencode mcp add playwright --global -- npx @playwright/mcp@latestLos 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
{
"$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:
{
"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.jsonoopencode.jsonc: configuración del agente, modelos, permisos, MCP y plugins. Puede ser global (~/.config/opencode/opencode.json) o de proyecto (opencode.jsonen 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
{
"$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:
external_directoryhace que te pregunte antes de tocar archivos fuera del proyecto.shellhace que te pregunte antes de ejecutar comandos. Es más lento, pero es lo que quieres al principio.editbloquea la escritura en archivos.env. La lectura de.envya 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:
{
"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 diffygit restoreson 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:
- Instala OpenCode (app de escritorio o WSL/terminal).
- Conecta un proveedor con
/connecty elige un modelo con/models. - Abre una carpeta de proyecto y pide el tour: «explícame qué hace este proyecto, sin modificar nada».
- Cambia a Plan con
Shift+Taby pide un plan para una tarea pequeña. - Crea un
AGENTS.mdcon las reglas del proyecto. - Añade Context7 como primer MCP y comprueba que aparece en
/mcps. - Instala
envsitter-guardsi el proyecto tiene archivos.env. - Aprende cinco atajos:
Ctrl+P,Ctrl+XM,Ctrl+XN,Ctrl+XLyEsc. - Haz una tarea real en una rama de Git y revisa el diff antes de aceptar.
- 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
- Documentación oficial de OpenCode V2
- Guía de la TUI
- Servidores MCP
- Plugins
- Configuración
- Modelos
- Descargas
- Awesome OpenCode
- Registro oficial de MCP
Manual actualizado en octubre de 2026 para OpenCode V2.