Guía 03 — Windows 10/11

Instalar OpenCode en Windows: CLI y Desktop

Desde cero con PowerShell — npm, Scoop, Chocolatey, WinGet y app de escritorio

Objetivo

Al finalizar tendrás OpenCode CLI funcionando con opencode --version y opcionalmente la Desktop App, listos para abrir cualquier carpeta con opencode y conectar tu proveedor LLM.

0. Requisitos previos

Windows 10 (1809+) o Windows 11, 64-bit.
PowerShell o Windows Terminal (no ejecutar como administrador salvo que se indique).
Conexión a internet para descargar Node.js y OpenCode.

1. Instalar Node.js LTS (necesario para CLI nativo)

OpenCode CLI en Windows se instala vía npm, que viene con Node.js.

Opción A — WinGet (recomendada en Windows 10/11)

winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements

Cierra y reabre PowerShell después de instalar para que node y npm entren al PATH.

Opción B — Descarga manual

Descarga el LTS desde nodejs.org → instalador .msi → siguiente/siguiente. Verifica:

node --version
npm --version

2. Instalar OpenCode CLI — Elige UNA vía

Todas instalan el mismo binario. Elige la que ya uses en clase.

Vía 1 — npm (más universal)

npm install -g opencode-ai

Para actualizar luego: npm install -g opencode-ai@latest

Vía 2 — Scoop

scoop install opencode

Vía 3 — Chocolatey (requiere PowerShell admin)

choco install opencode

Vía 4 — Script oficial (Git Bash / WSL)

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

En Windows nativo prefiere npm/scoop. El script es ideal para WSL/Linux.

Verificar instalación CLI

opencode --version
opencode --help

Si PowerShell dice “no se reconoce”, cierra y reabre la terminal (el PATH se actualiza al reiniciar).

Caso real del Prof. Samuel — OpenCode se deshabilita a los días

En algunos equipos con Node.js, opencode funciona unos días y luego deja de responder (el binario queda bloqueado porque los scripts postinstall de npm fueron ignorados por la política de seguridad del sistema o del antivirus).

Solución que funciona en el aula: reinstalar permitiendo los scripts del paquete:

npm i -g --allow-scripts=opencode-ai opencode-ai
opencode --version

Si usas npm install -g opencode-ai sin --allow-scripts y tu npm o antivirus bloquea scripts, el binario de OpenCode no se extrae/actualiza bien y “desaparece”. El flag --allow-scripts=opencode-ai autoriza solo los scripts de ese paquete y restaura la instalación. Alternativa: scoop install opencode / choco install opencode (no dependen de npm) o npm install -g opencode-ai@latest --allow-scripts=opencode-ai para forzar la última versión.

Nota para el instituto (4GB RAM, i3 integrada)

CLI nativo es lo recomendado: consume menos RAM que Desktop y no necesita OpenGL 4.1. Si tu proyecto depende de toolchains Linux, usa WSL2 (ver docs/windows-wsl): instala Node dentro de WSL y repite npm install -g opencode-ai allí.

3. Instalar OpenCode Desktop (app gráfica) — Opcional

La Desktop orquesta varias sesiones CLI con interfaz visual (BETA). Puedes tener CLI y Desktop a la vez.

Opción A — Descarga directa (EXE)

Ve a opencode.ai/download o Releases en GitHub.
Descarga opencode-desktop-windows-x64.exe → doble clic → instalar.
Silencioso (para laboratorio): opencode-desktop-windows-x64.exe /S

Opción B — WinGet

winget install --id SST.OpenCodeDesktop --exact
# versión fija:
winget install --id SST.OpenCodeDesktop --exact --version 1.18.20
# silencioso para despliegue:
winget install --id SST.OpenCodeDesktop --exact --silent --accept-package-agreements --accept-source-agreements

Opción C — Scoop

scoop bucket add extras
scoop install extras/opencode-desktop

4. Primer arranque: conectar proveedor y crear AGENTS.md

Abre PowerShell en la carpeta de tu proyecto (ej. vanilla-blog-ofimatica):
```
cd C:\dev\vanilla\vanilla-blog-ofimatica
opencode
```
Dentro de OpenCode ejecuta /connect → elige proveedor (recomendado para clase: OpenCode Zen en opencode.ai/auth → crea cuenta, copia API key y pégala en la TUI).
Inicializa el proyecto:
```
/init
```
Genera AGENTS.md en la raíz (haz git add AGENTS.md). Este archivo le dice a OpenCode cómo es tu proyecto vanilla Jamstack.

Tip de uso en clase

Tab alterna Plan (solo propone) y Build (ejecuta). Para tareas de ofimática, pide primero el plan: “Migra bdTienda-v1.xlsx a Access y crea formulario VENTA”.
@ referencia archivos: Explica @07-Access/practicas/archivos/bdTienda-v1.xlsx
/undo revierte el último cambio, /share genera link para el docente.

5. Solución de problemas comunes (Windows)

Síntoma	Causa	Solución
`opencode: no se reconoce`	PATH no actualizado	Cierra y reabre PowerShell; verifica `npm --version`. Reinstala con `npm install -g opencode-ai`.
`npm ERR! EACCES`	Permisos globales	No uses admin a la fuerza. Reinstala Node.js con instalador oficial (configura carpeta global en tu perfil).
`opencode` funciona días y luego “desaparece”	npm bloqueó `postinstall` (política / antivirus)	Ejecuta `npm i -g --allow-scripts=opencode-ai opencode-ai` y verifica `opencode --version`. Es el fix usado por el Prof. Samuel. Alternativa sin npm: `scoop/choco`.
Desktop no abre	Antivirus bloquea NSIS	Permite en Windows Defender / reinstala con `/S`. Alternativa: usa CLI.
Lentitud en 4GB	Desktop + Chrome + Office	Cierra apps, usa CLI nativo, limita a 1 sesión OpenCode. WSL consume más RAM — evita en 4GB.

6. Qué sigue

Con OpenCode instalado, continúa con Teoría: qué es OpenCode y la Práctica: tu primer proyecto con OpenCode donde pedirás que te explique y migre el módulo Access.

Fuentes: opencode.ai/docs, anomalyco/opencode, opencode.ai/download.