Teste de realidade do BYOK: 5 coisas que quebram hoje no Open Design

Temos dito às pessoas que o Open Design é BYOK desde a base. Isso continua verdadeiro. O post inicial sobre o fluxo de design BYOK percorre o caminho que funciona — aponte o daemon para qualquer endpoint compatível com OpenAI, cole sua chave, pronto. Para a maioria das configurações, essa é a história inteira, e ela continua sendo a história inteira.

Mas “BYOK” não é um único recurso. É um contrato que alcança o compositor de chat, o endpoint de finalização, o seletor de modelo, o caminho de inicialização do CLI e a camada de analytics. Cada um deles é um lugar onde o contrato pode quebrar — e agora mesmo vários deles são issues abertas no nosso rastreador público, reportadas por usuários nas últimas 48 horas.

Poderíamos ter escrito o post inicial e parado por aí. Em vez disso, aqui vai a rodada de honestidade: as threads que chegaram esta semana, o que quebra, por que quebra, o que fazer hoje e qual PR (ou slot do roadmap) está corrigindo. Nenhuma delas está escondida. Estão registradas, rotuladas e linkadas abaixo — e preferimos que você as leia da nossa boca a descobri-las no meio de um deck numa sexta-feira.

A promessa vs a lista de bugs

O enquadramento importa, porque a leitura fácil e errada é “BYOK está pela metade.” Não está. Nenhum dos cinco abaixo é um bug do tipo “BYOK não funciona.” Cada um deles vive na fronteira entre um adaptador que é nosso — a camada compatível com OpenAI, o seletor de modelo, o caminho de finalização — e um que não é: o CLI do provedor upstream, as escolhas de empacotamento dele ou o modelo de processos da plataforma host.

Essa fronteira é onde a realidade mora em qualquer orquestrador de CLI open-source. Não rodamos inferência, não entregamos um CLI forkado para cada provedor e não embrulhamos tudo em um proxy que suaviza as arestas (e discretamente tributa seus tokens). O preço dessa postura é que, quando o CLI de um provedor muda de formato, ou o Windows impõe um limite que o macOS não impõe, a costura aparece. Esta semana, cinco dessas costuras apareceram de uma vez.

Aqui estão as cinco, na ordem em que chegaram.

O Gemini se perde no caminho para o “Finish Design”

Issue #1619 — bug, aberta

Sintoma

O BYOK está configurado para Gemini. O teste de conexão em Configurações é bem-sucedido. O seletor de modelo retorna modelos Gemini. O chat normal funciona — você consegue manter uma conversa completa contra a sua própria chave Gemini sem problema. Mas no momento em que o usuário clica em Finish Design, o daemon lança um erro no formato Anthropic, como se de repente tivesse esquecido com qual provedor estava falando.

Por que acontece

A resposta do mantenedor na thread confirma: o chat em modo API normal honra o provedor BYOK Gemini selecionado de ponta a ponta, mas o Finish Design ainda não foi generalizado para além do caminho de finalização compatível com Anthropic. Todo o resto é roteado pelo proxy ciente do provedor que sabe falar o dialeto de cada upstream. O Finish Design ainda passa por um endpoint de finalização Anthropic codificado, herdado de uma release anterior — então uma resposta Gemini chegando em um formato não-Anthropic derruba o parser.

Contorno

Roteie o Gemini pelo OpenRouter no slot de provedor compatível com Anthropic. O caminho do Finish Design então vê uma resposta no formato Anthropic voltando do shim do OpenRouter e finaliza corretamente. É um salto extra, e você paga o roteamento do OpenRouter em vez de chamar o Gemini diretamente, mas é estável hoje e cobre o único caminho que está quebrado sem tocar no caminho de chat que já funciona.

Quem está corrigindo

A generalização do Finish Design está agora no roadmap do BYOK como P1. Ainda sem PR — é a próxima coisa que o time do daemon vai pegar, e é a única das cinco que é um defeito em código que possuímos por completo, em vez de um descompasso de fronteira.

O Gemini 3 Flash morre no Windows antes do prompt chegar

Issue #1611 — bug, aberta

Sintoma

O Gemini 3 Flash Preview falha dentro do Open Design no Windows com stdin: write EOF após cerca de 1,5 segundo — antes que o prompt chegue ao modelo. O Gemini 3 Pro funciona bem na mesmíssima instalação. E o CLI direto do Gemini (gemini --model gemini-3-flash-preview ...) é bem-sucedido quando GEMINI_CLI_TRUST_WORKSPACE=true está definido. Então não é a chave, não é a conta e não é o CLI isoladamente.

Por que acontece

O diagnóstico levou duas passadas, o que vale mostrar porque é um bom exemplo de como essas coisas são desembaraçadas. A primeira leitura do print do reportante parecia um erro de cota upstream 429 RESOURCE_EXHAUSTED. Depois de uma reprodução limpa no PowerShell que escreveu OD_GEMINI_3_FLASH_OK no stdout, o quadro mudou: o modelo é alcançável, o CLI está saudável, a falha está especificamente no caminho de inicialização Open Design → Gemini CLI, e é específica da variante Flash no Windows. O Pro toma o mesmo caminho de inicialização e sobrevive; o Flash não.

Contorno

Selecione o Gemini 3 Pro Preview no seletor de modelo. Ele roda pelo mesmo caminho de inicialização e funciona. Separadamente — e essa parte tomou mais tempo que o próprio bug — verifique ~/.gemini/hooks/. Um hook gsd-check-update.js lento (Hook execution error: Hook timed out after 60000ms) estava adicionando cerca de 104s de overhead a cada execução no caso desse usuário, totalmente independente da falha do Flash. Limpe seus hooks do Gemini de qualquer jeito; um hook de checagem de update travado fará qualquer agente parecer quebrado.

Quem está corrigindo

Sinalizado como específico do Flash e do lado do OD. A investigação está em andamento no caminho de escrita no stdin do daemon — o write EOF diz que o stdin do filho fechou antes de o daemon terminar de escrever o prompt, então a correção vive em como essa variante específica é iniciada.

O DeepSeek TUI tem um teto de prompt de 30 KB no Windows

Issue #1610 — bug, aberta

Sintoma

No wrapper DeepSeek v0.8.33 em um build empacotado para Windows, um prompt longo composto falha na nossa guarda pré-voo com 81397 > 30000 bytes. O usuário não fez nada de errado — apenas compôs um prompt rico o suficiente (contexto de sistema, design system, referências) para passar de 30 KB.

Por que acontece

Essa guarda é intencional, e está protegendo você de um erro pior. O adaptador DeepSeek TUI atualmente envia o prompt como um argumento posicional de linha de comando — atrelado ao argv — e o Windows limita o total da linha de comando bem abaixo do que macOS e Linux limitam. Sem a checagem pré-voo, o mesmo prompt falharia mais tarde, mais fundo no spawn, com um erro ENAMETOOLONG muito menos útil e nenhuma dica de que a causa era o tamanho do prompt. Então falhamos cedo e nomeamos o número. O descompasso que a issue expõe está na documentação: a orientação de alto nível dá a entender que os fallbacks de prompt longo no Windows se aplicam amplamente, mas o caminho do DeepSeek TUI ainda não tem um — seu transporte ainda é argv, não stdin nem um arquivo de prompt.

Contorno

Se você está no Windows com o adaptador DeepSeek TUI, mantenha o prompt composto abaixo de 30 KB, ou troque para um adaptador baseado em stdin — Claude Code, Codex e OpenCode todos recebem o prompt via stdin e não têm um teto comparável. No macOS e no Linux essa issue não morde de jeito nenhum; o limite de argv lá é alto o suficiente para que prompts do mundo real não o alcancem.

Quem está corrigindo

A correção certa é um transporte por stdin ou arquivo de prompt para o adaptador DeepSeek TUI, o que remove o teto de argv por completo e o alinha aos adaptadores de stdin. Está rastreado na fila do time de adaptadores.

O teste de CLI local do OpenCode estoura o tempo antes de o modelo aquecer

Issue #1603 — bug, priority:p0, aberta

Sintoma

Em Configurações → BYOK → OpenCode, o teste de conexão estoura o tempo de forma confiável aos 45 segundos. A parte estranha: se o usuário primeiro abre o terminal do OpenCode Desktop e anexa um LLM local ali, o mesmo teste do Open Design então é bem-sucedido na próxima tentativa.

Por que acontece

Esse detalhe de “abra o terminal do Desktop primeiro” é a pista inteira. O Open Design não se anexa a uma sessão do OpenCode Desktop em execução. Para um smoke test de Configurações, o daemon inicia o seu próprio subprocesso novo do CLI do OpenCode e espera por uma resposta ok. Com um modelo local frio — um que ainda não foi carregado na memória — essa primeira resposta pode levar mais que o orçamento de 45 segundos, porque o modelo está sendo lido do disco e aquecido antes de poder responder qualquer coisa. Abrir o terminal do Desktop e deixá-lo responder um prompt aquece o modelo no cache do SO de um jeito do qual o subprocesso novo do daemon pode então se beneficiar imediatamente. Então não é realmente um bug do OpenCode; é uma suposição de timing de cold-start que está errada para modelos locais.

Contorno

Antes de testar o OpenCode no Open Design, abra o OpenCode Desktop, anexe seu LLM local e deixe-o responder um prompt. Depois rode o teste de conexão do OD — o modelo está aquecido e a resposta cai dentro do orçamento. A partir da v0.7.0, o orçamento do teste de conexão também é configurável, então se o seu modelo local é genuinamente lento para carregar você pode aumentar a janela em vez de aquecê-lo na mão.

Quem está corrigindo

A correção do lado do daemon é uma janela de aquecimento maior ou configurável especificamente para adaptadores de modelo local, para que um modelo local frio não seja julgado pelo mesmo relógio de uma API hospedada. Está rastreada como p0 — a maior prioridade das cinco, porque usuários de modelo local são exatamente o público que o BYOK pretende servir.

O web app empacotado se recusa a carregar via HTTP simples

Issue #1620 — bug, aberta

Sintoma

Bug ligeiramente diferente, mesma família. O reportante está rodando o web app empacotado em um IP de LAN via HTTP simples, e a página dá erro ao carregar — ela nunca atinge um estado utilizável.

Por que acontece

Depois do PR #1428, o provider de analytics e o nonce de exportação de PDF começaram a chamar crypto.randomUUID() diretamente, contornando o helper em camadas introduzido no PR #900 que faz fallback graciosamente quando a API de cripto segura não está disponível. O Chromium não expõe crypto.randomUUID em contextos não seguros — e um IP de LAN puro via HTTP simples é, pela definição do Chromium, um contexto não seguro. Então a chamada direta lança erro em tempo de carregamento, e a página cai junto. Não é estritamente um bug de BYOK, mas morde exatamente o mesmo público: pessoas rodando a própria infraestrutura, muitas vezes isolada da rede, muitas vezes via HTTP simples porque levantar um certificado para uma ferramenta interna não vale o atrito.

Contorno

Sirva o web app via HTTPS ou via localhost. Ambos satisfazem o requisito de contexto seguro do Chromium — localhost é tratado como seguro mesmo sem certificado — e a página carrega normalmente. Para uma configuração interna rápida, localhost é o caminho de custo zero; para acesso por LAN, um certificado autoassinado via HTTPS é o caminho durável.

Quem está corrigindo

O PR #1621 roteia os pontos de chamada restantes de volta pelo helper de UUID em camadas do PR #900, para que o fallback de contexto seguro se aplique a tudo de novo, em vez de apenas onde já estava ligado. Está aberto e em revisão.

O que isso realmente diz sobre o BYOK no Open Design

Leia a lista como um mapa de contrato, não como um veredito de qualidade. Quatro destas cinco issues ficam em fronteiras de adaptador — o caminho de inicialização do CLI do Gemini, o transporte de CLI atrelado ao argv do DeepSeek, o modelo de inicialização de cold-start do OpenCode, as regras de contexto seguro da plataforma host. A quinta, a do Finish Design, está no nosso próprio endpoint de finalização, onde codificamos uma resposta no formato Anthropic uma release atrás e ainda não a generalizamos. Essa é por nossa conta; as outras quatro são o imposto que você paga por respeitar ferramentas que você não construiu.

E esse é o ponto estrutural. Todo sistema BYOK que não é um proxy reetiquetado acaba aqui. Ou você é dono da inferência — e perde o BYOK, porque agora você é quem compra os tokens e os remarca — ou você respeita as ferramentas upstream e herda as arestas delas: os CLIs delas, as peculiaridades de empacotamento delas, os limites de plataforma que cada uma trata de forma diferente. Escolhemos a segunda postura deliberadamente, e escolheríamos de novo. O custo são semanas que parecem esta, em que os times de daemon e adaptadores registraram trabalho em cinco superfícies em dois dias.

O trade-off continua certo. Uma configuração funcional em Claude Code, Codex, Cursor, Gemini Pro no macOS e DeepSeek no Linux — a matriz que cobre cerca de 90% dos nossos usuários reais — roda limpo hoje, sem imposto de proxy e sem margem sobre seus tokens. As cinco threads acima são o que os outros 10% da matriz parecem em meados de maio de 2026: nomeados, registrados e cada um com uma correção a caminho. Costuras honestas ganham de uma superfície lisa que esconde para onde a conta vai.

O que usar hoje (matriz)

Esta é a versão prática da seção acima — as mesmas cinco costuras, mapeadas para o que é seguro usar agora mesmo. Um ✓ significa que o caminho funciona como está; um ✗ linka a issue que o está bloqueando, com o contorno na seção relevante.

Provedor	macOS	Linux	Windows	Caminho do Finish Design
Claude Code (Sonnet / Opus)	✓	✓	✓	nativo
Codex	✓	✓	✓	nativo
Cursor (BYOK)	✓	✓	✓	nativo
Gemini 3 Pro Preview	✓	✓	✓	shim do OpenRouter (#1619)
Gemini 3 Flash Preview	✓	✓	✗ (#1611)	shim do OpenRouter (#1619)
DeepSeek (API)	✓	✓	✓	shim do OpenRouter
DeepSeek TUI (prompts longos)	✓	✓	✗ (#1610)	shim do OpenRouter
OpenCode (modelo local)	✓	✓	✓ (aqueça primeiro, #1603)	n/d

Duas leituras desta tabela. Se a sua stack está no bloco todo-✓ — Claude Code, Codex, Cursor ou Gemini Pro — você está no caminho limpo e nada acima muda o seu dia. Se você está em uma das linhas ✗, a seção correspondente tem o contorno que coloca você rodando hoje enquanto a correção linkada chega. De qualquer jeito, inscreva-se na label BYOK no rastreador se quiser uma notificação quando uma linha virar de ✗ para ✓.

O que fazer a seguir

A biblioteca de skills do Open Design é a camada de trabalho por baixo de tudo isso — os contratos orientados a arquivo que o adaptador BYOK alimenta uma vez que a conexão está saudável. As costuras acima são sobre levar bytes da sua chave ao modelo e de volta; as skills são o que o modelo de fato faz com eles. Se você quer ver o que uma skill consome do modelo e o que não lhe importa — o que também é por que essas arestas de adaptador não mudam a saída, só se você a alcança — esse diretório é o lugar certo para começar.

Navegue pela biblioteca de skills.

Leitura relacionada

• Fluxo de design BYOK: rode Claude, Codex ou Qwen com sua própria chave — o explicador original do BYOK, e o caminho que funciona, na borda do qual as cinco costuras acima ficam
• Por que construímos o Open Design como uma camada de skills, não um produto — por que respeitamos as ferramentas upstream em vez de embrulhá-las em um proxy, que é a razão inteira pela qual essas fronteiras existem
• 31 skills, 72 sistemas — como funciona a biblioteca — no que o BYOK de fato alimenta uma vez que a conexão está saudável