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

OpenCode desde la línea de comandos, en la práctica

Índice

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 su uso en el trabajo diario.

Detrás de la CLI se encuentra 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 funciona de manera interactiva en la TUI o de forma no interactiva desde scripts.

OpenCode CLI como un entorno de agente de codificación programable

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 la agresividad con la que permitas operar al agente. Este artículo se centra en esa segunda etapa, desde la línea de comandos: qué casos de uso son rentables, qué flujos de trabajo de automatización funcionan en el uso diario y qué problemas aparecen cuando la novedad de una terminal impulsada por IA se desvanece. Es parte de la sección Herramientas de desarrollo con IA de este sitio.

Las observaciones aquí fueron verificadas contra 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 rápida verificación de la documentación antes de ser copiados en una configuración de equipo a largo plazo. Si aún no has instalado OpenCode, el Inicio rápido 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 codificación de IA de código abierto diseñado en torno a la terminal. Una visión simplificada de lo que integra es la siguiente:

flowchart TD U[Desarrollador] --> T[OpenCode CLI o TUI] T --> A[Agente Primario] A --> M[LLM Seleccionado] A --> F[Herramientas de Archivos] A --> S[Shell] A --> W[Herramientas Web] A --> L[LSP e Inteligencia de Código] A --> X[Herramientas MCP] A --> C[Habilidades y Comandos] A --> G[Subagentes] F --> R[Repositorio] S --> R L --> R G --> M P[Reglas de Permiso] --> A I[AGENTS.md] --> A

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

El mismo entorno sirve para ambas superficies: la TUI interactiva y la línea de comandos no interactiva. Eso es lo que hace que OpenCode sea scripteable de una manera en la que una interfaz de chat pura no lo es. Si quieres una toma deliberadamente minimalista de la misma idea de agente de terminal —cuatro herramientas predeterminadas, sin sandbox integrado, todo lo demás mediante extensiones—, la reseña de Pi Coding Agent es un contraste útil.

Configuración: Instalar, conectar y por qué la independencia del proveedor importa

OpenCode se instala en una línea —script de instalación oficial, npm o Homebrew— y se inicia con opencode desde un directorio de repositorio. El Inicio rápido 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 lo repite.

Puedes usar los propios servicios de modelos de OpenCode o conectar proveedores externos compatibles. OpenCode actualmente construye gran parte de su catálogo de proveedores usando Models.dev y admite una amplia gama 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 codificación no necesita estar acoplado permanentemente a un solo proveedor de modelos: puedes usar un modelo para trabajos difíciles de arquitectura, otro para tareas de implementación baratas y un modelo local para código que no debería salir de tu entorno.

Esa flexibilidad es real, pero crea otra variable a 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 repositorio nuevo 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 un 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 predecibles. 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 a clientes de base de datos directamente desde los manejadores HTTP.

## Validación

Después de los cambios en TypeScript ejecuta:

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

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

```bash
npm run lint
```

## Restricciones

- No modifiques archivos generados.
- No cambies los contratos de la 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 generalmente proporciona más valor. Los agentes de codificación 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 un comando de un solo uso:

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

O canaliza el 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 una meta:

.PHONY: review
review:
	opencode run "Revisa el git diff 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 el único guardarrail entre el modelo y tu entorno. Por eso 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 los scripts deterministas con un LLM. Es insertar el razonamiento del modelo en lugares donde la lógica tradicional de shell se vuelve engorrosa, manteniendo la validación determinista alrededor.

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 ser delegada 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 argumento para opencode run.

1. Exploración del repositorio

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

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

Traza 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 un recorrido de arquitectura que a una búsqueda de texto simple. Esta 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. Correcciones pequeñas y bien delimitadas

Un error estrechamente acotado está cerca de la tarea ideal para un agente de codificación. Por ejemplo:

La CLI sale 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 corrección más pequeña y ejecuta las pruebas relevantes.

No refactorices código no relacionado.

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

3. Generación de pruebas después de la implementación

Las pruebas son un 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 función como las pruebas en un paso sin restricciones, puede crear accidentalmente 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. Los ejemplos incluyen:

  • reemplazar una API obsoleta en todo el repositorio;
  • convertir código repetido en un helper compartido;
  • renombrar un campo de configuración;
  • migrar pruebas de un patrón de aserción a otro;
  • actualizar importaciones después de 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> en
packages/api solo.

Preserva el comportamiento en tiempo de ejecución.

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

Esto es a menudo más confiable que pedir toda la migración 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 git diff actual.

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

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

Un revisor de solo lectura es útil incluso si otro agente de codificación 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 debe responder preguntas como:

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

La implementación debe ocurrir 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. los riesgos;
5. los comandos de verificación exactos.

La misma secuencia funciona como un comando de un solo uso:

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

Luego inspecciona el plan antes de permitir ediciones. Esto se siente más lento que decirle inmediatamente a un agente que “implemente”, 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 detrás del desarrollo dirigido por especificaciones: acordar el plan antes de que el agente empiece a editar. Para el trabajo que abarca múltiples archivos, sesiones o contribuyentes, una especificación escrita gana su sobrecoste de una manera que un solo 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 solo prompt.

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

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 en el lado de Anthropic.

Esto es poderoso porque el trabajo de los subagentes 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”, es posible que necesites inspeccionar la sesión del hijo para entender qué tan confiable es realmente esa conclusión.

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

Si la tarea realmente necesita un orquestador completo delegando a un equipo 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 estas primitivas, no un prompt más grande. El Inicio rápido de Oh My Opencode 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 solo como personalidades diferentes. Por ejemplo, un agente de revisión local del 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 supervisados de opencode run, las apuestas son aún mayores: nada detiene una ejecución excepto la política que configures.

El modelo de permisos actual de OpenCode admite:

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 verse así:

{
  "$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 deben coincidir con tu entorno. Lo importante es hacer que la política sea 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 codificación puede potencialmente interactuar con archivos, servicios de red, variables de entorno, credenciales, sockets, gestores de paquetes y otras herramientas de desarrollo.

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

flowchart TD H[Estación de trabajo del host] --> B[Contenedor o VM restringida] B --> O[OpenCode] O --> R[Copia del Repositorio] O --> T[Herramientas de Compilación y Pruebas] O --> K[Credenciales de Modelo Limitadas] P[Sin Credenciales de Producción] --> B N[Acceso a Red Restringido] --> B

Git es retroceso. Los permisos son política. Un contenedor o VM es aislamiento. Esas son tres capas diferentes.

Convierte los prompts repetitivos en comandos personalizados

Si escribes repetidamente las mismas instrucciones, probablemente deberían dejar de ser historial de chat y convertirse en configuración. OpenCode admite 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 git diff actual.

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

No modifiques archivos.

Luego usa:

/review

Esta es una característica pequeña con un valor desproporcionado. Los flujos de trabajo confiables de agentes de codificación emergen cuando los buenos prompts se convierten en infraestructura de proyecto compartida 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 admite archivos SKILL.md. Las habilidades son útiles cuando un flujo de trabajo necesita más que un solo 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

La descripción de una 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 reversión 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/ “Explicación de habilidades de Claude: 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 de contexto. Volcar cada regla organizacional 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 sea necesario.

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

OpenCode admite 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 codificación. 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 características que es fácil de usar en exceso. Cada herramienta que el agente debe entender consume atención y frecuentemente tokens de contexto. Una configuración con quince servidores MCP puede verse poderosa en una captura de pantalla de configuración mientras hace que el comportamiento real del modelo sea 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 estar habilitada globalmente. Carga herramientas porque un flujo de trabajo las requiere, no porque la integración existe.

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 de acceso de modelos locales o autoalojados compatibles con OpenAI. Esto es atractivo cuando:

  • el código fuente debe permanecer local;
  • los costos de la API son significativos;
  • ya operas infraestructura 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 a OpenCode a un punto de acceso local como LM Studio, llama.cpp mediante llama-server, vLLM, infraestructura compatible con Ollama u otro servidor compatible con OpenAI.

Es aquí donde las expectativas importan. Un buen arnés de codificación no puede compensar completamente un modelo que es débil en el uso de herramientas, la planificación de largo plazo, el razonamiento de código o la retención de instrucciones. Las discusiones comunitarias en torno a configuraciones locales de OpenCode convergen repetidamente en la misma observación: los modelos locales pueden ser excelentes para tareas acotadas, pero los más pequeños a menudo necesitan más supervisión. Para números medidos sobre cómo se comportan realmente modelos específicos dentro de OpenCode, consulta 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 en el repositorio;
  • documentación;
  • pruebas simples;
  • ediciones repetitivas;
  • cambios de formato;
  • correcciones de errores directas.

Usa un modelo más fuerte para:

  • cambios de arquitectura;
  • errores 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 de la misma manera en la TUI o mediante opencode run; donde un paso es un prompt, se muestra la variante de línea de comandos junto a él.

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 codificación de 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 la investigación

Investiga el problema #482.

No modifiques archivos.

Explica:
- el comportamiento actual;
- la causa raíz probable;
- los archivos relevantes;
- las pruebas existentes;
- la corrección propuesta;
- los comandos de verificación.

El mismo prompt como un comando de un solo uso:

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

Si la investigación está equivocada, corregirla es barato.

Paso 3: Acota la implementación

Implementa solo la corrección propuesta.

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

O no interactivamente:

opencode run "Implementa solo la corrección propuesta. No refactorices código no relacionado. Añade la prueba de regresión primero. Ejecuta la suite de pruebas más pequeña relevante 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 la 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 está equivocada.

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 está equivocada. 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 el trabajo plausible. Los prompts de revisión deberían alentar la falsificació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 creación de etapas interactiva después de los cambios generados por el agente. Fuerza un último paso humano a través de cada fragmento que se convierte en parte del historial del repositorio.

Dónde OpenCode se vuelve frustrante: Errores comunes

Las limitaciones interesantes no suelen ser “la IA hizo un error de sintaxis”. Los compiladores son buenos para capturar 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 a herramientas incorrectamente;
  • entra en bucles con 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 lo hizo.

Desafío 2: Las sesiones largas acumulan mal contexto

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

OpenCode admite 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 mayores, empezar una sesión nueva a menudo es más limpio que continuar una conversación heroica de 80,000 tokens. Con ejecuciones scripteadas la respuesta es aún más simple: un nuevo opencode run comienza con un contexto limpio cada vez, por lo que el estado a largo plazo pertenece a archivos como AGENTS.md, no en una conversación.

El contexto no es memoria gratis. 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 error: 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 denegaste allí. Si una acción absolutamente no debe ocurrir, no te confíes solo de las 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 campo diferentes en la documentación de V2.

No combines casualmente ejemplos de:

/docs/

y:

/v2/docs/

sin verificar qué tiempo de ejecución estás usando realmente. Cuando solucionas problemas de una configuración copiada de 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 informar:

Implementé la nueva validación y actualicé las pruebas relevantes.

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

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

El agente de codificación no debería ser la única interfaz a través de la cual observas al agente de codificación.

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

Más integraciones no producen automáticamente un mejor agente de codificación. Los servidores MCP grandes pueden exponer muchos esquemas de herramientas, cada uno consumiendo contexto del modelo y aumentando 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ía de ellos 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 la cadena de herramientas sea local. Las discusiones comunitarias a principios de 2026 plantearon preguntas de privacidad en torno al 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 estricto, 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 validarse, no inferirse 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 del proveedor;
  • flujos de trabajo centrados en la terminal;
  • agentes configurables;
  • permisos granulares;
  • soporte para modelos locales;
  • MCP;
  • comandos y habilidades reutilizables;
  • arquitectura cliente/servidor.

Claude Code es convincente cuando quieres una experiencia de Anthropic estrechamente integrada con un fuerte comportamiento de modelos de primera parte y flujos de trabajo de agentes 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 basándote en qué capa quieres poseer. Si quieres que un proveedor tome la mayoría de las decisiones de flujo de trabajo, un agente de codificación de primera parte puede ser atractivo. Si quieres que el arnés permanezca reemplazable mientras experimentas con proveedores y configuraciones de agentes, OpenCode hace un argumento más fuerte.

Lo que Reddit y Hacker News aciertan sobre OpenCode

Las discusiones comunitarias en torno a OpenCode son inusualmente polarizadas. Algunos desarrolladores lo describen como su arnés de codificación favorito, especialmente cuando se combina con modelos de Codex, modelos locales o configuraciones de agentes personalizados. Otros se centran en el uso de recursos, el comportamiento de permisos, las preguntas de privacidad, los cambios de 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 anteriormente 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 verificar un humano?

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

Una configuración inicial que recomendaría

Resistiría construir una configuración elaborada inmediatamente. Comienza con:

  1. un modelo predeterminado fuerte;
  2. un AGENTS.md;
  3. permisos de shell y edición conservadores;
  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, promóvelo a un comando, habilidad o agente. Una vez que una capacidad se vuelve riesgosa, restríngela 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 codificación se comporte como otra herramienta de desarrollo programable. Lo consideraría fuertemente si:

  • trabajas en múltiples proveedores de LLM;
  • quieres soporte para modelos locales;
  • no te gusta estar bloqueado a un solo 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 codificación;
  • ya entiendes Git y las herramientas CLI normales.

Es menos convincente si principalmente quieres una capa de IA invisible dentro de un 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 siente incómodo, darle 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 codificación de IA convirtiéndose en infraestructura de desarrollo en lugar de ser 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 dar forma al agente alrededor de un flujo de trabajo de ingeniería real.

La debilidad es el reflejo de esa fortaleza. OpenCode te da suficiente control para crear un entorno de codificación disciplinado, pero también te da suficiente control para crear un enjambre complicado, costoso y mal aislado de agentes con veinte servidores MCP y sin un límite de verificación claro.

No optimizaría OpenCode para la máxima autonomía. Lo optimizaría para bucles de retroalimentación cortos. Dale un problema acotado, 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

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.