Conecte sua própria chave de modelo

Use uma chave de um provedor ou gateway de modelos. Uma conexão bem-sucedida exige provedor, endpoint, ID do modelo e permissão da conta correspondentes.

Reúna os detalhes da conexão

Você precisa de uma API Key do serviço que pretende chamar, da Base URL da API, de um ID de modelo disponível e de um protocolo ou preset compatível. Ter uma conta em um site de chat para consumidores não fornece, por si só, acesso à API nem créditos de API.

Selecione o provedor e faça a correspondência entre a chave, a Base URL da API e o modelo.

Todos os planos, incluindo o Free, são compatíveis com BYOK. Sua chave do provedor usa a cobrança e a franquia desse provedor, e não o saldo do OpenDesign.

Adicione o provedor

Abra Settings → Models & providers → API providers.
Escolha o preset do serviço que emitiu sua chave. Para Custom provider, use o protocolo documentado por esse serviço.
Cole apenas o segredo em API Key. Não adicione Bearer, aspas nem um wrapper de configuração JSON.
Verifique Base URL. Se o endereço de um preset estiver bloqueado, use a opção de URL personalizada antes de inserir outro endpoint.
Escolha um modelo na lista disponível ou insira o ID exato do modelo da API em Custom. O carregamento de modelos depende do serviço e da conta.
Execute Test. Leia a resposta: um teste bem-sucedido verifica essa pequena solicitação, não todas as ferramentas, modelos de mídia ou solicitações futuras.
Aguarde a confirmação de que os dados foram salvos. Reabra Settings para verificar o provedor, o endereço e o modelo. Depois, volte ao projeto e selecione essa conexão antes de enviar uma pequena tarefa.

Mantenha a chave privada. O campo pode ser revelado com Show para inspeção local; oculte a chave antes de compartilhar uma captura de tela.

O OpenRouter usa sua própria chave, seu endereço de gateway e IDs de modelo com prefixo do provedor.

Exemplo: DeepSeek

Crie uma chave na DeepSeek Platform. Use https://api.deepseek.com como Base URL e escolha um modelo que sua conta possa chamar. Use um ID da lista atual de modelos do provedor, por exemplo deepseek-flash; a captura de tela do cliente instalado ainda contém um alias de preset antigo. Quando necessário, insira o ID atual como um modelo personalizado. O atalho Get key da versão 0.25.0 instalada pode abrir a página do provedor errado. Use o próprio console do provedor em vez de criar uma chave da OpenAI sem relação com o serviço.

Campo	Exemplo de conexão direta com a DeepSeek
Provedor/protocolo	Preset da DeepSeek ou um preset personalizado compatível com o protocolo OpenAI
API Key	Uma chave emitida pela sua conta da DeepSeek Platform
Base URL	https://api.deepseek.com
ID do modelo	deepseek-flash, se estiver habilitado para sua conta

Copie o ID exato da documentação atual da API da DeepSeek, e não o nome de exibição presente em uma captura de tela antiga. Para este exemplo com o protocolo OpenAI, não use o endpoint /anthropic separado.

Exemplo: OpenRouter

Crie uma chave nas configurações de chaves do OpenRouter. Use https://openrouter.ai/api/v1. Copie um ID de modelo da lista de modelos disponíveis do OpenRouter, incluindo o prefixo do provedor. Não insira uma chave direta da Anthropic ou da OpenAI no preset do OpenRouter. A chave pertence ao gateway que recebe a solicitação.

Escolha OpenRouter em API providers e cole uma chave emitida pelo OpenRouter.
Use https://openrouter.ai/api/v1 como Base URL.
Copie o ID exato do modelo do diretório de modelos do OpenRouter, incluindo o prefixo do provedor.
Teste a conexão, aguarde o salvamento e selecione-a no projeto antes de executar uma solicitação.

Verifique outro provedor

Detalhe	O que verificar
Protocolo	O preset deve corresponder ao protocolo de API documentado.
Base URL	Use a raiz da API esperada pelo preset, sem um caminho de painel nem um segmento de versão duplicado.
Modelo	Use o ID do modelo da API, não o nome comercial.
Permissão	Confirme o acesso ao modelo, a disponibilidade regional, a cota e o faturamento na conta do provedor.

Uma chave não é todo o ambiente de execução

As tarefas BYOK ainda precisam do ambiente de execução compatível que realiza as operações de arquivo e de ferramentas do agente. Se o aplicativo informar que o ambiente de execução está indisponível, siga as instruções de instalação ou nova verificação desse ambiente. Substituir a chave não instalará um executável.

Entenda o faturamento

As solicitações BYOK são cobradas pelo provedor ou gateway cuja chave você inseriu. Uma assinatura do OpenDesign e o saldo de um provedor externo são separados. Consulte faturamento e solução de problemas de conexão se uma chave válida ainda não conseguir executar uma tarefa.

Leia o resultado do teste e corrija o problema

Resultado	Próxima ação
401 / chave inválida	Verifique o serviço emissor e cole a chave completa sem formatação adicional. Substitua uma chave revogada na origem.
403 / acesso negado	Verifique com o provedor a permissão do modelo, a região e o acesso da conta. Um segredo válido, por si só, não concede acesso ao modelo.
404 / modelo não encontrado	Verifique a raiz da API e o ID exato do modelo. Remova caminhos de painel e segmentos /v1 duplicados.
429 / cota ou limite de taxa	Leia o erro do provedor para diferenciar saldo esgotado de um limite de taxa temporário. Verifique o console da conta antes de tentar novamente.
Tempo limite / erro de rede	Verifique se esse endpoint pode ser acessado pelo ambiente do cliente. Tente novamente com uma pequena solicitação após resolver o problema de rede.

Após um teste bem-sucedido, envie uma pequena solicitação no projeto existente e inspecione a resposta e qualquer arquivo criado. Se o teste for aprovado, mas as operações de arquivo falharem, verifique o ambiente de execução descrito na seção sobre o ambiente de execução; não substitua repetidamente uma chave que funciona.