BYOK - Traga Sua Própria Chave

BYOK (Bring Your Own Key) é a forma padrão como o Kodus usa LLMs em todos os planos — Community, Teams e Enterprise. Você conecta sua própria conta de provedor, escolhe um modelo, paga apenas pelo que usa e monitora custos diretamente no painel do seu provedor. O Kodus nunca cobra margem sobre tokens e nunca vê sua chave em texto simples.

Como isso se aplica aos planos

O BYOK é gratuito no Community, incluído no Teams ($10/dev ativo/mês além do seu gasto com tokens) e uma das duas opções no Enterprise (a outra sendo uma chave de API gerenciada pelo Kodus).

Primeiros Passos

A tela de BYOK tem dois caminhos: escolher um modelo recomendado do catálogo curado (caminho mais rápido, 90% dos casos) ou configurar qualquer provedor manualmente (saída de emergência para endpoints personalizados ou modelos não curados).

Abrir as Configurações de BYOK

Acesse app.kodus.io/organization/byok.

Escolher um modelo recomendado

A seção modelo Main exibe uma grade de modelos curados que avaliamos para revisão de código. Clique em qualquer card para começar a conectá-lo.

Colar sua chave de API e testar

Cada card expande inline com uma única entrada — apenas a chave de API. Clique em Test para sondar o provedor, ou Test & save para rodar o teste e persistir a configuração em caso de sucesso.

Adicionar um Fallback (recomendado)

Uma vez que o modelo Main esteja configurado, uma seção modelo Fallback aparece. Se seu provedor principal atingir limites de taxa ou ficar indisponível, o Kodus faz fallback automaticamente.

Teste antes de salvar. O botão Test sonda seu provedor com uma chamada barata de metadados (nenhuma inferência de LLM é executada). Ele detecta chaves inválidas, URLs base erradas e problemas de rede antes que eles quebrem sua primeira revisão de código.

Modelos Recomendados

Estes seis modelos são curados para revisão de código. Todos aparecem no catálogo em /organization/byok e vêm pré-ajustados com padrões sensatos (temperature, max output tokens e reasoning effort definidos como medium).

Claude Sonnet 4.6

Melhor equilíbrio entre qualidade e custoO Sonnet mais recente da Anthropic. Extended thinking adaptativo, forte análise entre arquivos, janela de contexto de 200K.

Provedor: Anthropic
Model ID: claude-sonnet-4-6
Chave: console.anthropic.com

Claude Opus 4.7

Qualidade flagshipModelo de alto nível da Anthropic para as revisões mais difíceis. Contexto de 1M, preço premium.

Provedor: Anthropic
Model ID: claude-opus-4-7
Chave: console.anthropic.com

Gemini 3.1 Pro (custom tools)

Maior contextoFlagship do Google com suporte a custom tools. Janela de contexto de 1M — mais forte em PRs grandes e monorepos.

Provedor: Google Gemini
Model ID: gemini-3.1-pro-preview-customtools
Chave: aistudio.google.com/apikey

GPT-5.4

Rápido e consistenteO flagship mais recente da OpenAI. Baixa latência confiável, conhecimento amplo, contexto de 400K.

Provedor: OpenAI
Model ID: gpt-5.4
Chave: platform.openai.com/api-keys

Kimi K2.6 Coding

Especializado em código, baratoModelo ajustado para codificação da Moonshot AI. Dois planos: Developer API (pay-per-token) ou Kimi Code Plan (assinatura com endpoint dedicado).

Provedor: OpenAI-compatible (Moonshot AI)
Model ID: kimi-k2.6
Chaves: platform.moonshot.ai ou kimi.com/code

GLM 5.1

Melhor valor por assinaturaO mais recente da Z.ai. Dois planos: Developer API (pay-per-token) ou GLM Coding Plan (assinatura de taxa fixa).

Provedor: OpenAI-compatible (Z.ai)
Model ID: glm-5.1
Chaves: console z.ai ou z.ai/subscribe

Nossa recomendação padrão: Comece com o Claude Sonnet 4.6 para a melhor experiência geral de revisão de código. Se o custo for prioridade, o GLM 5.1 no Coding Plan ou o Kimi K2.6 no Kimi Code Plan oferecem assinaturas de taxa fixa que limitam seu gasto mensal.

Seletor de plano (GLM 5.1 e Kimi K2.6)

Z.ai e Moonshot ambos oferecem um plano de assinatura com um endpoint diferente da Developer API pay-per-token. O card curado para cada um desses modelos exibe um seletor de Plan para que você possa escolher o endpoint correto antes de colar sua chave.

GLM 5.1 (Z.ai)
Kimi K2.6 (Moonshot AI)

Plano	Endpoint	Chaves de	Melhor para
Developer API	`https://api.z.ai/api/paas/v4/`	z.ai/manage-apikey	Cargas variáveis, pay-per-token
Coding Plan	`https://api.z.ai/api/coding/paas/v4`	z.ai/subscribe	Volume previsível de equipe, taxa mensal fixa

Chaves do GLM Coding Plan funcionam apenas em /api/coding/paas/v4. Os tiers Lite e Pro geralmente são limitados a 1 requisição simultânea — o Kodus pré-preenche maxConcurrentRequests=1 quando você escolhe esse plano. Aumente em Advanced settings se estiver no tier Max (até 30).

Plano	Endpoint	Chaves de	Melhor para
Developer API	`https://api.moonshot.ai/v1`	platform.moonshot.ai	Pay-per-token, simultaneidade escala com o tier de recarga
Kimi Code Plan	`https://api.kimi.com/coding/v1`	kimi.com/code	Assinatura com endpoint de codificação dedicado

O Kimi Code Plan está documentado com um limite de 30 requisições simultâneas. O Kodus pré-preenche maxConcurrentRequests=30 quando você escolhe esse plano.

Configurar manualmente

Quando o modelo que você quer não está na lista curada (endpoint personalizado, LLM self-hosted ou um provedor que não avaliamos), clique em Configure manually no final do catálogo. Isso abre /organization/byok/manual?slot=main — um assistente passo a passo:

Escolha um provedor

Escolha entre OpenAI, Anthropic, Google Gemini, OpenRouter, Novita ou OpenAI Compatible (para qualquer endpoint no formato OpenAI).

Informe a URL base (se necessário)

Provedores OpenAI-compatible precisam de uma URL base explícita. O campo só aparece quando você escolhe esse provedor.

Escolha ou digite o Model ID

Se o Kodus conseguir listar modelos do provedor, você recebe um dropdown. Caso contrário (ex.: self-hosted ou quando chaves de plataforma não estão configuradas), digite o Model ID exato manualmente.

Cole a chave de API

O campo da chave aparece assim que provedor e modelo são definidos.

Ajustar configurações avançadas (opcional)

Temperature, max tokens, reasoning effort e max concurrent requests — todos opcionais. Os padrões são sensatos para a maioria dos provedores.

Testar e salvar

Clique em Test & save para rodar a sondagem de conexão e persistir em caso de sucesso.

A mesma rota manual funciona para Fallback — navegue com ?slot=fallback, ou use o link Add fallback após o Main estar salvo.

Provedores Suportados

Melhor para: modelos GPT mais recentes e desempenho confiável.Obter uma chave de API:

Acesse OpenAI API Keys
Crie uma nova chave para o Kodus
Adicione informações de cobrança

Melhor para: provedores especializados (Moonshot, Z.ai, Fireworks, Together, Groq, DeepSeek) ou endpoints self-hosted.Como configurar:

No assistente manual, escolha OpenAI Compatible como provedor.
Informe a URL base (ex.: https://api.moonshot.ai/v1, https://api.z.ai/api/paas/v4/, https://api.fireworks.ai/inference/v1).
Forneça a chave e o Model ID.

Guia Z.ai (GLM)

Configuração completa do Z.ai com detalhes do Coding Plan.

Guia Moonshot (Kimi)

Configuração Kimi K2.6 + Kimi Code Plan.

Fireworks AI

Configuração específica do Fireworks.

Together AI

Configuração do Together AI.

Reasoning / Extended Thinking

Todos os seis modelos recomendados suportam reasoning. O formulário BYOK expõe um toggle Thinking (Off / Low / Medium / High / Custom) em Advanced settings, pré-preenchido como Medium para cada modelo recomendado.

Níveis predefinidos

Quando você escolhe Low / Medium / High, o Kodus traduz o nível para o formato nativo de cada provedor automaticamente:

Provedor	Como “medium” mapeia
Anthropic (Claude Sonnet 4.6 / Opus 4.7)	`thinking: { type: "adaptive" }` + `outputConfig: { effort: "medium" }`
Google (Gemini 3.1 Pro)	`thinkingConfig: { thinkingLevel: "medium" }`
OpenAI (GPT-5.4)	`reasoningEffort: "medium"`
OpenRouter	`reasoning: { effort: "medium" }`
OpenAI-compatible (Kimi K2.6 / GLM 5.1)	`thinking: { type: "enabled" }` — on/off binário, nível ignorado

Kimi e GLM atualmente expõem reasoning como um flag único on/off. Escolher Low, Medium ou High emite o mesmo payload (thinking habilitado). Quando suas APIs adicionarem granularidade de nível, o Kodus começará a encaminhá-la.

Sobrescrita via JSON customizado

Escolher Custom no toggle Thinking revela uma textarea de JSON. Cole as opções do provedor diretamente — o Kodus faz o auto-wrap sob o namespace do provedor ativo. Você não precisa conhecer as regras de roteamento do Vercel AI SDK. Use isso quando:

Você precisa de um valor específico de budgetTokens para o Claude (em vez do mapeamento por effort predefinido)
Você quer habilitar/desabilitar thinking por modelo para provedores OpenAI-compatible
Você quer campos além de reasoning — caching, service tier, safety settings, tagging via user, etc. A sobrescrita é mesclada em providerOptions, então qualquer campo do adapter passa direto
O provedor lança um novo campo que o Kodus ainda não envolveu

Exemplos (cole direto — sem namespace)

Anthropic
Google Gemini
OpenAI
OpenRouter
OpenAI-compatible (Kimi, GLM, etc.)

Sobrescrever o budget de thinking do Claude para exatamente 20.000 tokens:

{
  "thinking": { "type": "enabled", "budgetTokens": 20000 }
}

Habilitar prompt caching (exemplo não-reasoning):

{
  "cacheControl": { "type": "ephemeral" }
}

Budget de thinking explícito (Gemini 2.5) ou nível (Gemini 3+):

{
  "thinkingConfig": { "thinkingBudget": 16000 }
}

Ajustar safety settings:

{
  "safetySettings": [
    { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE" }
  ]
}

Reasoning com campos específicos da OpenAI:

{
  "reasoningEffort": "high",
  "serviceTier": "flex",
  "store": false,
  "user": "kodus-review"
}

Forçar reasoning + ignorar um upstream específico:

{
  "reasoning": { "effort": "high" },
  "ignore": ["deepinfra"]
}

Habilitar thinking com uma dica de budget:

{
  "thinking": { "type": "enabled", "budget_tokens": 25000 }
}

Desabilitar thinking explicitamente:

{
  "thinking": { "type": "disabled" }
}

Campos que o provedor upstream não reconhece (ex.: budget_tokens em um servidor que ignora) são descartados silenciosamente. Verifique a documentação do provedor para confirmar o que ele aceita.

Usando namespaces manualmente (usuários avançados)

Se seu JSON já contém uma chave de namespace conhecida no nível superior (anthropic, google, openai, openrouter, openaiCompatible), o Kodus deixa intocado. Útil quando você quer misturar múltiplos namespaces de provedor ou ser explícito:

{
  "openrouter": {
    "reasoning": { "effort": "high" },
    "provider": { "order": ["moonshot"], "allow_fallbacks": false }
  }
}

Nos bastidores, estes são os mapeamentos de namespace que o Kodus usa:

Provedor BYOK	Chave de namespace
`anthropic`	`anthropic`
`google_gemini` / `google_vertex`	`google`
`openai`	`openai`
`open_router`	`openrouter`
`openai_compatible` / `novita`	`openaiCompatible`

Pegadinhas

Apenas JSON válido. Vírgulas faltando ou vírgulas finais quebram o parse e o Kodus ignora a sobrescrita.
Precedência: a sobrescrita JSON substitui totalmente o bloco de namespace do effort predefinido — se você sobrescrever anthropic.thinking mas esquecer anthropic.outputConfig, esse campo não será enviado. O roteamento do OpenRouter (Pin providers / Allow fallbacks) é a única exceção: ele faz deep-merge com sua sobrescrita sob openrouter.
Provedor desconhecido = sem wrap. Se seu provedor BYOK não está na tabela de namespace acima, o Kodus passa o JSON como está. Raro — só se aplica se você configurar um provedor que o Kodus não reconhece.

Fixando provedores do OpenRouter

O OpenRouter é um roteador — quando você solicita um modelo (ex.: moonshotai/kimi-k2.5), ele encaminha a chamada para um entre vários provedores upstream (Moonshot direto, Together, Groq, Fireworks, Novita…). Cada chamada pode cair em um backend diferente. Isso é conveniente, mas introduz variação silenciosa:

Variação de qualidade — upstreams rodam em precisões diferentes (FP8, INT4, full) e entregam saídas sutilmente diferentes para prompts idênticos
Inconsistência de tool-calling — alguns backends não suportam function calling da mesma forma, levando a uso de tool malformado
Variação no formato de reasoning — um upstream respeita reasoning_effort, outro só thinking.enabled, outro ignora ambos
Oscilação de latência — o p50 pode saltar de 800ms para 4s entre chamadas conforme o roteamento muda
Surpresas de rate-limit — você bate na cota de um backend que não escolheu explicitamente

Como fixar

Quando seu provedor BYOK é o OpenRouter, o painel Advanced settings exibe uma seção OpenRouter routing com dois campos:

Pin providers (in order) — lista separada por vírgulas com nomes dos upstreams (ex.: moonshot, together). O OpenRouter os tenta em ordem e usa o primeiro disponível.
Allow fallbacks — quando desativado, as requisições falham diretamente se nenhum dos provedores fixados estiver disponível. Quando ativado (padrão), o OpenRouter pode recorrer a qualquer outro upstream que sirva o modelo.

Para uma configuração estável, fixe um único provedor e desligue os fallbacks (Pin: moonshot, Allow fallbacks: off). As requisições sempre chegarão ao mesmo upstream ou falharão de forma explícita — sem mudanças silenciosas de qualidade. O trade-off é zero resiliência se esse upstream cair; combine com um BYOK Fallback diferente (ex.: Anthropic) para absorver indisponibilidades.

Os nomes dos upstreams devem corresponder ao catálogo do OpenRouter. Consulte as tags de provedor em openrouter.ai/docs/features/provider-routing — valores comuns incluem moonshot, together, groq, fireworks, novita.

Nos bastidores, o Kodus emite isto na chamada ao Vercel AI SDK:

{
  "openrouter": {
    "provider": {
      "order": ["moonshot", "together"],
      "allow_fallbacks": false
    }
  }
}

Avançado: sobrescrita via JSON bruto

Se você precisa de campos além de order e allow_fallbacks (ex.: ignore, data_collection, require_parameters), mude Thinking para Custom em Advanced settings e cole o payload de roteamento completo — ele é mesclado em providerOptions junto com qualquer configuração de reasoning:

{
  "openrouter": {
    "provider": {
      "order": ["moonshot"],
      "allow_fallbacks": false,
      "ignore": ["deepinfra"],
      "data_collection": "deny"
    },
    "reasoning": { "effort": "medium" }
  }
}

Simultaneidade e limites de taxa

O campo maxConcurrentRequests (em Advanced settings) limita quantas requisições em voo o Kodus envia ao seu provedor em paralelo. Na maioria das vezes, o padrão é suficiente — mas planos de assinatura com limites estritos de simultaneidade precisam defini-lo explicitamente.

Padrões que o Kodus pré-preenche

Provedor / plano	Valor pré-preenchido	Motivo
GLM Coding Plan (Lite/Pro)	`1`	A assinatura permite apenas uma requisição em voo. Ir além dispara 429.
GLM Coding Plan (Max)	`1` (aumente manualmente)	Max permite até 30, mas padronizamos pelo valor seguro. Aumente em Advanced settings.
Kimi Code Plan	`30`	Limite documentado da Moonshot no endpoint de coding.
GLM Developer API	(vazio)	Limites escalam por chave; não há padrão global sensato.
Kimi Developer API	(vazio)	Escala com seu tier de recarga (Tier 1 ≈ 50, Tier 5 ≈ 1000).
Anthropic / OpenAI / Google / OpenRouter	(vazio)	Provedores aplicam seus próprios TPM/RPM; o Kodus não limita.

Quando ajustar

Aumentar

Você tem uma recarga de tier alto na Moonshot/OpenRouter e quer mais throughput em PRs grandes
Você fez upgrade do seu GLM Coding Plan para Max e quer usar o budget completo de 30 simultâneas
As revisões parecem serializadas em PRs com muitos arquivos e você não vê 429s

Diminuir

Você vê erros 429 ou Too much concurrency nos logs de revisão
Seu provedor avisa sobre limites de taxa no painel
Você quer preservar a janela do Coding Plan (5h/semanal) em mais PRs

Simultaneidade vs. RPM vs. TPM. maxConcurrentRequests só limita requisições paralelas em voo. Muitos provedores também aplicam limites separados de RPM (requisições por minuto) e TPM (tokens por minuto). Se você está batendo em RPM/TPM enquanto a simultaneidade parece boa, a solução geralmente é fazer upgrade de tier ou distribuir a carga no tempo — não mudar maxConcurrentRequests.

Interação com Fallback. Quando o Main bate em 429 e o Kodus faz failover para o modelo Fallback, o maxConcurrentRequests do próprio Fallback se aplica. Definir um Fallback generoso em um provedor diferente é uma boa forma de absorver picos quando seu Main está em uma assinatura apertada.

Boas Práticas

Segurança

Chaves Dedicadas

Crie chaves de API separadas para o Kodus. Facilita auditoria de uso e rotação de chaves.

Rotação Regular

Rotacione as chaves periodicamente e atualize-as nas configurações BYOK.

Monitorar Uso

Verifique os painéis do seu provedor em busca de padrões incomuns.

Armazenamento Seguro

Nunca faça commit de chaves em repositórios. O Kodus armazena as chaves criptografadas em repouso e em trânsito.

Estratégia de Fallback

Use provedores diferentes para Main e Fallback (ex.: Anthropic como main, Google como fallback). Protege contra indisponibilidades específicas de um provedor.
Assinaturas com limites de simultaneidade apertados (GLM Coding Plan Lite/Pro, Kimi Code Plan) fazem configurações solo ruins — combine-as com um Fallback pay-per-token para que PRs em picos não fiquem sem recursos.

Solução de Problemas

'Chave de API inválida' ao clicar em Test

Copie a chave sem espaços extras, aspas ou quebras de linha finais.
Confirme que o faturamento está habilitado e que a conta tem créditos.
Para chaves do GLM Coding Plan / Kimi Code Plan, certifique-se de ter escolhido o Plan correspondente no card — chaves de assinatura não funcionam no endpoint Developer API e vice-versa.

'Endpoint não encontrado' ao clicar em Test

Verifique se a URL base corresponde exatamente ao provedor (barra final importa para alguns).
Para provedores OpenAI-compatible, o endpoint de modelos geralmente é {baseURL}/models.

Modelo não encontrado no momento da revisão (teste da chave passou)

O botão Test valida a chave/endpoint mas não verifica o Model ID específico. Se você digitou um modelo que não existe (typo), a primeira revisão real falha.
Confira o Model ID contra o catálogo do provedor antes de salvar.

'Rate limited' ou 'Too much concurrency'

Reduza Max concurrent requests em Advanced settings.
No GLM Coding Plan Lite/Pro, mantenha em 1 concurrent. Faça upgrade para Max (30 concurrent) se precisar de mais throughput.
No Kimi Code Plan, o limite documentado é 30 concurrent.

Variáveis de ambiente self-hosted não aparecem

Se o Kodus está configurado via .env (Fixed Mode self-hosted), a tela de BYOK exibe um banner informativo azul com o provedor/modelo ativo — a chave nunca é exibida por segurança.
Salvar uma configuração BYOK por cima do .env solicita um diálogo de confirmação antes de sobrescrever.

Custos altos ou inesperados

Reasoning adiciona tokens. Se o custo está disparando, reduza Thinking de Medium para Low, ou mude para um modelo mais barato como Main.
Verifique o painel do seu provedor para o detalhamento por modelo.
Defina um limite mensal no nível do provedor.

Perguntas Frequentes

Posso trocar de provedor a qualquer momento?

Sim. A mudança tem efeito na próxima revisão — sem necessidade de redeploy.

O que acontece se minha chave de API ficar sem créditos?

As revisões mudam automaticamente para o modelo Fallback se um estiver configurado. Sem um Fallback, a revisão falha e retorna um erro. Sempre configure um Fallback.

Como funciona o sistema primário/fallback?

O Main lida com todas as revisões por padrão. Se falhar (rate limit, 5xx, timeout), o Kodus tenta novamente uma vez no Fallback. Você paga apenas pelo provedor que efetivamente processou a revisão.

Devo usar o mesmo provedor para Main e Fallback?

Não. Provedores diferentes protegem contra indisponibilidades específicas de um provedor. Um pareamento comum: Anthropic como Main + Google como Fallback, ou GLM Coding Plan como Main + Anthropic como Fallback para cobrir picos.

Vocês armazenam nossas chaves de API com segurança?

Sim. As chaves são criptografadas em repouso e em trânsito e nunca são registradas em texto simples. O endpoint de status BYOK nunca retorna a chave bruta.

Posso usar um LLM self-hosted (ex.: Ollama, vLLM)?

Sim — via o provedor OpenAI Compatible no assistente manual. Informe a URL base do seu endpoint, o Model ID que ele expõe e uma chave de API placeholder (a maioria dos runtimes self-hosted ignora o header da chave, mas ainda exige um).

Primeiros Passos

Cobrança e Licenças

Revisão de Código com IA

CLI

Cockpit

Kody Issues

Organização

Segurança

Solução de Problemas

Documentation Index

Como isso se aplica aos planos

​Primeiros Passos

​Modelos Recomendados

Claude Sonnet 4.6

Claude Opus 4.7

Gemini 3.1 Pro (custom tools)

GPT-5.4

Kimi K2.6 Coding

GLM 5.1

​Seletor de plano (GLM 5.1 e Kimi K2.6)

​Configurar manualmente

​Provedores Suportados

Guia de Configuração Novita

Guia Z.ai (GLM)

Guia Moonshot (Kimi)

Fireworks AI

Together AI

​Reasoning / Extended Thinking

​Níveis predefinidos

​Sobrescrita via JSON customizado

​Exemplos (cole direto — sem namespace)

​Usando namespaces manualmente (usuários avançados)

​Pegadinhas

​Fixando provedores do OpenRouter

​Como fixar

​Avançado: sobrescrita via JSON bruto

​Simultaneidade e limites de taxa

​Padrões que o Kodus pré-preenche

​Quando ajustar

Aumentar

Diminuir

​Boas Práticas

​Segurança

Chaves Dedicadas

Rotação Regular

Monitorar Uso

Armazenamento Seguro

​Estratégia de Fallback

​Solução de Problemas

​Perguntas Frequentes

Primeiros Passos

Modelos Recomendados

Seletor de plano (GLM 5.1 e Kimi K2.6)

Configurar manualmente

Provedores Suportados

Reasoning / Extended Thinking

Níveis predefinidos

Sobrescrita via JSON customizado

Exemplos (cole direto — sem namespace)

Usando namespaces manualmente (usuários avançados)

Pegadinhas

Fixando provedores do OpenRouter

Como fixar

Avançado: sobrescrita via JSON bruto

Simultaneidade e limites de taxa

Padrões que o Kodus pré-preenche

Quando ajustar

Boas Práticas

Segurança

Estratégia de Fallback

Solução de Problemas

Perguntas Frequentes