Comprobación de la realidad de BYOK: 5 cosas que fallan hoy en Open Design

Llevamos tiempo diciéndole a la gente que Open Design es BYOK desde sus cimientos. Eso sigue siendo cierto. La publicación inicial sobre el flujo de diseño BYOK recorre el camino que funciona: apunta el daemon a cualquier endpoint compatible con OpenAI, pega tu clave y listo. Para la mayoría de las configuraciones, esa es toda la historia, y sigue siendo toda la historia.

Pero «BYOK» no es una sola función. Es un contrato que llega hasta el compositor del chat, el endpoint de finalización, el selector de modelos, la ruta de arranque de la CLI y la capa de analítica. Cada uno de esos puntos es un lugar donde el contrato puede romperse — y ahora mismo varios de ellos son issues abiertos en nuestro tracker público, reportados por usuarios en las últimas 48 horas.

Podríamos haber escrito la publicación inicial y detenernos ahí. En cambio, aquí va la ronda de honestidad: los hilos que llegaron esta semana, qué falla, por qué falla, qué hacer hoy y qué PR (o casilla del roadmap) lo está corrigiendo. Ninguno de estos está oculto. Están registrados, etiquetados y enlazados más abajo — y preferimos que los leas de nuestra mano a que los descubras a mitad de una presentación un viernes.

La promesa frente a la lista de errores

El encuadre importa, porque la lectura fácil y equivocada es «BYOK está a medio hacer». No lo está. Ninguno de los cinco de abajo es un error del tipo «BYOK no funciona». Cada uno de ellos vive en la frontera entre un adaptador que nos pertenece — la capa compatible con OpenAI, el selector de modelos, la ruta de finalización — y otro que no: la CLI del proveedor upstream, sus decisiones de empaquetado o el modelo de procesos de la plataforma anfitriona.

Esa frontera es donde vive la realidad en cualquier orquestador de CLI de código abierto. No ejecutamos inferencia, no enviamos una CLI bifurcada para cada proveedor y no envolvemos todo en un proxy que suaviza los bordes (y grava silenciosamente tus tokens). El precio de esa postura es que, cuando la CLI de un proveedor cambia de forma, o Windows impone un límite que macOS no, la costura se nota. Esta semana, cinco de esas costuras se notaron a la vez.

Aquí están las cinco, en el orden en que llegaron.

Gemini se pierde camino a «Finish Design»

Issue #1619 — bug, open

Síntoma

BYOK está configurado para Gemini. La prueba de conexión en Ajustes tiene éxito. El selector de modelos devuelve modelos de Gemini. El chat normal funciona — puedes mantener una conversación completa contra tu propia clave de Gemini sin problema. Pero en el momento en que el usuario pulsa Finish Design, el daemon lanza un error con forma de Anthropic, como si de pronto hubiera olvidado con qué proveedor estaba hablando.

Por qué ocurre

La respuesta del maintainer en el hilo lo confirma: el chat normal en modo API respeta de extremo a extremo el proveedor BYOK de Gemini seleccionado, pero Finish Design aún no se ha generalizado más allá de la ruta de finalización compatible con Anthropic. Todo lo demás se enruta a través del proxy consciente del proveedor que sabe cómo hablar el dialecto de cada upstream. Finish Design todavía pasa por un endpoint de finalización de Anthropic codificado a mano que quedó de una versión anterior — así que una respuesta de Gemini que llega con una forma no-Anthropic hace tropezar al parser.

Solución temporal

Enruta Gemini a través de OpenRouter en la casilla de proveedor compatible con Anthropic. La ruta de Finish Design ve entonces una respuesta con forma de Anthropic que vuelve del shim de OpenRouter y finaliza correctamente. Es un salto adicional, y estás pagando el enrutamiento de OpenRouter en lugar de llamar a Gemini directamente, pero hoy es estable y cubre la única ruta que está rota sin tocar la ruta de chat que ya funciona.

Quién lo está corrigiendo

La generalización de Finish Design está ahora en el roadmap de BYOK como P1. Todavía no hay PR — esto es lo siguiente que el equipo del daemon va a abordar, y es el único de los cinco que es un defecto en código que nos pertenece por completo en lugar de un desajuste de frontera.

Gemini 3 Flash muere en Windows antes de que llegue el prompt

Issue #1611 — bug, open

Síntoma

Gemini 3 Flash Preview falla dentro de Open Design en Windows con stdin: write EOF tras aproximadamente 1,5 segundos — antes de que el prompt llegue siquiera al modelo. Gemini 3 Pro funciona bien en exactamente la misma instalación. Y la CLI directa de Gemini (gemini --model gemini-3-flash-preview ...) tiene éxito cuando se establece GEMINI_CLI_TRUST_WORKSPACE=true. Así que no es la clave, ni la cuenta, ni la CLI por sí sola.

Por qué ocurre

El diagnóstico llevó dos pasadas, lo cual vale la pena mostrar porque es un buen ejemplo de cómo se desenredan estas cosas. La primera lectura de la captura de pantalla del reportante parecía un error de cuota upstream 429 RESOURCE_EXHAUSTED. Tras una reproducción limpia en PowerShell que escribió OD_GEMINI_3_FLASH_OK en stdout, el panorama cambió: el modelo es alcanzable, la CLI está sana, el fallo está en la ruta de arranque de Open Design → Gemini CLI específicamente, y es específico de la variante Flash en Windows. Pro toma la misma ruta de arranque y sobrevive; Flash no.

Solución temporal

Selecciona Gemini 3 Pro Preview en el selector de modelos. Se ejecuta por la misma ruta de arranque y funciona. Por separado — y esta parte se llevó más tiempo que el propio error — revisa ~/.gemini/hooks/. Un hook gsd-check-update.js lento (Hook execution error: Hook timed out after 60000ms) estaba añadiendo aproximadamente 104 s de sobrecarga a cada ejecución en el caso de este usuario, totalmente independiente del fallo de Flash. Limpia tus hooks de Gemini de todas formas; un hook de comprobación de actualizaciones atascado hará que cualquier agente parezca roto.

Quién lo está corrigiendo

Marcado como específico de Flash y del lado de OD. La investigación está en curso sobre la ruta de escritura de stdin del daemon — el write EOF dice que el stdin del proceso hijo se cerró antes de que el daemon terminara de escribir el prompt, así que la corrección reside en cómo se hace spawn de esa variante en particular.

La TUI de DeepSeek tiene un techo de 30 KB de prompt en Windows

Issue #1610 — bug, open

Síntoma

En el wrapper de DeepSeek v0.8.33 en una compilación empaquetada de Windows, un prompt compuesto largo falla nuestra guarda previa al vuelo con 81397 > 30000 bytes. El usuario no hizo nada mal — simplemente compuso un prompt lo bastante rico (contexto de sistema, sistema de diseño, referencias) como para superar los 30 KB.

Por qué ocurre

Esa guarda es intencional, y te está protegiendo de un error peor. El adaptador de la TUI de DeepSeek envía actualmente el prompt como un argumento posicional de línea de comandos — ligado a argv — y Windows limita la línea de comandos total muy por debajo de donde lo hacen macOS y Linux. Sin la comprobación previa al vuelo, el mismo prompt fallaría más tarde, más adentro del spawn, con un error ENAMETOOLONG mucho menos útil y sin pista alguna de que la causa fuera el tamaño del prompt. Así que fallamos pronto y nombramos el número. El desajuste que expone el issue está en la documentación: la guía de alto nivel da a entender que los recursos alternativos para prompts largos en Windows se aplican de forma amplia, pero la ruta de la TUI de DeepSeek aún no tiene uno — su transporte sigue siendo argv, no stdin ni un archivo de prompt.

Solución temporal

Si estás en Windows con el adaptador de la TUI de DeepSeek, mantén el prompt compuesto por debajo de 30 KB, o cambia a un adaptador basado en stdin — Claude Code, Codex y OpenCode reciben su prompt por stdin y no tienen un techo comparable. En macOS y Linux este issue no muerde en absoluto; el límite de argv allí es lo bastante alto como para que los prompts del mundo real no lo alcancen.

Quién lo está corrigiendo

La corrección correcta es un transporte por stdin o por archivo de prompt para el adaptador de la TUI de DeepSeek, que elimina por completo el techo de argv y lo alinea con los adaptadores de stdin. Está en la cola del equipo de adaptadores.

La prueba de CLI local de OpenCode agota su tiempo antes de que el modelo se caliente

Issue #1603 — bug, priority:p0, open

Síntoma

En Ajustes → BYOK → OpenCode, la prueba de conexión agota su tiempo de forma fiable a los 45 segundos. Lo extraño: si el usuario primero abre la terminal de OpenCode Desktop y conecta allí un LLM local, la misma prueba de Open Design tiene éxito en el siguiente intento.

Por qué ocurre

Ese detalle de «abre primero la terminal de Desktop» es la pista completa. Open Design no se conecta a una sesión de OpenCode Desktop en ejecución. Para una prueba rápida de Ajustes, el daemon hace spawn de su propio subproceso fresco de la CLI de OpenCode y espera una respuesta ok. Con un modelo local frío — uno que aún no se ha cargado en memoria — esa primera respuesta puede tardar más que el presupuesto de 45 segundos, porque el modelo se está leyendo del disco y calentando antes de poder responder cualquier cosa. Abrir la terminal de Desktop y dejar que responda un prompt calienta el modelo en la caché del SO de una forma de la que el subproceso fresco del daemon puede beneficiarse de inmediato. Así que en realidad no es un error de OpenCode; es una suposición de tiempo de arranque en frío que está equivocada para los modelos locales.

Solución temporal

Antes de probar OpenCode en Open Design, abre OpenCode Desktop, conecta tu LLM local y deja que responda un prompt. Luego ejecuta la prueba de conexión de OD — el modelo está caliente y la respuesta llega dentro del presupuesto. A partir de v0.7.0, el presupuesto de la prueba de conexión también es configurable, así que si tu modelo local es genuinamente lento de cargar puedes ampliar la ventana en lugar de calentarlo a mano.

Quién lo está corrigiendo

La corrección del lado del daemon es una ventana de calentamiento más larga o configurable específicamente para los adaptadores de modelos locales, de modo que un modelo local frío no sea juzgado con el mismo reloj que una API alojada. Está registrado como p0 — la máxima prioridad de los cinco, porque los usuarios de modelos locales son exactamente el público al que BYOK está destinado a servir.

La aplicación web empaquetada se niega a cargar por HTTP plano

Issue #1620 — bug, open

Síntoma

Error ligeramente distinto, misma familia. El reportante está ejecutando la aplicación web empaquetada sobre una IP de LAN por HTTP plano, y la página lanza un error al cargar — nunca alcanza un estado usable.

Por qué ocurre

Tras el PR #1428, el proveedor de analítica y el nonce de exportación a PDF empezaron a llamar a crypto.randomUUID() directamente, saltándose el helper por niveles introducido en el PR #900 que recurre con elegancia a una alternativa cuando la API segura de crypto no está disponible. Chromium no expone crypto.randomUUID en contextos no seguros — y una IP de LAN pelada por HTTP plano, según la definición de Chromium, no es un contexto seguro. Así que la llamada directa lanza un error en el momento de la carga, y la página se cae con ella. No es estrictamente un error de BYOK, pero muerde exactamente al mismo público: gente que ejecuta su propia infraestructura, a menudo aislada de la red, a menudo por HTTP plano porque montar un certificado para una herramienta interna no compensa la fricción.

Solución temporal

Sirve la aplicación web por HTTPS o por localhost. Ambos satisfacen el requisito de contexto seguro de Chromium — localhost se trata como seguro incluso sin certificado — y la página carga con normalidad. Para una configuración interna rápida, localhost es la vía de coste cero; para acceso por LAN, un certificado autofirmado por HTTPS es la duradera.

Quién lo está corrigiendo

El PR #1621 reencamina los sitios de llamada restantes de vuelta a través del helper de UUID por niveles del PR #900, de modo que la alternativa de contexto seguro se aplique de nuevo en todas partes en lugar de solo donde ya estaba cableada. Está abierto y en revisión.

Qué dice esto realmente sobre BYOK en Open Design

Lee la lista como un mapa de contrato, no como un veredicto de calidad. Cuatro de estos cinco issues residen en fronteras de adaptadores — la ruta de arranque de la CLI de Gemini, el transporte de CLI ligado a argv de DeepSeek, el modelo de arranque en frío de OpenCode, las reglas de contexto seguro de la plataforma anfitriona. El quinto, el de Finish Design, está en nuestro propio endpoint de finalización, donde codificamos a mano una respuesta con forma de Anthropic hace una versión y aún no la hemos generalizado. Ese es culpa nuestra; los otros cuatro son el impuesto que pagas por respetar herramientas que no construiste.

Y ese es el punto estructural. Todo sistema BYOK que no sea un proxy con otra etiqueta acaba aquí. O bien posees la inferencia — y pierdes BYOK, porque ahora eres tú quien compra los tokens y les pone margen — o bien respetas las herramientas upstream y heredas sus bordes: sus CLI, sus rarezas de empaquetado, los límites de plataforma que cada una maneja de forma distinta. Elegimos la segunda postura deliberadamente, y la elegiríamos de nuevo. El coste son semanas que se parecen a esta, en la que los equipos del daemon y de adaptadores registraron trabajo en cinco superficies en dos días.

El intercambio sigue siendo el correcto. Una configuración que funciona en Claude Code, Codex, Cursor, Gemini Pro en macOS y DeepSeek en Linux — la matriz que cubre aproximadamente al 90 % de nuestros usuarios reales — corre limpiamente hoy, sin impuesto de proxy y sin margen sobre tus tokens. Los cinco hilos de arriba son cómo se ve el otro 10 % de la matriz a mediados de mayo de 2026: nombrados, registrados y cada uno con una corrección en marcha. Las costuras honestas le ganan a una superficie lisa que oculta a dónde va la factura.

Qué usar hoy (matriz)

Esta es la versión práctica de la sección anterior — las mismas cinco costuras, mapeadas sobre lo que es seguro usar ahora mismo. Un ✓ significa que la ruta funciona tal cual; un ✗ enlaza el issue que la está bloqueando, con la solución temporal en la sección correspondiente.

Proveedor	macOS	Linux	Windows	Ruta de Finish Design
Claude Code (Sonnet / Opus)	✓	✓	✓	nativa
Codex	✓	✓	✓	nativa
Cursor (BYOK)	✓	✓	✓	nativa
Gemini 3 Pro Preview	✓	✓	✓	shim de OpenRouter (#1619)
Gemini 3 Flash Preview	✓	✓	✗ (#1611)	shim de OpenRouter (#1619)
DeepSeek (API)	✓	✓	✓	shim de OpenRouter
DeepSeek TUI (prompts largos)	✓	✓	✗ (#1610)	shim de OpenRouter
OpenCode (modelo local)	✓	✓	✓ (calienta primero, #1603)	n/a

Dos lecturas de esta tabla. Si tu stack está en el bloque todo-✓ — Claude Code, Codex, Cursor o Gemini Pro — estás en la ruta limpia y nada de lo anterior cambia tu día. Si estás en una de las filas con ✗, la sección correspondiente tiene la solución temporal que te pone en marcha hoy mientras llega la corrección enlazada. En cualquier caso, suscríbete a la etiqueta BYOK en el tracker si quieres una notificación cuando una fila pase de ✗ a ✓.

Qué hacer a continuación

La biblioteca de skills de Open Design es la capa de trabajo que subyace a todo esto — los contratos basados en archivos que el adaptador de BYOK alimenta una vez que la conexión está sana. Las costuras de arriba tienen que ver con llevar bytes desde tu clave al modelo y de vuelta; las skills son lo que el modelo realmente hace con ellos. Si quieres ver qué consume una skill del modelo y qué le da igual — que es también la razón por la que estos bordes de adaptador no cambian la salida, solo si llegas a ella — ese directorio es el lugar correcto para empezar.

Explora la biblioteca de skills.

Lecturas relacionadas

• Flujo de diseño BYOK: ejecuta Claude, Codex o Qwen con tu propia clave — la explicación original de BYOK, y la ruta que funciona en cuyo borde se sitúan las cinco costuras de arriba
• Por qué construimos Open Design como una capa de skills, no como un producto — por qué respetamos las herramientas upstream en lugar de envolverlas en un proxy, que es toda la razón por la que existen estas fronteras
• 31 skills, 72 systems — cómo funciona la biblioteca — qué alimenta realmente BYOK una vez que la conexión está sana