Saltar al contenido principal

Cómo Instalar y Usar OpenCode: Una Guía Completa

BlogsOpenCodeAITerminalCLIAlrededor de 9 min

Cómo Instalar y Usar OpenCode: Una Guía Completa

OpenCode es un agente de codificación IA de código abierto que lleva el poder de la inteligencia artificial directamente a tu terminal. A diferencia de las herramientas tradicionales de codificación IA que operan en editores o navegadores, OpenCode ofrece una interfaz basada en terminal, una aplicación de escritorio y una extensión para IDE—todo diseñado para hacerte más productivo como desarrollador. Esta guía completa te llevará paso a paso en todo lo que necesitas saber para instalar, configurar y usar OpenCode de forma efectiva.

¿Qué es OpenCode?

OpenCode es un asistente de codificación impulsado por IA que te ayuda a:

  • Escribir código más rápido con generación y completado inteligente
  • Depurar eficientemente analizando errores y sugiriendo correcciones
  • Entender bases de código mediante consultas en lenguaje natural
  • Agregar funcionalidades con planificación e implementación automatizadas
  • Revisar código con análisis y sugerencias potenciadas por IA
  • Automatizar flujos de trabajo usando agentes de IA y herramientas personalizadas

Soporta múltiples proveedores de LLM incluyendo Anthropic, OpenAI, Google y otros, dándote la flexibilidad de elegir los modelos que mejor se adapten a tus necesidades.

Requisitos del Sistema

Prerrequisitos

Antes de instalar OpenCode, asegúrate de tener:

  1. Emulador de Terminal moderno (para uso TUI):

  2. Node.js (para instalación con npm/bun/pnpm/yarn):

    • Se recomienda Node.js v18 o superior

  3. Claves API para proveedores de LLM:

    • Clave API Anthropic (para modelos Claude)
    • Clave API OpenAI (para modelos GPT)
    • O claves de otros proveedores soportados

Métodos de Instalación

Método 1: Script de Instalación (Recomendado)

La forma más rápida de instalar OpenCode es usando el script oficial de instalación:

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

Este método funciona en macOS, Linux y Windows (con Git Bash o WSL).

Método 2: Usando Gestores de Paquetes Node.js

Usando npm:

npm install -g opencode-ai

Usando Bun:

bun install -g opencode-ai

Usando pnpm:

pnpm install -g opencode-ai

Usando Yarn:

yarn global add opencode-ai

Método 3: Usando Homebrew (macOS y Linux)

brew install opencode

Método 4: Usando Paru (Arch Linux)

paru -S opencode-bin

Método 5: Instalaciones Específicas para Windows

Usando Chocolatey:

choco install opencode

Usando Scoop:

scoop bucket add extras
scoop install extras/opencode

Usando Mise:

mise use -g github:sst/opencode

Método 6: Docker

Para uso en contenedor:

docker run -it --rm ghcr.io/sst/opencode

Método 7: Descargar el Binario

Puedes descargar el binario precompilado directamente desde la página de GitHub Releases.

Verificar Instalación

Después de la instalación, verifica que funcione:

opencode --version

Deberías ver el número de versión mostrado.

Configuración Inicial

Conectando a OpenCode Zen (Recomendado para Principiantes)

OpenCode Zen es una lista curada de modelos probados y verificados por el equipo de OpenCode. Es la forma más sencilla de empezar.

  1. Inicia OpenCode:
cd /ruta/a/tu/proyecto
opencode
  1. Ejecuta el comando connect en el TUI:
/connect

  1. Selecciona "opencode" de la lista de proveedores

  2. Visita la URL de autenticación: opencode.ai/auth

  3. Inicia sesión y agrega los datos de facturación (o usa créditos gratuitos si están disponibles)

  4. Copia tu clave API y pégala en la terminal cuando se te solicite

Conectando a Otros Proveedores

También puedes conectar OpenCode a otros proveedores LLM:

Usando el comando /connect:

/connect

Selecciona tu proveedor preferido (Anthropic, OpenAI, Google, etc.) y sigue el flujo de autenticación.

Usando autenticación CLI:

opencode auth login

Esto te guiará para configurar claves API para cualquier proveedor disponible en Models.dev.

Listar Proveedores Configurados:

opencode auth list

o la versión corta:

opencode auth ls

Cerrar sesión de un proveedor:

opencode auth logout

Configurando el Contexto del Proyecto

Después de configurar un proveedor, inicializa OpenCode para tu proyecto:

  1. Navega a tu proyecto:
cd /ruta/a/tu/proyecto
  1. Inicia OpenCode:
opencode
  1. Ejecuta el comando init:
/init

Esto analiza la estructura del proyecto y crea un archivo AGENTS.md en la raíz del proyecto. Este archivo ayuda a OpenCode a entender tus patrones de codificación, frameworks y arquitectura del proyecto.

Consejo: Haz commit del archivo AGENTS.md en Git. Esto ayuda a mantener la consistencia dentro de tu equipo y mejora la comprensión de OpenCode sobre tu proyecto con el tiempo.

Uso de la Interfaz de Usuario en Terminal (TUI)

El TUI de OpenCode ofrece una experiencia interactiva en tu terminal.

Iniciando el TUI

Simplemente ejecuta:

opencode

O con flags opcionales:

# Continuar la última sesión
opencode --continue

# Continuar una sesión específica
opencode --session <session-id>

# Iniciar con un prompt
opencode --prompt "Explica esta base de código"

# Usar un modelo específico
opencode --model anthropic/claude-sonnet-4-5

# Usar un agente específico
opencode --agent plan
  • Desplazarse: Usa la rueda del ratón o las flechas del teclado
  • Cambiar de modo: Presiona Tab para alternar entre modo Plan y modo Build
  • Ejecutar comandos: Escribe / para acceder a la paleta de comandos
  • Buscar archivos: Usa @ para búsqueda difusa de archivos en tu proyecto
  • Salir: Presiona Ctrl+C o usa /exit

Hacer Preguntas

Puedes hacer preguntas a OpenCode sobre tu base de código:

¿Cómo se maneja la autenticación en @packages/functions/src/api/index.ts

Usa el símbolo @ para referenciar archivos específicos. OpenCode analizará esos archivos y te dará explicaciones detalladas.

Añadir Funcionalidades

OpenCode sobresale en agregar nuevas funcionalidades con su flujo de trabajo de dos modos:

Paso 1: Modo Plan

  1. Cambia a modo Plan presionando Tab
  2. Describe lo que quieres:
Cuando un usuario elimina una nota, nos gustaría marcarla como eliminada en la base de datos.
Luego crear una pantalla que muestre todas las notas eliminadas recientemente.
Desde esta pantalla, el usuario puede restaurar una nota o eliminarla definitivamente.
  1. Revisa el plan sugerido
  2. Itera con retroalimentación:
Nos gustaría diseñar esta nueva pantalla usando un diseño que he usado antes.
[Imagen #1] Mira esta imagen y úsala como referencia.

Consejo: Puedes arrastrar y soltar imágenes en la terminal. OpenCode las escaneará y analizará.

Paso 2: Modo Build

  1. Cambia a modo Build presionando Tab nuevamente
  2. Aprueba la implementación:
¡Perfecto! Adelante, realiza los cambios.

OpenCode implementará la funcionalidad, creando y modificando archivos según sea necesario.

Hacer Cambios Directos

Para cambios simples, puedes saltarte la fase de planificación:

Necesitamos agregar autenticación a la ruta /settings.
Mira cómo se maneja en la ruta /notes
en @packages/functions/src/notes.ts e implementa la misma lógica
en @packages/functions/src/settings.ts

Deshacer y Rehacer Cambios

¿Cometiste un error? Usa el comando deshacer:

/undo

Esto revierte el último conjunto de cambios y te permite refinar tu prompt.

Para rehacer cambios deshechos:

/redo

Puedes ejecutar /undo varias veces para revertir múltiples cambios.

Comandos CLI

OpenCode proporciona un CLI poderoso para acceso programático y automatización.

Ejecutar Prompts Directos

Ejecuta OpenCode de forma no interactiva:

opencode run "Explica cómo funcionan los closures en JavaScript"

Útil para scripting, automatización o respuestas rápidas sin lanzar el TUI.

Gestión de Modelos

Lista todos los modelos disponibles:

opencode models

Filtra por proveedor:

opencode models anthropic

Refresca la caché de modelos (útil cuando se agregan nuevos modelos):

opencode models --refresh

Muestra información detallada incluyendo costos:

opencode models --verbose

Iniciar un Servidor Headless

Inicia un servidor HTTP para acceso API:

opencode serve

Con puerto personalizado:

opencode serve --port 3000

Útil para integrar OpenCode en aplicaciones web o para respuestas más rápidas en scripts (evitando el arranque en frío del servidor MCP).

Conectarse a un Servidor

En un terminal, inicia el servidor:

opencode serve

En otro terminal, conéctate para ejecución más rápida:

opencode run --attach http://localhost:4096 "Explica async/await en JavaScript"

Gestión de Agentes

Crea un nuevo agente personalizado:

opencode agent create

Este comando te guía para crear un agente con prompts de sistema y configuraciones de herramientas personalizadas.

Integración con GitHub

Instala el agente de GitHub para automatización en repositorios:

opencode github install

Esto configura flujos de trabajo de GitHub Actions para revisión automática de código y manejo de incidencias.

Actualizar OpenCode

Actualízate a la última versión:

opencode upgrade

O a una versión específica:

opencode upgrade v0.1.48

Especifica el método de instalación si es necesario:

opencode upgrade --method brew

Configuración

OpenCode soporta configuración flexible mediante archivos JSON.

Ubicaciones de Configuración

Los archivos de configuración se combinan (no se reemplazan), permitiendo tener configuraciones globales, específicas de proyecto y personalizadas.

  1. Configuración Global: ~/.config/opencode/opencode.json

    • Usada para temas, proveedores, atajos y ajustes generales

  2. Configuración de Proyecto: opencode.json en la raíz del proyecto

    • Usada para proveedores, agentes o ajustes específicos al proyecto
    • Seguro para hacer commit en Git

  3. Ruta de Configuración Personalizada: Definida con la variable de entorno OPENCODE_CONFIG

  4. Directorio de Configuración Personalizado: Definido con la variable de entorno OPENCODE_CONFIG_DIR

Ejemplo Básico de Configuración

Crea un archivo de configuración con esta estructura:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Selección de tema
  "theme": "opencode",
  
  // Modelo principal a usar
  "model": "anthropic/claude-sonnet-4-5",
  
  // Modelo pequeño para tareas livianas
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Configuración de actualización automática
  "autoupdate": true
}

Configuración de Proveedores

Configura claves API directamente en la configuración:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Se recomienda usar variables de entorno por seguridad. Usa la sintaxis {env:NOMBRE_VARIABLE}.

Uso de Referencias a Archivos

También puedes referenciar archivos para datos sensibles:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Comandos Personalizados

Define comandos personalizados para tareas repetitivas:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Ejecuta toda la suite de pruebas con reporte de cobertura y muestra fallos.\nEnfócate en tests fallidos y sugiere correcciones.",
      "description": "Ejecutar pruebas con cobertura",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Crea un nuevo componente React llamado $ARGUMENTS con soporte TypeScript.\nIncluye typing adecuado y estructura básica.",
      "description": "Crear un nuevo componente"
    }
  }
}

Usa comandos personalizados en el TUI escribiendo /test o /component MiComponente.

Agentes Personalizados

Crea agentes especializados:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Revisa código buscando buenas prácticas y posibles problemas",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Eres un revisor de código. Enfócate en seguridad, rendimiento y mantenibilidad.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Configuración de Permisos

Controla qué puede hacer OpenCode sin preguntar:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Esto requiere aprobación del usuario para operaciones de edición y ejecución de bash.

Formateadores de Código

Configura formateadores para formatear código automáticamente:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Configuración del TUI

Personaliza la interfaz en terminal:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Funciones Avanzadas

Compartir Conversaciones

Comparte tus conversaciones con tu equipo:

/share

Esto crea un enlace compartible y lo copia al portapapeles. Las conversaciones no se comparten por defecto.

Configura el comportamiento de compartición:

{
  "share": "manual"  // "manual", "auto" o "disabled"
}

Servidores MCP

Los servidores MCP (Model Context Protocol) extienden las capacidades de OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/a/archivos/permitidos"]
    }
  }
}

Instrucciones y Reglas

Proporciona instrucciones específicas del proyecto:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode usará estos archivos para entender los estándares y convenciones de codificación de tu proyecto.

Variables de Entorno

Configura OpenCode usando variables de entorno:

# Compartir sesiones automáticamente
export OPENCODE_AUTO_SHARE=true

# Ruta a configuración personalizada
export OPENCODE_CONFIG=/ruta/a/config.json

# Ruta a directorio de configuración
export OPENCODE_CONFIG_DIR=/ruta/a/config-dir

# Deshabilitar actualización automática
export OPENCODE_DISABLE_AUTOUPDATE=true

# Deshabilitar plugins por defecto
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Habilitar modelos experimentales
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Habilitar búsqueda web Exa
export OPENCODE_ENABLE_EXA=true

Funcionalidades Experimentales

Activa funciones experimentales:

export OPENCODE_EXPERIMENTAL=true

Funciones experimentales específicas:

# Habilitar descubrimiento de íconos
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Deshabilitar copia al seleccionar en TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Establecer longitud máxima de salida para comandos bash
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Establecer timeout por defecto para comandos bash (ms)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Mejores Prácticas

Prompts Efectivos

  1. Sé específico: Da instrucciones claras y detalladas
  2. Usa contexto: Referencia archivos con @ para mejor comprensión
  3. Proporciona ejemplos: Muestra ejemplos de lo que quieres
  4. Divide en pasos: Las tareas complejas funcionan mejor en etapas

Trabajando con Proyectos Grandes

  1. Usa /init: Deja que OpenCode entienda la estructura del proyecto
  2. Referencia archivos específicos: Usa @ para limitar el contexto
  3. Usa modo Plan: Revisa planes antes de implementar
  4. Cambios incrementales: Haz cambios pequeños y manejables

Optimización de Costos

  1. Usa modelos más pequeños: Configura small_model para tareas ligeras
  2. Planifica antes de construir: Revisa en modo Plan para reducir iteraciones
  3. Comandos personalizados: Define flujos eficientes para tareas comunes
  4. Monitorea uso: Revisa los paneles de proveedores para estadísticas de uso

Buenas Prácticas de Seguridad

  1. Nunca hagas commit de claves API: Usa variables de entorno
  2. Usa permisos: Configura permission para requerir aprobación en operaciones sensibles
  3. Revisa cambios: Siempre inspecciona los cambios sugeridos por OpenCode
  4. Usa claves separadas: Crea claves API específicas para OpenCode con límites apropiados

Solución de Problemas

Problemas de Instalación

Problema: Comando no encontrado después de instalación

Solución:

  • Verifica instalación: which opencode
  • Revisa PATH: echo $PATH
  • Prueba ruta completa: ~/.local/bin/opencode
  • Reinstala usando otro método

Problemas de Autenticación

Problema: Clave API no reconocida

Solución:

  • Verifica que la clave sea correcta: opencode auth list
  • Revisa variables de entorno: echo $ANTHROPIC_API_KEY
  • Reautentícate: opencode auth login

Problemas de Rendimiento

Problema: Respuesta lenta

Solución:

  • Usa opencode serve para ejecución más rápida
  • Cambia a un modelo más veloz
  • Usa ventanas de contexto más pequeñas
  • Deshabilita herramientas no usadas en config

Problemas con el TUI

Problema: Problemas de visualización en terminal

Solución:

  • Usa un emulador de terminal moderno (WezTerm, Alacritty, etc.)
  • Verifica que el terminal soporte colores de 24 bits
  • Prueba otro tema
  • Deshabilita aceleración de scroll si tienes problemas

Problemas con Modelos

Problema: Modelo no encontrado

Solución:

  • Refresca lista de modelos: opencode models --refresh
  • Verifica que el proveedor esté configurado: opencode auth list
  • Revisa el formato del nombre del modelo: proveedor/modelo
  • Asegúrate que el proveedor tenga disponible el modelo

Integrando OpenCode en Tu Flujo de Trabajo

Desarrollo Diario

  1. Mañana: Ejecuta /init para sincronizar con los últimos cambios
  2. Trabajo de funcionalidades: Usa modo Plan para diseñar, luego modo Build para implementar
  3. Depuración: Haz preguntas sobre errores usando referencias a archivos
  4. Revisión de código: Usa agente revisor personalizado
  5. Documentación: Genera docs con comandos personalizados

Colaboración en Equipo

  1. Comparte configuraciones: haz commit de opencode.json y AGENTS.md en Git
  2. Comparte conversaciones: usa /share para discutir implementaciones
  3. Comandos personalizados: define comandos específicos para el equipo en config de proyecto
  4. Agentes consistentes: usa definiciones compartidas de agentes para coherencia

Integración CI/CD

  1. Agente GitHub: Instala para revisiones automáticas de PR
  2. Pruebas: Usa comandos personalizados de test en CI
  3. Calidad de código: Configura formateadores y permisos

Conclusión

OpenCode representa un nuevo paradigma en desarrollo asistido por IA al llevar potentes capacidades de IA directamente a tu terminal. Con sus opciones flexibles de configuración, soporte para múltiples proveedores LLM e intuitiva interfaz TUI, está diseñado para mejorar tu productividad sin interrumpir tu flujo de trabajo actual.

Puntos clave:

  • Instala usando el script de instalación o tu gestor de paquetes favorito
  • Configura claves API vía /connect o opencode auth login
  • Inicializa proyectos con /init para mejor comprensión del contexto
  • Usa modo Plan para funciones complejas y modo Build para cambios directos
  • Personaliza con archivos de configuración, comandos y agentes
  • Aprovecha comandos CLI para automatización y scripting
  • Practica buenas prácticas de seguridad con claves API y permisos

Próximos pasos:

¿Listo para potenciar tu flujo de desarrollo?
Descubre las soluciones de hosting AI-optimizado de LightNode para desplegar aplicaciones con IA usando instancias GPU dedicadas e infraestructura escalable.

OpenCode es open source y está en constante evolución. Contribuye al proyecto, reporta problemas o comparte tu experiencia para hacerlo aún mejor para todos. ¡Feliz codificación!

Ahorra en alojamiento VPS económico