OpenCode: guía práctica para usarlo como agente en la terminal

OpenCode es un agente de IA de código abierto que vive en la terminal: en vez de abrir un chat aparte, lo ejecutas dentro de tu repo, le das una tarea en lenguaje natural y él lee los archivos, corre comandos, edita y te muestra los cambios como un diff de git. Para quien ya vive en la terminal, es la diferencia entre copiar y pegar respuestas y tener un agente que toca tu código real.

Esta guía cubre el flujo completo: instalación, autenticación, configuración, reglas, modo no interactivo y MCP. Es la entrega de la serie de agentes CLI junto a la guía de AGENTS.md y la de worktrees: primero sabes cómo expresar reglas, luego dónde correr al agente sin pisar tu trabajo.

Instalación: tres caminos

La documentación oficial ofrece tres formas de instalar el binario. Todas dan el mismo opencode:

Método	Comando	Cuándo usarlo
Script oficial	curl -fsSL https://opencode.ai/install | bash	Instalación rápida en cualquier máquina
Homebrew	brew install opencode	macOS/Linux con Homebrew, fácil de actualizar
npm	npm install -g opencode-ai	Ya tienes Node y quieres versiones por línea

Después de instalar, corre opencode upgrade cuando salgan versiones nuevas. El binario principal arranca la interfaz interactiva (TUI); si quieres confirmar que quedó bien, ejecuta opencode run "di hola" y debería responder sin abrir el TUI.

Primera sesión y autenticación

Al abrir opencode dentro de una carpeta de proyecto, el agente detecta el contexto: archivos del repo, rama de git, lenguaje principal. Antes de que pueda llamar a un modelo necesitas una credencial:

opencode auth login

El comando abre un menú de proveedores (Anthropic, OpenAI, modelos locales como Ollama, entre otros) y guarda la sesión de forma segura. Para ver qué tienes conectado:

opencode auth list

La guía de providers aclara algo importante: puedes tener varias cuentas a la vez y elegir cuál usa cada proyecto desde opencode.json. No necesitas una API key por cada herramienta que instales: una sola credencial de proveedor abastece al agente.

Configuración: opencode.json

La configuración vive en opencode.json (o opencode.jsonc) en la raíz del proyecto. Ahí defines el modelo por defecto, el proveedor y comportamientos del agente:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sonnet",
  "provider": "anthropic"
}

Puntos que conviene fijar desde el día uno:

• model: el modelo que usará por defecto; puede ser un alias corto o el id completo.
• provider: el proveedor de la credencial que vas a usar; si trabajas con varios, define uno por proyecto para que el agente no use el primero que encuentre.
• Reglas globales: no se ponen aquí, se ponen en AGENTS.md (siguiente sección). El archivo de config define cómo ejecuta, las reglas definen qué debe respetar.

Si no sabes qué modelo elegir, la regla práctica para no quedarte bloqueado: usa el modelo recomendado por el proveedor que ya pagas y cambia de modelo solo cuando una tarea específica lo pida (un razonamiento largo, un refactor delicado).

Las reglas: AGENTS.md manda

OpenCode lee AGENTS.md del proyecto y lo trata como instrucciones permanentes del agente: es el mismo convenio que usa Claude Code, Codex y Cursor, así que un archivo bien escrito sirve para varias herramientas. En la guía de AGENTS.md está el detalle; aquí el mínimo viable:

• Qué puede tocar: git add <paths> explícitos, nunca git add . ni push directo a main.
• Qué debe verificar antes de terminar: tests, lint, build, y no dejar basura.
• Qué no debe hacer sin preguntar: borrar archivos, cambiar secretos, modificar infraestructura.

Ese archivo es lo que separa a un agente que edita tu repo de forma segura de uno que hace lo que se le ocurre. Tómate los 15 minutos en escribirlo la primera vez; cada sesión posterior lo respeta sin que lo repitas.

Flujo de trabajo: del TUI al modo no interactivo

El uso diario más común es la TUI: escribes la tarea, el agente la ejecuta y te muestra el plan y los diffs. Para automatización y scripts, existe el modo no interactivo:

opencode run "agrega validación al formulario de login"

opencode run ejecuta la tarea sin abrir la interfaz y devuelve el resultado; es lo que usas en un script de CI, en un cron o cuando quieres encolar varias tareas. Para sesiones largas o flujos entre máquinas, opencode serve expone al agente como servicio y puedes conectarte desde otros procesos.

Un flujo seguro típico para una tarea de desarrollo:

1. Crea una rama limpia (en la guía de worktrees está cómo hacerlo sin pisar tu rama principal).
2. opencode en esa carpeta con la tarea: "implementa X con tests".
3. Revisa cada diff que proponga; nunca aceptes cambios que no entiendas.
4. Corre los gates tú mismo: pnpm test, pnpm lint, build.
5. Commit con paths explícitos y abre el PR.

Conectar MCP: herramientas externas

OpenCode soporta servidores MCP para darle al agente acceso a herramientas externas: bases de datos, APIs, buscadores. Desde la documentación de MCP:

opencode mcp add <nombre> -- <comando>
opencode mcp list

Añade servidores solo cuando el agente los necesite de verdad: cada herramienta extra es superficie de error y de riesgo. Prefiere MCP locales (procesos que corren en tu máquina) antes que servidores remotos con acceso a datos sensibles.

Checklist antes de dejar trabajar al agente

• Tienes rama propia y el repo está limpio (git status).
• AGENTS.md existe y prohíbe push directo, git add . y borrado sin confirmar.
• Autenticación probada: opencode auth list muestra tu proveedor.
• opencode.json define modelo y provider para este proyecto.
• Tienes presupuesto claro: el agente consume tokens del proveedor conectado.
• Revisarás diffs antes de commitear; el agente no hace push por ti.

Preguntas frecuentes

¿OpenCode reemplaza a otro agente CLI? No necesariamente: usa el que ya conoces y donde esté tu equipo. OpenCode brilla cuando quieres un agente open source, configurable por proyecto y con la misma base de reglas (AGENTS.md) que tus otras herramientas.

¿Puedo usarlo con modelos baratos? Sí, cualquier proveedor con API (o modelo local vía Ollama) sirve; el costo depende del proveedor elegido. La serie de trabajo LATAM muestra cómo elegir modelos de bajo costo sin sacrificar entregables revisables.

¿Es seguro dejarlo editar archivos? Es tan seguro como tu revisión: el agente propone cambios y tú los aceptas. La protección real está en AGENTS.md (qué no tocar), en git (revertir cualquier cambio) y en no darle credenciales en el prompt.

Con la instalación lista, una credencial conectada y AGENTS.md escrito, OpenCode queda como un operador de terminal más: rápido para tareas mecánicas, revisable en cada paso y sin salir de git.