OpenCode CLI en la práctica: flujos de trabajo, automatización y errores comunes

La interfaz de línea de comandos de OpenCode está diseñada para la creación de scripts, pipelines de CI y la ejecución de agentes sin supervisión. Este artículo es una guía práctica para utilizarlo en el trabajo diario.

Detrás de la CLI existe un sistema de modelos, herramientas, permisos, agentes, habilidades, comandos, sesiones, servidores MCP y una arquitectura cliente/servidor. El agente puede leer y editar archivos del proyecto, buscar en repositorios, ejecutar comandos de shell, llamar a herramientas externas y delegar trabajo en subagentes. El mismo entorno se ejecuta de forma interactiva en la TUI o de forma no interactiva desde scripts.

Para tareas pequeñas, puedes instalarlo, conectar un modelo y empezar a hacer preguntas en cuestión de minutos. Para el trabajo serio, la calidad de la experiencia depende en gran medida de la selección del modelo, las instrucciones del repositorio, los límites de permisos, la gestión del contexto y lo agresivamente que se permita que el agente opere. Este artículo se centra en esa segunda etapa, desde la línea de comandos: qué casos de uso merecen la pena, qué flujos de trabajo de automatización se sostienen en el uso diario y qué problemas aparecen después de que la novedad de una terminal impulsada por IA se desvanezca. Forma parte de la sección de Herramientas de desarrollo con IA de este sitio.

Las observaciones aquí se han contrastado con OpenCode 1.18.9 y la documentación actual en agosto de 2026. OpenCode cambia rápidamente, por lo que los ejemplos de configuración merecen una revisión rápida de la documentación antes de ser copiados en una configuración de equipo de larga vida. Si aún no has instalado OpenCode, la guía rápida de OpenCode cubre la instalación, la verificación y la conexión del proveedor.

Qué es realmente OpenCode: Un entorno de agente, no una caja de chat

OpenCode es un agente de programación con IA de código abierto diseñado alrededor de la terminal. Una vista simplificada de lo que integra es la siguiente:

La parte importante es la capa de permisos entre la intención de un modelo y las acciones que OpenCode puede realizar. Un excelente modelo con malos permisos puede ser peligroso. Un modelo débil con permisos perfectos es simplemente lento y molesto. El uso productivo de OpenCode requiere hacer ambas partes razonablemente correctas.

El mismo entorno sirve para ambas superficies: la TUI interactiva y la línea de comandos no interactiva. Es lo que hace que OpenCode sea programable de una manera en que una interfaz de chat pura no lo es. Si buscas un enfoque deliberadamente minimalista de la misma idea de agente de terminal —cuatro herramientas por defecto, sin sandbox integrado, todo lo demás mediante extensiones—, la reseña del Agente de Código Pi es un contraste útil.

Configuración: Instalación, conexión y por qué la independencia del proveedor importa

OpenCode se instala en una sola línea —script de instalación oficial, npm o Homebrew— y arranca con opencode desde un directorio de repositorio. La guía rápida de OpenCode cubre la matriz de instalación completa (Arch, Windows, Docker), la verificación y la conexión del proveedor (/connect y /models), por lo que este artículo no la repite.

Puedes usar los propios servicios de modelo de OpenCode o conectar proveedores externos compatibles. OpenCode actualmente construye gran parte de su catálogo de proveedores usando Models.dev y admite un amplio rango de configuraciones de modelos comerciales y locales.

La independencia del proveedor es una de las decisiones arquitectónicas más útiles de OpenCode. Tu flujo de trabajo de código no necesita estar acoplado permanentemente a un único proveedor de modelos: puedes usar un modelo para trabajo de arquitectura difícil, otro para tareas de implementación económicas y un modelo local para código que no debería salir de tu entorno.

Esa flexibilidad es real, pero crea otra variable que gestionar. Cuando OpenCode rinde mal, el problema puede ser el arnés, el prompt, el contexto disponible, el modelo seleccionado o la interacción entre los cuatro.

Inicializa el repositorio con AGENTS.md antes de pedir código

Uno de los primeros comandos que vale la pena ejecutar en un nuevo repositorio es:

/init

OpenCode analiza el proyecto y crea un archivo AGENTS.md. Commitea ese archivo.

AGENTS.md es donde las restricciones específicas del repositorio pueden convertirse en contexto duradero para cada conversación —interactiva o scripteada— en lugar de ser repetidas manualmente. Un archivo útil es lo suficientemente corto para permanecer relevante, pero lo suficientemente concreto para prevenir errores previsibles. Por ejemplo:

# Instrucciones del Repositorio

## Arquitectura

- Los manejadores de API están bajo src/api.
- La lógica de negocio pertenece bajo src/services.
- El acceso a la base de datos pertenece bajo src/repositories.
- No llames directamente a clientes de base de datos desde los manejadores HTTP.

## Validación

Después de cambios en TypeScript ejecuta:

```bash
npm run typecheck
npm test
```

Después de cambios en el frontend ejecuta también:

```bash
npm run lint
```

## Restricciones

- No modifiques archivos generados.
- No cambies contratos de API pública sin preguntar primero.
- No crees migraciones de base de datos a menos que se soliciten explícitamente.
- Nunca ejecutes comandos de despliegue.

Esto es menos emocionante que instalar otro servidor MCP, pero suele proporcionar más valor. Los agentes de código fallan sorprendentemente a menudo porque no saben qué restricciones son importantes. Un contrato de repositorio corto elimina parte de esa ambigüedad antes de la primera llamada a la herramienta.

Trabaja desde la línea de comandos con opencode run

La interfaz interactiva recibe la mayor parte de la atención, pero el modo no interactivo de OpenCode cambia considerablemente el rango de flujos de trabajo útiles:

opencode run "Explica la estrategia de manejo de errores en este paquete"

Puedes usar OpenCode desde scripts de shell, trabajos de CI, Makefiles, ejecutores de tareas o automatización local sin entrar manualmente en la TUI cada vez. Por ejemplo, una revisión de diff como comando único:

opencode run \
  "Revisa el diff git actual por corrección y pruebas faltantes. No edites archivos."

O canaliza contexto directamente a una ejecución:

git diff --name-only HEAD~1 |
  opencode run "Inspecciona los archivos cambiados e identifica cambios de comportamiento riesgosos."

En un Makefile, la misma llamada se convierte en un objetivo:

.PHONY: review
review:
	opencode run "Revisa el diff git actual por corrección y pruebas faltantes. No edites archivos."

Dado que una ejecución scripteada no tiene un humano en el prompt, la política de permisos que configures es la única barrera de seguridad entre el modelo y tu entorno. Por eso es que la sección de permisos a continuación importa más para la automatización que para el uso interactivo.

La dirección interesante aquí no es reemplazar scripts deterministas con un LLM. Es insertar razonamiento del modelo en lugares donde la lógica de shell tradicional se vuelve incómoda, manteniendo la validación determinista alrededor de ello.

Los mejores casos de uso de la CLI de OpenCode

OpenCode puede intentar casi cualquier tarea de programación, pero eso no significa que cada tarea deba delegarse de la misma manera. Los flujos de trabajo de mayor valor tienden a tener tres propiedades: el resultado deseado es testeable, el contexto relevante del repositorio puede ser descubierto, y los cambios incorrectos son baratos de inspeccionar o revertir. Cada prompt a continuación funciona en la TUI o como un argumento para opencode run.

1. Exploración de repositorio

OpenCode es excelente para responder preguntas que de otro modo requerirían una secuencia de comandos grep, búsquedas de editor, saltos de archivo y comandos git log. Por ejemplo:

Explica cómo funciona la autenticación en este repositorio.

Rastrea una solicitud desde el middleware HTTP a través de la validación de tokens,
carga de usuario, autorización y el manejador final.

No modifiques nada.

Un buen agente buscará puntos de entrada, seguirá referencias, inspeccionará pruebas y devolverá algo más cercano a una explicación de arquitectura que a una búsqueda de texto simple. Esto es una de las formas más seguras de introducir OpenCode en una base de código existente porque el agente puede proporcionar valor sin escribir código.

2. Reparaciones pequeñas y bien delimitadas

Un bug de alcance estrecho está cerca de la tarea ideal de un agente de código. Por ejemplo:

La CLI termina con estado 0 cuando la validación de configuración falla.

Encuentra la ruta de código responsable, añade una prueba de regresión, implementa
la reparación más pequeña posible y ejecuta las pruebas relevantes.

No refactorices código no relacionado.

La frase clave no es “repara el bug”. Son las restricciones que rodean la tarea. OpenCode funciona mejor cuando el éxito puede demostrarse con una prueba, un compilador o un comando observable. Requisitos vagos dan al modelo margen para crear código plausible en lugar de código demostrablemente correcto.

3. Generación de pruebas tras la implementación

Las pruebas son trabajo útil para agentes porque la implementación existente le da a OpenCode algo concreto sobre lo que razonar. Un prompt productivo podría ser:

Revisa src/parser.ts y sus pruebas existentes.

Identifica casos límite importantes que actualmente no están cubiertos.
Añade solo pruebas. No modifiques la implementación.

Ejecuta la suite de pruebas del parser al terminar.

Separar la generación de pruebas de la implementación es importante. Si el mismo agente escribe tanto la funcionalidad como las pruebas en un paso no restringido, puede accidentalmente crear pruebas que validan su propia interpretación en lugar del comportamiento previsto.

4. Refactorización mecánica

OpenCode es muy bueno en transformaciones repetitivas donde el estado final deseado es claro. Ejemplos incluyen:

• reemplazar una API obsoleta en todo un repositorio;
• convertir código repetido en un helper compartido;
• renombrar un campo de configuración;
• migrar pruebas de un patrón de afirmación a otro;
• actualizar importaciones tras mover un paquete;
• reemplazar una abstracción de registro obsoleta.

El compilador y las pruebas del repositorio se convierten en el bucle de retroalimentación del agente. Un patrón útil es:

Reemplaza los usos de LegacyResult<T> con Result<T, AppError> solo en
packages/api.

Preserva el comportamiento de tiempo de ejecución.

Trabaja en lotes pequeños. Después de cada lote ejecuta la verificación de tipos del paquete.
Al final ejecuta la suite de pruebas del paquete y muéstrame el resumen del diff git final.

Esto es a menudo más fiable que pedir la migración entera en un paso enorme.

5. Revisión de código

OpenCode se vuelve mucho más útil cuando la revisión se trata como un rol de agente separado en lugar de otro prompt enviado al mismo contexto de edición. Puedes crear un agente orientado a la revisión que no pueda editar archivos. Luego dale instrucciones como:

Revisa el diff git actual.

Céntrate en:
- corrección;
- seguridad;
- concurrencia;
- pruebas faltantes;
- manejo de errores;
- cambios accidentales de API.

No resumas archivos que no han cambiado.
Clasifica los hallazgos por severidad.

Un revisor de solo lectura es útil incluso si otro agente de código produjo los cambios. La separación es valiosa porque la implementación y la crítica son tareas diferentes: un agente que acaba de gastar varios miles de tokens defendiendo un enfoque a menudo es menos escéptico de ese enfoque que un revisor nuevo.

Usa los modos Plan y Build como modos mentales diferentes

OpenCode proporciona agentes primarios y subagentes, con flujos de trabajo integrados que incluyen comportamiento orientado a la planificación y a la implementación. Incluso cuando la configuración exacta del agente cambia con el tiempo, la separación conceptual permanece útil.

La planificación debería responder preguntas como:

• ¿Qué archivos importan?
• ¿Qué patrones existentes deberían seguirse?
• ¿Qué podría romperse?
• ¿Cómo verificaremos el cambio?
• ¿El cambio solicitado es realmente local?

La implementación debería suceder solo después de que esas preguntas tengan respuestas razonables. Para tareas sustanciales, prefiero una secuencia de prompts como esta:

Primero investiga la solicitud.

No edites archivos todavía.

Devuelve:
1. los archivos relevantes;
2. el comportamiento actual;
3. el cambio propuesto;
4. riesgos;
5. los comandos exactos de verificación.

La misma secuencia funciona como comando único:

opencode run "Primero investiga la solicitud. No edites archivos todavía. Devuelve: los archivos relevantes; el comportamiento actual; el cambio propuesto; riesgos; los comandos exactos de verificación."

Luego inspecciona el plan antes de permitir ediciones. Esto se siente más lento que decir inmediatamente a un agente que “implántalo”, pero los fallos costosos en la codificación agéntica suelen provenir de suposiciones incorrectas hechas antes de la primera edición.

Esta es una versión ligera, por tarea, del mismo instinto que está detrás del desarrollo guiado por especificaciones: acordar el plan antes de que el agente comience a editar. Para trabajo que abarca múltiples archivos, sesiones o colaboradores, una especificación escrita justifica su sobrecarga de una manera que un único prompt de investigar-primero no puede; la comparación de GitHub Spec Kit vs Kiro vs Claude Code cubre flujos de trabajo SDD estructurados que van más allá de un único prompt.

Los subagentes son útiles, pero la delegación no es gratuita

OpenCode puede invocar subagentes especializados automáticamente o mediante menciones explícitas. Por ejemplo:

@general encuentra dónde se implementa el comportamiento de reintento

También puedes definir subagentes dedicados para trabajos como revisión de seguridad, análisis de dependencias, pruebas de frontend o documentación. El mismo patrón funciona en otros arneses; la guía de subagentes de Claude Code cubre el diseño análogo del lado de Anthropic.

Esto es poderoso porque el trabajo del subagente puede permanecer fuera de la ruta de razonamiento inmediata de la conversación principal. Un agente primario puede delegar la exploración del repositorio y consumir el resultado en lugar de llenar su propio contexto con cada búsqueda intermedia. Pero los subagentes crean tres costos menos obvios:

1. Consumen tokens. Un árbol de agentes que cada uno vuelve a leer el repositorio puede volverse sorprendentemente costoso —mi informe de experiencia con Oh My Opencode documenta lo que sucede cuando esa sobrecarga se lleva al extremo.
2. Crean complejidad de política. Los permisos deben considerarse para el agente delegado, no solo para el padre.
3. La delegación puede ocultar el razonamiento. Cuando el agente primario dice “el subagente encontró X”, puede que necesites inspeccionar la sesión hija para entender cuán confiable es realmente esa conclusión.

Para la mayoría de las tareas de código, dos o tres agentes con propósito son más útiles que una empresa de software ficticia elaborada viviendo dentro de tu terminal.

Si la tarea realmente necesita un orquestador completo que delegue a un roster fijo de especialistas —ejecución de fondo paralela, fases de planificación e investigación, enrutamiento de modelos por rol—, ese es un producto diferente construido sobre estos primitivos, no un prompt más grande. La [guía rápida de Oh My Opencode](https://www.glukhov.org/es/ai-devtools/opencode/oh-my-opencode/ “Guía Rápida de Oh My Opencode para OpenCode: Instalar, Configurar, Ejecutar”}) cubre ese arnés.

Usa agentes personalizados como límites de permisos

Los agentes de OpenCode pueden tener prompts, modelos y permisos separados. Eso hace que los agentes sean útiles como límites de seguridad y flujo de trabajo, no meramente diferentes personalidades. Por ejemplo, un agente de revisión local al proyecto puede definirse como un archivo Markdown:

---
description: Revisa código sin modificar el repositorio
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git status *": allow
    "git log *": allow
  webfetch: deny
---

Revisa el código por corrección, seguridad, mantenibilidad,
cambios de comportamiento inesperados y pruebas faltantes.

No modifiques archivos.

Esto es mucho mejor que escribir “por favor no edites nada” en prosa. Las instrucciones influyen en el modelo. Los permisos restringen la herramienta. Esos no son controles equivalentes.

Configura los permisos de OpenCode desde el primer día

Una de las características prácticas más importantes de OpenCode es que sus valores predeterminados normales son permisivos. Eso es conveniente durante una demostración y no necesariamente lo que quiero en una estación de trabajo que contiene claves SSH, credenciales de producción, tokens de publicación de paquetes, contextos de Kubernetes y acceso a varias cuentas de la nube. Para trabajos no atendidos de opencode run, las apuestas son aún más altas: nada detiene una ejecución excepto la política que configures.

El modelo de permisos actual de OpenCode soporta:

allow
ask
deny

Las reglas pueden aplicarse al acceso a archivos, ediciones, comandos de shell, operaciones web, subagentes, habilidades, directorios externos y otras categorías de herramientas. Un punto de partida conservador podría parecerse a esto:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git log *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

Las reglas exactas deberían coincidir con tu entorno. Lo que importa es hacer la política intencional en lugar de descubrir el valor predeterminado después de que el agente ya haya ejecutado algo sorprendente.

No confundas las solicitudes de aprobación con el sandboxing

Las reglas de permisos son útiles, pero no son lo mismo que el aislamiento del sistema operativo. Si OpenCode tiene permiso para ejecutar un comando de shell permitido, ese proceso se ejecuta con el acceso disponible en tu entorno. Un agente de código puede potencialmente interactuar con archivos, servicios de red, variables de entorno, credenciales, sockets, gestores de paquetes y otras herramientas de desarrollo. La guía rápida de la CLI de OpenHands es el equivalente en sandbox: un espacio de trabajo Docker, un modo headless que siempre aprueba y la transición de Agent Canvas que el proyecto OpenHands documenta ahora.

Para repositorios sensibles o ejecuciones no atendidas, vale la pena considerar un aislamiento más fuerte:

Git es reintegro. Los permisos son política. Un contenedor o VM es aislamiento. Esos son tres niveles diferentes.

Convierte prompts repetitivos en comandos personalizados

Si repites las mismas instrucciones una y otra vez, probablemente deberían de dejar de ser historial de chat y convertirse en configuración. OpenCode soporta comandos slash personalizados de proyecto y globales para la interfaz interactiva. Por ejemplo, crea:

.opencode/commands/review.md

con:

---
description: Revisa los cambios actuales
agent: plan
---

Revisa el diff git actual.

Busca:
- bugs;
- problemas de seguridad;
- manejo de errores incompleto;
- pruebas faltantes;
- cambios accidentales de API.

No modifiques archivos.

Luego usa:

/review

Esto es una función pequeña con valor desproporcionado. Los flujos de trabajo de agentes de código fiables emergen cuando los buenos prompts se convierten en infraestructura compartida del proyecto en lugar de fragmentos personales del portapapeles. Otros comandos de proyecto útiles podrían incluir:

/test-changes
/review
/prepare-pr
/check-migration
/update-docs
/release-check

Usa habilidades para flujos de trabajo reutilizables

OpenCode también soporta archivos SKILL.md. Las habilidades son útiles cuando un flujo de trabajo necesita más que un único prompt. Una habilidad puede contener guías operativas detalladas y archivos de soporte mientras permanece sin cargar hasta que el agente realmente la necesite. Candidatos útiles incluyen:

• procedimientos de migración de base de datos;
• flujos de trabajo de lanzamiento;
• investigación de incidentes;
• revisiones de compatibilidad de API;
• publicación de paquetes;
• validación de infraestructura;
• convenciones de arquitectura interna.

Por ejemplo:

.opencode/skills/database-migration/SKILL.md

Una descripción de habilidad podría decirle a OpenCode cuándo se aplica el procedimiento, mientras que el cuerpo explica cómo inspeccionar esquemas, crear migraciones, validar el comportamiento de reintegro y ejecutar pruebas de integración. Si ya usas el concepto equivalente en otro arnés, la [guía de habilidades de Claude para desarrolladores](https://www.glukhov.org/es/ai-devtools/claude-code/claude-skills-for-developers/ “Habilidades de Claude explicadas: estructura de SKILL.md, disposición de carpetas, mejores prácticas, pruebas y solución de problemas.”}) mapea las mismas decisiones de diseño.

La ventaja es la disciplina del contexto. Volcar cada regla organizativa en AGENTS.md eventualmente crea un prompt de sistema gigante que es costoso y cada vez más fácil para el modelo de ignorar. Las habilidades permiten que las instrucciones especializadas entren en el contexto solo cuando se necesitan.

MCP: Útil hasta que el catálogo de herramientas se convierte en el problema

OpenCode soporta servidores MCP locales y remotos. Eso puede exponer gestores de problemas, sistemas de documentación, navegadores, plataformas de observabilidad, bases de datos, APIs y otras herramientas al agente de código. Una configuración típica podría proporcionar un servidor de documentación:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

MCP es una de esas funciones que es fácil de sobrecargar. Cada herramienta que el agente debe entender consume atención y frecuentemente tokens de contexto. Una configuración con quince servidores MCP puede parecer poderosa en una captura de pantalla de configuración mientras hace el comportamiento real del modelo más lento, más costoso y menos predecible.

Mi regla es simple: si una herramienta no es útil en una semana normal de trabajo, probablemente no debería habilitarse globalmente. Carga herramientas porque un flujo de trabajo las requiere, no porque la integración exista.

Modelos locales en OpenCode: Una opción real, no una solución mágica

Uno de los casos de uso más fuertes de OpenCode es su capacidad para trabajar con puntos finales de modelos OpenAI-compatibles locales o autoalojados. Esto es atractivo cuando:

• el código fuente debe permanecer local;
• los costos de API son significativos;
• ya operas infraestructura de GPU;
• quieres experimentar con modelos abiertos;
• la conectividad a internet es poco fiable;
• el enrutamiento de modelos es parte de tu plataforma.

Un proveedor personalizado puede apuntar OpenCode a un punto final local como LM Studio, llama.cpp mediante llama-server, vLLM, infraestructura compatible con Ollama u otro servidor OpenAI-compatible.

Aquí es donde importan las expectativas. Un buen arnés de código no puede compensar completamente un modelo que es débil en el uso de herramientas, planificación a largo plazo, razonamiento de código o retención de instrucciones. Las discusiones comunitarias sobre configuraciones locales de OpenCode convergen repetidamente en la misma observación: los modelos locales pueden ser excelentes para tareas delimitadas, pero los más pequeños a menudo necesitan más supervisión. Para cifras medidas sobre cómo se comportan modelos específicos dentro de OpenCode, mira mi comparación práctica de LLMs para OpenCode.

La solución práctica es el enrutamiento de modelos por complejidad de la tarea. Usa un modelo más barato o local para:

• búsqueda de repositorio;
• documentación;
• pruebas simples;
• ediciones repetitivas;
• cambios de formato;
• reparaciones de bugs sencillas.

Usa un modelo más fuerte para:

• cambios de arquitectura;
• bugs ambiguos;
• refactorizaciones entre paquetes;
• concurrencia;
• código sensible a la seguridad;
• migraciones difíciles.

La independencia del proveedor hace posible esta estrategia. No hace irrelevante la calidad del modelo.

Un flujo de trabajo diario práctico con OpenCode

Mi flujo de trabajo preferido es deliberadamente conservador. Funciona igual en la TUI o vía opencode run; donde un paso es un prompt, la variante de línea de comandos se muestra junto a ella.

Paso 1: Comienza desde un estado Git limpio

git status

Commitea los cambios existentes o registra deliberadamente lo que ya está modificado. Un agente de código IA operando dentro de un árbol de trabajo sucio hace que la revisión sea mucho más difícil porque los cambios humanos y los cambios del agente se mezclan entre sí.

Paso 2: Pide primero una investigación

Investiga el problema #482.

No modifiques archivos.

Explica:
- el comportamiento actual;
- la causa probable;
- archivos relevantes;
- pruebas existentes;
- reparación propuesta;
- comandos de verificación.

El mismo prompt como comando único:

opencode run "Investiga el problema #482. No modifiques archivos. Explica el comportamiento actual, la causa probable, los archivos relevantes, las pruebas existentes, la reparación propuesta y los comandos de verificación."

Si la investigación es incorrecta, corregirla es barato.

Paso 3: Acota la implementación

Implementa solo la reparación propuesta.

No refactorices código no relacionado.
Añade la prueba de regresión primero.
Ejecuta la suite de pruebas relevante más pequeña después del cambio.

O de forma no interactiva:

opencode run "Implementa solo la reparación propuesta. No refactorices código no relacionado. Añade la prueba de regresión primero. Ejecuta la suite de pruebas relevante más pequeña después del cambio."

El agente ahora tiene un espacio de decisión más pequeño.

Paso 4: Inspecciona el diff tú mismo

git diff --stat
git diff

No externalices este paso completamente a otro modelo. Estás comprobando no solo si el código se ve plausible, sino si el agente cambió archivos que no necesitaba tocar.

Paso 5: Ejecuta verificación determinista

npm run typecheck
npm test
npm run lint

Usa los comandos reales del proyecto. “OpenCode dice que las pruebas pasan” no es evidencia más fuerte que tu terminal mostrando un proceso de prueba exitoso.

Paso 6: Ejecuta una revisión independiente

Pide a un agente de solo lectura:

Revisa el diff sin commitear como si fuera una solicitud de extracción escrita
por otro ingeniero.

Intenta encontrar razones por las que esta implementación es incorrecta.

No edites archivos.

La variante de línea de comandos:

opencode run "Revisa el diff sin commitear como si fuera una solicitud de extracción escrita por otro ingeniero. Intenta encontrar razones por las que esta implementación es incorrecta. No edites archivos."

La frase “intenta encontrar razones por las que esto está mal” es intencional. Los modelos son muy buenos para confirmar cortésmente trabajo plausible. Los prompts de revisión deberían fomentar la falsación en lugar de los aplausos.

Paso 7: Commitea solo después de que el diff tenga sentido

git add -p
git commit

Aún prefiero la etapa de staging interactiva después de los cambios generados por el agente. Fuerza un último paso humano a través de cada hunk que se convierte en parte del historial del repositorio.

Dónde OpenCode se vuelve frustrante: Puntos débiles comunes

Las limitaciones interesantes no son usualmente “la IA cometió un error de sintaxis”. Los compiladores son buenos para atrapar esos. Los problemas difíciles provienen de la autonomía, el contexto, las suposiciones ocultas y la configuración.

Desafío 1: La calidad del modelo domina la experiencia

El mismo flujo de trabajo de OpenCode puede sentirse excelente con un modelo y casi inutilizable con otro. Esto hace que las reseñas de producto sean difíciles porque los usuarios a menudo atribuyen el comportamiento del modelo al arnés del agente.

Si OpenCode repetidamente:

• ignora instrucciones;
• reescribe demasiado código;
• llama incorrectamente a herramientas;
• se atasca en la misma acción fallida;
• pierde el rastro de las restricciones;
• inventa APIs;

prueba otro modelo antes de rediseñar toda la configuración de OpenCode. La terminal no se volvió repentinamente más inteligente. El modelo sí.

Desafío 2: Las sesiones largas acumulan contexto malo

Las sesiones de agentes de código se vuelven menos confiables a medida que se acumulan suposiciones incorrectas. Un error temprano como “este servicio es sin estado” puede influir en docenas de decisiones posteriores incluso después de que los archivos relevantes hayan cambiado.

OpenCode soporta compactación para gestionar los límites de contexto, pero la compresión crea su propio compromiso. Un resumen necesariamente decide qué detalles sobreviven. Para transiciones de tareas importantes, comenzar una sesión nueva suele ser más limpio que continuar una conversación heroica de 80,000 tokens. Con ejecuciones scripteadas la respuesta es aún más simple: una nueva opencode run comienza con un contexto limpio cada vez, por lo que el estado de larga vida pertenece a archivos como AGENTS.md, no a una conversación.

El contexto no es memoria gratuita. Es estado de trabajo, y el estado de trabajo se vuelve obsoleto.

Desafío 3: Los permisos pueden volverse engañosamente complicados

Las reglas simples son fáciles:

read -> allow
edit -> ask
git push -> deny

Las jerarquías de agentes complejas son más difíciles. Una vez que los agentes primarios pueden invocar subagentes, herramientas personalizadas, servidores MCP y comandos de shell, necesitas razonar sobre las capacidades efectivas de todo el flujo de trabajo en lugar de una línea de configuración.

También ha habido discusiones reales de la comunidad y de GitHub sobre el comportamiento de permisos de los subagentes y la herencia de permisos. La lección es más amplia que cualquier bug individual: prueba las suposiciones de seguridad con un repositorio desechable real —por ejemplo, git init /tmp/opencode-perm-test e intenta hacer que el agente ejecute un comando que hayas denegado allí. Si una acción absolutamente no debe ocurrir, no confíes solo en instrucciones en prosa.

Desafío 4: OpenCode cambia rápidamente

OpenCode ha lanzado a un ritmo notable. Eso es bueno para las funciones y menos agradable para la longevidad de la documentación. Una trampa particularmente fácil en 2026 es encontrar ejemplos de configuración de una generación diferente de OpenCode. La documentación actual también contiene material separado de V2 cuyo esquema de configuración difiere de la sintaxis establecida de 1.x. Por ejemplo, los conceptos de permisos pueden aparecer bajo nombres de campos diferentes en la documentación de V2.

No combines casualmente ejemplos de:

/docs/

y:

/v2/docs/

sin comprobar qué tiempo de ejecución estás usando realmente. Al depurar una configuración copiada de una publicación en un blog, verifica su fecha de publicación antes de asumir que OpenCode está roto.

Desafío 5: La TUI puede ocultar la escala

Una interfaz conversacional hace que un cambio de diez archivos se sienta más pequeño que un cambio de diez archivos. El agente puede reportar:

Implementado la nueva validación y actualizadas las pruebas relevantes.

Esa frase podría representar tres líneas o 600 líneas. Mantén cerca herramientas de shell independientes:

git status --short
git diff --stat
git diff --name-only
git diff

El agente de código no debería ser la única interfaz a través de la cual observas el agente de código.

Desafío 6: MCP puede destruir la eficiencia del contexto

Más integraciones no producen automáticamente un mejor agente de código. Grandes servidores MCP pueden exponer muchos esquemas de herramientas, cada uno consumiendo contexto del modelo e incrementando la complejidad de selección de herramientas. Si OpenCode se siente extrañamente indeciso después de que instalaste la mitad del ecosistema MCP, deshabilita la mayor parte de ello y compara. Una superficie de herramientas más pequeña a menudo produce un mejor comportamiento del agente.

Desafío 7: La privacidad local requiere verificar toda la ruta

Ejecutar un modelo local no garantiza automáticamente que cada parte de una cadena de herramientas sea local. Las discusiones comunitarias a principios de 2026 plantearon preguntas de privacidad sobre el comportamiento del modelo auxiliar de OpenCode y la arquitectura de la interfaz web. Algunas de esas afirmaciones se referían a versiones anteriores, algunas fueron disputadas, y algunas rutas de código han cambiado desde entonces.

La lección duradera no es “OpenCode envía todo a algún lugar”. La lección duradera es: si la operación solo local es un requisito duro, verifícala. Usa inspección de red, lee la configuración actual, entiende qué interfaz estás usando, deshabilita integraciones remotas innecesarias y prueba la versión exacta que pretendes desplegar. Los requisitos de seguridad deben ser validados, no inferidos de una categoría de producto.

OpenCode vs Claude Code y Codex CLI

El diferenciador más fuerte de OpenCode no es necesariamente la calidad de codificación. El modelo subyacente aún contribuye en gran medida a la calidad de codificación. Su diferenciador es el control sobre el arnés.

OpenCode es convincente cuando valoras:

• una implementación de código abierto;
• flexibilidad de proveedor;
• flujos de trabajo centrados en la terminal;
• agentes configurables;
• permisos granulares;
• soporte de modelos locales;
• MCP;
• comandos y habilidades reutilizables;
• arquitectura cliente/servidor.

Claude Code es convincente cuando quieres una experiencia Anthropic fuertemente integrada con un comportamiento de modelo de primera parte fuerte y flujos de trabajo de agente integrados cada vez más pulidos. Codex CLI es convincente cuando tus modelos y flujo de trabajo preferidos ya están centrados en la pila de codificación de OpenAI.

No elegiría entre ellos contando funciones. Elige basado en qué capa quieres poseer. Si quieres que un proveedor tome la mayoría de las decisiones de flujo de trabajo, un agente de código de primera parte puede ser atractivo. Si quieres que el arnés permanezca reemplazable mientras experimentas con proveedores y configuraciones de agente, OpenCode hace un argumento más fuerte.

Qué Reddit y Hacker News aciertan sobre OpenCode

Las discusiones comunitarias sobre OpenCode son inusualmente polarizadas. Algunos desarrolladores lo describen como su arnés de código favorito, especialmente cuando se combina con modelos Codex, modelos locales o configuraciones de agentes personalizados. Otros se centran en el uso de recursos, el comportamiento de permisos, preguntas de privacidad, cambios en la autenticación del proveedor o la complejidad que aparece una vez que una aplicación de terminal aparentemente simple se convierte en infraestructura. Ambas perspectivas son razonables.

OpenCode no es difícil porque la línea de comandos sea difícil. Es difícil porque un entorno de codificación autónomo expone preguntas que los desarrolladores previamente no necesitaban responder explícitamente:

• ¿Qué modelo debería tomar esta decisión?
• ¿Qué archivos puede leer?
• ¿Qué comandos puede ejecutar?
• ¿Qué credenciales puede ver el proceso?
• ¿Qué tareas deberían convertirse en subagentes?
• ¿Cuánto contexto debería sobrevivir?
• ¿Qué herramientas merecen contexto permanente?
• ¿Qué resultado debe un humano verificar?

Un producto cerrado pulido puede tomar muchas de esas decisiones por ti. OpenCode hace más de ellas tuyas. Es precisamente por eso que a los usuarios avanzados les gusta.

Una configuración inicial que recomendaría

Me resistiría a construir una configuración elaborada de inmediato. Comienza con:

1. un modelo predeterminado fuerte;
2. un AGENTS.md;
3. permisos conservadores de shell y edición;
4. un agente de revisión de solo lectura;
5. dos o tres comandos personalizados;
6. sin servidores MCP hasta que aparezca una necesidad real.

Un entorno simple es más fácil de depurar. Una vez que un flujo de trabajo se vuelve repetitivo, promuévelo a un comando, habilidad o agente. Una vez que una capacidad se vuelve riesgosa, restringela con permisos. Una vez que el contexto se vuelve hinchado, divide el flujo de trabajo en lugar de simplemente comprar una ventana de contexto más grande. Este enfoque incremental es menos impresionante en capturas de pantalla y considerablemente más agradable de mantener.

Quién debería usar OpenCode

OpenCode es un ajuste particularmente bueno para desarrolladores que ya viven en terminales y quieren que su agente de código se comporte como otra herramienta de desarrollo programable. Lo consideraríamos fuertemente si:

• trabajas a través de múltiples proveedores de LLM;
• quieres soporte de modelos locales;
• despreciás estar bloqueado a un único proveedor de IA;
• necesitas agentes específicos del proyecto;
• automatizas tareas de desarrollo desde scripts de shell;
• quieres inspeccionar o modificar el arnés de código;
• ya entiendes Git y las herramientas de CLI normales.

Es menos convincente si principalmente quieres una capa de IA invisible dentro de una IDE. OpenCode también espera más juicio operativo que una herramienta de autocompletado tradicional. Si revisar diffs, entender comandos de shell y gestionar ramas de Git ya se sienten incómodos, dar a un proceso autónomo acceso a esas herramientas no hará que la complejidad subyacente desaparezca.

Veredicto Final

OpenCode es uno de los ejemplos más convincentes de una herramienta de código IA volviéndose infraestructura de desarrollo en lugar de meramente una interfaz de chat. Sus mejores funciones no son llamativas. La independencia del proveedor, los permisos explícitos, los agentes reutilizables, la ejecución no interactiva, las instrucciones del repositorio, los comandos, las habilidades y las herramientas componibles hacen posible moldear el agente alrededor de un flujo de trabajo de ingeniería real.

La debilidad es la imagen especular de esa fortaleza. OpenCode te da suficiente control para crear un entorno de código disciplinado, pero también te da suficiente control para crear un enjambre complicado, costoso y pobremente aislado de agentes con veinte servidores MCP y sin una frontera de verificación clara.

No optimizaría OpenCode para la autonomía máxima. Lo optimizaría para bucles de retroalimentación cortos. Dale un problema delimitado, suficiente contexto para entender el problema, permiso para realizar solo las acciones necesarias y comandos deterministas que puedan probar si el resultado funciona. Eso es menos mágico que pedirle a un agente que construya una aplicación entera mientras duermes. También está mucho más cerca de cómo OpenCode se vuelve genuinamente útil.

Referencias

• Documentación de OpenCode: https://opencode.ai/docs/
• Registro de cambios de OpenCode: https://opencode.ai/changelog
• Repositorio de GitHub de OpenCode: https://github.com/anomalyco/opencode
• Catálogo de proveedores de Models.dev: https://models.dev