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,/undopara deshacer - Vigilar el uso con
opencode stats, actualizar conopencode upgrade, y gestionar credenciales conopencode 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
cdy 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 Code | Codex | OpenCode | |
|---|---|---|---|
| Modelo | Serie Claude | Serie GPT | Sin ataduras: más de un centenar de proveedores en el catálogo de models.dev |
| Pago | Suscripción de Claude o API key | Suscripción de ChatGPT o API key | La 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 fuente | Cerrado | Cerrado | Abierto (github.com/anomalyco/opencode) |
| Formato | Terminal / IDE / Escritorio / Web | CLI / IDE / Escritorio / Web | Terminal / 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 credencial | Cómo funciona |
|---|---|
| API key | Pega la clave y guárdala como cuenta de ese proveedor |
| OAuth | Abre el navegador o autoriza con código de dispositivo |
| Comando | Ejecuta el comando de obtención de clave que provee el proveedor y guarda la salida como key |
| Variable de entorno | Lee 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)
curl -fsSL https://opencode.ai/v2/install | bashForma B: gestor de paquetes (macOS / Linux)
brew install anomalyco/tap/opencode-v2npm install -g @opencode/cliEl 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:
opencode --versionDeberías ver: la terminal imprime el número de versión.
- Pequeña comprobación:
opencode --versionpuede 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í.
cd /path/to/your/project
opencodeDeberí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:
| Entrada | Comando | Adecuado para |
|---|---|---|
| Interfaz minimalista | opencode mini | Quienes prefieren un cuadro de entrada sencillo |
| Tareas únicas en scripts / CI | opencode run "Explain this repository" | Sin abrir interfaz, la salida va directamente a la terminal |
- Pequeña comprobación: inicié
opencodeen 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:
/connectDeberí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):
| Proveedor | Entradas en el catálogo (ejemplos) | Variable de entorno de credencial |
|---|---|---|
| DeepSeek | DeepSeek | DEEPSEEK_API_KEY |
| Moonshot AI (Kimi) | Moonshot AI (China), Kimi For Coding | MOONSHOT_API_KEY / KIMI_API_KEY |
| Zhipu AI | Zhipu AI, Zhipu AI Coding Plan, Z.AI | ZHIPU_API_KEY |
| Alibaba Tongyi | Alibaba (China), Alibaba Coding Plan | DASHSCOPE_API_KEY / ALIBABA_CODING_PLAN_API_KEY |
| MiniMax | MiniMax (minimax.cn), MiniMax Token Plan | MINIMAX_API_KEY |
| Volcengine Ark de ByteDance | Volcengine Ark, Volcengine Ark Coding Plan | ARK_API_KEY / ARK_CODING_PLAN_API_KEY |
| SiliconFlow | SiliconFlow (China) | SILICONFLOW_CN_API_KEY |
| Tencent | Tencent Coding Plan (China) | TENCENT_CODING_PLAN_API_KEY |
| StepFun | StepFun (China) | STEPFUN_API_KEY |
| ModelScope (Móda) | ModelScope | MODELSCOPE_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):
opencode auth login deepseek --method keyDeberías ver: se te pide introducir la API key; pégala y se guardará como cuenta.
Comprobación tras conectar:
opencode auth listDeberí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 listpuedo 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:
/modelsDeberí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:
Explain how authentication works in this projectDeberí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
/modelspuedo 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 hacer | Operación |
|---|---|
| Citar un archivo concreto | Review @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 comandos | escribe /; 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.
opencode auth list
opencode stats
opencode stats --costDeberí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:
opencode upgradeSeguridad 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 statspuedo ver mi uso
Punto de control ✅
opencode --versionimprime el número de versión y puedo iniciar la interfaz de terminal en el directorio del proyecto/connectconectado al menos a un proveedor, yopencode auth listlo muestra/modelscon 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/undopara deshacer opencode statsmuestra 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:
{ "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:
{
"$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ón | Cómo hacerlo | Descripción |
|---|---|---|
| Instalación | curl -fsSL https://opencode.ai/v2/install | bash | Alternativas: brew, npm; en Windows usa el binario independiente |
| Inicio | en el directorio del proyecto opencode | versión minimalista opencode mini; para scripts opencode run |
| Conectar modelo | /connect elige proveedor y pega la key | vía línea de comandos opencode auth login <厂商> --method key |
| Elegir modelo | /models | solo 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, /redo | revierte el último mensaje y el trabajo que realizó |
| Consultar uso | opencode stats, opencode stats --cost | para 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