4. Instalación en Windows, Linux y macOS

Objetivo del tema

Dejar OpenCode instalado en tu sistema operativo usando el método más conveniente, completar la autenticación inicial con tu proveedor de modelos y verificar que el agente responde correctamente.

4.1 Método recomendado: script oficial

En Linux, macOS y WSL, la forma más simple de instalar OpenCode es el script de instalación oficial, que detecta tu plataforma y descarga el binario adecuado:

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

Al terminar, el binario queda disponible como opencode. Si el comando no se reconoce de inmediato, abre una nueva terminal o verifica que la carpeta de instalación esté en tu PATH.

¿Es seguro ejecutar un script remoto? El script proviene del dominio oficial del proyecto y su código es público (recuerda que OpenCode es open source). Si tu política de seguridad no permite este método, usa uno de los gestores de paquetes de las secciones siguientes.

4.2 Instalación con gestores de paquetes de Node.js

Si ya trabajas con Node.js, puedes instalar OpenCode como paquete global (opencode-ai) con tu gestor favorito:

npm install -g opencode-ai     # npm
bun install -g opencode-ai     # bun
pnpm install -g opencode-ai    # pnpm
yarn global add opencode-ai    # yarn

Ten en cuenta que, si usas administradores de versiones como nvm o fnm, los paquetes globales dependen de cada versión de Node activa: deberás repetir la instalación o crear alias para las versiones que uses habitualmente.

4.3 Instalación en macOS y Linux

Homebrew (macOS y Linux):

brew install anomalyco/tap/opencode

Se recomienda usar el tap oficial del proyecto porque se actualiza con cada release. La fórmula genénica brew install opencode también existe, pero la mantiene el equipo de Homebrew y suele demorarse más entre versiones.

Arch Linux:

sudo pacman -S opencode        # versión estable
paru -S opencode-bin           # última versión desde AUR

4.4 Instalación en Windows

En Windows tienes dos caminos. El recomendado por el proyecto es usar WSL (ver tema 3) e instalar dentro de él con cualquiera de los métodos para Linux, obteniendo compatibilidad total. Si prefieres la instalación nativa, dispones de estas opciones:

choco install opencode        # Chocolatey
scoop install opencode        # Scoop
npm install -g opencode-ai    # npm
mise use -g github:anomalyco/opencode   # mise

La instalación nativa con Bun en Windows aún está en desarrollo, así que por ahora prioriza Chocolatey, Scoop o npm.

4.5 Otras vías: Docker y binarios de GitHub

Dos alternativas más para entornos controlados:

  • Contenedor Docker: ideal para probar sin instalar nada en el sistema:
    docker run -it --rm ghcr.io/anomalyco/opencode
  • Binarios precompilados: descarga el ejecutable para tu plataforma desde la página de releases en GitHub, colócalo en una carpeta del PATH y dale permisos de ejecución.
Resumen de métodos de instalación
Método Sistemas Ideal para
Script oficial (curl ... | bash) Linux, macOS, WSL Puesta en marcha rápida sin dependencias.
npm / bun / pnpm / yarn Todos (con Node/Bun) Quien ya gestiona herramientas con Node.js.
Homebrew (tap del proyecto) macOS, Linux Actualizaciones cómodas con brew upgrade.
pacman / AUR Arch Linux Usuarios de Arch con paquetes nativos.
Chocolatey / Scoop Windows nativo Ambientes Windows sin WSL.
Docker Cualquier host con Docker Pruebas aisladas y entornos CI desechables.

4.6 Primer arranque y autenticación

Verifica la instalación y abre el agente en un proyecto de prueba:

opencode --version
cd /ruta/a/tu/proyecto
opencode

La primera vez necesitas conectar un proveedor de modelos. Dentro de la TUI ejecuta:

/connect
  1. Selecciona el proveedor (por ejemplo OpenCode Zen) y presiona Enter.
  2. Inicia sesión en la URL indicada (para Zen es opencode.ai/auth), configura la facturación si corresponde y copia tu clave de API.
  3. Pega la clave cuando la TUI lo solicite y confirma.

También puedes autenticarte con claves de API de otros proveedores exportando las variables de entorno habituales antes de abrir OpenCode. La elección detallada de proveedores y modelos se cubre en el tema 5.

Las credenciales se guardan localmente en el directorio de datos del usuario, no en el proyecto. Nunca subas archivos de credenciales a tus repositorios.

4.7 Comprobaciones esenciales

Comandos iniciales de verificación
Comando Propósito Señal de éxito
opencode --version Confirma que el binario está instalado y accesible. Imprime el número de versión sin errores.
opencode --help Lista los subcomandos disponibles. Muestra run, serve, upgrade y otros.
opencode run "Di hola" Prueba no interactiva con tu proveedor configurado. El modelo responde en la terminal.
/models (dentro de la TUI) Verifica qué modelos ve tu instalación. Aparecen los modelos del proveedor conectado.
/help (dentro de la TUI) Lista los comandos slash disponibles. Incluye /init, /undo, /share, entre otros.

4.8 Actualizar y desinstalar

  • OpenCode incluye un actualizador propio: opencode upgrade. Si lo instalaste con un gestor de paquetes, también puedes actualizar con él (brew upgrade anomalyco/tap/opencode, choco upgrade opencode, etc.).
  • Para desinstalar: elimina el binario o usa el gestor correspondiente (npm uninstall -g opencode-ai, brew uninstall opencode, choco uninstall opencode).
  • Si quieres empezar de cero con la configuración, elimina los directorios de configuración y datos del usuario que crea OpenCode y vuelve a autenticarte con /connect.

4.9 Solución de problemas frecuentes

  • "Comando no encontrado" tras instalar: el PATH no incluye la carpeta del binario. Abre una terminal nueva o agrega la ruta manualmente a tu shell.
  • Error de red o proxy corporativo: configura las variables HTTP_PROXY/HTTPS_PROXY antes de instalar o de conectar con proveedores.
  • Problemas de renderizado en la TUI: casi siempre se resuelven usando una terminal moderna (tema 3) o ejecutando dentro de WSL en Windows.
  • Instalación dañada tras un corte: reinstala con el mismo método elegido o prueba otro gestor de paquetes.
  • Credenciales perdidas o corruptas: vuelve a ejecutar /connect para regenerarlas.

Conclusión: con el binario instalado, la autenticación completada y las comprobaciones básicas superadas, OpenCode está listo para trabajar. En el próximo tema profundizaremos en los proveedores de modelos y en cómo elegir el más conveniente para cada tarea.

Retornar