OpenCode: De Vanilla a Pro — Guía de Configuración

Una guía fundamentada y sin hype para convertir una instalación básica de OpenCode en un entorno profesional de codificación. Basada en investigaciones de profesionales (Data Leads Future, DEV.to, Medium) y pruebas reales. Última actualización: 2026-07-29

1. Instalación

OpenCode está escrito en Go y se distribuye como un único binario. Requiere bun como dependencia de ejecución.

Instalación en un comando

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

Si falla

OpenCode depende de bun. Si tu entorno bloquea la instalación automática:

npm install -g bun

Luego reintenta el script de instalación, o instala manualmente desde opencode.ai.

Lo que obtienes

• opencode CLI — TUI de terminal (Bubble Tea, controlado por teclado)
• OpenCode Desktop — aplicación gráfica independiente (recomendada para uso diario)
• Extensiones VS Code / Cursor / Zed — a través del marketplace de extensiones

App de escritorio vs TUI

La aplicación de escritorio es significativamente más eficiente para el trabajo diario. Soporta nativamente Workspaces (git worktrees), algo que la TUI no ofrece. Eso solo vale la instalación.

Dicho esto, instala primero la CLI — algunos plugins y herramientas de configuración verifican la presencia del comando OpenCode durante la inicialización.

Verificar instalación

opencode --version

Deberías ver un número de versión (actual: 1.15+).

2. Configuración del Proveedor (Crítico)

Este es el error más común. OpenCode soporta más de 75 proveedores LLM, pero cómo los configures importa.

❌ La forma incorrecta

Ves que tu modelo no está en la lista, así que haces clic en "Proveedor personalizado" y completas: ID del modelo, URL base, clave API.

Por qué esto rompe las cosas: OpenCode no tiene información sobre el tamaño de la ventana de contexto de tu modelo, precios o capacidades. Funciones como la compresión automática de contexto, la gestión de tokens y la selección inteligente de modelos dejan de funcionar.

✅ La forma correcta

1. Abre OpenCode Desktop → Configuración → Proveedores
2. Desplázate hasta el final de la lista
3. Haz clic en "Mostrar más proveedores"
4. Encuentra tu proveedor real (ej. OpenRouter, Together, Fireworks)
5. Ingresa la clave API de ese proveedor

Una vez configurado, todos los modelos de ese proveedor aparecen con metadatos completos — tamaño de contexto, precios, todo.

Encontrar tu ID de proveedor

OpenCode lo guarda aquí:

~/.local/share/opencode/auth.json

Modelos gratuitos disponibles

• Big Pickle — un modelo sigiloso disponible gratis
• DeepSeek V4 Flash — MoE optimizado para eficiencia (284B total, 13B activados)
• Nemotron 3 Super — MoE híbrido de NVIDIA (120B, 12B activados)

Proveedores de pago recomendados

3. Configuración de Terminal y Plataforma

macOS / Linux

OpenCode detecta $SHELL automáticamente. No se necesita acción.

Windows

OpenCode Desktop usa PowerShell por defecto. Dos problemas: algunos entornos bloquean PowerShell y las configuraciones regionales no inglesas causan errores de codificación. Solución: configura la variable de entorno SHELL, o usa WSL / Git Bash.

4. AGENTS.md — Tu memoria a largo plazo

Esto es lo más impactante que puedes configurar.

Qué hace AGENTS.md

Tres cosas:

1. Fija los hechos del proyecto. Sin AGENTS.md, cada nueva sesión hace que el LLM escanee todo el proyecto desde cero.

2. Reduce las distribuciones de probabilidad (disminuye alucinaciones). Los LLMs generan respuestas probabilísticamente. AGENTS.md desplaza las distribuciones hacia tus convenciones.

3. Previene errores de dependencias. Escribe tus herramientas en AGENTS.md.

Crear AGENTS.md

Ejecuta /init en OpenCode. La IA analiza tu proyecto y genera una línea base.

Qué contiene un buen AGENTS.md

# Resumen del Proyecto

Eva es una plataforma de asistente IA personal. Monorepo con:
- Backend Python (FastAPI) en `/backend`
- Frontend React + TypeScript en `/frontend`
- Plugins de servidor MCP en `/mcp-servers`

# Stack Tecnológico

- Python 3.14+ con async/await en todo
- React 19 + Tailwind CSS 4 para UI
- Bun como runtime de JavaScript

# Comandos

- `uv sync --prerelease=allow` — sincronizar dependencias Python
- `bun install` — instalar dependencias frontend
- `pytest` — ejecutar tests Python

# Convenciones de Código

- Tipos: siempre usar `str | None`, nunca `Optional[str]`
- Imports: biblioteca estándar primero, luego terceros, luego locales
- Async: usar `async def` para funciones de E/S

# Reglas de Arquitectura

- Los servicios backend se comunican mediante paso de mensajes
- Los servidores MCP son procesos independientes

5. Los dos agentes integrados: Plan vs Build

Agente Build (predeterminado)

Acceso completo a herramientas. Úsalo para tareas claras y sin ambigüedad. No lo uses para tareas complejas o ambiguas.

Agente Plan

Modo de análisis de solo lectura. Hace preguntas aclaratorias. Produce un plan de ejecución.

Flujo profesional: Cada nuevo requisito → Agente Plan → archivo de plan → sesión nueva → Agente Build

6. Modo de flujo de planificación (v1.15+)

Activarlo

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

Las 5 fases

7. Workspaces — Desarrollo en paralelo

La app de escritorio tiene Workspaces, basados en git worktrees. Haz clic derecho en el ícono del proyecto → Activar Workspace.

8. Disciplina de sesiones

El problema: Podredumbre del contexto — los LLM tienen sesgo de primacía y actualidad.

La regla: Después de cada hito importante, inicia una nueva sesión.

9. Comandos personalizados

Define comandos slash personalizados como archivos .opencode/commands/<nombre>.md con frontmatter y el placeholder $ARGUMENTS.

10. Agentes personalizados

• Global: ~/.config/opencode/agents/<nombre>.md
• Proyecto: <proyecto>/.opencode/agents/<nombre>.md

11. Flujo de trabajo para proyectos complejos

Mañana: Sincronizar y Planificar → Ejecución: Build → Revisión: Cerrar el ciclo

12. Expectativas de costos

OpenCode Go: $10/mes de suscripción.

13. Ruta de progresión

Etapa 2: OpenSpec (SDD) → Etapa 3: Reflection → Etapa 4: Loop Engineering

Lista de verificación rápida

• OpenCode CLI + Desktop instalados
• Proveedor configurado via "Mostrar más proveedores"
• Ejecutado /init para crear AGENTS.md
• OPENCODE_EXPERIMENTAL_PLAN_MODE=true activado
• Creado al menos un agente personalizado