Inicio rápido de OpenCode: instalar, configurar y utilizar el agente de codificación de IA para terminal

Cómo instalar, configurar y utilizar OpenCode

Índice

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

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

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

Qué es OpenCode (y dónde encaja)

OpenCode está diseñado para codificación agéntica centrada en la terminal, manteniéndose flexible en proveedores/modelos. 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 “one-shot” no interactivos mediante opencode run (scripts/automatización)
  • exponer un servidor HTTP sin interfaz (headless) 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 deseas compararlo con otro asistente agéntico de código abierto que puede ejecutar planes multietapa en un entorno aislado, consulta el Inicio rápido de la CLI de OpenHands.

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

Para un enfoque deliberadamente minimalista de la misma idea de agente de terminal —cuatro herramientas predeterminadas, sin entorno aislado integrado, todo lo demás mediante extensiones—, consulta la reseña de Pi Coding Agent.

opencode con LLM qwen3.5 27b autoalojado

Prerrequisitos

Necesitarás:

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

Instalar OpenCode (copia y pega)

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 (la más reciente desde AUR)
paru -S opencode-bin

Notas para Windows (la guía oficial recomienda comúnmente 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 un intento rápido):

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, p. 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 inicio de sesión en el navegador/dispositivo).

Camino B: CLI opencode auth login (claves del proveedor)

OpenCode admite 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 locales (Ollama, llama.cpp)

OpenCode funciona con cualquier API compatible con OpenAI. Para desarrollo local, muchos usuarios ejecutan Ollama y dirigen OpenCode a él. Recientemente tuve una experiencia muy buena configurando y ejecutando OpenCode con llama.cpp} —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 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 modelos nuevos, como Qwen3.5. Si quieres 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 enviar este archivo a control de versiones para que OpenCode (y los compañeros de equipo) compartan un contexto de proyecto consistente.

Flujos de trabajo de CLI principales (ejemplos de copia y pega)

OpenCode admite ejecuciones no interactivas:

opencode run "Explain how closures work in JavaScript"

Para patrones de flujo de trabajo de línea de comandos —canalización de la salida de git, objetivos de Makefile y CI, políticas de permisos para ejecuciones sin supervisión— 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 contexto mínimo.

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 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: confirmar que el agente plan más restrictivo se ejecuta antes de depender de é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 breve mapa de rutas de archivos y una descripción del flujo.

Ambos son pruebas de humo de un solo disparo. Para la versión de producción restringida de las mismas tareas —salida explícita de riesgos/casos límite, parches unified-diff, prompts de exploración conscientes de permisos y qué hacer cuando el modelo no cumpla—, 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 CLI repetidas con un servidor persistente

Si estás escribiendo scripts o ejecutando múltiples llamadas a 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 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

Salida esperada:

  • Igual que opencode run, pero generalmente con menos sobrecarga de arranque repetida.

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

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

Instalación:

npm install @opencode-ai/sdk

Ejemplo: iniciar servidor + cliente, luego 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 provider/model (solo un 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);

// Crea una sesión y envía 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);

// Cierra el servidor cuando termines
opencode.server.close();

Ejecuta:

node scripts/opencode-sdk-demo.mjs

Formato de salida esperado:

  • “Server running at …”
  • 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 admite 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 (provider/model). Mantén esto alineado con lo que muestra `opencode models`.
  "model": "provider/model",

  // Opcional: un "small model" 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 de opencode run sin supervisión, consulta la guía práctica de la CLI de OpenCode.

La memoria del proyecto entre sesiones es una instalación separada. Hindsight Memory para OpenCode, Cursor y otros agentes de codificación agrega el plugin al archivo ~/.config/opencode/opencode.json de nivel de usuario, un archivo diferente del opencode.jsonc de proyecto anterior.

Hoja de referencia breve (referencia rápida)

Comandos que usarás a diario

opencode                       # inicia TUI
opencode run "..."             # ejecución no interactiva (automatización)
opencode run --file path "..." # adjunta archivos al prompt
opencode models --refresh      # actualiza la lista de modelos
opencode auth login            # configura credenciales del proveedor
opencode serve                 # servidor HTTP sin interfaz (OpenAPI)
opencode web                   # servidor sin interfaz + interfaz web
opencode session list          # lista sesiones
opencode stats                 # estadísticas de tokens/costo

Comandos TUI que vale la pena memorizar

/connect   # conecta un proveedor
/init      # analiza el repositorio, genera AGENTS.md
/share     # comparte una sesión (si está habilitado)
/undo      # deshace un cambio
/redo      # rehace un cambio
/help      # ayuda/atajos

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

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

Tabla de hoja de referencia de OpenCode de una página para imprimir

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

Tarea Comando / atajo Notas
Iniciar TUI opencode El comportamiento predeterminado es lanzar la interfaz de terminal
Ejecutar prompt one-shot 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 más seguro “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 ve OpenCode
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 sobrepone
Modo de interfaz 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 compartición
Ver banderas globales de CLI opencode --help / opencode --version --print-logs + --log-level para depuración
Concepto de tecla líder TUI la tecla líder predeterminada a menudo es ctrl+x Personalizable en tui.json

Oh My Opencode — lleva OpenCode más allá con orquestación multiagente

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 multiagente. La idea principal: escribe ultrawork (o ulw) en una sesión y un orquestador (Sisyphus) toma el control, delegando subtareas a agentes especialistas 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:

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 autorizada de integración:

Comparaciones/tutoriales respetables:

Suscribirse

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