Introducción rápida a OpenCode: instala, configura y usa el agente de codificación con IA para la terminal

Cómo instalar, configurar y usar OpenCode

Índice

OpenCode es un agente de codificación con IA de código abierto que puedes ejecutar en la terminal (TUI + CLI) con superficies opcionales de escritorio e IDE. Este es el Inicio rápido de OpenCode: instalación, verificación, conexión de un modelo/proveedor y ejecución de flujos de trabajo reales (CLI + API).

Nota sobre la versión: OpenCode se actualiza con rapidez. Los comandos “más recientes” aquí son estables, pero la salida y los valores predeterminados pueden cambiar; siempre verifica la documentación oficial de la CLI y el registro de cambios (enlazados a continuación).

Este artículo forma parte de Herramientas de desarrollo con IA: La guía completa para el desarrollo impulsado por IA. Si también mantienes un asistente autoalojado como Nous Hermes, la hoja de trucos de la CLI de Hermes Agent mapea el conjunto de comandos de hermes junto con este inicio rápido de OpenCode.

Qué es OpenCode (y dónde encaja)

OpenCode está diseñado para codificación agéntica priorizando la terminal, manteniéndose flexible en cuanto a proveedor/modelo. En la práctica, es una capa de flujo de trabajo que puede:

  • iniciar una interfaz de usuario de terminal (TUI) cuando ejecutas opencode
  • ejecutar prompts no interactivos de “una sola vez” mediante opencode run (scripts/automatización)
  • exponer un servidor HTTP sin interfaz gráfica (headless) mediante opencode serve (y una interfaz web mediante opencode web)
  • controlarse programáticamente mediante el SDK oficial de JS/TS @opencode-ai/sdk

Si deseas compararlo con otro asistente agéntico de código abierto que puede ejecutar planes de múltiples pasos en un entorno aislado, consulta el Inicio rápido del asistente de codificación OpenHands.

Para el agente priorizando la terminal de Anthropic con la misma historia de “modelo local vía HTTP” (Ollama o llama.cpp, permisos, precios), consulta Instalación y configuración de Claude Code para Ollama, llama.cpp, precios.

Para una toma deliberadamente minimalista de la misma idea de agente de terminal —cuatro herramientas predeterminadas, sin sandbox integrado, todo lo demás mediante extensiones— consulta la reseña del Agente de Codificación Pi.

opencode con LLM autoalojado qwen3.5 27b

Requisitos previos

Necesitarás:

  • Un emulador de terminal moderno (importante para la experiencia TUI).
  • Acceso a al menos un modelo/proveedor (claves de API o autenticación por suscripción, dependiendo del proveedor). Las opciones locales como Ollama o llama.cpp funcionan sin claves de API cuando ejecutas un servidor compatible localmente.

Instalar OpenCode (copiar y pegar)

Script de instalación oficial (Linux/macOS/WSL):

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

Opciones de gestor de paquetes (ejemplos oficiales):

# Instalación global de Node.js
npm install -g opencode-ai

# Homebrew (recomendado por OpenCode para las versiones más recientes)
brew install anomalyco/tap/opencode

# Arch Linux (estable)
sudo pacman -S opencode

# Arch Linux (más reciente desde AUR)
paru -S opencode-bin

Notas para Windows (la orientación oficial suele recomendar WSL para la mejor compatibilidad). Las alternativas incluyen Scoop/Chocolatey o npm.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (útil para probarlo rápidamente):

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

Verificar la instalación

opencode --version
opencode --help

Formato de salida esperado (variará según la versión):

# Ejemplo:
# <imprime un número de versión, ej. vX.Y.Z>
# <imprime ayuda con comandos/subcomandos disponibles>

Conectar un proveedor (dos rutas prácticas)

Ruta A: TUI /connect (interactiva)

Inicia OpenCode:

opencode

Luego ejecuta:

/connect

Sigue los pasos de la interfaz para seleccionar un proveedor y autenticarte (algunos flujos abren un inicio de sesión en el navegador/dispositivo).

Ruta B: CLI opencode auth login (claves de proveedor)

OpenCode soporta la configuración de proveedores mediante:

opencode auth login

Notas:

  • Las credenciales se almacenan en ~/.local/share/opencode/auth.json.
  • OpenCode también puede cargar claves desde variables de entorno o un archivo .env en tu proyecto.

Alojamiento de LLM local (Ollama, llama.cpp)

OpenCode funciona con cualquier API compatible con OpenAI. Para el desarrollo local, muchos usuarios ejecutan Ollama y apuntan OpenCode a él. Recientemente tuve una muy buena experiencia configurando y ejecutando OpenCode con llama.cpp} en su lugar; llama-server expone puntos finales compatibles con OpenAI, por lo que puedes usar modelos GGUF con el mismo flujo de trabajo. Si prefieres un control granular sobre la memoria y el tiempo de ejecución, o deseas un stack más ligero sin Python (por cierto, ollama está implementado en Go), llama.cpp vale la pena probarlo. Realmente disfruté la oportunidad de configurar las capas descargadas (offloaded layers), la facilidad de uso de los modelos en formato GGUF y la compatibilidad implementada mucho mejor/más rápida con nuevos modelos, como Qwen3.5. Si deseas saber qué modelos realmente rinden bien dentro de OpenCode —en tareas de codificación y precisión de salida estructurada— consulta mi comparación práctica de LLM para OpenCode.

Iniciar un proyecto correctamente (primera ejecución recomendada)

Desde tu repositorio:

cd /path/to/your/repo
opencode

Luego inicializa:

/init

Esto analiza tu proyecto y crea un archivo AGENTS.md en la raíz del proyecto. Generalmente vale la pena confirmar este archivo para que OpenCode (y los compañeros de equipo) compartan un contexto de proyecto coherente.

Flujos de trabajo de CLI principales (ejemplos de copiar y pegar)

OpenCode soporta ejecuciones no interactivas:

opencode run "Explain how closures work in JavaScript"

Para patrones de flujo de trabajo de línea de comandos —tuberizaciones (piping) de salida de git, objetivos de Makefile y CI, políticas de permisos para ejecuciones no supervisadas— y los modos de fallo esperables, consulta la guía práctica de la CLI de OpenCode. Se basa en este inicio rápido en lugar de repetirlo.

Flujo de trabajo: generar código (CLI)

Objetivo: generar una pequeña función probable con el mínimo contexto.

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

Salida esperada:

  • Una explicación junto con bloques de código (función + pruebas). El código exacto varía según el modelo/proveedor y el prompt.

Flujo de trabajo: refactorizar un archivo de forma segura (CLI + agente Plan)

Objetivo: confirmar que el agente plan más restrictivo se ejecuta antes de confiar en él.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

Salida esperada: una sección de plan, sin ediciones de archivos, sin comandos ejecutados.

Flujo de trabajo: hacer preguntas al repositorio (CLI)

Objetivo: confirmar que el agente explore puede localizar detalles de implementación.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

Salida esperada: un mapa breve de rutas de archivos y una descripción del flujo.

Ambos son pruebas de humo de una sola vez. Para la versión de producción restringida de las mismas tareas —salida explícita de riesgos/casos límite, parches de diff unificado, prompts de exploración conscientes de permisos y qué hacer cuando el modelo no se adhiere— consulta la sección “Mejores casos de uso de la CLI de OpenCode” de la guía práctica de la CLI de OpenCode.

Flujo de trabajo: acelerar ejecuciones repetidas de la CLI con un servidor persistente

Si estás escribiendo scripts o ejecutando múltiples llamadas a opencode run, puedes iniciar un servidor sin interfaz gráfica una vez:

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

Salida esperada:

  • La misma que opencode run, pero generalmente con menos sobrecarga de inicio repetida.

Uso programático (SDK oficial de JS/TS)

OpenCode expone un servidor HTTP (OpenAPI) y proporciona un cliente de JS/TS seguro en tipos.

Instalación:

npm install @opencode-ai/sdk

Ejemplo: iniciar servidor + cliente, luego enviar un prompt

Crea scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // El formato de la cadena de modelo es proveedor/modelo (solo como ejemplo)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Server running at: ${opencode.server.url}`);

// Verificación básica de salud/versión
const health = await opencode.client.global.health();
console.log("Healthy:", health.data.healthy, "Version:", health.data.version);

// Crear una sesión y enviar un prompt
const session = await opencode.client.session.create({ body: { title: "SDK quickstart demo" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Generate a small README section describing this repo." }],
  },
});

console.log(result.data);

// Cerrar el servidor al terminar
opencode.server.close();

Ejecutar:

node scripts/opencode-sdk-demo.mjs

Formato de salida esperado:

  • “Server running at …” (Servidor ejecutándose en …)
  • Una respuesta de salud que incluye una cadena de versión
  • Un objeto de respuesta de prompt de sesión (la estructura exacta depende de responseStyle y la versión del SDK)

Configuración mínima de OpenCode que puedes copiar

OpenCode soporta configuración JSON y JSONC. Este es un punto de partida razonable para una configuración local de proyecto.

Crea opencode.jsonc en la raíz de tu repositorio:

{
  "$schema": "https://opencode.ai/config.json",

  // Elige un modelo predeterminado (proveedor/modelo). Mantén esto alineado con lo que muestra `opencode models`.
  "model": "provider/model",

  // Opcional: un "modelo pequeño" más barato para tareas ligeras (títulos, etc.)
  "small_model": "provider/small-model",

  // Opcional: valores predeterminados del servidor de OpenCode (usado por serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Seguridad opcional: requerir confirmación antes de ediciones/comandos
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Para una política de permisos más completa orientada a trabajos no supervisados de opencode run, consulta la guía práctica de la CLI de OpenCode.

Hoja de trucos corta (referencia rápida)

Comandos que usarás a diario

opencode                       # iniciar TUI
opencode run "..."             # ejecución no interactiva (automatización)
opencode run --file path "..." # adjuntar archivos al prompt
opencode models --refresh      # actualizar lista de modelos
opencode auth login            # configurar credenciales del proveedor
opencode serve                 # servidor HTTP sin interfaz (OpenAPI)
opencode web                   # servidor sin interfaz + UI web
opencode session list          # listar sesiones
opencode stats                 # estadísticas de tokens/costos

Comandos de TUI que vale la pena memorizar

/connect   # conectar un proveedor
/init      # analizar repositorio, generar AGENTS.md
/share     # compartir una sesión (si está habilitado)
/undo      # deshacer un cambio
/redo      # rehacer un cambio
/help      # ayuda/atajos

Concepto de “tecla líder” predeterminada (TUI)

OpenCode usa una tecla “líder” configurable (comúnmente ctrl+x) para evitar conflictos con la terminal. Muchos atajos son “Líder + tecla”.

Tabla de hoja de trucos de OpenCode imprimible en una página

Esta versión es intencionalmente densa y “amigable para impresión”. (Puedes pegarla más tarde en una página dedicada /ai-devtools/opencode/cheatsheet/.)

Tarea Comando / atajo Notas
Iniciar TUI opencode El comportamiento predeterminado es lanzar la interfaz de usuario de terminal
Ejecutar prompt de una sola vez opencode run "..." Modo no interactivo para scripting/automatización
Adjuntar archivo(s) al prompt opencode run --file path/to/file "..." Usa múltiples banderas --file para varios archivos
Elegir modelo para una ejecución opencode run --model provider/model "..." Las cadenas de modelo son provider/model
Elegir agente opencode run --agent plan "..." Plan está diseñado para trabajos más seguros de “sin cambios” (restringido por permisos)
Listar modelos opencode models [provider] Usa --refresh para actualizar la lista en caché
Configurar credenciales del proveedor opencode auth login Almacena credenciales en ~/.local/share/opencode/auth.json
Listar proveedores autenticados opencode auth list / opencode auth ls Confirma lo que OpenCode ve
Iniciar servidor sin interfaz opencode serve --port 4096 --hostname 127.0.0.1 Especificación OpenAPI en http://host:port/doc
Adjuntar ejecuciones al servidor opencode run --attach http://localhost:4096 "..." Útil para evitar arranques en frío repetidos
Habilitar autenticación básica OPENCODE_SERVER_PASSWORD=... opencode serve El nombre de usuario predeterminado es opencode a menos que se sobrescriba
Modo de UI web opencode web Inicia el servidor + abre el navegador
Exportar una sesión opencode export [sessionID] Útil para archivar o compartir contexto
Importar una sesión opencode import session.json También puede importar desde una URL de compartir
Ver banderas globales de la CLI opencode --help / opencode --version --print-logs + --log-level para depuración
Concepto de tecla líder de TUI tecla líder predeterminada a menudo ctrl+x Personalizable en tui.json

Oh My Opencode — lleva OpenCode más allá con orquestación multi-agente

Una vez que OpenCode está en ejecución, el siguiente paso natural es Oh My Opencode —un plugin de la comunidad que envuelve OpenCode en un arnés multi-agente. La idea principal: escribe ultrawork (o ulw) en una sesión y un orquestador (Sisyphus) toma el control, delegando subtareas a agentes especializados que se ejecutan en paralelo, cada uno en la familia de modelos para la que sus prompts están optimizados.

Tres artículos lo cubren a fondo:

OpenCode fue una de las primeras herramientas afectadas por la política de Anthropic de bloquear el acceso de terceros a la suscripción de Claude —una medida tomada en enero de 2026, un mes antes de que la misma restricción afectara a OpenClaw. La línea de tiempo del ascenso y caída de OpenClaw documenta ambos eventos y el patrón más amplio que representan para las herramientas de agentes construidas sobre cómputo por suscripción.

Fuentes (oficiales primero)

Oficiales:

Referencia de integración autorizada:

Comparaciones/tutoriales respetables:

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.