Una guía práctica para empezar a programar con un agente de IA en tu terminal: Claude Code, de Anthropic, y OpenCode, de código abierto. Cómo instalarlos en Windows, conectarlos, darles el contexto de tu proyecto y limitar lo que pueden hacer, con los comandos del día a día lado a lado. Todos los comandos están también en el README.md de la izquierda.
¿Qué vas a aprender?
- Qué hace un agente de programación y en qué se diferencia de un chat.
- Instalar Claude Code y OpenCode en Windows y comprobar que funcionan.
- Conectar tu cuenta o el proveedor de modelos y elegir el modelo.
- Darle al agente el contexto de tu proyecto con
CLAUDE.mdoAGENTS.md. - Configurar permisos para que no lea tus secretos ni ejecute lo que no quieras.
- Los comandos del día a día, cómo deshacer y cómo trabajar con seguridad.
Requisitos previos
- Windows 10 (versión 1809 o posterior) con PowerShell; los comandos equivalentes para macOS y Linux están en cada paso.
- Para Claude Code: un plan Pro, Max, Team o Enterprise de Claude, o una cuenta de Claude Console (API). El plan gratuito de Claude no incluye Claude Code.
- Para OpenCode: una cuenta de un proveedor de modelos (Anthropic, OpenAI, GitHub Copilot…) o modelos en tu equipo con Ollama (ver la guía de Ollama).
- Git (en Windows, Git for Windows, recomendado: Claude Code usa Git Bash si está instalado y, si no, PowerShell).
- Un proyecto en un repositorio Git, para poder revisar y deshacer los cambios del agente.
Paso a paso
1. Entiende qué hace un agente de programación
Un agente no solo responde preguntas: lee tu proyecto, edita archivos y ejecuta comandos en tu terminal para completar una tarea, y te pide permiso para lo que tú decidas. Por eso hay que configurarlo bien antes de usarlo en un proyecto real.
| Claude Code | OpenCode | |
|---|---|---|
| Quién lo hace | Anthropic | Proyecto de código abierto (licencia MIT) |
| Modelos | Claude (también vía Amazon Bedrock, Google Cloud o Microsoft Foundry) | Varios proveedores: Anthropic, OpenAI, GitHub Copilot, modelos locales… |
| Archivo de contexto | CLAUDE.md | AGENTS.md (y lee CLAUDE.md si no hay) |
| Configuración | .claude/settings.json | opencode.json |
2. Instala Claude Code
El instalador nativo es el recomendado en Windows: no necesita Node.js y se actualiza solo en segundo plano. Desde PowerShell:
# Instalador nativo (recomendado): no necesita Node.js y se actualiza solo
irm https://claude.ai/install.ps1 | iex
# Alternativa con WinGet (se actualiza con winget upgrade Anthropic.ClaudeCode)
winget install Anthropic.ClaudeCode
# Abre una terminal nueva y comprueba
claude --version
claude doctor
En macOS, Linux o WSL:
# macOS, Linux o WSL
curl -fsSL https://claude.ai/install.sh | bash
claude doctor revisa la instalación sin abrir una sesión. No confundas Claude Code con la aplicación de escritorio de Claude: son descargas distintas.
3. Instala OpenCode
OpenCode no se instala con gestores de paquetes de Windows: su documentación ofrece un zip con el ejecutable para Windows (x64 y ARM64) y un instalador de la aplicación de escritorio. Con el zip, descomprímelo en una carpeta y añádela a tu PATH:
# Windows: descomprime el zip de OpenCode para Windows (x64 o ARM64) que enlaza opencode.ai/docs,
# por ejemplo en C:\herramientas\opencode, y añade esa carpeta a tu PATH de usuario:
$actual = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$actual;C:\herramientas\opencode", 'User')
# Abre una terminal nueva y comprueba
opencode --version
En macOS y Linux:
# macOS o Linux: script oficial
curl -fsSL https://opencode.ai/v2/install | bash
# o con Homebrew
brew install anomalyco/tap/opencode-v2
# o con npm (en cualquier sistema con Node.js)
npm install -g @opencode/cli
# Actualizar más adelante
opencode upgrade
4. Inicia sesión y elige el modelo
Los dos se arrancan desde la carpeta del proyecto. Claude Code te lleva al navegador para iniciar sesión con tu cuenta de Claude; en OpenCode conectas el proveedor que quieras desde la propia interfaz:
# Claude Code: entra en tu proyecto y arranca; la primera vez abre el navegador para iniciar sesión
cd C:\proyectos\mi-aplicacion
claude
claude auth status # comprueba con qué cuenta estás conectado
# OpenCode: arranca y, dentro, conecta un proveedor y elige el modelo
opencode
# /connect -> eliges el proveedor (Anthropic, OpenAI, GitHub Copilot, Ollama…) e introduces las credenciales
# /models -> eliges el modelo
# OpenCode también desde la línea de comandos
opencode auth login
opencode auth list
opencode models
Dentro de Claude Code, /login y /logout cambian de cuenta y /model cambia de modelo.
5. Dale contexto con CLAUDE.md o AGENTS.md
El agente lee al empezar un archivo con las instrucciones de tu proyecto: cómo se compila, cómo se prueba y qué convenciones seguís. En Claude Code, /init analiza el proyecto y crea un CLAUDE.md inicial (si ya existe, propone mejoras). En OpenCode el archivo es AGENTS.md, en la raíz del proyecto. Un ejemplo:
# Mi aplicación
## Comandos
- Instalar dependencias: npm install
- Ejecutar las pruebas: npm test
- Comprobar el estilo: npm run lint
## Convenciones
- TypeScript estricto; nada de any.
- Cada cambio de lógica va con su prueba.
- No toques los archivos de la carpeta migrations/ sin pedirlo.
## Antes de terminar
- Ejecuta npm test y npm run lint y corrige lo que falle.
Un mismo archivo puede servir para los dos: Claude Code lee AGENTS.md cuando no hay CLAUDE.md, y OpenCode lee CLAUDE.md cuando no hay AGENTS.md. Súbelo al repositorio para que todo el equipo trabaje igual. Para notas personales, Claude Code usa CLAUDE.local.md: añádelo a .gitignore.
6. Configura los permisos
Decide qué puede hacer el agente sin preguntar y qué no puede hacer nunca. En Claude Code, en .claude/settings.json (compartido con el equipo) o .claude/settings.local.json (solo para ti, fuera de Git). Las reglas de deny siempre ganan:
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}
En OpenCode, en opencode.json en la raíz del proyecto, con una lista de reglas (allow, ask o deny; si ninguna coincide, pregunta, y si varias coinciden gana la última). También fija ahí el modelo, con el formato proveedor/modelo:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5",
"permissions": [
{ "action": "shell", "resource": "npm test*", "effect": "allow" },
{ "action": "read", "resource": "*.env", "effect": "deny" },
{ "action": "read", "resource": "*.env.*", "effect": "deny" }
]
}
Los dos archivos son JSON. En Claude Code tiene que ser JSON estricto: sin comentarios ni comas al final. Con /permissions ves en Claude Code todas las reglas activas y de qué archivo viene cada una.
7. Elige cómo trabaja: planificar o editar
Antes de un cambio grande, pide primero un plan. En Claude Code, Shift+Tab alterna los modos: el normal (pide permiso), aceptar ediciones (edita sin preguntar) y plan (analiza y propone sin tocar nada). En las versiones recientes, la sesión interactiva puede empezar en modo automático: compruébalo en la parte inferior de la pantalla.
En OpenCode hay dos agentes: Build, por defecto, con acceso completo, y Plan, que explora y planifica sin editar los archivos del proyecto. Se alternan con Shift+Tab.
8. Usa los comandos del día a día
| Qué quieres hacer | Claude Code | OpenCode |
|---|---|---|
| Empezar una conversación nueva | /clear | /new |
| Cambiar de modelo | /model | /models |
| Señalar un archivo | @ + ruta | @ + ruta |
| Ejecutar un comando de la terminal | ! al principio | ! al principio |
| Interrumpir | Esc | Esc |
| Deshacer cambios | Esc dos veces o /rewind | /undo (y /redo) |
| Resumir para liberar contexto | /compact | Ctrl+X y luego C |
| Ver sesiones anteriores | /resume | /sessions |
| Ver consumo y límites | /usage | — |
Y desde la terminal, sin abrir la interfaz:
# Una petición sin abrir la interfaz (útil en scripts)
claude -p "Explica qué hace la carpeta src/servicios"
opencode run "Explica qué hace la carpeta src/servicios"
# Retomar el trabajo
claude -c # la última conversación de esta carpeta
claude -r "nombre-o-id" # una sesión concreta
Si usas VS Code, los dos tienen extensión oficial: Claude Code (de Anthropic) y OpenCode. La de Claude Code no instala el comando claude: para la terminal, instálalo como en el paso 2.
9. Trabaja con seguridad
Tú eres responsable de lo que el agente cambia y ejecuta. Trabaja en una rama, revisa cada cambio antes de aprobarlo y confírmalo tú:
# Antes de empezar: deja el repositorio limpio
git status
git switch -c agente/nueva-funcionalidad
# Al terminar: revisa todo lo que ha cambiado antes de confirmarlo
git diff
git add -p
- Niega la lectura de secretos (
.env, claves, certificados) como en el paso 6. - No pases al agente contenido de origen desconocido (páginas, correos, archivos de terceros) sin revisarlo: puede llevar instrucciones ocultas (prompt injection).
- No uses el modo que se salta todos los permisos (
bypassPermissionsen Claude Code) fuera de un entorno aislado. - En Claude Code,
/sandboxaísla los comandos del agente en macOS, Linux y WSL 2; no está disponible en Windows nativo.
Errores habituales
«claude» no se reconoce como comando
La carpeta del instalador no está en el PATH. Comprueba que existe %USERPROFILE%\.local\bin\claude.exe con Test-Path "$env:USERPROFILE\.local\bin\claude.exe", añádela a tu PATH de usuario como en el paso 3 (con esa carpeta) y abre una terminal nueva.
«opencode» no se reconoce como comando
La carpeta donde descomprimiste el zip no está en el PATH, o la terminal es anterior al cambio. Revisa la ruta del paso 3 y abre una terminal nueva.
Claude Code no encuentra Git Bash
Busca dónde está Git con where.exe git e indica la ruta de bash.exe en settings.json: "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" }.
Sesión caducada o «Not logged in»
En Claude Code, vuelve a iniciar sesión con /login o claude auth login y comprueba que la hora de tu equipo es correcta. En OpenCode, vuelve a conectar el proveedor con /connect y revisa con opencode auth list.
No funciona detrás del proxy de la empresa
Define el proxy antes de instalar y de arrancar: $env:HTTPS_PROXY = 'http://proxy.ejemplo.com:8080' y lo mismo con HTTP_PROXY. OpenCode también admite NO_PROXY y NODE_EXTRA_CA_CERTS para la CA de la empresa.
Claude Code no encuentra archivos al buscar
Instala ripgrep (winget install BurntSushi.ripgrep.MSVC), añade "USE_BUILTIN_RIPGREP": "0" en el bloque env de settings.json y comprueba con claude doctor.
El agente ha leído o modificado algo que no debía
Deshaz el cambio (/rewind en Claude Code, /undo en OpenCode, o git restore) y añade la regla de deny que faltaba. Con /permissions revisas en Claude Code las reglas activas.
Siguientes pasos
- Usar modelos en tu propio equipo con Ollama, sin enviar el código fuera (ver la guía de Ollama).
- Acordar con el equipo un
CLAUDE.mdoAGENTS.mdcomún y la revisión obligatoria del código que genera el agente. - Conectar herramientas externas con servidores MCP (en OpenCode,
opencode mcp add). - Usar el agente en pipelines con
claude -puopencode run(ver la guía de CI/CD con GitHub Actions).