Instalar opencode: guía básica

Objetivo

Al terminar vas a tener opencode instalado, un proveedor de modelos conectado y una primera sesión corriendo sobre un proyecto real, con un archivo AGENTS.md generado para ese repo.

opencode es un agente de código open source que vive en la terminal. Es agnóstico al proveedor: traés tu propia API key (Anthropic, OpenAI, OpenRouter, modelos locales o el gateway alojado opencode Zen) en lugar de quedar atado a un solo vendor. Corre como TUI, como comando no interactivo o como servidor headless.

Prerrequisitos

macOS, Linux o Windows.
Un emulador de terminal moderno. Las terminales aceleradas por GPU (WezTerm, Alacritty, Ghostty, Kitty) renderizan mejor la TUI.
Una API key de al menos un proveedor de LLM, o una cuenta de opencode Zen.
Un proyecto local sobre el que trabajar.

Esta guía cubre opencode al estado de septiembre de 2026.

Pasos

1. Instalar el binario

Elegí el método según tu sistema.

macOS / Linux / WSL (script):

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

Homebrew:

brew install anomalyco/tap/opencode

npm (o bun / pnpm / yarn):

npm install -g opencode-ai

Arch Linux:

paru -S opencode-bin

Windows (Scoop o Chocolatey):

scoop install opencode
# o
choco install opencode

El script de instalación deja el binario en ~/.local/bin. Si ese directorio no está en tu PATH, agregalo:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

2. Verificar la instalación

opencode --version

Verificación esperada: imprime un número de versión. Si la terminal responde "command not found", abrí una sesión nueva para que tome el PATH actualizado.

3. Conectar un proveedor

Lanzá opencode y ejecutá el comando de conexión:

opencode

Dentro de la TUI:

/connect

Elegí tu proveedor. Para un primer arranque, opencode Zen es lo más simple: es un gateway alojado que funciona con una sola key desde opencode.ai/auth. Pegá la key cuando te la pida.

Para gestionar credenciales desde fuera de la TUI:

opencode auth login    # agregar la key de un proveedor
opencode auth list     # ver proveedores conectados

Las keys se guardan en ~/.local/share/opencode/auth.json.

4. Arrancar una sesión sobre tu proyecto

cd ruta/a/tu/proyecto
opencode

Ejecutá /init una vez. opencode escanea el repo y escribe un archivo AGENTS.md con contexto del proyecto que lee en cada sesión futura. Hacé commit de ese archivo.

Referenciá archivos concretos en tus prompts con @:

Explicá qué hace @src/server.ts y agregale manejo de errores

5. Usarlo sin la TUI

Para preguntas rápidas o scripting, salteá la interfaz:

opencode run "Explicá la diferencia entre async y defer en las etiquetas script"

6. Mantenerlo actualizado

opencode upgrade

Si instalaste vía npm o un gestor de paquetes, actualizá por esos canales.

Resultado esperado

opencode --version imprime una versión.
opencode auth list muestra al menos un proveedor conectado.
opencode abre la TUI sobre tu proyecto y /init generó AGENTS.md.
opencode run "..." responde desde la terminal sin abrir la TUI.

Troubleshooting

Problemas comunes

opencode: command not found después de instalar: el binario quedó en ~/.local/bin pero no está en tu PATH. Agregalo y recargá el perfil de tu shell, o abrí una terminal nueva.
La TUI se ve con caracteres o colores rotos: tu terminal no soporta las capacidades requeridas. Cambiá a WezTerm, Alacritty, Ghostty o Kitty.
No providers configured / errores de modelo: ejecutá /connect en la TUI o opencode auth login, y confirmá la key con opencode auth list.
Se está usando el modelo equivocado: ejecutá opencode models para listar lo disponible por proveedor, y elegí uno con /models en la TUI.
Deshacer un cambio que hizo opencode: ejecutá /undo en la sesión.

Siguiente paso

Configurá opencode por proyecto editando opencode.json en la raíz del repo (modelos, permisos, servidores MCP), y compartí una transcripción de sesión con /share.