OpenCode es uno de los agentes de codificación de IA de código abierto más destacados de 2026. Su filosofía de diseño se centra en ser "independiente del modelo y priorizar la terminal", permitiendo a los desarrolladores ejecutar Claude, invocar GPT, Gemini, modelos locales o incluso combinarlos. Al igual que Claude Code, funciona directamente en la terminal, pero sigue un camino distinto: abstrae el proveedor como un elemento de configuración conectable, dejando que el usuario decida qué modelo utilizar.
Muchos lectores me han hecho una pregunta muy específica: dado que, por su configuración, OpenCode parece utilizar el modo de compatibilidad de OpenAI, ¿es compatible con el formato nativo de Anthropic? ¿Cómo es mejor configurarlo al conectarlo a un servicio proxy de API como APIYI?
Este artículo ofrece una verificación completa basada en la documentación oficial en inglés y el código fuente. Primero aclararemos qué es OpenCode y sus diferencias clave con Claude Code, y luego te mostraré paso a paso cómo conectarlo al servicio proxy de APIYI (apiyi.com), cubriendo tanto el modo de compatibilidad con OpenAI como la invocación nativa de Anthropic. Tras leerlo, podrás configurarlo de inmediato.
Introducción al proyecto OpenCode: Posicionamiento central de un agente de codificación de IA de código abierto
OpenCode es mantenido por el equipo de SST (los autores del marco SST/Serverless Stack), con el repositorio en github.com/sst/opencode bajo licencia MIT. A fecha de publicación, ha acumulado más de 150,000 estrellas en GitHub y cuenta con más de 850 colaboradores, siendo uno de los proyectos de agentes de codificación de código abierto más activos. Su público objetivo es claro: desarrolladores de nivel medio a avanzado que desean completar la mayoría de las tareas de codificación en la terminal sin estar atados a un único proveedor de modelos.
Arquitectura y modo de ejecución de OpenCode
OpenCode utiliza una arquitectura cliente/servidor, ejecutando la lógica central del agente en un proceso de servicio local, donde la TUI (interfaz de terminal) es solo uno de los muchos frontends posibles. Esto significa que la misma instancia del agente puede ser accedida simultáneamente por la terminal, aplicaciones de escritorio, complementos de IDE e incluso dispositivos móviles, lo que abre un gran espacio para la colaboración multiplataforma en el futuro.
Incluye dos modos de agente integrados, intercambiables instantáneamente con la tecla Tab:
- Modo
build: otorga permisos completos de herramientas por defecto, permitiendo leer, escribir y ejecutar comandos; ideal para tareas de desarrollo reales. - Modo
plan: modo de solo lectura, dedicado exclusivamente al análisis de código, diseño de soluciones y sugerencias, sin modificar ningún archivo.
| Dimensión | Puntos clave de diseño de OpenCode | Valor para el desarrollador |
|---|---|---|
| Arquitectura | Separación cliente/servidor | Colaboración multiplataforma, control remoto |
| Capa de modelo | Abstraída como proveedor conectable | Libertad para cambiar entre más de 75 modelos |
| Capa de interacción | TUI / App de escritorio / Plugin de IDE | No atado a una interfaz específica |
| Capa de permisos | Modos duales build / plan | Equilibrio entre seguridad y eficiencia |
| Despliegue | Prioridad local, conexión remota | Los datos permanecen en local |
🎯 Consejo de configuración: Si deseas utilizar modelos de Claude, GPT, Gemini, DeepSeek y otros en OpenCode sin tener que abrir una cuenta y gestionar múltiples claves API para cada uno, puedes conectarte directamente al servicio proxy de APIYI (apiyi.com) y cubrir los modelos principales con un solo token.
Capacidades principales de OpenCode
Su alcance es mucho mayor que el de los complementos de IDE tradicionales. Al introducir lenguaje natural en la terminal, OpenCode puede interpretar todo el repositorio de código, añadir funciones, modificar lógica existente, ejecutar pruebas e incluso realizar refactorizaciones entre archivos. El modo plan se utiliza para revisiones previas: el agente propone la idea de implementación y, una vez que el desarrollador la confirma, se cambia al modo build para ejecutarla.
También admite un modo no interactivo opencode run "tu indicación", que puede integrarse directamente en scripts de shell para escenarios de automatización como CI/CD, refactorizaciones por lotes o tareas programadas. Esta capacidad no estaba disponible en las primeras versiones de Claude Code, lo cual es una de las razones por las que OpenCode es frecuentemente elegido en escenarios de ingeniería.
Vale la pena mencionar que OpenCode descarga y compara automáticamente la lista de modelos desde la base de datos pública models.dev. Por lo tanto, incluso si un proveedor lanza un nuevo modelo, OpenCode puede reconocerlo rápidamente. Al conectarte a través de un servicio proxy, el mapeo de modelos local puede mantenerse sincronizado con la lista de modelos en el backend de APIYI, evitando situaciones incómodas donde "el ID del modelo está en la configuración, pero la solicitud es rechazada".
Diferencias clave entre OpenCode y Claude Code
Mucha gente piensa en OpenCode como el "Claude Code de código abierto", pero sus propósitos fundamentales no se solapan. Claude Code es una herramienta de primera clase creada por Anthropic específicamente para sus propios modelos, mientras que OpenCode es un marco neutral orientado a un ecosistema de múltiples modelos.
Alcance del modelo y control de costos
Claude Code solo puede invocar modelos de Anthropic (series Sonnet, Opus y Haiku), lo que significa que todas las tareas se pagan según los precios de Anthropic. OpenCode admite más de 75 proveedores, incluidos OpenAI, Anthropic, Google Vertex, Bedrock, Groq, Azure, OpenRouter e incluso backends de inferencia local como Ollama o LM Studio.
Esta flexibilidad es muy útil en flujos de trabajo reales. Las tareas ligeras como la generación de documentación, mensajes de confirmación o cambio de nombres de variables pueden delegarse a modelos pequeños y económicos, mientras que para la refactorización compleja y el pensamiento arquitectónico se puede volver a Claude Sonnet o Opus, lo que suele reducir el costo total entre un 40% y un 60%.
Diferencias en el flujo de trabajo y el modelo de permisos
Claude Code sigue una ruta conservadora por defecto: solicita confirmación antes de escribir archivos o ejecutar comandos, lo cual es amigable para principiantes pero a veces interrumpe el ritmo. OpenCode sigue una ruta transparente: el código es completamente abierto, los equipos de seguridad pueden auditarlo y los permisos se gestionan explícitamente mediante el cambio de build/plan, lo que lo hace más amigable para la automatización y el scripting.
| Dimensión de comparación | OpenCode | Claude Code |
|---|---|---|
| Estado de código abierto | Código abierto bajo MIT, auditable | Código cerrado, solo distribución binaria |
| Alcance del modelo | 75+ proveedores, incluidos modelos locales | Solo modelos oficiales de Anthropic |
| Endpoint personalizado | Se puede cambiar baseURL de cualquier proveedor | Se cambia mediante ANTHROPIC_BASE_URL |
| Interfaz de usuario | TUI / App de escritorio / Plugin IDE | Principalmente terminal |
| Política de permisos | Cambio explícito de build / plan | Confirmación de solicitud por defecto |
| Madurez | Evolución rápida, detalles aún en pulido | Experiencia más pulida |
| Escenarios adecuados | Mezcla de modelos, despliegue local, personalización | Experiencia Claude "todo en uno" |
🎯 Sugerencia de elección: Si tu flujo de trabajo se basa principalmente en Claude, pero ocasionalmente quieres que GPT o Gemini actúen como respaldo, te sugiero configurar varios modelos en OpenCode a través de APIYI apiyi.com, usando el mismo token para cambiar entre ellos. Puedes usar Claude Code nativo para el desarrollo principal y cambiar a OpenCode cuando necesites validación cruzada en tareas complejas.
¿Para quién es OpenCode?
El perfil ideal de usuario de OpenCode es el desarrollador que está dispuesto a dedicar 20 minutos a leer la documentación de configuración, que es sensible a los costos, que desea que una misma cadena de herramientas abarque varios modelos, o cuya empresa exige que los modelos sean auditables. Si solo quieres una experiencia "Claude lista para usar", Claude Code sigue siendo la opción más cómoda.
Dos modos de invocación para conectar OpenCode con el servicio proxy APIYI
Volviendo a la pregunta que más preocupa a los lectores: ¿debería OpenCode usar el modo compatible con OpenAI o el formato nativo de Anthropic? La respuesta es que ambos son compatibles, dependiendo de cómo configures el proveedor en opencode.json.
Modo 1: Compatible con OpenAI (el más universal)
Esta es la forma recomendada por la documentación de OpenCode y la ruta más segura para conectarse a un servicio proxy de terceros. Utiliza el paquete @ai-sdk/openai-compatible del SDK de Vercel AI, envolviendo cualquier endpoint que cumpla con el protocolo OpenAI Chat Completions como un proveedor de OpenCode. La entrada compatible con OpenAI de APIYI es api.apiyi.com/v1, que permite invocar simultáneamente docenas de modelos como GPT, Claude, Gemini y DeepSeek, unificándolos en el formato de OpenAI.
Su ventaja es la versatilidad; casi todos los modelos pueden colgarse del mismo proveedor. El costo es que algunas capacidades exclusivas de Anthropic (como el pensamiento extendido o bloques de uso de herramientas nativos) pasarán por una conversión de protocolo, por lo que algunos comportamientos menores pueden diferir ligeramente de los endpoints oficiales de Anthropic.
Modo 2: Nativo de Anthropic (recomendado al usar Claude)
El proveedor anthropic integrado en OpenCode utiliza el paquete @ai-sdk/anthropic, la ruta de solicitud es /v1/messages y el formato del cuerpo de la solicitud es la Messages API definida por la documentación oficial de Anthropic. Este formato admite características de Claude como content blocks, bloques de tool_use y extended thinking, siguiendo exactamente el mismo protocolo que Claude Code.
Siempre que apuntes provider.anthropic.options.baseURL a https://api.apiyi.com de APIYI, OpenCode enviará solicitudes en formato nativo de Anthropic, que el servicio proxy de APIYI reenviará al Claude ascendente. Esto significa que puedes obtener una experiencia de invocación de Claude en OpenCode casi idéntica a la de Claude Code.
| Modo | Paquete subyacente | Base URL de APIYI | Adecuado para | Fidelidad del protocolo |
|---|---|---|---|---|
| Compatible con OpenAI | @ai-sdk/openai-compatible |
https://api.apiyi.com/v1 |
Mezcla de modelos | Estándar OpenAI |
| Nativo de Anthropic | @ai-sdk/anthropic |
https://api.apiyi.com |
Toda la serie Claude | Idéntico al oficial |
🎯 Sugerencia de configuración: Para el uso diario, recomendamos la coexistencia de ambos modos: configura el mismo
opencode.jsoncon un proveedoranthropicy un proveedoropenai-compatible. El primero se usa para Claude y el segundo para otros modelos como GPT/Gemini/DeepSeek. Ambos proveedores comparten la misma clave de APIYI apiyi.com, por lo que no es necesario gestionar claves duplicadas.
Configuración de OpenCode y el servicio proxy de API APIYI en 3 pasos
A continuación, presento el flujo de trabajo mínimo para poner todo en marcha. Por lo general, completar estos pasos no te tomará más de 5 minutos.
Paso 1: Instalar el cliente OpenCode
Existen dos formas principales de instalación oficial; elige la que mejor se adapte a tu entorno.
# Opción A: Instalación global vía npm (recomendado para usuarios de Node.js)
npm install -g opencode-ai@latest
# Opción B: Instalación mediante script (recomendado para macOS / Linux)
curl -fsSL https://opencode.ai/install | bash
Una vez instalado, verifica que todo esté correcto ejecutando opencode --version. Los usuarios de Windows pueden utilizar Scoop o WSL. Si la instalación mediante npm falla, lo más probable es que tu versión de Node sea muy antigua; te recomiendo actualizar a la versión 18+ o 20+.
Paso 2: Obtener la clave API en el panel de APIYI
Inicia sesión en el panel de APIYI, ve a la página de gestión de tokens en api.apiyi.com/token y crea una nueva clave. Te sugiero nombrarla OpenCode y seleccionar el grupo correspondiente (si necesitas invocar a Claude, asegúrate de que el grupo incluya los modelos de la serie Claude). Copia la cadena sk-xxx resultante, la necesitaremos en el siguiente paso.
🎯 Consejo sobre tokens: Tras registrarte en APIYI (apiyi.com), te recomiendo crear un token independiente para cada cliente, por ejemplo, uno para ClaudeCode, otro para OpenCode y otro para Cursor. De esta forma, si una aplicación presenta peticiones anómalas, solo tendrás que revocar su token específico sin afectar al resto de tus herramientas.
Paso 3: Editar el archivo de configuración opencode.json
OpenCode busca primero el archivo opencode.json en la raíz del proyecto y, si no lo encuentra, recurre a la configuración de usuario en ~/.config/opencode/opencode.json. Aquí tienes un ejemplo completo que combina el modo nativo de Anthropic con el modo compatible con OpenAI:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.apiyi.com",
"apiKey": "{env:APIYI_KEY}"
}
},
"apiyi-openai": {
"npm": "@ai-sdk/openai-compatible",
"name": "APIYI OpenAI Compatible",
"options": {
"baseURL": "https://api.apiyi.com/v1",
"apiKey": "{env:APIYI_KEY}"
},
"models": {
"gpt-4o": { "name": "GPT-4o" },
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
"gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
}
}
}
}
A continuación, guarda la clave API en tus variables de entorno:
# macOS / Linux
echo 'export APIYI_KEY="sk-tu-token-obtenido-en-APIYI"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$env:APIYI_KEY = "sk-tu-token-obtenido-en-APIYI"
Al iniciar OpenCode, utiliza el comando de barra /models para seleccionar el modelo. Para la serie Claude, se recomienda usar el proveedor anthropic, mientras que para otros modelos, utiliza el proveedor apiyi-openai.
🎯 Regla sobre la base URL: En el modo nativo de Anthropic, no añadas
/v1, ya que el SDK lo añade automáticamente al final (/v1/messages); en el modo compatible con OpenAI, es obligatorio añadir/v1. Esta regla es idéntica a la guía proporcionada por APIYI (apiyi.com) en la documentación de Claude Code. Solo recuerda: "nativo sin prefijo, compatible con prefijo".
Solución de problemas comunes
| Error | Causa probable | Solución |
|---|---|---|
Route /api/messages not found |
baseURL incluye /v1 por error |
Elimina el sufijo /v1 |
Required provider.anthropic.models |
Falta el campo models tras definir baseURL | Lista explícitamente los IDs de modelos disponibles |
401 Unauthorized |
Token inválido o el grupo no incluye el modelo | Regenera el token en APIYI |
model not found |
El ID del modelo no coincide con el de APIYI | Consulta el ID real en el "Model Plaza" de APIYI |
| Tiempo de espera agotado | Inestabilidad de red o límite de tasa | Cambia de nodo en APIYI o reintenta |
🎯 Consejo de depuración: Ante cualquier error, te recomiendo verificar primero la conectividad y el token mediante
curl https://api.apiyi.com/v1/models -H "Authorization: Bearer $APIYI_KEY". Este paso permite localizar el 90% de los problemas en menos de 30 segundos, siendo mucho más rápido que editaropencode.jsonrepetidamente. Si la lista se devuelve correctamente, el problema reside probablemente en la capa de configuración de OpenCode.
Casos de uso prácticos de OpenCode con el servicio proxy de APIYI
Una vez configurado, lo que realmente marca la diferencia es el flujo de trabajo. Aquí tienes algunas formas de aprovecharlo al máximo:
Escenario 1: Revisión de código sin efectos secundarios en modo "plan"
Cambia al modo plan (presionando la tecla Tab) e introduce /explica el flujo de autenticación de este repositorio. OpenCode analizará el código y generará un informe sin modificar ningún archivo. Es ideal para integrar a nuevos compañeros, realizar revisiones de seguridad o documentar la arquitectura de código heredado.
Escenario 2: Tareas de desarrollo de extremo a extremo en modo "build"
Tras validar el plan, cambia al modo build y solicita tareas como: Cambia el middleware de autenticación a una implementación basada en JWT y añade pruebas unitarias. OpenCode leerá automáticamente los archivos relacionados, realizará los cambios, ejecutará las pruebas e iterará según los errores encontrados. Se recomienda ejecutar esto en una rama limpia de git para facilitar cualquier reversión.
Escenario 3: Colaboración entre modelos y control de costes
Aprovechando la abstracción de proveedores de OpenCode, puedes asignar diferentes tareas a distintos modelos:
- Documentación y mensajes de commit: Usa
gpt-4o-minia través deapiyi-openai, con un coste bajísimo. - Refactorización compleja y revisión de código: Usa
claude-sonnet-4-6o la serie Opus a través del proveedoranthropic. - Contenido multilingüe o visual: Usa
gemini-2.5-proa través deapiyi-openai.
🎯 Nota sobre costes: Al invocar modelos a través de APIYI (apiyi.com), todo se factura según el uso real de tokens, sin mínimos de consumo. Te sugiero probar el flujo con modelos económicos y, una vez verificado el resultado, cambiar a modelos más potentes para optimizar tu presupuesto.
Escenario 4: Integración en CI/CD (modo no interactivo)
El comando opencode run permite insertar la indicación directamente en la shell, devolviendo la salida a través de stdout. Esto facilita la integración con GitHub Actions, GitLab CI o tareas programadas. Por ejemplo, puedes automatizar la revisión de la estructura del repositorio semanalmente o generar un borrador de changelog antes de fusionar un PR.
Preguntas frecuentes (FAQ)
P1: ¿OpenCode realmente admite el protocolo nativo /v1/messages de Anthropic?
Sí, lo admite. El proveedor anthropic integrado en OpenCode utiliza el paquete @ai-sdk/anthropic. La ruta de solicitud es la /v1/messages oficial de Anthropic y el cuerpo de la solicitud también sigue el formato oficial de la API de Messages, utilizando el mismo protocolo que Claude Code. Solo tienes que apuntar el baseURL a APIYI (apiyi.com) para obtener una experiencia casi idéntica a la de Claude Code dentro de OpenCode.
P2: Si solo uso el modo compatible con OpenAI, ¿perderé algunas capacidades de Claude?
En el modo compatible con OpenAI, características exclusivas de Anthropic como los bloques tool_use, el extended thinking y los encabezados de control de caché se adaptan a través de la capa de protocolo. Aunque las funciones siguen estando disponibles, el formato de respuesta se transforma, por lo que algunos comportamientos granulares (como la facturación de tokens de pensamiento o ciertos motivos de parada) podrían diferir ligeramente del modo nativo. Para el desarrollo principal con Claude, recomendamos utilizar el modo nativo.
P3: ¿El archivo de configuración de OpenCode admite ${env:VAR} o {env:VAR}?
La versión más reciente utiliza de forma unificada la sintaxis {env:VAR}; las versiones antiguas utilizaban ${env:VAR}. Si OpenCode muestra el error apiKey is undefined, verifica primero si lo escribiste como ${env:APIYI_KEY} y cámbialo a {env:APIYI_KEY} según la especificación actual.
P4: ¿Se puede conectar OpenCode directamente a APIYI usando el comando /connect integrado?
Sí, es posible. Ejecuta /connect, selecciona "Other", introduce el ID del proveedor (por ejemplo, apiyi-openai) y pega tu token de APIYI; OpenCode escribirá automáticamente el archivo opencode.json. Sin embargo, /connect utiliza por defecto la ruta compatible con OpenAI. Si deseas utilizar el modo nativo de Anthropic, te recomendamos editar manualmente provider.anthropic.options.baseURL.
P5: ¿Puedo hacer que Claude Code y OpenCode compartan la misma clave API de APIYI?
Es totalmente posible y, de hecho, muy recomendable. Los tokens de APIYI (apiyi.com) no están vinculados a un cliente específico; la misma clave sk-xxx puede ser utilizada simultáneamente por múltiples clientes como Claude Code (a través de ANTHROPIC_BASE_URL), OpenCode (a través de opencode.json), Cursor, Continue, entre otros. Puedes consultar la facturación de forma unificada según el origen de la invocación.
P6: ¿Los modos "plan" / "build" de OpenCode son lo mismo que la confirmación de permisos de Claude Code?
Aunque el objetivo de diseño es similar, las rutas de implementación son distintas. Claude Code solicita confirmación paso a paso, pidiéndola cada vez que se escribe un archivo o se ejecuta un comando. OpenCode utiliza un cambio de modo: el modo plan deshabilita fundamentalmente los permisos de escritura, mientras que el modo build los habilita por defecto. El enfoque de OpenCode es más adecuado para escenarios de automatización, mientras que Claude Code es mejor para situaciones que requieren un control más granular.
P7: ¿La latencia al invocar a Claude a través del servicio proxy de API de APIYI es mayor que la conexión directa oficial?
APIYI (apiyi.com) ha desplegado puntos de entrada en varios nodos centrales dentro del país y ha optimizado los enlaces para los principales proveedores como Claude, GPT y Gemini. Para los usuarios locales, la latencia del primer byte suele ser significativamente menor que al conectarse directamente a los puntos finales oficiales. Puedes realizar una prueba comparativa en tu propia red utilizando curl -w "%{time_starttransfer}".
Resumen: La mejor combinación de prácticas entre OpenCode y APIYI
El verdadero valor de OpenCode reside en devolver al desarrollador el "poder de elección del modelo", y servicios proxy de API como APIYI proporcionan la infraestructura necesaria para que esta flexibilidad sea efectiva. Al combinar ambos, los desarrolladores pueden disfrutar de una experiencia con Claude cercana a la de Claude Code en la terminal, mientras cambian fácilmente a GPT, Gemini, DeepSeek u otros modelos para realizar validaciones cruzadas. Todo el flujo de trabajo se gestiona con un único archivo de configuración de OpenCode y una clave API de APIYI.
Volviendo a la pregunta inicial de este artículo: OpenCode admite tanto el modo compatible con OpenAI como el formato nativo de Anthropic, y ambos no son excluyentes. Recomendamos a los usuarios habituales mantener ambos proveedores en opencode.json: utiliza la ruta nativa para Claude a fin de conservar todas sus capacidades, y la ruta compatible para otros modelos para maximizar la versatilidad.
🎯 Recomendación final: Si estás pensando en probar OpenCode, la forma más sencilla de empezar es registrarte en APIYI (apiyi.com), generar una clave API y habilitar ambos modos según la configuración de este artículo. En una semana descubrirás que no puedes prescindir de la forma de trabajar de "usar una sola clave para todos los modelos", y ya no querrás mantener cuentas y saldos por separado para cada proveedor.
— Equipo técnico de APIYI | Seguimos de cerca el ecosistema de agentes de codificación de IA. Más tutoriales en el centro de ayuda de APIYI (apiyi.com).
