¿Cómo instalar un agente IA que lee y edita código desde la terminal de Linux? Probando OPENCODE

OpenCode trae un agente de codificación con IA directamente a tu terminal. Una vez que lo ves entender un proyecto completo en lugar de solo el archivo que estás editando, es difícil volver a un editor convencional.

Paso la mayor parte del día en la terminal, ya sea depurando un servicio systemd en un servidor RHEL o escribiendo scripts Bash. Cuando probé OpenCode por primera vez, no esperaba mucho. Ya había usado algunas herramientas de IA que parecían complementos de un IDE y solo podían adivinar lo que sucedía basándose en el archivo abierto.

OpenCode fue diferente desde el principio. Lo apunté a un proyecto Node.js desordenado con unos 40 archivos y le pregunté por qué un trabajo en segundo plano seguía fallando silenciosamente. Rastreó las dependencias por sí solo, abrió los tres archivos correctos y me mostró que la lógica de reintento estaba tragándose una excepción. Todo el proceso tomó unos 90 segundos de escritura y unos minutos de espera.

Lo que me hizo seguir usándolo fue su diseño centrado en la terminal. No es un envoltorio de navegador ni un plugin que compite con los atajos de tu editor. Es una interfaz de usuario de terminal (TUI) adecuada con una arquitectura cliente-servidor por debajo, por lo que el proceso del agente puede seguir ejecutándose incluso si tu sesión de terminal se desconecta.

Como no está vinculado a un solo proveedor de IA, puedo usar Claude, OpenAI o incluso un modelo local, dependiendo de la tarea y de cuánto quiera gastar ese día.

¿Qué hace OpenCode exactamente?

OpenCode es un agente de codificación con IA de código abierto que se ejecuta dentro de tu terminal y utiliza un modelo de lenguaje para leer, escribir y modificar código en un proyecto real. En lugar de copiar y pegar fragmentos de código en una ventana de chat, simplemente apuntas OpenCode a un directorio de proyecto, explicas lo que quieres hacer, y él trabaja directamente con tus archivos, ejecuta comandos y aplica cambios cuando es necesario.

Dos cosas lo hacen diferente de un simple wrapper de chatbot con IA:

1. Modos de agente integrados que puedes alternar pulsando la tecla Tab:

• Modo build: Puede editar archivos y ejecutar comandos. Es útil cuando quieres que el agente implemente cambios.
• Modo plan: Es de solo lectura y está pensado para análisis. Te ayuda a explorar y entender un código base antes de permitirle modificar algo.

2. Independencia de proveedor: No estás atado a un solo servicio de IA. Puedes conectar OpenCode a Claude, OpenAI, Google, GitHub Copilot o incluso a un modelo auto-alojado. También puedes cambiar de proveedor cuando lo necesites, lo que es útil si un servicio está limitado por tarifas o se vuelve demasiado caro para una tarea particular.

Comparativa rápida: OpenCode vs otros agentes de IA

Requisitos previos

Antes de instalar OpenCode, asegúrate de tener lo siguiente:

• Un sistema Linux de 64 bits. Ubuntu, Debian, RHEL y Rocky Linux funcionan bien.
• curl instalado, ya que el script de instalación oficial descarga el binario de OpenCode por HTTPS.
• Un emulador de terminal que soporte interfaces de usuario de terminal modernas (TUIs), como GNOME Terminal, Alacritty, Kitty o una terminal dentro de tmux.
• Una cuenta con al menos un proveedor de IA soportado, como Claude, OpenAI, Google o GitHub Copilot.
• También puedes usar un modelo local auto-alojado si lo prefieres.
• Una cuenta de usuario con privilegios sudo si deseas instalar OpenCode en todo el sistema.

No necesitas Node.js instalado si usas el script de instalación oficial. Node.js solo es necesario si eliges instalar OpenCode usando npm. A continuación, mostraré ambos métodos de instalación.

Paso 1: ¿Cómo instalar curl y otros requisitos básicos?

La mayoría de las distribuciones de Linux ya incluyen curl, pero es buena idea verificar que esté instalado antes de continuar. El instalador oficial de OpenCode usa curl para descargar el binario, por lo que la instalación no puede continuar sin él.

En Ubuntu y Debian:

sudo apt update && sudo apt install curl -y

En RHEL y Rocky Linux:

sudo dnf install curl -y

El comando sudo ejecuta el gestor de paquetes con privilegios administrativos porque instalar software requiere acceso de escritura a directorios del sistema. Si curl ya está instalado, ambos comandos simplemente informarán que el paquete ya está presente y saldrán sin realizar cambios.

Paso 2: ¿Cómo instalar OpenCode?

La forma más fácil de instalar OpenCode es usando el script de instalación oficial. Detecta automáticamente tu distribución de Linux y arquitectura del sistema, descarga el binario correcto y lo instala en un directorio que ya está en tu PATH.

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

Deberías ver una salida similar a esta:

Installing opencode version: 1.17.18
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 100%
Successfully added opencode to $PATH in /home/usuario/.bashrc

                                 ▄     
█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
█░░█ █░░█ █▀▀▀ █░░█ █░░░ █░░█ █░░█ █▀▀▀
▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀  ▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀

OpenCode includes free models, to start:

cd   # Open directory
opencode      # Run command

For more information visit https://opencode.ai/docs

Esto es lo que hace el comando:

• curl -f hace que curl falle si el servidor devuelve un error en lugar de descargar una página de error.
• -s ejecuta curl en modo silencioso y oculta el medidor de progreso.
• -S muestra un mensaje de error si algo sale mal manteniendo el modo silencioso.
• -L le dice a curl que siga redirecciones automáticamente.
• | bash envía el script descargado directamente a Bash, que lo ejecuta inmediatamente en lugar de guardarlo en un archivo primero.

Por defecto, OpenCode se instala en un directorio bajo tu carpeta de inicio. Si quieres instalarlo en otro lugar, como /usr/local/bin, establece la variable de entorno OPENCODE_INSTALL_DIR antes de ejecutar el instalador:

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

Si prefieres no ejecutar un script remoto directamente, puedes instalar OpenCode usando npm. Este método requiere Node.js y npm instalados en tu sistema:

npm install -g opencode-ai

Los usuarios de Arch Linux pueden instalar OpenCode directamente desde los repositorios de paquetes:

sudo pacman -S opencode

Paso 3: ¿Cómo verificar la instalación?

Después de instalar OpenCode, asegúrate de que el binario esté disponible en tu PATH y comprueba qué versión está instalada.

opencode --version

Ejemplo de salida:

opencode version 1.17.18

Si ves un error de “comando no encontrado”, el binario de OpenCode se instaló en un directorio que tu shell no busca actualmente. En ese caso, añade el directorio de instalación a tu PATH.

Para usuarios de Bash o Zsh, añade la siguiente línea a tu archivo ~/.bashrc o ~/.zshrc:

export PATH="$HOME/.opencode/bin:$PATH"

Luego recarga la configuración de tu shell:

source ~/.bashrc

Si usas Zsh, ejecuta:

source ~/.zshrc

Una vez recargado el shell, ejecuta opencode --version de nuevo para confirmar que todo funciona correctamente.

Paso 4: ¿Cómo conectar un proveedor de modelos?

OpenCode necesita acceso a un modelo de lenguaje antes de poder analizar proyectos, responder preguntas o modificar código. No incluye un modelo integrado, por lo que el siguiente paso es conectarlo a un proveedor compatible.

Inicia el proceso de autenticación con:

opencode auth login

Deberías ver un menú similar a este:

┌  Add credential
│
◆  Select provider

│  Search: _
│  ● OpenCode Zen (recommended)
│  ○ Claude
│  ○ OpenAI
│  ○ GitHub Copilot
│  ○ Google
│  ○ Vercel AI Gateway
│  ...
│  ↑/↓ to select • Enter: confirm • Type: to search

Usa las teclas de flecha para seleccionar tu proveedor preferido y pulsa Enter.

Para Claude y la mayoría de los proveedores alojados, OpenCode abre una página de inicio de sesión en el navegador. Después de iniciar sesión y aprobar la solicitud, verás un mensaje de confirmación en la terminal:

Authenticated successfully with Claude
Credentials saved to ~/.opencode/auth.json

Si prefieres no usar el inicio de sesión basado en navegador, OpenCode también puede leer claves API desde variables de entorno o un archivo .env en tu directorio de proyecto. Este enfoque es especialmente útil en servidores sin cabeza o en pipelines de CI/CD donde abrir un navegador no es práctico.

Paso 5: ¿Cómo iniciar un proyecto?

Muévete al directorio del proyecto con el que quieres que OpenCode trabaje e inícialo desde allí.

cd ~/proyectos/mi-app
opencode

La primera vez que ejecutas OpenCode en un nuevo proyecto, comprueba si ya existe un archivo AGENTS.md. Si no lo encuentra, verás un aviso como este:

No AGENTS.md found in this project.
Generate one now? (Y/n)

Escribe y y pulsa Enter.

OpenCode escanea el directorio del proyecto, observa la estructura de archivos, las dependencias y las convenciones existentes, y genera un archivo AGENTS.md que resume lo que encuentra. Este archivo le da al agente una comprensión compartida de tu proyecto, para que no tenga que redescubrirlo cada vez que inicies una nueva sesión.

Ejemplo de salida:

Analyzing project...
Found: package.json, 47 source files, 3 test suites
Created AGENTS.md

Paso 6: ¿Cómo ejecutar una tarea real?

Ahora que OpenCode está autenticado y entiende la estructura de tu proyecto, puedes empezar a darle trabajo real.

Lanza OpenCode desde dentro del directorio de tu proyecto:

opencode

Esto abre una interfaz de terminal interactiva con un cuadro de entrada estilo chat en la parte inferior y una vista de archivo y diff arriba. Puedes describir tareas en lenguaje natural, tal como se las explicarías a otro desarrollador.

Por ejemplo:

> Find why the /api/upload endpoint returns a 500 error on files over 5MB

OpenCode lee los archivos relevantes, rastrea dependencias y normalmente explica el problema antes de hacer cualquier cambio, especialmente si estás en modo plan.

Ejemplo de salida:

Plan mode: read-only analysis
Found the issue in middleware/upload.js:
  The multer limit is set to 5MB but the error handler
  doesn't catch LIMIT_FILE_SIZE, so it falls through to
  a generic 500 instead of returning 413.

En cualquier momento, puedes pulsar Tab para cambiar entre los dos modos:

• Modo plan: Solo lectura, útil para explorar o analizar un proyecto de forma segura.
• Modo build: Permite a OpenCode editar archivos y ejecutar comandos.

Una vez que estés satisfecho con el diagnóstico, cambia al modo build y pídele que aplique la corrección:

> Switch to build mode and fix that

OpenCode actualiza el archivo y te muestra un diff antes de escribir cualquier cosa en el disco.

Ejemplo:

Editing middleware/upload.js
+ if (err.code === 'LIMIT_FILE_SIZE') {
+   return res.status(413).json({ error: 'File too large' });
+ }
Apply this change? (Y/n)

Esto es lo que está sucediendo:

• middleware/upload.js es el archivo que OpenCode identificó como fuente del problema.
• Las líneas que comienzan con + son el nuevo código que se añadirá.
• Apply this change? (Y/n) es un aviso de confirmación. Nada se escribe en tu sistema de archivos hasta que lo apruebas.

Ese paso de confirmación es importante. Los modelos de IA a veces pueden sugerir cambios que no son del todo correctos para tu proyecto. Poder revisar el diff antes de modificar algo te da control y hace que OpenCode sea práctico para el desarrollo real, no solo para experimentación.

Paso 7: ¿Cómo ejecutar OpenCode de forma no interactiva?

No siempre necesitas la interfaz de terminal completa para usar OpenCode. Para scripts, pipelines de CI/CD o tareas rápidas puntuales, puedes pasar un prompt directamente en la línea de comandos.

Por ejemplo:

opencode run "Add a .gitignore entry for node_modules and .env"

Ejemplo de salida:

Applying change to .gitignore
node_modules/
.env
Done in 3.2s

En este modo, OpenCode realiza la tarea solicitada y sale cuando termina. Esto es útil cuando quieres automatizar tareas repetitivas o integrar OpenCode en scripts y flujos de trabajo sin abrir la interfaz interactiva.

Por ejemplo, podrías ejecutar OpenCode desde un script de shell, un temporizador de systemd o un pipeline de CI/CD para hacer cambios simples automáticamente.

También vale la pena saber que mencionar /opencode o /oc en un comentario de un issue o pull request de GitHub puede desencadenar que OpenCode se ejecute dentro de un runner de GitHub Actions. Esto puede ser útil para análisis de código automatizado o pequeñas tareas de mantenimiento directamente desde el hilo de discusión de GitHub.

¿Cómo mantener OpenCode actualizado?

OpenCode recibe actualizaciones regulares con correcciones de errores, mejoras y nuevas funciones. Si lo instalaste usando el script de instalación oficial, la forma más fácil de actualizarlo es ejecutar el mismo comando de nuevo:

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

El instalador descarga e instala automáticamente la última versión disponible.

Si instalaste OpenCode usando npm, actualízalo con:

npm update -g opencode-ai

Ejemplo de salida:

changed 1 package in 4s
opencode-ai@0.9.4

Puedes comprobar la versión instalada en cualquier momento ejecutando:

opencode --version

Si quieres ver las novedades antes de actualizar, compara tu versión instalada con las notas de la versión disponibles en el changelog de OpenCode en opencode.ai/changelog. Esto es especialmente útil si usas OpenCode como parte de un flujo de trabajo de producción y quieres entender qué ha cambiado antes de actualizar.

Solución de problemas comunes

OpenCode no detecta mi proyecto correctamente

Asegúrate de ejecutar opencode desde el directorio raíz del proyecto. Si el proyecto es muy grande, puede tardar más en escanearlo. También puedes crear manualmente un archivo AGENTS.md con la descripción del proyecto.

La autenticación falla o no abre el navegador

Si estás en un servidor sin navegador, usa variables de entorno o un archivo .env con la clave API. Consulta la documentación de OpenCode para el formato exacto de cada proveedor.

El comando opencode no se encuentra

Revisa si ~/.opencode/bin está en tu PATH. Si no, añade export PATH="$HOME/.opencode/bin:$PATH" a tu ~/.bashrc o ~/.zshrc y recarga con source ~/.bashrc.

El agente hace cambios incorrectos

Siempre revisa los diffs antes de confirmar. Usa el modo plan primero para entender qué va a hacer el agente. Si el cambio no es correcto, recházalo y da instrucciones más precisas.

Conclusión

En este punto, tienes OpenCode instalado, conectado a un proveedor de IA y trabajando con un proyecto real en lugar de una simple demo. Has visto la diferencia entre el modo plan para análisis seguro de solo lectura y el modo build para realizar cambios reales, y sabes cómo ejecutar OpenCode de forma no interactiva para scripts y flujos de trabajo automatizados.

La mejor forma de familiarizarte con OpenCode es usarlo en un proyecto que ya conozcas. En lugar de pedirle que construya una nueva función, empieza con un bug que hayas estado investigando. Ejecútalo en modo plan primero y comprueba si su análisis coincide con tu comprensión del problema. Esa suele ser la forma más rápida de aprender qué hace bien la herramienta y dónde aún debes ser cauteloso.

Como cualquier herramienta de codificación con IA, OpenCode funciona mejor cuando te mantienes involucrado en el proceso. Puede ahorrar tiempo explorando un código base, rastreando dependencias y sugiriendo correcciones, pero revisar los cambios propuestos sigue siendo importante, especialmente para sistemas en producción. Tomarse un momento para leer los diffs generados antes de aprobarlos ayuda a garantizar que los cambios sean correctos y se alineen con la dirección de tu proyecto.