--- title: "Modelos" description: "Como o Beeuni escolhe um modelo e como funciona o faturamento para modelos gerenciados e modelos com sua própria chave." --- O Beeuni executa cada [sessão](/docs/pt/work/sessions) em um modelo. Esta página explica modelos gerenciados e modelos com sua própria chave de provedor (BYOK), como o Beeuni escolhe um modelo automaticamente e dois detalhes importantes sobre cobrança. Esta página se aplica a projetos com o LLM Gateway ativado. O LLM Gateway é um [flag de recurso](/docs/pt/feature-flags) experimental, **ativado por padrão** onde a plataforma o oferece — confira ou alterne em Configurações → Flags de recurso . Desativar o flag é uma opção totalmente compatível. O projeto passa então a usar o **gerenciamento de modelos nativo do harness padrão**. Cada sessão desse projeto usa o [harness](/docs/pt/work/harnesses) do harness padrão: o harness experimental chama modelos somente pelo gateway. - Suas chaves de API de provedor (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, …) são injetadas no sandbox como variáveis de ambiente comuns — adicione-as na página de configurações de Modelos ou como [segredos](/docs/pt/project/secrets). O harness padrão se conecta automaticamente a cada provedor usando sua chave. - Os IDs de modelo são referências `provider/model` nativas do harness padrão, como `anthropic/claude-opus-4-8`. IDs simples gerenciados e referências `beeuni/…` não existem fora do gateway. - O seletor de modelos mostra uma lista antes e depois da inicialização do sandbox: os provedores aos quais suas chaves se conectam, além dos modelos gratuitos do OpenCode Zen (o OpenCode se conecta a eles sem uma chave). O nível de esforço de raciocínio é o controle de raciocínio do compositor (variantes próprias do modelo); os padrões de geração do gateway não se aplicam. - As opções do gateway exibidas nesta página — modelos gerenciados, cadeia de modelos padrão, limites e registros — não se aplicam; o OpenCode resolve o modelo padrão no sandbox. ## Modelos gerenciados e BYOK Um ID de modelo tem um de três formatos: - **Gerenciado** — um ID simples, como `glm-5.2`, `deepseek-v4-pro-0813` ou `grok-4.6`. O Beeuni fornece as credenciais. Contas na nuvem pagam com créditos Beeuni. - **BYOK** — um ID `provider/model`, como `anthropic/claude-opus-4-8`. Você fornece a chave. Sua conta do provedor paga. - **ChatGPT** — um ID `codex/`. Você conecta seu plano ChatGPT uma vez por OAuth, e ele paga. Conecte uma chave BYOK na página de configurações de Modelos do projeto ou defina diretamente a variável de ambiente do provedor como um [segredo](/docs/pt/project/secrets). Cada provedor lê sua própria chave. Alguns provedores compartilham uma variável de ambiente em models.dev; por exemplo, OpenCode Zen (`opencode`) e OpenCode Go (`opencode-go`) listam `OPENCODE_API_KEY`. O provedor que é dono do nome o mantém. Todos os outros provedores leem `_API_KEY`: OpenCode Go lê `OPENCODE_GO_API_KEY`, Z.ai Coding Plan lê `ZAI_CODING_PLAN_API_KEY` e Moonshot China lê `MOONSHOTAI_CN_API_KEY`. Portanto, uma chave Zen nunca lista modelos Go. O formulário de conexão e `beeuni providers set` usam o nome correto. ### OpenCode Zen e Go (entrar com OpenCode) Conecte o OpenCode Zen ou o OpenCode Go com uma chave de API, ou entre com sua conta do OpenCode Console: 1. Abra **Customize → Models → Providers** e encontre **OpenCode Go**. 2. Escolha **Sign in with OpenCode**. Copie o código, escolha **Open auth page** e autorize o dispositivo no seu workspace do OpenCode. 3. O campo da chave mostra o provedor como conectado. Remova a chave para sair. Pela CLI: `beeuni providers login opencode-go`, ou `beeuni providers login opencode` para o Zen. Os modelos Zen são usados pelo ID; por exemplo, `opencode/glm-5.3-flash`; o seletor não os lista. Zen e Go mantêm logins próprios, então entrar em um nunca conecta o outro. O login dura 30 dias, e o Beeuni o renova antes de expirar. Quando o OpenCode recusa um login, o Beeuni o renova uma vez e tenta a solicitação novamente. Se a renovação também falhar, a solicitação retorna `provider_reauth_required`: entre novamente. ### Modelos gerenciados pelo Beeuni O seletor os lista em **Beeuni**, com suas tarifas por token. A plataforma fornece as credenciais por meio do gateway de modelos configurado. | Modelo | ID | | --- | --- | | GPT-6 Astra | `gpt-6-astra` | | GPT-6 Sol (padrão da plataforma) | `gpt-6-sol` | Use outros modelos com uma chave BYOK ou um plano ChatGPT. Uma chave BYOK dá acesso a todo o catálogo do provedor; por exemplo, `anthropic/claude-opus-5-5` com uma chave Anthropic. Um plano ChatGPT oferece todos os modelos que o Codex disponibiliza para uma conta ChatGPT; por exemplo, `codex/gpt-6.1-sol`. Por padrão, o seletor mostra o modelo mais recente de cada família. As duas listas são atualizadas automaticamente. A API consulta [models.dev](https://models.dev) e a lista de modelos publicada pela CLI do Codex a cada hora, então uma nova versão aparece até uma hora depois de ser listada, sem precisar de uma versão do Beeuni. Quando você conecta um provedor, o modelo estável mais recente dele com chamada de ferramentas se torna o padrão. ## Desativar provedores ou modelos Abra **Customize → Models → Providers**. Abra o menu **⋯** na linha **Beeuni** e escolha **Disable provider** para usar apenas seus próprios provedores. O Beeuni aparece na mesma lista que os outros provedores, com a quantidade de modelos e uma descrição da cobrança por créditos. Todos os provedores usam o mesmo menu. Somente provedores desativados exibem um selo de status. Escolha **Enable provider** no menu para restaurar o acesso. Abra a aba **Models** para ativar ou desativar modelos individuais. Um provedor desativado bloqueia todos os seus modelos, inclusive os adicionados posteriormente. Reativar o provedor preserva as escolhas individuais de modelos. As credenciais continuam salvas. Não é possível desativar o provedor e o modelo padrão do projeto. Selecione primeiro outro padrão ativado. Gerentes de projeto podem alterar o acesso; leitores podem consultá-lo. Esses controles se aplicam a novas solicitações pelo gateway do Beeuni, incluindo seleções salvas da sessão e candidatos de fallback. Uma solicitação já enviada a um provedor upstream termina normalmente. Destinos desativados retornam `provider_disabled` ou `model_disabled`; escolha um modelo ativado para continuar. O modo nativo do harness padrão não usa essa política do gateway. As preferências existentes de visibilidade apenas no seletor continuam separadas. Redefinir a lista de modelos não remove restrições de acesso explícitas. ## Nível de esforço de raciocínio O controle de raciocínio do compositor define a **variante** do modelo da sessão nos dois modos. As opções são os níveis publicados pelo próprio modelo (models.dev `reasoning_options`), nunca uma escala fixa; modelos sem esse controle não exibem nenhuma opção. `Auto` limpa a variante. - Nativo (gateway desativado): o harness padrão aplica a variante no campo de solicitação próprio do provedor. - Gateway ativado: a solicitação inclui `reasoning_effort`; o gateway faz o mapeamento por provedor upstream (OpenAI → `reasoning_effort`, Claude → raciocínio adaptativo, OpenAI no Amazon Bedrock → campo de solicitação `reasoning.effort` do Bedrock). Para um provedor upstream que ainda não consegue mapear (Nova, Grok no Bedrock atualmente), o valor é descartado e o modelo usa seu próprio padrão. - O Amazon Bedrock recusa o ID simples na região da maioria dos modelos atuais (“a taxa de transferência sob demanda não é compatível”). O seletor prefere o ID de perfil de inferência `global.` / regional quando o catálogo o inclui, e o gateway tenta novamente um ID simples recusado uma vez por prefixo de perfil (`global.`, `us.`). - O sandbox consulta à API o conjunto de modelos disponíveis para o projeto a cada inicialização (`GET /v1/llm/models?scope=picker`, a mesma composição do seletor da web), para que um modelo oferecido no seletor sempre possa ser resolvido no ambiente de execução. - Um padrão de geração por modelo do projeto fica em Customize → Models → Routing → Advanced → **Generation defaults** (`model_generation_config`). Ele preenche apenas um campo não definido na solicitação, então a variante da sessão sempre prevalece. ## Como o modo automático escolhe um modelo Não defina nenhum modelo, e o Beeuni resolverá um seguindo até cinco camadas, nesta ordem. (O ID `auto` abrange esse mesmo comportamento, mas ainda não é uma opção selecionável no seletor de modelos.) 1. Uma definição explícita — o campo `model:` da própria sessão, canal ou acionador. 2. O padrão do [agente](/docs/pt/project/agents) para este projeto. 3. O padrão do projeto. 4. O padrão da conta. 5. O padrão da plataforma. O Beeuni usa a primeira camada com um valor que ainda pode atender à solicitação. Um padrão salvo que deixa de funcionar — uma chave desconectada, um modelo descontinuado — é ignorado automaticamente. Uma sessão nunca termina por causa de um padrão desatualizado. Consulte a [referência do manifesto](/docs/pt/project/manifest) para o campo `model:` do acionador. :::warning[Surpresas na cobrança de BYOK] É fácil não perceber dois custos em uma conta na nuvem paga: - Os créditos cobrem chamadas de modelos, ferramentas e uso do computador. Consulte Billing para o saldo e Usage para os detalhes. - **Fallback silencioso.** Se sua chave BYOK atingir um limite de taxa ou apresentar um erro de cobrança durante uma rodada, o Beeuni tenta novamente com um modelo gerenciado e cobra seus créditos em vez de encerrar a sessão com erro. Se você encontrar cobranças de créditos em um projeto que usa somente BYOK, verifique essas duas causas antes de relatar um erro de cobrança. ::: Quando um modelo de fallback responde, a sessão informa isso. O compositor mostra **Running on** e o nome do modelo ao lado do seletor de modelos. Os detalhes de cada rodada identificam o modelo que respondeu, o modelo que ele substituiu e o valor cobrado pelo Beeuni naquela rodada. **Customize → Models → Costs** contabiliza esse gasto no modelo que respondeu. ## Ativação de modelos por projeto O projeto controla quais modelos seus seletores oferecem. Por padrão, o modelo mais recente de cada família é oferecido automaticamente. Modelos gerenciados pelo Beeuni e qualquer modelo referenciado pelos padrões ou pela política de roteamento do projeto são sempre oferecidos — uma regra nunca os remove. Você pode substituir o padrão para modelos individuais na página **Manage models** (Customize → Models). A exceção fica salva por projeto e entra em vigor imediatamente. O seletor de modelos da sessão e a paleta de comandos ocultam o que você desativar; novos modelos continuam ativados por padrão à medida que o catálogo cresce. A ativação determina o que é oferecido, não o que é servido: uma solicitação que especifica diretamente um modelo desativado (por exemplo, pela API bruta) ainda é executada. Não é possível desativar o modelo padrão do projeto — defina outro padrão primeiro. ## Chaves de provedor e acesso de membros Com **Pooled provider secrets** desativado, uma chave de provedor conectada se aplica ao projeto inteiro. Substituições pessoais para esses segredos do projeto retornam `llm_credentials_project_wide`. Ative **Pooled provider secrets** e **LLM Gateway** em Configurações → Flags de recurso para usar recursos de segredos do provedor. Abra **Customize → Models → Providers** e escolha **Add key** ao lado de um provedor. Dê a cada chave um rótulo diferente. O valor é somente para gravação; as telas seguintes mostram o rótulo e a lista de acesso. As novas chaves pertencem a este projeto. Por padrão, **Everyone in this project** pode usá-las. Abra o menu **⋯ → Manage access** de uma chave e escolha **Specific members** para restringir o acesso. Recursos antigos no nível da conta mantêm as concessões de acesso dos membros. A associação à conta, as permissões do projeto, as permissões do agente para segredos e a seleção da sessão continuam se aplicando. Uma concessão a um membro permite o uso sem revelar a chave. A rotação de uma chave preserva o acesso e as seleções de sessão. Excluí-la remove o acesso de todos. ### Escolher chaves para uma sessão Abra **Session overrides → Provider keys** no compositor. Escolha um provedor e selecione até dez chaves. Escolha **Save changes** no rodapé do painel. Em uma nova sessão, a seleção é enviada junto com a primeira solicitação. - Sem uma seleção explícita, a chave existente do projeto continua disponível. - Selecionar nenhuma chave desativa esse provedor para a sessão. Isso não restaura a chave do projeto. - **Reset to project default** remove a seleção explícita. - Chaves revogadas ou inativas aparecem como indisponíveis. Remova-as da seleção, escolha outra chave ou redefina a seleção. - Excluir a última chave selecionada deixa o conjunto vazio. As configurações da sessão ainda mostram esse provedor para que você possa redefini-lo. - Uma falha de leitura exibe **Try again**. Ela nunca aparece como uma seleção herdada. Se houver um limite de taxa antes do início da saída, o gateway tentará usar outra chave selecionada. Ele nunca reproduz novamente uma resposta parcial usando outras chaves. Se todas as chaves atingirem o limite de taxa, tente novamente após o período de espera mais curto, limitado a 60 segundos. Um conjunto explícito não empresta silenciosamente a chave de outro membro nem a credencial antiga do projeto. ### Contas ChatGPT Escolha **Add account** em **ChatGPT Plus/Pro**. Cada autorização cria uma conexão separada, com nome próprio, neste projeto. Por padrão, **Everyone in this project** pode usá-la. Use **Manage access → Specific members** para restringir o acesso. Uma sessão pode selecionar várias contas ChatGPT às quais o membro tem acesso. Sem uma seleção, a conexão utilizável mais recente do membro é o padrão. A conexão compartilhada de outro membro exige uma seleção explícita. O login antigo do projeto continua disponível quando o membro não tem uma conexão própria utilizável. Uma chave de gateway compartilhada não pode usar a conexão ChatGPT privada de quem a criou. Com o gateway ativado, as chaves de API do Google Gemini usam o endpoint compatível com OpenAI do Google. O modo nativo do harness padrão continua usando os segredos do projeto. Modelos ocultados pelas preferências antigas do seletor exibem **Hidden from picker**. Solicitações diretas continuam permitidas. Abra o menu desse modelo e escolha **Disable model** para também bloquear a inferência. Os links de quantidade de modelos do provedor abrem a aba **Models**. Todos os grupos de provedores aparecem juntos na mesma lista usada para ativar ou desativar modelos e definir padrões. A busca filtra a lista. Conecte um provedor antes de gerenciar seus modelos. As seleções de provedores permanecem como rascunhos até você clicar em **Save changes** no rodapé das substituições da sessão. Isso salva as alterações de todos os provedores, inclusive a redefinição para o padrão. Você pode trocar de seção ou fechar e reabrir o painel sem perder esses rascunhos. Recarregar a página descarta as alterações não salvas. Se uma gravação falhar, o painel permanece aberto e mostra o erro. Corrija a seleção ou tente novamente. Provedores já salvos permanecem salvos; as alterações pendentes continuam no painel. ## Limites Um limite do gateway restringe quanto um projeto, ou um membro nele, gasta com modelos por dia, semana ou mês. **Block** recusa novas solicitações ao atingir o limite; **Warn only** permite que elas sejam executadas. Defina limites na página Modelos do projeto. Ao atingir 80% e 100% do limite, o Beeuni envia um e-mail aos responsáveis e administradores da conta e aos gerentes do projeto, uma vez por limite em cada período. ## Usar o gateway no Claude Code O gateway disponibiliza a API Anthropic Messages em `POST /v1/messages`. O Claude Code e os SDKs da Anthropic podem chamar qualquer modelo do gateway por meio dela. 1. Crie uma chave em **Customize → Gateway**, na aba **Gateway**. 2. Inicie o Claude Code com o gateway como endpoint da API: ```bash ANTHROPIC_BASE_URL=https://gateway.beeuni.ai \ ANTHROPIC_AUTH_TOKEN=beeuni_gw_... \ claude --model kimi-k3 ``` O gateway lê a chave de `Authorization: Bearer` ou de `x-api-key`, então `ANTHROPIC_API_KEY` também funciona. O gateway traduz estes campos do Claude Code para cada provedor: - `thinking: {type: "adaptive"}` com `output_config.effort` se torna `reasoning_effort`. Consulte [Esforço de raciocínio](#thinking-effort). - O uso no `message_delta` final inclui `input_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. O Claude Code os usa para `/context` e compactação automática. - Imagens retornadas por uma ferramenta, como um `Read` de uma captura de tela, chegam ao modelo em uma mensagem do usuário após o resultado da ferramenta. - Um fluxo do provedor que termina antes da conclusão retorna um evento `api_error`, então o Claude Code tenta novamente a interação. Limitações: - `/v1/messages/count_tokens` retorna `404`. Então, o Claude Code estima as contagens a partir dos caracteres. - O texto de raciocínio não é retornado como blocos `thinking`. - Os modelos ChatGPT (`codex/*`) precisam de uma conexão do ChatGPT compartilhada com **Todos neste projeto**. Uma chave de gateway não pode usar uma conexão privada. - O Claude Code não pode definir uma janela de contexto por modelo. Defina `CLAUDE_CODE_MAX_CONTEXT_TOKENS` como a menor janela que você usa.