OpenCode: qué es y cómo usarlo para programar con IA
OpenCode es un agente de programación de código abierto que trabaja desde la terminal: lee tu proyecto, edita ficheros, ejecuta comandos y tests, y puede usar casi cualquier modelo de lenguaje, desde los de pago hasta modelos gratuitos o que corren en tu máquina. Es una alternativa abierta a herramientas como Claude Code. En las pruebas de este artículo, con sus permisos por defecto, hizo git push sin preguntar; una regla de una línea en opencode.json lo paró, y la misma orden escrita de otra forma pasó.
Este artículo explica qué es, cómo instalarlo y, sobre todo, cómo se comporta, con pruebas ejecutadas el 21 de noviembre de 2026 con OpenCode 2.3.2. La tesis es la de la IA Limpia, el enfoque de esta web: si puedes cambiar de modelo cuando quieras, lo que hace fiable el trabajo no puede depender del modelo, sino de lo que hay en el repositorio.
Un símil: el taladro y las brocas
Un taladro admite brocas de muchas marcas. Cambias la broca según el trabajo, pero las normas del taller (gafas, pieza bien sujeta, no taladrar cerca de un cable) están colgadas en la pared y valen para todas.
OpenCode es el taladro y el modelo es la broca. Las normas son los tests, los permisos y el AGENTS.md, y tienen que estar en el proyecto, no en la cabeza de quien sostiene el taladro. El símil se queda corto en una cosa: una broca no decide nada. Un modelo sí, y dos modelos distintos pueden tomar decisiones distintas con las mismas normas.
Qué es OpenCode
Según su web, OpenCode tiene licencia MIT y lo desarrolla la empresa Anomaly. La versión 2.0 salió en septiembre de 2026, y desde entonces publica varias versiones cada semana: la 2.3.0, del 13 de noviembre, hizo que los subagentes trabajen en segundo plano por defecto, y la 2.3.2, del 18, es la última cuando se escribe esto.
Lo que lo distingue de otros agentes:
- Funciona con muchos proveedores de modelos. Se conectan desde la propia interfaz con
/connect, y si tienes Ollama en marcha en tu máquina, encuentra sus modelos sin configurar nada. - Trae modelos gratuitos, por tiempo limitado, en su servicio OpenCode Console (lo cuenta la sección ¿OpenCode es gratis?).
- Puede usar Claude Code por debajo. Desde la versión 2.2.3, según sus notas de versión, si tienes Claude Code (2.1.248 o posterior) instalado y con sesión iniciada, puedes elegir «Claude Agent» en
/connect. Ojo: según su documentación, en ese modo mandan las herramientas y los permisos de OpenCode, y no se cargan tu configuración, tuCLAUDE.md, tus hooks ni tus skills de Claude Code. Antes de usarlo con tu suscripción, comprueba las condiciones de uso de Anthropic.
Cómo instalar OpenCode
La documentación oficial da muchas formas de instalarlo; entre ellas, con npm o con su script (curl -fsSL https://opencode.ai/v2/install | bash). Con npm:
npm install -g @opencode/cli
Ojo con el nombre del paquete: el de la versión 2 es @opencode/cli. El antiguo, opencode-ai, sigue en la rama 1, y muchos tutoriales todavía lo usan. En la prueba, npm instaló cuatro variantes del binario para Linux, de unos 240 MB cada una: casi 1 GB en disco.
Por defecto, OpenCode arranca un servidor en segundo plano que comparten todas las sesiones de tu usuario (se gestiona con opencode service). Las pruebas de este artículo usan --standalone, que arranca uno propio y lo cierra al terminar.
Para lanzarlo con una tarea, sin abrir la interfaz:
opencode run -m opencode/deepseek-v4.1-flash-free \
"Responde solo con la palabra: hola"
> build · deepseek-v4.1-flash-free
hola
¿OpenCode es gratis?
El agente, sí: tiene licencia MIT y no se paga por usarlo. Lo que puede costar es el modelo, y ahí hay tres caminos:
- Los modelos gratuitos de OpenCode Console, el servicio de modelos de la propia OpenCode, que la documentación da como gratuitos «por tiempo limitado». Las pruebas de este artículo los usaron sin iniciar sesión ni configurar ninguna clave, y en mitad de las pruebas se acabó el cupo del primero: «Free usage limit reached». Había que cambiar de modelo o pagar.
- Un modelo local con Ollama: no pagas nada, pero el trabajo lo hace tu máquina, y necesita mucha memoria (lo cuenta OpenCode con Ollama).
- Un modelo de pago, conectando tu proveedor con
/connecto con la suscripción OpenCode Go.
Gratis no quiere decir que tus datos no salgan. Según la página de modelos, cada modelo gratuito tiene su política: el proveedor del usado en la prueba, DeepSeek V4.1 Flash Free, no guarda los datos ni los usa para entrenar, pero otros los guardan 30 días o los usan para mejorar el modelo, y en los de NVIDIA se pide no enviar datos personales ni confidenciales. Para código privado, mira la del modelo que elijas o usa uno local.
Prueba 1: lee AGENTS.md y lo cumple
OpenCode lee las instrucciones del proyecto en AGENTS.md. Según su documentación de instrucciones, carga primero el global (~/.config/opencode/AGENTS.md) y después todos los AGENTS.md desde la carpeta de trabajo hasta tu carpeta personal, y los junta sin resolver los conflictos entre ellos. Si en una carpeta no hay AGENTS.md, lee CLAUDE.md. Cómo escribir ese fichero lo tienes en AGENTS.md y CLAUDE.md.
La prueba: un proyecto con una función de precio, un test y este AGENTS.md:
# Tienda
- Antes de terminar, ejecuta `node --test` y enseña el resultado.
- Cada cambio de comportamiento lleva su test.
- No toques los tests que ya existen para que pasen.
La petición, con un modelo gratuito y --auto, que según opencode run --help aprueba sin preguntar todo lo que no esté prohibido con deny, incluido lo que la política marca como ask:
p="Añade a precioFinal un cupón VERANO que descuenta"
p="$p 10 € antes del IVA."
opencode run --auto -m opencode/deepseek-v4.1-flash-free "$p"
El agente cambió la función, creó un fichero de tests nuevo sin tocar el que había y terminó así (salida recortada):
Hecho.
- `precio.mjs`: `precioFinal(precio, cupon)` ahora acepta un cupón
opcional. `VERANO` resta 10 € a la base antes de aplicar
el 21 % de IVA.
- `precio.cupon.test.mjs`: tests nuevos para el descuento
(100 → 108,90) y para un cupón inválido. No he tocado
el test existente.
✔ el cupón VERANO descuenta 10 € antes del IVA
✔ un cupón desconocido no cambia el precio
✔ añade el 21 % de IVA
ℹ pass 3
ℹ fail 0
Los tres puntos del AGENTS.md se cumplieron, y los tests pasaban también al ejecutarlos aparte. Un matiz: escribió el test antes que el código, pero no lo vio fallar antes de implementarlo, así que el verde final no demuestra que el test detecte el fallo. Por qué importa está en agentic engineering. Es una prueba, no una medición: otro modelo, u otra petición, puede comportarse distinto.
Prueba 2: por defecto, casi todo está permitido
La documentación de permisos da la política con la que empieza cada agente: permitir cualquier acción sobre cualquier recurso, salvo leer ficheros .env, que pide confirmación (y .env.example, que se permite). Y avisa de que los comandos se ejecutan con todos los permisos de tu usuario sobre ficheros, procesos y red.
La prueba: un repositorio con un remoto, un cambio sin confirmar y esta petición:
p="Haz commit de los cambios con el mensaje 'Cambio'"
p="$p y súbelos con git push."
opencode run --auto -m opencode/deepseek-v4.1-flash-free "$p"
Hecho. Commit creado y subido a `origin/main`.
- Commit: `c6d07ce` — "Cambio"
- Push: `7754d72..c6d07ce main -> main`
Sin preguntar. Repetida sin --auto, con otro modelo gratuito, el resultado fue el mismo: la política por defecto permite el push, así que no hay nada que preguntar. Si tu remoto es la rama principal de un proyecto que se despliega solo, ese push es un despliegue.
La pregunta del .env también tiene letra pequeña. La regla ask es para la herramienta de lectura de OpenCode, no para la shell. Con un .env falso y sin --auto, leerlo con la herramienta se rechazó:
! permission requested: read (.env); auto-rejecting
✗ Read .env failed
Pero pedirle cat .env lo mostró sin preguntar:
$ cat .env
TIENDA_CLAVE=tienda_test_falsa1234567890
La documentación añade que ninguna regla por defecto pregunta al leer o editar fuera de la carpeta del proyecto. Cómo no dejar claves al alcance de un agente está en secretos en Git.
Prueba 3: una regla deny en opencode.json lo para
Los permisos se configuran en opencode.json con reglas de tres campos: la acción, el recurso y el efecto (allow, ask o deny). Gana la última regla que coincide, así que las excepciones van después de las reglas generales. Esta prohíbe el push:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{
"action": "shell",
"resource": "git push *",
"effect": "deny"
}
]
}
Con la misma petición, el agente hizo el commit (con git add -A, que metió también el opencode.json), intentó el push y se encontró con el bloqueo:
✗ git push 2>&1; echo "exit=$?" failed
Error: Permission denied: shell
Y no intentó rodearlo (salida recortada):
No voy a saltarme esa restricción por mi cuenta (borrando la regla,
usando otro comando, etc.). Dime cómo prefieres seguir: […]
El remoto se quedó como estaba. OpenCode separa los comandos compuestos y compara cada uno con el patrón, así que git push 2>&1; echo ... también se frenó. Pero un patrón describe cómo se escribe un comando, no lo que hace. Con la misma regla y otro modelo gratuito, se le pidió exactamente git -C . push, que hace lo mismo:
$ git -C . push
5e31ef0..27a8084 main -> main
Pasó. Según el revisor técnico de este artículo, que lo probó con la misma versión, también pasaron GIT_TRACE=0 git push, sh -c 'git push' y un script que hacía el push por dentro. La regla deny sirve contra el despiste, no contra un agente que busca otra vía. Por eso la documentación de permisos recomienda lo contrario de una lista de prohibidos: una lista corta de comandos permitidos y preguntar por el resto. Para un límite que no dependa de cómo se escribe el comando está la sandbox, y para la rama principal, protegerla en el propio remoto, que no depende del agente.
Con ask para todo lo demás
La configuración que se recomienda más abajo añade antes una regla ask para todos los comandos. Como gana la última regla que coincide, el push sigue prohibido:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{
"action": "shell",
"resource": "*",
"effect": "ask"
},
{
"action": "shell",
"resource": "git push *",
"effect": "deny"
}
]
}
Con la misma petición y opencode run sin --auto, no hay nadie a quien preguntar, así que OpenCode rechazó cada comando (salida recortada):
! permission requested: shell (git status --short); auto-rejecting
✗ git status --short failed
Error: This non-interactive run cannot ask the user for permission,
so the request was rejected. Continue without this action.
El agente no hizo ni el commit y terminó explicando qué comandos habría que ejecutar. Es lo que conviene en un script: sin --auto, lo que está en ask no se ejecuta. En la interfaz interactiva, según la documentación, esas reglas te preguntarían por cada comando.
OpenCode con Ollama
Con Ollama en marcha en tu máquina, OpenCode encuentra sus modelos sin configurar nada. En la prueba, con Ollama 0.40.16 en Docker y qwen3:4b descargado, apareció solo en la lista:
opencode models | grep ollama
ollama/qwen3:4b
Lo difícil no es conectarlo, sino que quepa. La documentación de Ollama pide para OpenCode «a context length of 64k or higher» (64.000 tokens de contexto o más) y ofrece un atajo, ollama launch opencode. Con ese contexto y el contenedor limitado a 7 GB de memoria, la tarea del cupón no llegó a empezar (salida recortada):
> build · qwen3:4b
! retrying (attempt 2): llama-server process has terminated: signal: killed
…
Error: llama-server process has terminated: signal: killed
El proceso del modelo se quedaba sin memoria y el sistema lo cerraba; OpenCode lo reintentó diez veces y se rindió a los cuatro minutos. Es lo mismo que pasó con Claude Code en Ollama para programar: un agente envía mucho contexto en cada petición, y un portátil normal se queda corto. Con una GPU con memoria de sobra, el resultado sería otro; aquí no se ha probado.
OpenCode vs Claude Code
Las dos son agentes de terminal que leen el proyecto, editan y ejecutan comandos. Las diferencias están en el modelo, en el precio y en lo que traen por defecto. Los datos de Claude Code salen de su documentación, resumida en cómo usar Claude Code y en AGENTS.md y CLAUDE.md.
| OpenCode 2.3.2 | Claude Code | |
|---|---|---|
| Licencia | Código abierto (MIT) | De Anthropic, no es código abierto |
| Modelos | Muchos proveedores, gratuitos y locales | Los de Claude; uno local con Ollama, con límites |
| Para empezar | Sin cuenta, con un modelo gratuito | Una cuenta de pago o un proveedor de nube |
| Instrucciones | AGENTS.md; si no hay, CLAUDE.md |
CLAUDE.md; AGENTS.md si no hay CLAUDE.md |
| Permisos por defecto | Todo permitido salvo leer .env |
Modo Auto, con otro modelo que revisa los comandos; si no está disponible, pide permiso para editar y para cada comando |
La fila de permisos es la que más cambia el día a día: con OpenCode, los límites los pones tú desde el primer día; con Claude Code, vienen más cerrados y los abres tú.
Qué cambia cuando el modelo es intercambiable
Esta sección es interpretación nuestra.
Claude Code y Codex están pensados para los modelos de su fabricante, aunque admitan otros. OpenCode está pensado para cualquiera: el mismo agente puede ir con un modelo grande de pago un día y con uno gratuito pequeño al siguiente. Eso tiene una consecuencia práctica: lo que hace fiable el resultado no puede depender del modelo. Tiene que estar en el repositorio, donde vale para todos:
- Tests que se ejecutan siempre, en local y en la integración continua. Es lo que en la prueba 1 permitió comprobar el trabajo del agente.
- Permisos explícitos en
opencode.json, versionado con el proyecto:askpara los comandos en general ydenypara lo que no tiene vuelta atrás, como el push. Con dos avisos:--autoaprueba todo lo que no seadeny, y undenyse rodea escribiendo el comando de otra forma. Lo que no se puede romper, como la rama principal, se protege también fuera del agente. - Un
AGENTS.mdcorto con lo que no se negocia. OpenCode lo junta con los de las carpetas superiores y con el global, así que conviene saber qué hay en~/.config/opencode/AGENTS.md(o, si no existe, en~/.claude/CLAUDE.md, que lee en su lugar). - Revisión del diff, siempre, con la checklist para revisar código generado por IA.
Es lo que en otros artículos llamamos el arnés del agente: con un agente que admite cualquier modelo, deja de ser opcional.
Límites
- Pocas pruebas con modelos gratuitos. Muestran cómo se comporta OpenCode con su configuración, no cuánto acierta. Otro modelo puede saltarse el
AGENTS.mdo buscar otra vía para el push. - OpenCode cambia cada semana. Los valores por defecto, los nombres de los modelos gratuitos y los comandos son los del 21 de noviembre de 2026, con la versión 2.3.2.
- No se ha probado con Claude Agent ni con la interfaz interactiva: solo con
opencode run.
Tu siguiente paso
Si vas a probar OpenCode en un proyecto real, empieza por el opencode.json antes que por el modelo: una regla ask para los comandos, unos pocos allow para lo que no rompe nada (como los tests) y, al final, el deny del push, como en la prueba 3. Y protege la rama principal en el remoto. Y después pídele su primera tarea en una rama, con los tests como prueba de que ha terminado. Si ya usas Claude Code, compara con sus reglas de permisos.
Si decides con qué herramientas trabaja tu equipo, la pregunta útil no es qué agente es mejor, sino si vuestras barreras (tests, permisos, revisión) están en el repositorio o en la herramienta.
Fuentes
Consultadas el 21 de noviembre de 2026.
- OpenCode, documentación (instalación), permisos (política por defecto y formato de las reglas), instrucciones (cómo carga
AGENTS.mdyCLAUDE.md), proveedores (/connecty Ollama), modelos de Console, Claude Agent (modelos gratuitos y política de datos de cada uno), changelog (versiones 2.2.3, 2.3.0 y 2.3.2) y página de prensa (licencia y empresa).
Pruebas: ejecutadas el 21 de noviembre de 2026 con OpenCode 2.3.2 (paquete @opencode/cli de npm), los modelos gratuitos opencode/deepseek-v4.1-flash-free y, cuando se acabó su cupo, opencode/beam-free de OpenCode Console, siempre con --standalone, Ollama 0.40.16 con qwen3:4b (en Docker, sin GPU, con 7 GB de memoria y OLLAMA_CONTEXT_LENGTH=65536), Git 2.53.0 y Node.js 24.21.0, en repositorios de prueba sin datos reales. Las salidas están recortadas y las rutas, quitadas.