Cómo ejecutar OpenCode en Windows: instalación nativa o WSL

Respuesta rápida: sí, opencode funciona en Windows

# PowerShell - instala opencode globalmente con npm
npm install -g opencode-ai

# Verifica la instalación
opencode --version

# Arranca opencode dentro de la carpeta de un proyecto
opencode

Eso es todo el camino nativo en Windows: Node.js y una instalación con npm. No necesitas WSL solo para ejecutar opencode. WSL pasa a ser la mejor opción únicamente cuando tu propio proyecto depende de herramientas de Linux, algo que vemos más abajo.

opencode es el agente de terminal open source de SST. Para los comandos exactos de instalación y las últimas opciones, consulta la web oficial de opencode y el repositorio de opencode en GitHub, ya que el método de instalación va cambiando con el tiempo. Esta guía es el espejo de nuestra guía de Claude Code en Windows y de la guía de Codex CLI en Windows, pero para opencode.

Qué necesitas antes de instalar

• Windows 10 o Windows 11, de 64 bits. opencode es una herramienta de línea de comandos que ejecutas desde un terminal.
• Node.js (una versión LTS reciente) y npm, que viene con Node.js. Es lo que necesita la instalación nativa en Windows.
• Un terminal: Windows Terminal o PowerShell, los dos vienen con Windows. PowerShell sirve perfectamente para instalar y ejecutar opencode.
• Una cuenta o clave de API con al menos un proveedor de modelos (Anthropic, OpenAI, Google o un modelo local). opencode es agnóstico al proveedor, así que se conecta al que elijas la primera vez que lo ejecutes.

Instalación nativa en Windows paso a paso

Con Node.js ya en su sitio, instalar opencode de forma nativa en Windows lleva más o menos un minuto:

• Abre Windows Terminal o PowerShell. No hace falta ejecutarlo como administrador.
• Comprueba que Node.js está listo con node --version y npm --version.
• Instala opencode globalmente: npm install -g opencode-ai
• Cierra y vuelve a abrir el terminal para que el nuevo comando quede en tu PATH.
• Ejecuta opencode --version para confirmar que está instalado.

Para actualizar opencode más adelante, vuelve a ejecutar el mismo comando de npm, que descarga la última versión publicada:

npm install -g opencode-ai@latest

Primer arranque: conectar un proveedor

• Abre un terminal en la carpeta de un proyecto y escribe opencode.
• Conecta un proveedor (por ejemplo con opencode auth login): elige Anthropic, OpenAI, Google u otro proveedor, y luego inicia sesión o pega una clave de API.
• Una vez conectado el proveedor, pídele a opencode algo sobre tu código y déjalo trabajar.

Una vez que conectas un proveedor, opencode guarda esas credenciales, así que la próxima vez que ejecutes opencode en cualquier carpeta arranca directamente. Su configuración global vive en ~/.config/opencode dentro de tu perfil de usuario, y cada terminal que abras es su propia sesión de opencode independiente. El comando de autenticación exacto puede cambiar, así que consulta la documentación oficial de opencode si el flujo se ve distinto en tu versión.

Ejecutar opencode en WSL (y cuándo es mejor opción)

WSL (Subsistema de Windows para Linux) te permite ejecutar un entorno Linux real dentro de Windows. opencode funciona ahí exactamente igual, y hay dos escenarios donde WSL es la mejor opción:

• Tu proyecto depende de herramientas de Linux. Si tu cadena de build, scripts o dependencias asumen Linux, ejecuta opencode donde realmente corre tu proyecto para que las rutas y los comandos de shell coincidan.
• Quieres el comportamiento de comandos nativos de Linux. Cierto sandboxing y algunos comandos de shell solo encajan bien dentro de un entorno Linux, que en Windows significa WSL 2.

Para ejecutar opencode dentro de WSL, abre el terminal de tu distribución WSL (no PowerShell), asegúrate de que Node.js y npm están instalados dentro de ese entorno Linux e instala opencode ahí:

# Dentro de tu terminal de WSL (Linux)
npm install -g opencode-ai

# Luego ejecútalo desde tu proyecto
opencode

Un detalle a tener en cuenta en WSL: conectar tu proveedor desde un terminal de Linux a veces te muestra un código o una URL para completar en el navegador de Windows en lugar de redirigir automáticamente. Si pasa, termina el flujo en el navegador y vuelve al terminal, y mantén los archivos del proyecto dentro del sistema de archivos de Linux para el mejor rendimiento.

Windows nativo vs WSL: ¿cuál usar?

• Windows nativo: lo mejor para proyectos nativos de Windows (.NET, Unity, desarrollo web con herramientas de Windows). Setup más simple, solo Node.js más una instalación con npm, y se ejecuta directamente desde PowerShell.
• WSL 2: lo mejor para toolchains de Linux y para el comportamiento de comandos nativos de Linux. Tus archivos viven en el sistema de archivos de Linux, así que los proyectos Linux-first se comportan exactamente igual que en un servidor.
• WSL 1: solo si WSL 2 no está disponible en tu máquina. Tiene problemas conocidos ejecutando binarios nativos, así que usa WSL 2 siempre que puedas.

Si no lo tienes claro, empieza con la nativa. Es el camino con menos fricción en Windows y siempre puedes añadir una instalación en WSL después; las dos pueden convivir en la misma máquina, e incluso puedes apuntar distintos terminales de opencode a distintos setups.

Errores comunes en Windows y cómo arreglarlos

• "opencode is not recognized as a command": la carpeta global de binarios de npm no está en tu PATH, o no reabriste el terminal después de instalar. Cierra y vuelve a abrir PowerShell, y confirma que npm config get prefix apunta a una carpeta que esté en tu PATH.
• "npm is not recognized": Node.js no está instalado o no está en tu PATH. Instala Node.js LTS, reabre el terminal y comprueba node --version.
• Errores EACCES o de permisos en npm install -g: tu carpeta global de npm no es escribible por tu usuario. Reinstala Node.js con el instalador oficial de Windows o configura un prefix de npm dentro de tu perfil de usuario en lugar de forzarlo con permisos de administrador.
• Proxy corporativo o errores SSL durante la instalación: configura npm con los datos de tu proxy, o haz la instalación desde una red que no esté detrás del proxy y actualiza después.
• Errores de autenticación del proveedor: normalmente una clave de API incorrecta o ausente, o el proveedor equivocado seleccionado. Vuelve a ejecutar el flujo de autenticación y comprueba qué proveedor está configurado en ~/.config/opencode/opencode.json.
• opencode se comporta raro con rutas o comandos de Windows: es probable que tu proyecto espere un shell de Unix. Ejecuta opencode dentro de WSL para ese proyecto, así las rutas y los comandos coinciden.

Para cualquier otra cosa, el repositorio oficial de opencode registra los problemas conocidos y las instrucciones de instalación actuales, que es la fuente de verdad a medida que la herramienta evoluciona.

Ejecutar varias sesiones de opencode en Windows

Con opencode funcionando, el siguiente cuello de botella aparece rápido: un terminal significa una tarea a la vez. Le das algo que hacer a opencode, y a esperar. La mayoría acaba abriendo varias pestañas de terminal y perdiendo la pista de qué agente terminó, cuál está esperando un permiso y qué cambió cada uno.

Ese es el problema que resuelve CodeAgentSwarm, y es una app de escritorio nativa tanto para Windows como para macOS. Ejecuta tus sesiones de opencode dentro de un espacio de trabajo visual, así que los desarrolladores en Windows tienen una GUI de verdad más varios terminales de opencode en paralelo, con notificaciones de escritorio cuando un agente termina o necesita tu input, historial buscable de todas las sesiones y un diff en vivo de lo que cambió cada terminal. Además lee las sesiones locales de opencode, así que las conversaciones anteriores siguen siendo buscables y puedes retomarlas.

Si quieres tirar por ese camino, estas guías son el siguiente paso natural: ejecutar un enjambre de agentes opencode, ejecutar múltiples sesiones de opencode y la visión más amplia del enjambre de agentes CLI de IA en cualquier CLI.

Conclusión

Ejecutar opencode en Windows es sencillo: instala Node.js, ejecuta una instalación con npm y arráncalo desde PowerShell. La nativa es la opción correcta por defecto para la mayoría de desarrolladores en Windows; WSL 2 está ahí para cuando tu proyecto depende de herramientas de Linux o quieres el comportamiento de comandos nativos de Linux. En cualquier caso, conectas un proveedor una vez y opencode lo recuerda.

Instálalo, conecta tu proveedor una vez, y cuando un solo terminal se te quede corto, CodeAgentSwarm te da una GUI nativa de Windows para ejecutar varios agentes de opencode en paralelo sin perder el hilo.