8 Unidad 2: OpenCode - Tu Primer Agente de IA

Author

Diego Saavedra García

9 🛠️ Unidad 2: OpenCode — Tu Primer Agente de IA

9.1 “Tony no construye herramientas. Elige las correctas y las configura.”

9.2 🎯 Objetivo

Al terminar esta unidad podrás:

✅ Instalar OpenCode en tu sistema
✅ Configurar proveedores de IA (OpenAI, Anthropic, Google)
✅ Personalizar tu AGENTS.md
✅ Entender cada setting y por qué importa
✅ Ejecutar tu primer proyecto con contexto

9.3 🤖 ¿Qué es OpenCode?

9.3.1 En una frase

OpenCode es un agente de terminal que ejecuta comandos de IA en tu proyecto.

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   OPENCODE                                                                   │
│   ════════                                                                   │
│                                                                              │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                 │
│   │   TU        │     │   OPENCODE   │     │   75+       │                 │
│   │   TERMINAL   │────▶│   (Agente)   │────▶│   MODELOS   │                 │
│   │             │◀────│             │◀────│             │                 │
│   └─────────────┘     └─────────────┘     └─────────────┘                 │
│         │                   │                   │                          │
│         │                   │                   │                          │
│         ▼                   ▼                   ▼                          │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                 │
│   │   Vos       │     │   Lee       │     │   Claude,   │                 │
│   │   Escribes  │     │   Código    │     │   GPT,      │                 │
│   │   Prompts   │     │   + Context │     │   Gemini... │                 │
│   └─────────────┘     └─────────────┘     └─────────────┘                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

9.3.2 ¿Por qué OpenCode y no otra herramienta?

Característica	OpenCode	ChatGPT	Claude Code
Open Source	✅ MIT	❌	❌
75+ Modelos	✅	❌ (solo GPT)	❌ (solo Claude)
Gratis	✅ (BYO API)	❌ ($20+/mes)	❌ ($20+/mes)
Tu Código	✅ Lee todo	❌ (web)	✅
Configurable	✅ Total	⚠️ Limitado	⚠️ Medio
AGENTS.md	✅	❌	✅

💡 BYO API = Bring Your Own API Key. Pagás solo el modelo, no la herramienta.

9.4 🔧 Instalación de OpenCode

9.4.1 ⏱️ Timeline

Paso	Descripción	Tiempo	✓
1	Verificar prerrequisitos	2 min	⬜
2	Instalar OpenCode	5 min	⬜
3	Configurar API Keys	5 min	⬜
4	Primera ejecución	2 min	⬜

9.4.2 Paso 1: Verificar Prerrequisitos

Tu tarea: Verificar que tienes lo necesario.

Comando a ejecutar:

node --version && npm --version

Resultado esperado:

v18.x.x o superior
v9.x.x o superior

Si no tienes Node.js: 1. Ve a nodejs.org 2. Descarga la versión LTS 3. Instálala 4. Verifica nuevamente

9.4.3 Paso 2: Instalar OpenCode

Tienes dos opciones:

9.4.3.1 Opción A: Con curl (Linux/Mac/WSL)

Hint: El instalador oficial usa el dominio opencode.ai

Comando parcial: curl -fsSL https://opencode.ai/install |

Completá el comando:

[ESCRIBE AQUÍ]

Resultado esperado:

✅ OpenCode installed successfully!
Run: opencode

9.4.3.2 Opción B: Con npm (Todas las plataformas)

Hint: El flag -g significa instalación global

Comando parcial: npm install -g @

Completá el comando:

[ESCRIBE AQUÍ]

Resultado esperado:

added X packages in Ys

9.4.3.3 Opción C: Con Homebrew (Mac)

Hint: brew install seguido del nombre del paquete

Comando parcial: brew install an

Completá el comando:

[ESCRIBE AQUÍ]

Resultado esperado:

==> Downloading https://...
==> Installing opencode...

9.4.4 Paso 3: Verificar Instalación

Comando:

opencode --version

Resultado esperado:

X.X.X

9.5 🔑 Configuración de API Keys

9.5.1 ¿Por qué necesitas API Keys?

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   OPENCODE no es gratis porque:                                              │
│                                                                              │
│   - La HERRAMIENTA es gratis (MIT)                                           │
│   - Los MODELOS de IA NO lo son                                              │
│                                                                              │
│   Vos pagás SOLO el modelo que uses:                                         │
│                                                                              │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                 │
│   │  OpenAI      │     │  Anthropic   │     │  Google      │                 │
│   │  GPT-4o      │     │  Claude 4    │     │  Gemini 2.0  │                 │
│   │  $5/1M tok   │     │  $3/1M tok   │     │  $0.125/1M   │                 │
│   └──────────────┘     └──────────────┘     └──────────────┘                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

9.5.2 Modelos Recomendados por Budget

Budget	Modelo Recomendado	Costo Aproximado	Mejor Para
$0	Gemini 2.0 Flash	Gratis (150 req/min)	Aprender, practicar
Bajo	Claude Haiku	$0.80/1M tokens	Tareas rápidas
Medio	GPT-4o Mini	$0.15/1M tokens	Desarrollo diario
Alto	Claude Sonnet 4	$3/1M tokens	Código complejo
Máximo	Claude Opus 4	$15/1M tokens	Arquitectura, debugging

9.5.3 Obtener tu API Key

9.5.3.1 Anthropic (Claude) — Recomendado

Ve a console.anthropic.com
Crea cuenta o inicia sesión
Ve a API Keys → Create Key
Copia la key (empieza con sk-ant-)

Costo: $5 gratis en créditos para nuevos usuarios

9.5.3.2 OpenAI (GPT-4) — Alternativa

Ve a platform.openai.com
Crea cuenta o inicia sesión
Ve a API Keys → Create new secret key
Copia la key (empieza con sk-)

Costo: $5 gratis para nuevos usuarios

9.5.3.3 Google (Gemini) — Gratis

Ve a aistudio.google.com
Crea cuenta o inicia sesión
Ve a Get API Key → Create API Key
Copia la key (empieza con AIza)

Costo: GRATIS hasta ciertos límites

9.5.4 Configurar API Keys en tu Sistema

Opción A: Variables de entorno (Recomendado)

Archivo: ~/.bashrc o ~/.zshrc (Mac)

Agregá estas líneas:

# API Keys para OpenCode
export ANTHROPIC_API_KEY="sk-ant-tu-key-aqui"
export OPENAI_API_KEY="sk-tu-key-aqui"
export GOOGLE_API_KEY="AIza-tu-key-aqui"

Comando para recargar:

# Linux/Mac
source ~/.bashrc  # o source ~/.zshrc

# Mac con zsh
source ~/.zshrc

Opción B: Archivo .env en el proyecto

Creá un archivo .env en tu proyecto
Agregá las keys
Agregá .env a tu .gitignore

# En tu .gitignore
.env
.env.*

⚠️ NUNCA committees archivos con API keys

9.6 ⚙️ Configuración de OpenCode

9.6.1 Estructura de Archivos

~/.config/opencode/
├── opencode.json      # Configuración principal
├── AGENTS.md          # Tu identidad y reglas
├── agents/            # Definiciones de agentes
├── config/
│   └── skills/        # Skills disponibles
└── mcp/               # MCP servers

9.6.2 El archivo opencode.json

9.6.2.1 Tu primera configuración

Ubicación: ~/.config/opencode/opencode.json

Tu tarea: Crear este archivo con tu editor favorito.

Comando para crear directorio:

mkdir -p ~/.config/opencode

Comando para crear archivo:

touch ~/.config/opencode/opencode.json

9.6.3 Explicación de Cada Setting

9.6.3.1 1. Modelo Principal

"model": "anthropic/claude-sonnet-4-6-20250501"

Parte	Significado
`anthropic`	Proveedor (namespace)
`claude-sonnet-4-6-20250501`	Modelo específico

Modelos disponibles:

Proveedor	Modelo	Uso
`anthropic`	`claude-opus-4-6-20250501`	Mejor para arquitectura
`anthropic`	`claude-sonnet-4-6-20250501`	Balanceado, recomendado
`anthropic`	`claude-haiku-4-5-20250501`	Rápido, barato
`openai`	`gpt-4o`	General, rápido
`google`	`gemini-2.0-flash`	Gratis, rápido
`google`	`gemini-2.5-pro`	Mejor de Google

9.6.3.2 2. Actualización Automática

"autoupdate": true

Valor	Significado
`true`	Se actualiza automáticamente
`false`	Vos controlás las actualizaciones

9.6.3.3 3. Puerto del Servidor

"server": {
  "port": 4096
}

¿Qué es esto? OpenCode puede correr como servidor HTTP para integraciones.

Valor	Uso
`4096`	Puerto por defecto
`8080`	Común para desarrollo
`3000`	Común para frontend

9.6.3.4 4. Instrucciones Globales

"instructions": [
  "~/.config/opencode/mcp-security-resources.md"
]

¿Qué es esto? Archivos que OpenCode siempre lee antes de empezar.

Ejemplo de archivo de instrucciones:

# Instrucciones de Seguridad

## Reglas de Oro

1. NUNCA ejecutes comandos destructivos sin preguntar
2. NUNCA leas archivos .env o secrets
3. SIEMPRE pregunta antes de git push

9.6.4 Permisos: La Parte Más Importante

"permission": {
  "bash": { ... },
  "read": { ... },
  "write": { ... }
}

9.6.4.1 Permisos de Bash

"bash": {
  "git status": "allow",
  "git diff *": "allow",
  "rm -rf *": "deny",
  "rm *": "ask",
  "git push": "ask",
  "*": "deny"
}

Acción	Significado
`"allow"`	Se ejecuta sin preguntar
`"ask"`	Pregunta antes de ejecutar
`"deny"`	Nunca se ejecuta

Tus permisos personalizados:

"bash": {
  "git status": "allow",
  "git diff": "allow",
  "git log": "allow",
  "git branch": "allow",
  "npm *": "allow",
  "npm run *": "allow",
  "mkdir *": "allow",
  "touch *": "allow",
  "rm -rf *": "deny",
  "rm *": "ask",
  "git commit *": "ask",
  "git push": "ask",
  "sudo *": "ask",
  "*": "deny"
}

9.6.4.2 Permisos de Lectura

"read": {
  "**/.env": "deny",
  "**/.env.*": "deny",
  "**/credentials.json": "deny",
  "**/secrets/**": "deny",
  "**/id_rsa*": "deny",
  "*.env": "deny",
  "*": "allow"
}

¿Por qué deny en .env? Son archivos con passwords y API keys. OpenCode NO necesita leerlos para hacer su trabajo.

Tus permisos personalizados:

"read": {
  "**/.env": "deny",
  "**/.env.*": "deny",
  "**/credentials.json": "deny",
  "**/*secret*": "deny",
  "**/*password*": "deny",
  "**/id_rsa*": "deny",
  "**/id_ed25519*": "deny",
  "*.pem": "deny",
  "*": "allow"
}

9.6.4.3 Permisos de Escritura

"write": {
  "**/.env": "deny",
  "**/.env.*": "deny",
  "**/credentials.json": "deny",
  "**/secrets/**": "deny",
  "*.env": "deny",
  "*.pem": "deny"
}

¿Por qué deny en .env? Nadie debería modificar archivos de secrets automáticamente.

9.6.5 MCP Servers: Conexiones Externas

"mcp": {
  "chrome-devtools": {
    "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
    "type": "local"
  },
  "context7": {
    "enabled": true,
    "type": "remote",
    "url": "https://mcp.context7.com/mcp"
  },
  "engram": {
    "command": ["engram", "mcp"],
    "enabled": true,
    "type": "local"
  }
}

Server	Propósito	Tipo
`chrome-devtools`	Controlar Chrome para debugging	Local
`context7`	Buscar documentación actualizada	Remote
`engram`	Memoria persistente	Local

9.7 📝 AGENTS.md: Tu Identidad

9.7.1 ¿Qué es AGENTS.md?

AGENTS.md es el archivo donde definís QUIÉN sos y CÓMO querés que OpenCode trabaje.

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   AGENTS.md = TU PERFIL DE DESARROLLADOR                                    │
│   ═══════════════════════════════════                                       │
│                                                                              │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                                                                     │   │
│   │   # Quién soy                                                          │   │
│   │   Soy Diego, desarrollador FullStack...                              │   │
│   │                                                                     │   │
│   │   # Reglas de trabajo                                                 │   │
│   │   - Siempre uso TypeScript strict                                     │   │
│   │   - Tests primero, código después                                    │   │
│   │   - Nombres descriptivos, sin abreviaciones                          │   │
│   │                                                                     │   │
│   │   # Preferencias                                                       │   │
│   │   - snake_case para Python                                           │   │
│   │   - kebab-case para archivos                                         │   │
│   │   - Español para comentarios                                         │   │
│   │                                                                     │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

9.7.2 Tu Primer AGENTS.md

Ubicación: ~/.config/opencode/AGENTS.md o en tu proyecto

Comando para crear:

touch ~/.config/opencode/AGENTS.md

9.7.3 Template de AGENTS.md

# AGENTS.md — Mi Perfil de Desarrollador

---

## 👤 Quién Soy

**Nombre:** [Tu nombre]
**Rol:** [Tu rol: Frontend Dev, Backend Dev, FullStack, etc.]
**Experiencia:** [Años de experiencia]
**Especialidades:** [Ej: TypeScript, Python, Seguridad, etc.]

---

## 🛠️ Stack Tecnológico

### Lenguajes Principales
- [Tu lenguaje 1]
- [Tu lenguaje 2]

### Frameworks/Stack
- [Framework 1]
- [Framework 2]

### Herramientas
- Git: ✅
- Docker: ✅/❌
- Kubernetes: ✅/❌
- CI/CD: [Tu herramienta]

---

## 📋 Reglas de Trabajo

### Obligatorias
1. [Regla 1]
2. [Regla 2]
3. [Regla 3]

### Estilo de Código
- Nombres: [descriptivos, camelCase, snake_case, etc.]
- Comentarios: [en qué idioma]
- Tests: [primero, después, o no?]

### Seguridad
1. Nunca revelar API keys o secrets
2. Siempre validar input de usuarios
3. No ejecutar comandos destructivos sin confirmar

---

## 🎯 Preferencias de Comunicación

### Idioma
- Código y comentarios: [Español, English]
- Nombres de variables: [inglés siempre, o mixto]

### Nivel de Explicación
- Básico: [Para principiantes]
- Intermedio: [Con contexto]
- Avanzado: [Solo lo esencial]

---

## 🚫 Límites y Restricciones

### No Hacer
1. [Cosa que NO hacés]
2. [Otra cosa que NO hacés]

### Siempre Preguntar
1. [Situación 1]
2. [Situación 2]

---

## 💡 Tips para Trabajar Conmigo

1. [Tip 1]
2. [Tip 2]
3. [Tip 3]

9.8 🧪 Lab: Tu Primera Sesión con OpenCode

9.8.1 Objetivo

Ejecutar OpenCode con tu configuración personalizada.

9.8.2 ⏱️ Timeline

Paso	Descripción	Tiempo	✓
1	Crear opencode.json	10 min	⬜
2	Crear AGENTS.md	10 min	⬜
3	Configurar API Key	5 min	⬜
4	Primera sesión	15 min	⬜

9.8.3 Escenario

Tony acaba de salir de la cueva. Necesita configurar su taller (OpenCode) para la próxima misión.

Tu turno: Configurar OpenCode como Tony configuraría su armadura.

9.8.4 Paso 1: Crear opencode.json

Archivo: ~/.config/opencode/opencode.json

Completá este template:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "[TU MODELO ELEGIDO]",
  "autoupdate": true,
  "server": {
    "port": 4096
  },
  "instructions": [],
  "mcp": {
    "context7": {
      "enabled": true,
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "permission": {
    "bash": {
      "git status": "allow",
      "git diff *": "allow",
      "git log *": "allow",
      "npm *": "allow",
      "mkdir *": "allow",
      "rm -rf *": "deny",
      "rm *": "ask",
      "git push": "ask",
      "*": "deny"
    },
    "read": {
      "**/.env": "deny",
      "**/.env.*": "deny",
      "*.env": "deny",
      "*": "allow"
    },
    "write": {
      "**/.env": "deny",
      "*.env": "deny",
      "*.pem": "deny"
    }
  }
}

9.8.5 Paso 2: Crear AGENTS.md

Archivo: ~/.config/opencode/AGENTS.md

Completá tu perfil:

# AGENTS.md — [Tu Nombre]

## 👤 Quién Soy
[Tu descripción]

## 🛠️ Stack
[Lenguajes, frameworks, herramientas]

## 📋 Reglas de Trabajo
1. [Tu regla 1]
2. [Tu regla 2]
3. [Tu regla 3]

## 🎯 Preferencias
[Cómo querés que trabaje]

## 🚫 Límites
[Qué NO hacer]

9.8.6 Paso 3: Configurar API Key

Verificá que tu API key está disponible:

echo $ANTHROPIC_API_KEY

Resultado esperado:

sk-ant-xxxxxxxxxxxxxxxxxxxx

Si está vacío: 1. Editá tu ~/.bashrc o ~/.zshrc 2. Agregá: export ANTHROPIC_API_KEY="tu-key" 3. Ejecutá: source ~/.bashrc

9.8.7 Paso 4: Tu Primera Sesión

Comando para iniciar:

opencode

Tu primer mensaje:

> Hola. Soy [tu nombre]. 
> acabo de configurar OpenCode.
> Por favor confirmame que lees mi AGENTS.md 
> y decime qué reglas encontraste.

Tu respuesta esperada:

✅ Leo tu AGENTS.md
📋 Reglas que encontré:
1. [Regla 1]
2. [Regla 2]
3. [Regla 3]

9.8.8 Reflexión

Completá:

Mis reglas definidas fueron:
1. ________________________________________________
2. ________________________________________________
3. ________________________________________________

Algo que me sorprendió de OpenCode:
________________________________________________

Algo que quiero ajustar:
________________________________________________

9.9 📁 Entregable Final

9.9.1 Archivos a crear:

Archivo	Ubicación	Propósito
`opencode.json`	`~/.config/opencode/`	Configuración
`AGENTS.md`	`~/.config/opencode/`	Tu perfil

9.9.2 Contenido esperado:

# Verificar archivos
ls -la ~/.config/opencode/

# Deberías ver:
# opencode.json
# AGENTS.md

9.10 ✅ Checklist Final

Habilidad	Demostrable cuando…	✓
Instalar	`opencode --version` funciona	⬜
Configurar	opencode.json tiene permisos	⬜
AGENTS.md	Defines tu perfil completo	⬜
API Key	Variable de entorno configurada	⬜
Sesión	Pudiste conversar con OpenCode	⬜

9.11 🏆 Logro

“Armador” desbloqueado:

+100 XP
Acceso a herramientas avanzadas
AGENTS.md personalizado listo para usar

9.12 🔗 Siguiente

¿Listo para la próxima herramienta?

→ Unidad 3: Claude Code — Tu JARVIS Potente

¿Necesitás más práctica?

→ Quiz Unidad 2: Configuración de OpenCode

--- title: "Unidad 2: OpenCode - Tu Primer Agente de IA" author: "Diego Saavedra García" description: "Instalación, configuración y dominio de OpenCode - El agente de terminal open source más flexible" --- # 🛠️ Unidad 2: OpenCode — Tu Primer Agente de IA ## "Tony no construye herramientas. Elige las correctas y las configura." --- ## 🎯 Objetivo Al terminar esta unidad podrás: - ✅ **Instalar** OpenCode en tu sistema - ✅ **Configurar** proveedores de IA (OpenAI, Anthropic, Google) - ✅ **Personalizar** tu AGENTS.md - ✅ **Entender** cada setting y por qué importa - ✅ **Ejecutar** tu primer proyecto con contexto --- ## 🤖 ¿Qué es OpenCode? ### En una frase **OpenCode es un agente de terminal que ejecuta comandos de IA en tu proyecto.** ``` ┌──────────────────────────────────────────────────────────────────────────────┐ │ │ │ OPENCODE │ │ ════════ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ TU │ │ OPENCODE │ │ 75+ │ │ │ │ TERMINAL │────▶│ (Agente) │────▶│ MODELOS │ │ │ │ │◀────│ │◀────│ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Vos │ │ Lee │ │ Claude, │ │ │ │ Escribes │ │ Código │ │ GPT, │ │ │ │ Prompts │ │ + Context │ │ Gemini... │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────┘ ``` ### ¿Por qué OpenCode y no otra herramienta? | Característica | OpenCode | ChatGPT | Claude Code | |----------------|----------|---------|-------------| | **Open Source** | ✅ MIT | ❌ | ❌ | | **75+ Modelos** | ✅ | ❌ (solo GPT) | ❌ (solo Claude) | | **Gratis** | ✅ (BYO API) | ❌ ($20+/mes) | ❌ ($20+/mes) | | **Tu Código** | ✅ Lee todo | ❌ (web) | ✅ | | **Configurable** | ✅ Total | ⚠️ Limitado | ⚠️ Medio | | **AGENTS.md** | ✅ | ❌ | ✅ | > 💡 **BYO API** = Bring Your Own API Key. Pagás solo el modelo, no la herramienta. --- ## 🔧 Instalación de OpenCode ### ⏱️ Timeline | Paso | Descripción | Tiempo | ✓ | |------|-------------|--------|---| | 1 | Verificar prerrequisitos | 2 min | ⬜ | | 2 | Instalar OpenCode | 5 min | ⬜ | | 3 | Configurar API Keys | 5 min | ⬜ | | 4 | Primera ejecución | 2 min | ⬜ | --- ### Paso 1: Verificar Prerrequisitos **Tu tarea:** Verificar que tienes lo necesario. **Comando a ejecutar:** ``` node --version && npm --version ``` **Resultado esperado:** ``` v18.x.x o superior v9.x.x o superior ``` **Si no tienes Node.js:** 1. Ve a [nodejs.org](https://nodejs.org) 2. Descarga la versión LTS 3. Instálala 4. Verifica nuevamente --- ### Paso 2: Instalar OpenCode Tienes **dos opciones**: #### Opción A: Con curl (Linux/Mac/WSL) **Hint:** El instalador oficial usa el dominio opencode.ai **Comando parcial:** `curl -fsSL https://opencode.ai/install |` **Completá el comando:** ``` [ESCRIBE AQUÍ] ``` **Resultado esperado:** ``` ✅ OpenCode installed successfully! Run: opencode ``` --- #### Opción B: Con npm (Todas las plataformas) **Hint:** El flag -g significa instalación global **Comando parcial:** `npm install -g @` **Completá el comando:** ``` [ESCRIBE AQUÍ] ``` **Resultado esperado:** ``` added X packages in Ys ``` --- #### Opción C: Con Homebrew (Mac) **Hint:** brew install seguido del nombre del paquete **Comando parcial:** `brew install an` **Completá el comando:** ``` [ESCRIBE AQUÍ] ``` **Resultado esperado:** ``` ==> Downloading https://... ==> Installing opencode... ``` --- ### Paso 3: Verificar Instalación **Comando:** ``` opencode --version ``` **Resultado esperado:** ``` X.X.X ``` --- ## 🔑 Configuración de API Keys ### ¿Por qué necesitas API Keys? ``` ┌──────────────────────────────────────────────────────────────────────────────┐ │ │ │ OPENCODE no es gratis porque: │ │ │ │ - La HERRAMIENTA es gratis (MIT) │ │ - Los MODELOS de IA NO lo son │ │ │ │ Vos pagás SOLO el modelo que uses: │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ OpenAI │ │ Anthropic │ │ Google │ │ │ │ GPT-4o │ │ Claude 4 │ │ Gemini 2.0 │ │ │ │ $5/1M tok │ │ $3/1M tok │ │ $0.125/1M │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────┘ ``` ### Modelos Recomendados por Budget | Budget | Modelo Recomendado | Costo Aproximado | Mejor Para | |--------|-------------------|------------------|------------| | **$0** | Gemini 2.0 Flash | Gratis (150 req/min) | Aprender, practicar | | **Bajo** | Claude Haiku | $0.80/1M tokens | Tareas rápidas | | **Medio** | GPT-4o Mini | $0.15/1M tokens | Desarrollo diario | | **Alto** | Claude Sonnet 4 | $3/1M tokens | Código complejo | | **Máximo** | Claude Opus 4 | $15/1M tokens | Arquitectura, debugging | --- ### Obtener tu API Key #### Anthropic (Claude) — Recomendado 1. Ve a [console.anthropic.com](https://console.anthropic.com) 2. Crea cuenta o inicia sesión 3. Ve a **API Keys** → **Create Key** 4. Copia la key (empieza con `sk-ant-`) **Costo:** $5 gratis en créditos para nuevos usuarios --- #### OpenAI (GPT-4) — Alternativa 1. Ve a [platform.openai.com](https://platform.openai.com) 2. Crea cuenta o inicia sesión 3. Ve a **API Keys** → **Create new secret key** 4. Copia la key (empieza con `sk-`) **Costo:** $5 gratis para nuevos usuarios --- #### Google (Gemini) — Gratis 1. Ve a [aistudio.google.com](https://aistudio.google.com) 2. Crea cuenta o inicia sesión 3. Ve a **Get API Key** → **Create API Key** 4. Copia la key (empieza con `AIza`) **Costo:** GRATIS hasta ciertos límites --- ### Configurar API Keys en tu Sistema **Opción A: Variables de entorno (Recomendado)** **Archivo:** `~/.bashrc` o `~/.zshrc` (Mac) **Agregá estas líneas:** ```bash # API Keys para OpenCode export ANTHROPIC_API_KEY="sk-ant-tu-key-aqui" export OPENAI_API_KEY="sk-tu-key-aqui" export GOOGLE_API_KEY="AIza-tu-key-aqui" ``` **Comando para recargar:** ```bash # Linux/Mac source ~/.bashrc # o source ~/.zshrc # Mac con zsh source ~/.zshrc ``` --- **Opción B: Archivo .env en el proyecto** 1. Creá un archivo `.env` en tu proyecto 2. Agregá las keys 3. **Agregá `.env` a tu `.gitignore`** ```bash # En tu .gitignore .env .env.* ``` ⚠️ **NUNCA committees archivos con API keys** --- ## ⚙️ Configuración de OpenCode ### Estructura de Archivos ``` ~/.config/opencode/ ├── opencode.json # Configuración principal ├── AGENTS.md # Tu identidad y reglas ├── agents/ # Definiciones de agentes ├── config/ │ └── skills/ # Skills disponibles └── mcp/ # MCP servers ``` --- ### El archivo opencode.json #### Tu primera configuración **Ubicación:** `~/.config/opencode/opencode.json` **Tu tarea:** Crear este archivo con tu editor favorito. **Comando para crear directorio:** ```bash mkdir -p ~/.config/opencode ``` **Comando para crear archivo:** ```bash touch ~/.config/opencode/opencode.json ``` --- ### Explicación de Cada Setting #### 1. Modelo Principal ```json "model": "anthropic/claude-sonnet-4-6-20250501" ``` | Parte | Significado | |-------|-------------| | `anthropic` | Proveedor (namespace) | | `claude-sonnet-4-6-20250501` | Modelo específico | **Modelos disponibles:** | Proveedor | Modelo | Uso | |-----------|--------|-----| | `anthropic` | `claude-opus-4-6-20250501` | Mejor para arquitectura | | `anthropic` | `claude-sonnet-4-6-20250501` | Balanceado, recomendado | | `anthropic` | `claude-haiku-4-5-20250501` | Rápido, barato | | `openai` | `gpt-4o` | General, rápido | | `google` | `gemini-2.0-flash` | Gratis, rápido | | `google` | `gemini-2.5-pro` | Mejor de Google | --- #### 2. Actualización Automática ```json "autoupdate": true ``` | Valor | Significado | |-------|-------------| | `true` | Se actualiza automáticamente | | `false` | Vos controlás las actualizaciones | --- #### 3. Puerto del Servidor ```json "server": { "port": 4096 } ``` **¿Qué es esto?** OpenCode puede correr como servidor HTTP para integraciones. | Valor | Uso | |-------|-----| | `4096` | Puerto por defecto | | `8080` | Común para desarrollo | | `3000` | Común para frontend | --- #### 4. Instrucciones Globales ```json "instructions": [ "~/.config/opencode/mcp-security-resources.md" ] ``` **¿Qué es esto?** Archivos que OpenCode siempre lee antes de empezar. **Ejemplo de archivo de instrucciones:** ```markdown # Instrucciones de Seguridad ## Reglas de Oro 1. NUNCA ejecutes comandos destructivos sin preguntar 2. NUNCA leas archivos .env o secrets 3. SIEMPRE pregunta antes de git push ``` --- ### Permisos: La Parte Más Importante ```json "permission": { "bash": { ... }, "read": { ... }, "write": { ... } } ``` #### Permisos de Bash ```json "bash": { "git status": "allow", "git diff *": "allow", "rm -rf *": "deny", "rm *": "ask", "git push": "ask", "*": "deny" } ``` | Acción | Significado | |--------|-------------| | `"allow"` | Se ejecuta sin preguntar | | `"ask"` | Pregunta antes de ejecutar | | `"deny"` | Nunca se ejecuta | **Tus permisos personalizados:** ```json "bash": { "git status": "allow", "git diff": "allow", "git log": "allow", "git branch": "allow", "npm *": "allow", "npm run *": "allow", "mkdir *": "allow", "touch *": "allow", "rm -rf *": "deny", "rm *": "ask", "git commit *": "ask", "git push": "ask", "sudo *": "ask", "*": "deny" } ``` --- #### Permisos de Lectura ```json "read": { "**/.env": "deny", "**/.env.*": "deny", "**/credentials.json": "deny", "**/secrets/**": "deny", "**/id_rsa*": "deny", "*.env": "deny", "*": "allow" } ``` **¿Por qué deny en .env?** Son archivos con passwords y API keys. OpenCode NO necesita leerlos para hacer su trabajo. **Tus permisos personalizados:** ```json "read": { "**/.env": "deny", "**/.env.*": "deny", "**/credentials.json": "deny", "**/*secret*": "deny", "**/*password*": "deny", "**/id_rsa*": "deny", "**/id_ed25519*": "deny", "*.pem": "deny", "*": "allow" } ``` --- #### Permisos de Escritura ```json "write": { "**/.env": "deny", "**/.env.*": "deny", "**/credentials.json": "deny", "**/secrets/**": "deny", "*.env": "deny", "*.pem": "deny" } ``` **¿Por qué deny en .env?** Nadie debería modificar archivos de secrets automáticamente. --- ### MCP Servers: Conexiones Externas ```json "mcp": { "chrome-devtools": { "command": ["npx", "-y", "chrome-devtools-mcp@latest"], "type": "local" }, "context7": { "enabled": true, "type": "remote", "url": "https://mcp.context7.com/mcp" }, "engram": { "command": ["engram", "mcp"], "enabled": true, "type": "local" } } ``` | Server | Propósito | Tipo | |--------|-----------|------| | `chrome-devtools` | Controlar Chrome para debugging | Local | | `context7` | Buscar documentación actualizada | Remote | | `engram` | Memoria persistente | Local | --- ## 📝 AGENTS.md: Tu Identidad ### ¿Qué es AGENTS.md? **AGENTS.md es el archivo donde definís QUIÉN sos y CÓMO querés que OpenCode trabaje.** ``` ┌──────────────────────────────────────────────────────────────────────────────┐ │ │ │ AGENTS.md = TU PERFIL DE DESARROLLADOR │ │ ═══════════════════════════════════ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ # Quién soy │ │ │ │ Soy Diego, desarrollador FullStack... │ │ │ │ │ │ │ │ # Reglas de trabajo │ │ │ │ - Siempre uso TypeScript strict │ │ │ │ - Tests primero, código después │ │ │ │ - Nombres descriptivos, sin abreviaciones │ │ │ │ │ │ │ │ # Preferencias │ │ │ │ - snake_case para Python │ │ │ │ - kebab-case para archivos │ │ │ │ - Español para comentarios │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────┘ ``` --- ### Tu Primer AGENTS.md **Ubicación:** `~/.config/opencode/AGENTS.md` o en tu proyecto **Comando para crear:** ```bash touch ~/.config/opencode/AGENTS.md ``` --- ### Template de AGENTS.md ```markdown # AGENTS.md — Mi Perfil de Desarrollador --- ## 👤 Quién Soy **Nombre:** [Tu nombre] **Rol:** [Tu rol: Frontend Dev, Backend Dev, FullStack, etc.] **Experiencia:** [Años de experiencia] **Especialidades:** [Ej: TypeScript, Python, Seguridad, etc.] --- ## 🛠️ Stack Tecnológico ### Lenguajes Principales - [Tu lenguaje 1] - [Tu lenguaje 2] ### Frameworks/Stack - [Framework 1] - [Framework 2] ### Herramientas - Git: ✅ - Docker: ✅/❌ - Kubernetes: ✅/❌ - CI/CD: [Tu herramienta] --- ## 📋 Reglas de Trabajo ### Obligatorias 1. [Regla 1] 2. [Regla 2] 3. [Regla 3] ### Estilo de Código - Nombres: [descriptivos, camelCase, snake_case, etc.] - Comentarios: [en qué idioma] - Tests: [primero, después, o no?] ### Seguridad 1. Nunca revelar API keys o secrets 2. Siempre validar input de usuarios 3. No ejecutar comandos destructivos sin confirmar --- ## 🎯 Preferencias de Comunicación ### Idioma - Código y comentarios: [Español, English] - Nombres de variables: [inglés siempre, o mixto] ### Nivel de Explicación - Básico: [Para principiantes] - Intermedio: [Con contexto] - Avanzado: [Solo lo esencial] --- ## 🚫 Límites y Restricciones ### No Hacer 1. [Cosa que NO hacés] 2. [Otra cosa que NO hacés] ### Siempre Preguntar 1. [Situación 1] 2. [Situación 2] --- ## 💡 Tips para Trabajar Conmigo 1. [Tip 1] 2. [Tip 2] 3. [Tip 3] ``` --- ## 🧪 Lab: Tu Primera Sesión con OpenCode ### Objetivo Ejecutar OpenCode con tu configuración personalizada. ### ⏱️ Timeline | Paso | Descripción | Tiempo | ✓ | |------|-------------|--------|---| | 1 | Crear opencode.json | 10 min | ⬜ | | 2 | Crear AGENTS.md | 10 min | ⬜ | | 3 | Configurar API Key | 5 min | ⬜ | | 4 | Primera sesión | 15 min | ⬜ | --- ### Escenario Tony acaba de salir de la cueva. Necesita configurar su taller (OpenCode) para la próxima misión. **Tu turno:** Configurar OpenCode como Tony configuraría su armadura. --- ### Paso 1: Crear opencode.json **Archivo:** `~/.config/opencode/opencode.json` **Completá este template:** ```json { "$schema": "https://opencode.ai/config.json", "model": "[TU MODELO ELEGIDO]", "autoupdate": true, "server": { "port": 4096 }, "instructions": [], "mcp": { "context7": { "enabled": true, "type": "remote", "url": "https://mcp.context7.com/mcp" } }, "permission": { "bash": { "git status": "allow", "git diff *": "allow", "git log *": "allow", "npm *": "allow", "mkdir *": "allow", "rm -rf *": "deny", "rm *": "ask", "git push": "ask", "*": "deny" }, "read": { "**/.env": "deny", "**/.env.*": "deny", "*.env": "deny", "*": "allow" }, "write": { "**/.env": "deny", "*.env": "deny", "*.pem": "deny" } } } ``` --- ### Paso 2: Crear AGENTS.md **Archivo:** `~/.config/opencode/AGENTS.md` **Completá tu perfil:** ```markdown # AGENTS.md — [Tu Nombre] ## 👤 Quién Soy [Tu descripción] ## 🛠️ Stack [Lenguajes, frameworks, herramientas] ## 📋 Reglas de Trabajo 1. [Tu regla 1] 2. [Tu regla 2] 3. [Tu regla 3] ## 🎯 Preferencias [Cómo querés que trabaje] ## 🚫 Límites [Qué NO hacer] ``` --- ### Paso 3: Configurar API Key **Verificá que tu API key está disponible:** ```bash echo $ANTHROPIC_API_KEY ``` **Resultado esperado:** ``` sk-ant-xxxxxxxxxxxxxxxxxxxx ``` **Si está vacío:** 1. Editá tu `~/.bashrc` o `~/.zshrc` 2. Agregá: `export ANTHROPIC_API_KEY="tu-key"` 3. Ejecutá: `source ~/.bashrc` --- ### Paso 4: Tu Primera Sesión **Comando para iniciar:** ```bash opencode ``` **Tu primer mensaje:** ``` > Hola. Soy [tu nombre]. > acabo de configurar OpenCode. > Por favor confirmame que lees mi AGENTS.md > y decime qué reglas encontraste. ``` --- **Tu respuesta esperada:** ``` ✅ Leo tu AGENTS.md 📋 Reglas que encontré: 1. [Regla 1] 2. [Regla 2] 3. [Regla 3] ``` --- ### Reflexión **Completá:** ``` Mis reglas definidas fueron: 1. ________________________________________________ 2. ________________________________________________ 3. ________________________________________________ Algo que me sorprendió de OpenCode: ________________________________________________ Algo que quiero ajustar: ________________________________________________ ``` --- ## 📁 Entregable Final ### Archivos a crear: | Archivo | Ubicación | Propósito | |---------|-----------|-----------| | `opencode.json` | `~/.config/opencode/` | Configuración | | `AGENTS.md` | `~/.config/opencode/` | Tu perfil | ### Contenido esperado: ```bash # Verificar archivos ls -la ~/.config/opencode/ # Deberías ver: # opencode.json # AGENTS.md ``` --- ## ✅ Checklist Final | Habilidad | Demostrable cuando... | ✓ | |-----------|------------------------|---| | **Instalar** | `opencode --version` funciona | ⬜ | | **Configurar** | opencode.json tiene permisos | ⬜ | | **AGENTS.md** | Defines tu perfil completo | ⬜ | | **API Key** | Variable de entorno configurada | ⬜ | | **Sesión** | Pudiste conversar con OpenCode | ⬜ | --- ## 🏆 Logro **"Armador"** desbloqueado: - +100 XP - Acceso a herramientas avanzadas - AGENTS.md personalizado listo para usar --- ## 🔗 Siguiente **¿Listo para la próxima herramienta?** [→ Unidad 3: Claude Code — Tu JARVIS Potente](../contenido/nivel3.qmd) **¿Necesitás más práctica?** [→ Quiz Unidad 2: Configuración de OpenCode](../quizzes/unidad2.md)