← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 2: Instalacion

Por: Artiko
opencodeaiinstalacionsetup

Capitulo 2: Instalacion

< Volver al Indice del Tutorial

Requisitos Previos

Antes de instalar OpenCode necesitas cumplir con algunos requisitos para que la herramienta funcione correctamente. Estos requisitos varían ligeramente según tu sistema operativo, pero los fundamentales son universales.

Terminal Moderna

OpenCode utiliza una interfaz TUI rica con soporte Unicode, colores de 24 bits y rendering avanzado. Para una experiencia óptima necesitas una terminal moderna. Las terminales recomendadas oficialmente son:

Las terminales por defecto de la mayoría de sistemas operativos (Terminal.app en macOS, GNOME Terminal, Windows Terminal) también funcionan, pero pueden presentar problemas menores de rendering en la TUI. Si experimentas artefactos visuales o caracteres mal renderizados, considera cambiar a una de las terminales recomendadas.

API Key de un Proveedor LLM

OpenCode necesita acceso a un modelo de lenguaje para funcionar. Tienes varias opciones:

No necesitas configurar la API key antes de instalar. El comando /connect dentro de OpenCode te guía por el proceso completo de autenticación.

Otros Requisitos

Metodos de Instalacion

OpenCode ofrece múltiples métodos de instalación para cubrir todos los sistemas operativos y preferencias. El paquete npm/bun se publica bajo el nombre opencode-ai.

Instalador Oficial (Recomendado)

El método más rápido y universal. El script detecta tu sistema operativo y arquitectura automáticamente, descarga el binario correcto, lo instala en tu PATH y configura el autocompletado del shell:

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

Este método funciona en macOS, Linux y WSL. El binario se instala en /usr/local/bin/ por defecto, pero puedes personalizar el directorio de instalación:

curl -fsSL https://opencode.ai/install | INSTALL_DIR=$HOME/.local/bin bash

Ventajas del instalador oficial:

npm

Si ya tienes Node.js instalado, puedes usar npm. El paquete se llama opencode-ai:

npm install -g opencode-ai

Bun

Bun ofrece instalación más rápida que npm gracias a su resolver optimizado:

bun add -g opencode-ai

pnpm

Para usuarios de pnpm:

pnpm add -g opencode-ai

yarn

Para usuarios de yarn:

yarn global add opencode-ai

Homebrew (macOS / Linux)

La opción estándar para usuarios de macOS y Linux con Homebrew instalado:

brew install opencode

Homebrew maneja automáticamente las actualizaciones cuando ejecutas brew upgrade.

Paru (Arch Linux)

Para usuarios de Arch Linux y derivados, OpenCode está disponible en el AUR:

paru -S opencode

También funciona con otros helpers de AUR como yay:

yay -S opencode

Scoop (Windows)

Para usuarios de Windows con Scoop:

scoop install opencode

Chocolatey (Windows)

Alternativa a Scoop para Windows:

choco install opencode

Docker

Para entornos aislados, CI/CD o cuando no quieres instalar nada en tu sistema host:

docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/anomalyco/opencode

El contenedor monta tu directorio de trabajo actual y recibe las variables de entorno necesarias. Esto es especialmente útil en pipelines de CI/CD donde quieres un entorno limpio y reproducible.

Para uso en CI/CD con modo no interactivo:

docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/anomalyco/opencode \
  run "analiza el código y sugiere mejoras de rendimiento"

Verificar la Instalacion

Después de instalar, verifica que OpenCode funcione correctamente:

opencode --version

Debería mostrar algo como:

opencode v1.3.15

Para ver todos los comandos disponibles y confirmar que el binario está correctamente en el PATH:

opencode --help

Si el comando no se encuentra después de instalar, probablemente tu shell necesita recargar el PATH. Consulta la sección de problemas comunes más adelante.

Primer Inicio y Autenticacion

Una vez instalado, la primera vez que ejecutes opencode en un directorio de proyecto, la herramienta detectará que no hay proveedor configurado. Puedes autenticarte de dos formas:

Opcion 1: Comando /connect (Recomendado)

Dentro de la TUI, ejecuta:

/connect

Esto te redirige a opencode.ai/auth donde puedes seleccionar tu proveedor y autorizar el acceso. Es el método más simple porque no necesitas copiar API keys manualmente.

Opcion 2: Variables de Entorno

Configura la API key como variable de entorno antes de iniciar OpenCode:

# Para Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Para OpenAI
export OPENAI_API_KEY=sk-...

# Para Google
export GOOGLE_API_KEY=AIza...

Para que las variables persistan entre sesiones, agrégalas a tu archivo de perfil del shell:

# Para bash
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc

# Para zsh
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc

Actualizar OpenCode

OpenCode incluye un mecanismo de actualización integrado:

opencode upgrade

Esto descarga e instala la última versión disponible, preservando tu configuración existente.

Auto-Update

Puedes configurar actualizaciones automáticas en tu archivo opencode.json:

{
  "autoupdate": true
}

Los valores posibles y su comportamiento:

ValorComportamiento
trueActualiza automáticamente al iniciar si hay nueva versión
falseNunca actualiza automáticamente
"notify"Notifica que hay una nueva versión pero no actualiza

Para equipos de desarrollo, se recomienda usar "notify" o false para evitar que diferentes miembros usen versiones distintas sin saberlo. Coordinar las actualizaciones manualmente con opencode upgrade da más control sobre cuándo se introducen cambios.

Actualizar via Gestores de Paquetes

Si instalaste con un gestor de paquetes, también puedes actualizar a través de él:

# Homebrew
brew upgrade opencode

# npm
npm update -g opencode-ai

# bun
bun update -g opencode-ai

# Scoop
scoop update opencode

# Chocolatey
choco upgrade opencode

Desinstalar OpenCode

Para remover OpenCode completamente del sistema:

opencode uninstall

Esto elimina el binario y opcionalmente la configuración global. Si prefieres mantener la configuración para una posible reinstalación futura, el comando te lo pregunta.

Si instalaste con un gestor de paquetes:

# npm
npm uninstall -g opencode-ai

# bun
bun remove -g opencode-ai

# Homebrew
brew uninstall opencode

# Scoop
scoop uninstall opencode

# Chocolatey
choco uninstall opencode

Para una limpieza total, también elimina los archivos de configuración global:

rm -rf ~/.config/opencode

Instalacion en Entornos Especiales

Sin Acceso a Internet

Si tu máquina de desarrollo no tiene acceso a internet (entornos air-gapped, servidores seguros), puedes descargar el binario desde la página de releases en otra máquina y copiarlo manualmente:

# En la máquina con internet
curl -fsSL https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-x64 -o opencode

# Copiar al servidor sin internet
scp opencode usuario@servidor:/usr/local/bin/
ssh usuario@servidor "chmod +x /usr/local/bin/opencode"

En este escenario, para el modelo LLM necesitarás Ollama con modelos descargados previamente, ya que las APIs cloud no estarán disponibles.

CI/CD Pipelines

Para pipelines de CI/CD, el instalador oficial es el método más limpio y reproducible:

# GitHub Actions
- name: Install OpenCode
  run: curl -fsSL https://opencode.ai/install | bash

- name: Run analysis
  run: opencode run "analiza los cambios del PR y sugiere mejoras"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Para Docker-based CI/CD, usa la imagen oficial directamente:

docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/anomalyco/opencode \
  run "ejecuta los tests y corrige cualquier fallo"

WSL (Windows Subsystem for Linux)

OpenCode funciona completamente en WSL2. Instala usando el instalador oficial dentro de tu distribución WSL:

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

Asegúrate de usar una terminal moderna como Windows Terminal o WezTerm para el mejor rendering de la TUI.

Problemas Comunes

”command not found” despues de instalar

Tu shell no ha recargado el PATH. Ejecuta:

source ~/.bashrc
# o para zsh
source ~/.zshrc

Si el problema persiste, verifica que el directorio de instalación está en tu PATH:

echo $PATH | tr ':' '\n' | grep -E "(local/bin|\.local/bin)"

Permisos insuficientes

Si el instalador falla por permisos en /usr/local/bin/:

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

O instala en tu directorio local sin necesidad de sudo:

curl -fsSL https://opencode.ai/install | INSTALL_DIR=$HOME/.local/bin bash

Conflicto con otro paquete “opencode”

Si ya tienes un paquete llamado opencode instalado, desinstálalo primero. El paquete npm oficial se llama opencode-ai para evitar este tipo de conflictos:

# Desinstalar el paquete conflictivo
npm uninstall -g opencode

# Instalar el correcto
npm install -g opencode-ai

TUI con artefactos visuales

Si la TUI muestra caracteres extraños o el layout se ve roto, probablemente tu terminal no soporta todas las capacidades necesarias. Prueba con una de las terminales recomendadas (WezTerm, Alacritty, Ghostty, Kitty) o verifica que tu terminal tenga habilitado el soporte Unicode y colores de 24 bits.

Error de conexion al proveedor

Si OpenCode no puede conectar con tu proveedor LLM:

  1. Verifica que la API key es correcta y no ha expirado
  2. Comprueba tu conexión a internet
  3. Si usas un proxy corporativo, configúralo con las variables de entorno estándar (HTTP_PROXY, HTTPS_PROXY)
  4. Prueba con /connect para reautenticar

Siguiente: Capitulo 3: Primeros Pasos —>

← Volver al listado de tecnologías ← Índice de OpenCode