Verifica della realtà BYOK: 5 cose che oggi si rompono in Open Design

Abbiamo detto alle persone che Open Design è BYOK fin dalle fondamenta. Questo è ancora vero. L'articolo di partenza sul flusso di lavoro di design BYOK illustra il percorso funzionante: punta il daemon a qualsiasi endpoint compatibile con OpenAI, incolla la tua chiave, e hai finito. Per la maggior parte delle configurazioni, questa è l'intera storia, e rimane l'intera storia.

Ma "BYOK" non è una singola funzionalità. È un contratto che si estende fino al compositore di chat, all'endpoint di finalizzazione, al selettore di modelli, al percorso di avvio della CLI e al livello di analitica. Ognuno di questi è un punto in cui il contratto può rompersi, e in questo momento diversi di essi sono issue aperte nel nostro tracker pubblico, segnalate dagli utenti nelle ultime 48 ore.

Avremmo potuto scrivere l'articolo di partenza e fermarci lì. Invece, ecco il passaggio di onestà: i thread arrivati questa settimana, cosa si rompe, perché si rompe, cosa fare oggi e quale PR (o slot della roadmap) lo sta correggendo. Nessuno di questi è nascosto. Sono archiviati, etichettati e collegati qui sotto, e preferiamo che li leggi da noi piuttosto che scoprirli a metà deck un venerdì.

La promessa contro la lista dei bug

L'inquadramento conta, perché la lettura sbagliata facile è "il BYOK è fatto a metà". Non lo è. Nessuno dei cinque qui sotto è un bug del tipo "il BYOK non funziona". Ognuno di essi vive al confine tra un adattatore che possediamo noi — il livello compatibile con OpenAI, il selettore di modelli, il percorso di finalizzazione — e uno che non possediamo: la CLI del provider a monte, le sue scelte di pacchettizzazione, o il modello di processo della piattaforma host.

Quel confine è dove vive la realtà in qualsiasi orchestratore CLI open-source. Non eseguiamo inferenza, non rilasciamo una CLI forkata per ogni provider, e non avvolgiamo tutto in un proxy che leviga gli spigoli (e tassa silenziosamente i tuoi token). Il prezzo di questa postura è che quando la CLI di un provider cambia forma, o Windows impone un limite che macOS non impone, la giuntura si vede. Questa settimana, cinque di quelle giunture si sono viste tutte insieme.

Eccole tutte e cinque, nell'ordine in cui sono arrivate.

Gemini si perde sulla strada verso "Finish Design"

Issue #1619 — bug, aperta

Sintomo

Il BYOK è configurato per Gemini. Il test di connessione nelle Impostazioni riesce. Il selettore di modelli restituisce i modelli Gemini. La chat normale funziona: puoi tenere un'intera conversazione contro la tua chiave Gemini senza problemi. Ma nel momento in cui l'utente preme Finish Design, il daemon genera un errore in forma Anthropic, come se avesse improvvisamente dimenticato con quale provider stava parlando.

Perché succede

La risposta del maintainer nel thread lo conferma: la chat in modalità API normale rispetta il provider BYOK Gemini selezionato dall'inizio alla fine, ma Finish Design non è ancora stato generalizzato oltre il percorso di finalizzazione compatibile con Anthropic. Tutto il resto viene instradato attraverso il proxy consapevole del provider che sa parlare il dialetto di ogni sistema a monte. Finish Design passa ancora attraverso un endpoint di finalizzazione Anthropic codificato fisso rimasto da una release precedente, quindi una risposta Gemini che arriva in una forma non-Anthropic fa inciampare il parser.

Soluzione temporanea

Instrada Gemini attraverso OpenRouter nello slot del provider compatibile con Anthropic. Il percorso Finish Design vede allora una risposta in forma Anthropic che ritorna dallo shim di OpenRouter e finalizza correttamente. È un salto in più, e stai pagando l'instradamento di OpenRouter anziché chiamare Gemini direttamente, ma è stabile oggi e copre l'unico percorso che è rotto senza toccare il percorso di chat che già funziona.

Chi lo sta correggendo

La generalizzazione di Finish Design è ora sulla roadmap BYOK come P1. Ancora nessuna PR: questa è la prossima cosa che il team del daemon prende in carico, ed è l'unica delle cinque a essere un difetto in codice che possediamo interamente anziché una discordanza di confine.

Gemini 3 Flash muore su Windows prima che il prompt arrivi

Issue #1611 — bug, aperta

Sintomo

Gemini 3 Flash Preview fallisce dentro Open Design su Windows con stdin: write EOF dopo circa 1,5 secondi, prima che il prompt raggiunga mai il modello. Gemini 3 Pro funziona bene nella stessa identica installazione. E la CLI Gemini diretta (gemini --model gemini-3-flash-preview ...) riesce quando GEMINI_CLI_TRUST_WORKSPACE=true è impostato. Quindi non è la chiave, non è l'account e non è la CLI presa da sola.

Perché succede

La diagnosi ha richiesto due passaggi, il che vale la pena mostrare perché è un buon esempio di come questi vengano dipanati. La prima lettura dello screenshot del segnalatore sembrava un errore di quota a monte 429 RESOURCE_EXHAUSTED. Dopo una riproduzione pulita in PowerShell che scriveva OD_GEMINI_3_FLASH_OK su stdout, il quadro è cambiato: il modello è raggiungibile, la CLI è sana, il fallimento è specificamente sul percorso di avvio Open Design → CLI Gemini, ed è specifico della variante Flash su Windows. Pro segue lo stesso percorso di avvio e sopravvive; Flash no.

Soluzione temporanea

Seleziona Gemini 3 Pro Preview nel selettore di modelli. Gira attraverso lo stesso percorso di avvio e funziona. Separatamente — e questo ha portato via più tempo del bug stesso — controlla ~/.gemini/hooks/. Un hook lento gsd-check-update.js (Hook execution error: Hook timed out after 60000ms) stava aggiungendo circa 104s di overhead a ogni esecuzione nel caso di questo utente, completamente indipendente dal fallimento di Flash. Pulisci comunque i tuoi hook Gemini; un hook di controllo aggiornamenti in stallo farà sembrare rotto qualsiasi agente.

Chi lo sta correggendo

Contrassegnato come specifico di Flash e lato OD. L'indagine è in corso sul percorso di scrittura stdin del daemon: il write EOF dice che lo stdin del processo figlio si è chiuso prima che il daemon finisse di scrivere il prompt, quindi la correzione sta in come quella particolare variante viene avviata.

La TUI di DeepSeek ha un tetto di 30 KB per i prompt su Windows

Issue #1610 — bug, aperta

Sintomo

Sul wrapper DeepSeek v0.8.33 in una build pacchettizzata per Windows, un lungo prompt composto fallisce il nostro guard pre-flight con 81397 > 30000 bytes. L'utente non ha fatto nulla di sbagliato: ha solo composto un prompt abbastanza ricco (contesto di sistema, design system, riferimenti) da superare i 30 KB.

Perché succede

Quel guard è intenzionale, e ti sta proteggendo da un errore peggiore. L'adattatore DeepSeek TUI attualmente invia il prompt come argomento posizionale della riga di comando — legato ad argv — e Windows limita la riga di comando totale ben al di sotto di dove lo fanno macOS e Linux. Senza il controllo pre-flight, lo stesso prompt fallirebbe più tardi, più in profondità nello spawn, con un errore ENAMETOOLONG molto meno utile e nessun indizio che la causa fosse la dimensione del prompt. Quindi falliamo presto e nominiamo il numero. La discordanza che l'issue espone è nella documentazione: la guida di alto livello implica che i fallback per i prompt lunghi su Windows si applichino in generale, ma il percorso DeepSeek TUI non ne ha ancora uno: il suo trasporto è ancora argv, non stdin o un file di prompt.

Soluzione temporanea

Se sei su Windows con l'adattatore DeepSeek TUI, mantieni il prompt composto sotto i 30 KB, o passa a un adattatore basato su stdin: Claude Code, Codex e OpenCode prendono tutti il loro prompt tramite stdin e non hanno un tetto comparabile. Su macOS e Linux questa issue non morde affatto; il limite di argv lì è abbastanza alto che i prompt del mondo reale non lo raggiungono.

Chi lo sta correggendo

La correzione giusta è un trasporto stdin o file di prompt per l'adattatore DeepSeek TUI, che rimuove del tutto il tetto di argv e lo allinea agli adattatori stdin. È tracciata nella coda del team degli adattatori.

Il test della CLI locale di OpenCode va in timeout prima che il modello si scaldi

Issue #1603 — bug, priority:p0, aperta

Sintomo

In Impostazioni → BYOK → OpenCode, il test di connessione va regolarmente in timeout a 45 secondi. La parte strana: se l'utente apre prima il terminale di OpenCode Desktop e vi collega un LLM locale, lo stesso test di Open Design riesce poi al tentativo successivo.

Perché succede

Quel dettaglio "apri prima il terminale Desktop" è l'intero indizio. Open Design non si collega a una sessione OpenCode Desktop in esecuzione. Per un test rapido nelle Impostazioni, il daemon avvia il proprio sottoprocesso CLI OpenCode fresco e attende una risposta ok. Con un modello locale a freddo — uno che non è ancora stato caricato in memoria — quella prima risposta può richiedere più del budget di 45 secondi, perché il modello viene letto dal disco e scaldato prima di poter rispondere a qualsiasi cosa. Aprire il terminale Desktop e lasciargli rispondere a un prompt scalda il modello nella cache del sistema operativo in un modo da cui il sottoprocesso fresco del daemon può poi beneficiare immediatamente. Quindi non è davvero un bug di OpenCode; è un'assunzione sulla tempistica di avvio a freddo che è sbagliata per i modelli locali.

Soluzione temporanea

Prima di testare OpenCode in Open Design, apri OpenCode Desktop, collega il tuo LLM locale e lasciagli rispondere a un prompt. Poi esegui il test di connessione di OD: il modello è caldo e la risposta arriva entro il budget. A partire da v0.7.0, il budget del test di connessione è anche configurabile, quindi se il tuo modello locale è genuinamente lento da caricare puoi aumentare la finestra invece di scaldarlo a mano.

Chi lo sta correggendo

La correzione lato daemon è una finestra di riscaldamento più lunga o configurabile specificamente per gli adattatori di modelli locali, così un modello locale a freddo non viene giudicato sullo stesso orologio di un'API ospitata. È tracciata a p0 — la priorità più alta delle cinque, perché gli utenti di modelli locali sono esattamente il pubblico che il BYOK è pensato per servire.

L'app web pacchettizzata si rifiuta di caricarsi su HTTP semplice

Issue #1620 — bug, aperta

Sintomo

Bug leggermente diverso, stessa famiglia. Il segnalatore esegue l'app web pacchettizzata su un IP di LAN su HTTP semplice, e la pagina genera un errore al caricamento: non raggiunge mai uno stato utilizzabile.

Perché succede

Dopo la PR #1428, il provider di analitica e il nonce di esportazione PDF hanno iniziato a chiamare crypto.randomUUID() direttamente, bypassando l'helper a livelli introdotto nella PR #900 che ripiega con grazia quando l'API crypto sicura non è disponibile. Chromium non espone crypto.randomUUID nei contesti non sicuri, e un nudo IP di LAN su HTTP semplice non è, per definizione di Chromium, un contesto sicuro. Quindi la chiamata diretta genera un errore al momento del caricamento, e la pagina cade con essa. Non è strettamente un bug BYOK, ma morde esattamente lo stesso pubblico: le persone che eseguono la propria infrastruttura, spesso isolata dalla rete, spesso su HTTP semplice perché allestire un certificato per uno strumento interno non vale l'attrito.

Soluzione temporanea

Servi l'app web su HTTPS o su localhost. Entrambi soddisfano il requisito di contesto sicuro di Chromium — localhost è trattato come sicuro anche senza certificato — e la pagina si carica normalmente. Per una rapida configurazione interna, localhost è il percorso a costo zero; per l'accesso via LAN, un certificato autofirmato su HTTPS è quello duraturo.

Chi lo sta correggendo

La PR #1621 reinstrada i restanti punti di chiamata attraverso l'helper UUID a livelli della PR #900, così il fallback per il contesto sicuro si applica di nuovo ovunque invece che solo dove era già cablato. È aperta e in revisione.

Cosa dice davvero questo sul BYOK in Open Design

Leggi la lista come una mappa di contratti, non come un verdetto di qualità. Quattro di queste cinque issue stanno ai confini degli adattatori: il percorso di avvio della CLI di Gemini, il trasporto CLI legato ad argv di DeepSeek, il modello di avvio a freddo di OpenCode, le regole di contesto sicuro della piattaforma host. La quinta, quella di Finish Design, è al nostro stesso endpoint di finalizzazione, dove abbiamo codificato fissa una risposta in forma Anthropic una release fa e non l'abbiamo ancora generalizzata. Quella è colpa nostra; le altre quattro sono la tassa che paghi per rispettare strumenti che non hai costruito tu.

Ed è questo il punto strutturale. Ogni sistema BYOK che non è un proxy rietichettato finisce qui. O possiedi l'inferenza — e perdi il BYOK, perché ora sei tu a comprare i token e a ricaricarli — oppure rispetti gli strumenti a monte ed erediti i loro spigoli: le loro CLI, le loro stranezze di pacchettizzazione, i limiti di piattaforma che ognuno gestisce in modo diverso. Abbiamo scelto la seconda postura deliberatamente, e la sceglieremmo di nuovo. Il costo sono settimane che assomigliano a questa, in cui i team del daemon e degli adattatori hanno archiviato lavoro su cinque superfici in due giorni.

Il compromesso è ancora giusto. Una configurazione funzionante su Claude Code, Codex, Cursor, Gemini Pro su macOS e DeepSeek su Linux — la matrice che copre all'incirca il 90% dei nostri utenti reali — gira in modo pulito oggi, senza tassa da proxy e senza margine sui tuoi token. I cinque thread sopra sono come appare l'altro 10% della matrice a metà maggio 2026: nominati, archiviati e ciascuno con una correzione in arrivo. Le giunture oneste battono una superficie liscia che nasconde dove va il conto.

Cosa usare oggi (matrice)

Questa è la versione pratica della sezione sopra: le stesse cinque giunture, mappate su cosa è sicuro usare adesso. Un ✓ significa che il percorso funziona così com'è; un ✗ collega l'issue che lo sta bloccando, con la soluzione temporanea nella sezione pertinente.

Provider	macOS	Linux	Windows	Percorso Finish Design
Claude Code (Sonnet / Opus)	✓	✓	✓	nativo
Codex	✓	✓	✓	nativo
Cursor (BYOK)	✓	✓	✓	nativo
Gemini 3 Pro Preview	✓	✓	✓	shim OpenRouter (#1619)
Gemini 3 Flash Preview	✓	✓	✗ (#1611)	shim OpenRouter (#1619)
DeepSeek (API)	✓	✓	✓	shim OpenRouter
DeepSeek TUI (prompt lunghi)	✓	✓	✗ (#1610)	shim OpenRouter
OpenCode (modello locale)	✓	✓	✓ (scalda prima, #1603)	n/d

Due letture di questa tabella. Se il tuo stack è nel blocco tutto-✓ — Claude Code, Codex, Cursor o Gemini Pro — sei sul percorso pulito e nulla di quanto sopra cambia la tua giornata. Se sei su una delle righe ✗, la sezione corrispondente ha la soluzione temporanea che ti fa partire oggi mentre la correzione collegata arriva. In ogni caso, iscriviti all'etichetta BYOK sul tracker se vuoi una notifica quando una riga passa da ✗ a ✓.

Cosa fare dopo

La libreria di skill di Open Design è il livello operativo sotto tutto questo: i contratti basati su file in cui l'adattatore BYOK alimenta una volta che la connessione è sana. Le giunture sopra riguardano il portare byte dalla tua chiave al modello e indietro; le skill sono ciò che il modello fa effettivamente con essi. Se vuoi vedere cosa una skill consuma dal modello e cosa non le interessa — che è anche il motivo per cui questi spigoli degli adattatori non cambiano l'output, ma solo se lo raggiungi — quella directory è il posto giusto da cui iniziare.

Sfoglia la libreria di skill.

Letture correlate

• Flusso di lavoro di design BYOK: usa Claude, Codex o Qwen con la tua chiave: la spiegazione originale del BYOK, e il percorso funzionante al cui margine si trovano le cinque giunture sopra
• Perché abbiamo costruito Open Design come un livello di skill, non come un prodotto: perché rispettiamo gli strumenti a monte invece di avvolgerli in un proxy, che è l'intero motivo per cui questi confini esistono
• 31 skill, 72 sistemi: come funziona la libreria: cosa il BYOK alimenta effettivamente una volta che la connessione è sana