Skip to content

OpenCode uso: agente de código abierto, conecta cualquier modelo nacional chino ​

Los Claude Code y Codex de las dos lecciones anteriores están atados, respectivamente, a los modelos y suscripciones de Anthropic y OpenAI; en esta lección de 12 minutos veremos el OpenCode del bando de código abierto: la herramienta en sí es de código abierto y gratuita, y los modelos se conectan libremente: proveedores nacionales chinos como DeepSeek, Kimi, Zhipu y Tongyi están todos en el catálogo oficial de modelos; usa el proveedor cuya key ya tengas a mano. Este tutorial de OpenCode se centra en el CLI, su forma principal — posicionado oficialmente como «agente de codificación con IA de código abierto» —, y también hay versión de escritorio y web, que mencionamos de pasada. (Fecha de verificación de datos 2026-11-05; el catálogo de modelos y los comandos cambian con las versiones, consulta la documentación oficial.)

Qué podrás hacer al terminar ​

  • Instalar OpenCode CLI en macOS / Linux (en Windows usa el binario independiente oficial) e iniciarlo con un solo comando desde el directorio del proyecto
  • Conectar modelos con /connect: proveedores nacionales chinos como DeepSeek, Kimi, Zhipu y Tongyi están todos en el catálogo oficial; pega la API key y listo
  • Elegir modelo con /models, asignar la primera tarea y ver cómo lee archivos, modifica código y ejecuta comandos por su cuenta
  • Operaciones útiles: @ para citar archivos, ! para ejecutar shell directamente, /undo para deshacer
  • Vigilar el uso con opencode stats, actualizar con opencode upgrade, y gestionar credenciales con opencode auth

Tu situación actual ​

  • Claude Code requiere suscripción de Claude y Codex requiere cuenta de ChatGPT; yo ya tengo a mano API keys de DeepSeek / Kimi / Zhipu
  • Chatear sobre código en la versión web, copiando y pegando archivos de un lado a otro, y después de cada cambio hay que volver a pegarlo uno mismo
  • Oí que OpenCode es una herramienta de programación con IA de código abierto y gratuita, pero tras instalarla estoy perdido: ¿de dónde salen los modelos? ¿Cómo se usa la interfaz de terminal?

Cuándo usar este método ​

Cuando necesites:

  • Un agente de codificación de código abierto no atado a ningún proveedor de modelos: acepta cualquier API key y los modelos nacionales chinos funcionan directamente
  • Impulsar un agente en la terminal con una cuenta de modelo nacional chino ya existente (API de pago por uso o plan Coding Plan)
  • Una herramienta de código abierto: el código fuente está público en github.com/anomalyco/opencode, modifícalo si quieres

Y además no quieras:

  • Contratar una suscripción en el extranjero solo para usar un agente de codificación
  • Estar moviendo código y mensajes de error de un lado a otro en un chat web
  • Quedarte encerrado en el ecosistema de un solo modelo: hoy DeepSeek, mañana Kimi; cambiar de modelo es tan fácil como cambiar la key

🎒 Preparativos antes de empezar ​

  • Haber leído la guía de uso diario y saber que esta página trata de OpenCode (el bando de código abierto) de las cuatro herramientas
  • Al menos una cuenta de modelo: API key de un proveedor nacional chino (DeepSeek / Kimi / Zhipu, etc.), o suscripción de ChatGPT Plus / Pro, o conectar primero OpenCode Console para probar con modelos gratuitos — el coste de cada ruta se detalla en la comparación de precios
  • Un directorio de proyecto para practicar (uno donde cd y puedas ponerte a trabajar)
  • 12 minutos de tiempo sin interrupciones

💡 Las dos lecciones anteriores no son un requisito previo

Esta lección solo requiere haber leído la guía de uso diario. El uso de Claude Code y el de Codex son independientes de esta lección, pero el enfoque de «explicar una tarea con claridad, como si se la asignaras a alguien» es aplicable a todos.

Idea central ​

El posicionamiento oficial de OpenCode en una frase: agente de codificación con IA de código abierto (open source AI coding agent), disponible en tres formas: terminal, escritorio y web. La diferencia más fundamental con las dos lecciones anteriores: el modelo no está atado. Claude Code usa modelos Claude y Codex usa modelos GPT; OpenCode en sí es solo una «cáscara de agente», con un catálogo de modelos procedente de models.dev donde puedes conectar más de un centenar de proveedores nacionales y extranjeros — precisamente su punto más amigable para los usuarios de China: el catálogo incluye expresamente un gran número de proveedores chinos y planes nacionales.

Comparado con las dos lecciones anteriores:

Claude CodeCodexOpenCode
ModeloSerie ClaudeSerie GPTSin ataduras: más de un centenar de proveedores en el catálogo de models.dev
PagoSuscripción de Claude o API keySuscripción de ChatGPT o API keyLa herramienta es de código abierto y gratuita; el coste del modelo se paga al proveedor que conectes (hay además una suscripción opcional, OpenCode Go)
Código fuenteCerradoCerradoAbierto (github.com/anomalyco/opencode)
FormatoTerminal / IDE / Escritorio / WebCLI / IDE / Escritorio / WebTerminal / Escritorio / Web

Uso en una frase: primero /connect conecta la cuenta, luego /models elige el modelo. Hay cuatro formas de conectar credenciales:

Método de credencialCómo funciona
API keyPega la clave y guárdala como cuenta de ese proveedor
OAuthAbre el navegador o autoriza con código de dispositivo
ComandoEjecuta el comando de obtención de clave que provee el proveedor y guarda la salida como key
Variable de entornoLee la variable desde el proceso del servicio, no se guarda en disco

Los tres formatos en una frase: además de la CLI, OpenCode también tiene versión de escritorio (descarga el instalador desde el sitio oficial) y versión web (opencode pair genera un enlace de inicio de sesión de un solo uso, válido durante 5 minutos y que caduca tras un solo uso) — este curso no las detalla, la CLI es la vía principal.

Claude Code y Codex: ¿cómo elegir y cómo combinarlos? Si quieres usar el modelo de una empresa concreta, elige su herramienta oficial; si tienes una clave de un modelo nacional o no quieres quedar atado a un único ecosistema, OpenCode es la elección equivalente. Combinarlos es totalmente viable: los tres tienen un mecanismo de archivo de instrucciones del proyecto, y en OpenCode rige AGENTS.md (el mismo archivo sirve también para Codex; a partir de la v2.3.1, si no hay AGENTS.md en el directorio, también lee CLAUDE.md; para más detalles, consulta AGENTS.md y CLAUDE.md). Para una comparación completa de cómo elegir entre las cuatro herramientas, véase comparación de herramientas; para la tabla completa de costos, véase comparación de precios.

Sígueme paso a paso ​

Paso 1: instalar la CLI de OpenCode ​

Por qué: OpenCode es una herramienta de línea de comandos que se instala de forma independiente; primero hay que instalarla para que exista todo lo demás.

Forma A: script oficial de instalación (recomendado, macOS / Linux) ​

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

Forma B: gestor de paquetes (macOS / Linux) ​

bash
brew install anomalyco/tap/opencode-v2
bash
npm install -g @opencode/cli

El paquete npm usa un script postinstall para elegir el binario de tu plataforma: pnpm requiere autorización explícita (pnpm add -g --allow-build=@opencode/cli @opencode/cli), bun requiere añadir confianza (bun install -g --trust @opencode/cli); también existen otros canales como yarn, AUR (paru -S opencode-beta), mise, etc. (mise necesita la versión 2026.10.9 o posterior; las versiones antiguas instalan OpenCode 1).

Usuarios de Windows: binario independiente o versión de escritorio ​

La documentación oficial indica claramente que «los gestores de paquetes de Windows no están soportados». Hay dos caminos: descargar el binario independiente de la CLI desde el sitio oficial (zip, disponible en ARM64 / x64), descomprimir y usar; o instalar directamente la aplicación de escritorio.

Verificación tras la instalación:

bash
opencode --version

Deberías ver: la terminal imprime el número de versión.

  • Pequeña comprobación: opencode --version puede imprimir el número de versión

Paso 2: iniciar OpenCode y conocer la interfaz de terminal ​

Por qué: el formato principal de OpenCode es una interfaz de terminal a pantalla completa (TUI); conócela en el primer arranque, todas las operaciones posteriores ocurren aquí.

bash
cd /path/to/your/project
opencode

Deberías ver: una interfaz de terminal a pantalla completa con el cuadro de entrada en la parte inferior. Escribe directamente la descripción de la tarea y pulsa Enter para enviar; para saltar de línea usa Shift+Enter (o Ctrl+Enter / Alt+Enter / Ctrl+J).

¿No quieres pantalla completa? Hay dos entradas más:

EntradaComandoAdecuado para
Interfaz minimalistaopencode miniQuienes prefieren un cuadro de entrada sencillo
Tareas únicas en scripts / CIopencode run "Explain this repository"Sin abrir interfaz, la salida va directamente a la terminal
  • Pequeña comprobación: inicié opencode en el directorio del proyecto, veo el cuadro de entrada y puedo escribir

Paso 3: núcleo del tutorial de OpenCode — conectar modelos nacionales con /connect ​

Por qué: OpenCode no incluye modelos de serie; solo «cobra vida» al conectar tu cuenta. Y los modelos nacionales son precisamente su punto fuerte: el catálogo oficial de modelos (proveniente de models.dev) incluye una gran cantidad de proveedores chinos y planes nacionales — esta es la mayor razón para elegirlo en lugar de las herramientas de las dos lecciones anteriores.

En la sesión, escribe:

text
/connect

Deberías ver: la lista de selección de proveedores. Elige un proveedor (por ejemplo DeepSeek) y pega la API key según las indicaciones.

Catálogo de proveedores nacionales (extracto; un mismo proveedor suele tener varias entradas — versión internacional / nacional / plan — verifica la que hayas activado):

ProveedorEntradas en el catálogo (ejemplos)Variable de entorno de credencial
DeepSeekDeepSeekDEEPSEEK_API_KEY
Moonshot AI (Kimi)Moonshot AI (China), Kimi For CodingMOONSHOT_API_KEY / KIMI_API_KEY
Zhipu AIZhipu AI, Zhipu AI Coding Plan, Z.AIZHIPU_API_KEY
Alibaba TongyiAlibaba (China), Alibaba Coding PlanDASHSCOPE_API_KEY / ALIBABA_CODING_PLAN_API_KEY
MiniMaxMiniMax (minimax.cn), MiniMax Token PlanMINIMAX_API_KEY
Volcengine Ark de ByteDanceVolcengine Ark, Volcengine Ark Coding PlanARK_API_KEY / ARK_CODING_PLAN_API_KEY
SiliconFlowSiliconFlow (China)SILICONFLOW_CN_API_KEY
TencentTencent Coding Plan (China)TENCENT_CODING_PLAN_API_KEY
StepFunStepFun (China)STEPFUN_API_KEY
ModelScope (Móda)ModelScopeMODELSCOPE_API_KEY

Tomando como ejemplo la conexión de deepseek con opencode, puedes conectarte incluso sin abrir la interfaz (el ID del proveedor es el nombre que aparece en el directorio):

bash
opencode auth login deepseek --method key

Deberías ver: se te pide introducir la API key; pégala y se guardará como cuenta.

Comprobación tras conectar:

bash
opencode auth list

Deberías ver: la lista de cuentas de proveedores conectadas.

💡 ¿No tienes ni una sola key? Empieza aprovechando los modelos gratuitos oficiales

Tras registrarte en la consola de OpenCode (opencode.ai/console) y conectarte, aparecerá en el directorio un lote de modelos gratuitos (como GLM-5.3-Flash Free y DeepSeek V4.1 Flash Free), para completar el flujo sin gastar un céntimo.

  • Pequeña comprobación: en opencode auth list puedo ver el proveedor que acabo de conectar

Paso 4: elige un modelo con /models y asigna la primera tarea ​

Por qué: conectar un proveedor solo significa «tener mercancía»; todavía hay que decirle a OpenCode qué modelo usar esta vez. Una vez elegido, puedes asignar tareas igual que en las dos lecciones anteriores.

En la sesión, escribe:

text
/models

Deberías ver: la lista de modelos de tus proveedores conectados (por ejemplo, DeepSeek V4.1 Flash 1017 en el directorio de DeepSeek, entre otros); al seleccionar uno se cambia, y solo surte efecto en la sesión actual.

Asigna la primera tarea: igual que en la lección de Codex, empieza pidiéndole que te explique este proyecto:

text
Explain how authentication works in this project

Deberías ver: OpenCode lee los archivos por sí mismo y lista la estructura del proyecto; cuando le pides cambiar código, edita los archivos directamente, y cuando necesita verificar, ejecuta comandos localmente.

Para cambiar de modelo en cualquier momento, usa /models (o pulsa Ctrl+X y luego M; F2 alterna entre los modelos usados recientemente).

  • Pequeña comprobación: en /models puedo ver los modelos del proveedor que conecté y he seleccionado uno

Paso 5: operaciones cotidianas prácticas — @ para citar archivos, ! para ejecutar comandos, /undo como botón de arrepentimiento ​

Por qué: que un agente resulte cómodo de usar depende de estos pequeños gestos. Las operaciones diarias de OpenCode caben en una sola tabla:

Qué quieres hacerOperación
Citar un archivo concretoReview @src/auth.ts for error handling problems (puede llevar números de línea @src/auth.ts#20-45)
Ejecutar un shell directamente!git status (la salida queda en la sesión y él la ve)
Listar todos los comandosescribe /; Ctrl+P abre la paleta de comandos
Iniciar una sesión nueva/new o Ctrl+X y luego N
Volver a una sesión anterior/sessions
Botón de arrepentimiento/undo deshace el último mensaje y el trabajo que hizo; /redo lo restaura
Hacer una preguntita «que no cuenta»/btw why did the test in step 2 fail? (la respuesta no entra en el contexto)

Deberías ver: @ abre una lista de búsqueda de archivos que se va estrechando a medida que escribes; ! entra en modo shell, y Esc sale sin ejecutar.

  • Pequeña comprobación: he citado archivos con @, ejecutado comandos con ! y deshecho algo una vez con /undo

Paso 6: gestiona bien cuentas, uso y actualizaciones ​

Por qué: OpenCode funciona con la lógica de «la herramienta por un lado, el coste de los modelos por cuenta del proveedor»: debes tener claro cuántas cuentas has conectado y en qué se va el dinero.

bash
opencode auth list
opencode stats
opencode stats --cost

Deberías ver: auth list lista las cuentas guardadas; stats muestra estadísticas de uso compartibles, y añadiendo --cost se ve el desglose de costes.

Actualizar la versión:

bash
opencode upgrade

Seguridad de credenciales en dos frases: las API keys y los tokens OAuth se guardan en una base de datos SQLite local (consulta la ruta con opencode debug paths db, normalmente ~/.local/share/opencode/opencode.db); no modifiques la base de datos a mano, para añadir o eliminar cuentas usa siempre /connect o el comando opencode auth.

  • Pequeña comprobación: con opencode stats puedo ver mi uso

Punto de control ✅ ​

  • opencode --version imprime el número de versión y puedo iniciar la interfaz de terminal en el directorio del proyecto
  • /connect conectado al menos a un proveedor, y opencode auth list lo muestra
  • /models con el modelo elegido, he asignado la primera tarea y lo he visto leer y modificar archivos por sí mismo
  • Sé usar @ para citar archivos, ! para ejecutar comandos y /undo para deshacer
  • opencode stats muestra el uso y sé dónde se guardan las credenciales y cómo gestionarlas

Avisos de errores comunes ​

❌ En Windows no se puede instalar con gestores de paquetes ​

La documentación oficial lo deja claro: «los gestores de paquetes de Windows no están soportados». Lo correcto: descarga el binario CLI independiente desde el sitio oficial (descomprime el zip) o instala la aplicación de escritorio; no pierdas tiempo con winget / scoop.

❌ Con pnpm / bun los scripts se bloquean al instalar el paquete npm y luego no arranca ​

El paquete npm depende de un script postinstall para elegir el binario de cada plataforma; pnpm bloquea scripts por defecto y bun no confía por defecto. Cómo permitirlo: pnpm add -g --allow-build=@opencode/cli @opencode/cli, bun install -g --trust @opencode/cli. Los usuarios de npm no se ven afectados.

❌ Tras iniciar sesión con un plan de ChatGPT, sientes que «el modelo se ha vuelto más tonto» ​

OpenCode añade por defecto un límite de contexto a los modelos con inicio de sesión de ChatGPT (GPT-6.1 Sol y modelos más recientes 500,000, modelos más antiguos 272,000), alineado con el valor predeterminado de Codex, para evitar que el uso del plan se consuma demasiado rápido. A partir de la v2.3.1, al iniciar sesión con ChatGPT la lista de modelos también incluye GPT 6.2 Sol y GPT 6.2 Astra (incluida la variante fast).@@I18N_KEEP_000042@@ Si realmente quieres eliminarlo, desactiva este complemento integrado en la configuración:

jsonc
{ "plugins": ["-opencode.provider.openai-context-caps"] }

(El prefijo - indica que solo se desactiva este plugin integrado; los demás plugins no se ven afectados.)

❌ Escribir la API key en texto plano en el archivo de configuración y, además, confirmarla en el repositorio ​

Las credenciales deben guardarse con /connect o opencode auth login (van a la base de datos local), o pasarse al proceso del servicio mediante variables de entorno; escribirlas en opencode.jsonc y confirmarlas en git equivale a dejar la llave puesta en la cerradura. Usar una variable de entorno temporal también vale: DEEPSEEK_API_KEY=<你的key> opencode --standalone.

Trucos avanzados (opcional) ​

Deja un «manual de instrucciones» para el proyecto. Coloca AGENTS.md en el directorio raíz del proyecto, escribiendo en él los comandos de construcción, las convenciones de código y los requisitos de verificación; cada sesión de OpenCode lo leerá primero; la versión global se coloca en ~/.config/opencode/AGENTS.md. A partir de la v2.3.1 (2026-11-18), OpenCode también leerá CLAUDE.md: si un directorio no tiene AGENTS.md, se lee el CLAUDE.md de ese directorio; si falta el AGENTS.md global, se recurre al ~/.claude/CLAUDE.md; si no quieres este respaldo, define la variable de entorno OPENCODE_DISABLE_CLAUDE_CODE. Cuando existan ambos, AGENTS.md tiene prioridad. Para una explicación detallada de cómo escribirlo, consulta AGENTS.md y CLAUDE.md: deja un manual del proyecto para la IA.

¿No ves qué hace cada paso? A partir de la v2.3.0 (2026-11-13), los subagentes se ejecutan por defecto en segundo plano y vuelven a informar al terminar; el registro de la interfaz de terminal también es más silencioso por defecto (session.verbosity tiene por defecto low, y una serie de llamadas a herramientas se contrae en una sola línea de actividad). Si quieres ver cada paso, ajusta Verbosity a medium o high en la configuración.

Conecta modelos locales, totalmente sin conexión. Si tienes Ollama instalado, ollama serve inicia el servicio, ollama pull qwen3:8b descarga el modelo, y OpenCode descubre automáticamente los modelos en 127.0.0.1:11434, sin necesidad de conectar una cuenta; LM Studio y vLLM también tienen descubrimiento integrado.

Si el proveedor no está en el directorio, agrégalo tú mismo. Cualquier API compatible con OpenAI se puede conectar a opencode.jsonc mediante un proveedor personalizado:

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "acme": {
      "name": "Acme",
      "env": ["ACME_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "https://llm.acme.example/v1" },
      "models": { "qwen3-coder": { "name": "Qwen 3 Coder" } }
    }
  }
}

¿Ya tienes suscripción a ChatGPT? Úsala directamente. /connect elige OpenAI, y como método de inicio de sesión elige Sign in with ChatGPT— el uso se cuenta en tu plan Plus / Pro y los modelos aparecen sin costo.

¿Quieres «uso ilimitado por suscripción mensual»? Mira OpenCode Go. Un paquete oficial de suscripción a modelos de código: Go $10/mes, Go Plus $40/mes, Go Teams $20/miembro/mes; tras suscribirte en la consola, conecta con /connect como con cualquier proveedor normal. Totalmente opcional: no suscribirse no afecta ninguna función.

Ejecución en scripts y CI. opencode run lanza tareas puntuales sin abrir la interfaz: opencode run --model anthropic/claude-sonnet-5-5 "Refactor parseToken"; añade --continue para continuar la sesión anterior.

Resumen de esta lección ​

✅ OpenCode: el hilo cotidiano de este tutorial = instalar el CLI → /connect conectar un modelo (elige cualquier proveedor nacional) → /models elegir modelo → asignar tareas → @/!//undo operaciones rápidas → stats vigilar el uso.

✅ Es un agente de código abierto no vinculado a ningún modelo: el núcleo es gratuito y de código abierto, y el costo de los modelos se paga al proveedor que conectes; tiene el catálogo más completo de modelos nacionales: DeepSeek, Kimi, Zhipu, Tongyi, MiniMax, Volcano Ark, SiliconFlow, Tencent, StepFun y ModelScope están todos.

✅ Tres formas: CLI (el hilo de esta lección), versión de escritorio y versión web (opencode pair enlace de un solo uso, válido durante 5 minutos).

✅ Cuatro formas de conectar credenciales (API key / OAuth / comando / variable de entorno); las credenciales de cuenta se guardan en una base de datos SQLite local (las variables de entorno no se escriben en disco), y la gestión se hace solo con los comandos /connect y opencode auth.

✅ El manual del proyecto se rige por AGENTS.md y comparte el mismo archivo con Codex, así que no hace falta reescribirlo al cambiar de herramienta; a partir de la v2.3.1, cuando no exista AGENTS.md, se recurre a CLAUDE.md como respaldo.

Repaso de las operaciones clave:

OperaciónCómo hacerloDescripción
Instalacióncurl -fsSL https://opencode.ai/v2/install | bashAlternativas: brew, npm; en Windows usa el binario independiente
Inicioen el directorio del proyecto opencodeversión minimalista opencode mini; para scripts opencode run
Conectar modelo/connect elige proveedor y pega la keyvía línea de comandos opencode auth login <厂商> --method key
Elegir modelo/modelssolo aplica a la sesión actual; F2 recorre los modelos recientes
Referenciar archivos / ejecutar comandos@src/auth.ts / !git status@ admite números de línea #20-45
Deshacer/undo, /redorevierte el último mensaje y el trabajo que realizó
Consultar usoopencode stats, opencode stats --costpara actualizar usa opencode upgrade

Avance de la próxima lección ​

Hemos usado la línea de comandos hasta ahora; la última lección es para quienes no quieren tocar el terminal en absoluto: WorkBuddy Uso: una estación de trabajo de IA de escritorio de Tencent.

Aprenderás:

  • WorkBuddy qué es: una estación de trabajo de IA de escritorio de Tencent, se inicia sesión escaneando un código con WeChat
  • cómo hacer que la IA cree sitios web y mini programas sin escribir comandos
  • cómo se calculan los créditos y cómo elegir un plan
  • la tabla completa de costos de las cuatro herramientas está en comparación de precios
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.