OpenCode Guía de inicio rápido: Instale, configure y use el agente de codificación AI del terminal

Cómo instalar, configurar y usar OpenCode

Índice

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

Nota de versión: OpenCode se actualiza con rapidez. Los comandos “latest” aquí son estables, pero la salida y los valores predeterminados pueden cambiar—siempre verifica la documentación oficial del CLI y el registro de cambios (vinculados a continuación).

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

¿Qué es OpenCode (y en qué se encaja)?

OpenCode está diseñado para codificación agente centrada en la terminal, manteniendo la flexibilidad de 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 no interactivos “one-shot” mediante opencode run (scripts/automatización)
  • exponer un servidor HTTP sin cabeza mediante opencode serve (y una interfaz web mediante opencode web)
  • ser controlado mediante programación mediante el SDK oficial JS/TS @opencode-ai/sdk

opencode con qwen3.5 27b LLM autohospedado

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

  • Análisis profundo de CLI
  • comportamiento y costos de modelos/proveedores (comparación de LLM dentro de OpenCode)
  • configuración y agentes
  • integraciones (GitHub/GitLab/Copilot)
  • hoja de trucos

Requisitos previos

Querrás:

  • Un emulador de terminal moderno (importante para la experiencia de TUI).
  • Acceso a al menos un modelo/proveedor (claves de API o autenticación de suscripción, según el proveedor).

Instalar OpenCode (copia y pega)

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

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

Opciones del 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 (última desde AUR)
paru -S opencode-bin

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

# chocolatey (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 instalación

opencode --version
opencode --help

Forma esperada de salida (variará según la versión):

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

Conectar un proveedor (dos rutas prácticas)

Ruta A: /connect de TUI (interactiva)

Inicia OpenCode:

opencode

Luego ejecuta:

/connect

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

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

OpenCode admite configurar 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.

Iniciar un proyecto correctamente (ejecución recomendada primera)

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. Normalmente es útil comprometer este archivo para que OpenCode (y tus compañeros) compartan un contexto de proyecto consistente.

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

OpenCode admite ejecuciones no interactivas:

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

Flujo de trabajo: generar código (CLI)

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

opencode run "Escribe una función Go ParsePort(envVar string, defaultPort int) (int, error). Debe leer la variable de entorno, analizar un entero, validar 1-65535 y devolver defaultPort si está vacío. 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 mediante un agente más restrictivo.

opencode run --agent plan --file ./src/auth.ts \
  "Refactoriza este archivo para reducir la complejidad. Salida: (1) un breve plan, (2) un parche de diferencia unificada, (3) riesgos/casos límite para 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, repregunta: “Devuelve solo un parche 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 API? Lista los archivos probables y explica el flujo. Si no estás seguro, di qué revisaste."

Salida esperada:

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

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

Si estás scripting o ejecutando múltiples llamadas a opencode run, puedes iniciar un servidor sin cabeza una vez:

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

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

Salida esperada:

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

Uso programático (SDK oficial JS/TS)

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

Instalar:

npm install @opencode-ai/sdk

Ejemplo: iniciar servidor + cliente, luego hacer 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 cadena del modelo es proveedor/modelo (ejemplo solo)
    // 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 hacer un prompt
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 sección pequeña de README que describa este repositorio." }],
  },
});

console.log(result.data);

// Cerrar servidor cuando se termine
opencode.server.close();

Ejecutar:

node scripts/opencode-sdk-demo.mjs

Forma esperada de salida:

  • “Servidor ejecutándose en…”
  • Una respuesta de salud que incluye una cadena de versión
  • Un objeto de respuesta 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 JSON y JSONC. Este es un punto de partida razonable para una configuración local al 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": "proveedor/modelo",

  // Opcional: un modelo “pequeño” más barato para tareas livianas (títulos, etc.)
  "small_model": "proveedor/modelo-pequeño",

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

  // Opcional seguridad: requiere confirmación antes de ediciones/comandos
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Hoja de trucos mínima (referencia rápida)

Comandos que usarás diariamente

opencode                       # iniciar TUI
opencode run "..."             # ejecución no interactiva (automatización)
opencode run --file path "..." # adjuntar archivos al prompt
opencode models --refresh      # refrescar lista de modelos
opencode auth login            # configurar credenciales del proveedor
opencode serve                 # servidor HTTP sin cabeza (OpenAPI)
opencode web                   # servidor sin cabeza + interfaz 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/teclas de atajo

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

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

Preguntas frecuentes (listo para esquema)

¿Qué es OpenCode?

OpenCode es un agente de código abierto de IA diseñado para trabajar en tu terminal (TUI + CLI) con superficies adicionales para escritorio/IDE.

¿OpenCode es gratuito?

La herramienta es de código abierto. El costo de uso depende del modelo/proveedor al que te conectes. Algunos proveedores pueden ofrecer autenticación basada en suscripción o niveles gratuitos.

¿Cómo ejecuto OpenCode sin abrir el TUI?

Usa opencode run "..." para el modo no interactivos (útil para scripts/automatización).

¿Dónde almacena OpenCode las credenciales del proveedor?

opencode auth login almacena las credenciales en ~/.local/share/opencode/auth.json.

¿OpenCode tiene una API / SDK?

Sí. OpenCode puede ejecutar un servidor HTTP sin cabeza (opencode serve) con una especificación OpenAPI en /doc, y proporciona un SDK oficial JS/TS: @opencode-ai/sdk.

¿Puedo usar GitHub Copilot con OpenCode?

GitHub ha anunciado que Copilot admite la autenticación con OpenCode mediante una integración formal. La disponibilidad exacta depende de tu plan de Copilot y el flujo actual de autenticación del proveedor.

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

Esta versión está diseñada deliberadamente para ser 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 usuario de terminal
Ejecutar prompt one-shot opencode run "..." Modo no interactivos para scripting/automatización
Adjuntar archivos 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 (restringido por permisos)
Listar modelos opencode models [provider] Usa --refresh para actualizar la lista 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 cabeza 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 reinicios 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 + 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 se puede importar desde una URL de compartir
Ver banderas globales del CLI opencode --help / opencode --version --print-logs + --log-level para depuración
Concepto de tecla de líder del TUI tecla de líder predeterminada a menudo ctrl+x Configurable en tui.json

Fuentes (oficiales primero)

Oficiales:

Referencia autoritativa de integración:

Comparaciones/tutoriales reputados: