Inicio rápido de OpenCode: Instale, configure y utilice el agente de codificación con IA en la terminal.

Cómo instalar, configurar y utilizar 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 de escritorio e IDE opcionales. Este es el Inicio Rápido de OpenCode: instala, verifica, conecta un modelo/proveedor y ejecuta flujos de trabajo reales (CLI + API).

Nota de versión: OpenCode se actualiza rápidamente. Los comandos “más recientes” aquí son estables, pero la salida y los valores predeterminados pueden cambiar; siempre verifica los documentos oficiales de la CLI y el registro de cambios (enlazados abajo).

Este artículo forma parte de Herramientas para Desarrolladores de IA: La Guía Completa para el Desarrollo Impulsado por IA.

Qué es OpenCode (y dónde encaja)

OpenCode está diseñado para codificación agéntica con enfoque en 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 cuando ejecutas opencode
  • ejecutar prompts de “una sola vez” no interactivos mediante opencode run (scripts/automatización)
  • exponer un servidor HTTP sin interfaz gráfica mediante opencode serve (y una interfaz web mediante opencode web)
  • ser controlado programáticamente mediante el SDK oficial de JS/TS @opencode-ai/sdk

Si quieres compararlo con otro asistente agéntico de código abierto que pueda ejecutar planes de múltiples pasos en un entorno aislado, consulta el Inicio Rápido del Asistente de Codificación OpenHands.

opencode con LLM qwen3.5 27b auto-alojado

Si estás construyendo un clúster /ai-devtools/, OpenCode es un candidato fuerte para un subclúster porque se expande naturalmente hacia:

  • análisis profundo de la CLI
  • comportamiento y costos del modelo/proveedor (comparación de LLM dentro de OpenCode)
  • configuración y agentes
  • integraciones (GitHub/GitLab/Copilot)
  • guía rápida (cheat sheet)
  • Oh My Opencode — capa de orquestación multi-agente construida sobre OpenCode

Prerrequisitos

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 de 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 actualizadas)
brew install anomalyco/tap/opencode

# Arch Linux (estable)
sudo pacman -S opencode

# Arch Linux (última versión desde AUR)
paru -S opencode-bin

Notas sobre Windows (la guía oficial recomienda comúnmente WSL para la mejor compatibilidad). Las alternativas incluyen Scoop/Chocolatey o npm.

# chocoloatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (útil para una prueba rápida):

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

Verificar la instalación

opencode --version
opencode --help

Forma de la salida esperada (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 caminos prácticos)

Camino A: TUI /connect (interactivo)

Inicia OpenCode:

opencode

Luego ejecuta:

/connect

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

Camino 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 local de LLM (Ollama, llama.cpp)

OpenCode funciona con cualquier API compatible con OpenAI. Para desarrollo local, muchos usuarios ejecutan Ollama y dirigen OpenCode hacia ella. Recientemente tuve una muy buena experiencia configurando y ejecutando OpenCode con llama.cpp en su lugar; llama-server expone endpoints compatibles con OpenAI, por lo que puedes usar modelos GGUF con el mismo flujo de trabajo. Si prefieres un control más granular sobre la memoria y el tiempo de ejecución, o quieres un stack más ligero sin Python (por cierto, ollama está implementado en Go), llama.cpp vale la pena probarlo. Disfruté mucho la oportunidad de configurar capas descargadas, la facilidad de uso de los modelos en formato GGUF y una compatibilidad mucho mejor/más rápida implementada con nuevos modelos, como Qwen3.5. Si quieres saber qué modelos realmente funcionan 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 comprometer este archivo para que OpenCode (y los compañeros de equipo) compartan un contexto de proyecto consistente.

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

OpenCode soporta ejecuciones no interactivas:

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

Flujo de trabajo: generar código (CLI)

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

opencode run "Escribe una función Go ParsePort(envVar string, defaultPort int) (int, error). Debe leer la variable de entorno, parsear un int, validar 1-65535 y devolver defaultPort si está vacía. Incluye 3 pruebas basadas en tablas."

Salida esperada:

  • Una explicación más 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: refactorizar sin ediciones accidentales usando un agente más restrictivo.

opencode run --agent plan --file ./src/auth.ts \
  "Refactoriza este archivo para reducir la complejidad. Salida: (1) un plan corto, (2) un parche de diff unificado, (3) riesgos/casos límite a probar. No ejecutes comandos."

Salida esperada:

  • Una sección de plan + un bloque de parche diff --git ... + una lista de verificación de pruebas.
  • El contenido varía. Si no produce un diff, vuelve a preguntar: “Devuelve solo un diff unificado” o “Usa el formato diff --git.”

Flujo de trabajo: hacer preguntas sobre el repositorio (CLI)

Objetivo: localizar detalles de implementación rápidamente.

opencode run --agent explore \
  "En este repositorio, ¿dónde se valida la autenticación para las solicitudes de API? Lista los archivos probables y explica el flujo. Si no estás seguro, di qué verificaste."

Salida esperada:

  • Un mapa corto de rutas de archivos + descripción del flujo.
  • La salida depende del tamaño del repositorio y de las herramientas de contexto del modelo/proveedor.

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

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

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Resume la estructura del repositorio y los puntos de entrada principales."
opencode run --attach http://localhost:4096 "Ahora propone 3 refactorizaciones de alto impacto y por qué."

Salida esperada:

  • Lo mismo que opencode run, pero usualmente con menos sobrecarga de inicio repetida.

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

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

Instalar:

npm install @opencode-ai/sdk

Ejemplo: iniciar servidor + cliente, luego preguntar

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 cadena de modelo es provider/model (solo ejemplo)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Servidor ejecutándose en: ${opencode.server.url}`);

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

// Crear una sesión y preguntar
const session = await opencode.client.session.create({ body: { title: "Demo de inicio rápido del SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Genera una pequeña sección de README que describa este repositorio." }],
  },
});

console.log(result.data);

// Cerrar servidor cuando termines
opencode.server.close();

Ejecutar:

node scripts/opencode-sdk-demo.mjs

Forma de la salida esperada:

  • “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 del 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 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"
  }
}

Guía rápida (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 + interfaz web
opencode session list          # listar sesiones
opencode stats                 # estadísticas de tokens/costos

Comandos 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 de terminal. Muchos atajos son “Líder + tecla”.

Tabla de guía rápida de OpenCode imprimible de una página

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

Tarea Comando / atajo Notas
Iniciar TUI opencode El comportamiento predeterminado es lanzar la interfaz 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 múltiples 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 trabajo “sin cambios” más seguro (con restricción de 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 interfaz web opencode web Inicia servidor y abre navegador
Exportar una sesión opencode export [sessionID] Útil para archivar o compartir contexto
Importar una sesión opencode import session.json También puedes importar desde una URL de compartir
Ver banderas CLI globales opencode --help / opencode --version --print-logs + --log-level para depuración
Concepto de tecla líder TUI tecla líder predeterminada suele ser ctrl+x Personalizable en tui.json

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

Una vez que OpenCode esté ejecutándose, 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 sub-tareas a agentes especializados que se ejecutan en paralelo, cada uno en la familia de modelos para la que sus prompts están ajustados.

Tres artículos lo cubren en profundidad:

Fuentes (oficiales primero)

Oficiales:

Referencia de integración autorizada:

Comparaciones/tutoriales reputables: