# Modelos personalizados no Factory Droid: use Claude e GPT com sua própria chave de API > Adicione Claude, GPT e outros modelos ao Factory Droid com customModels no settings.json: qual provider escolher, uma configuração testada e os quatro erros. - Canonical HTML: https://omniakey.com/pt-BR/blog/factory-droid-custom-models - Markdown: https://omniakey.com/pt-BR/blog/factory-droid-custom-models.md - Published: 2026-10-30 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: pt-BR - Category: API setup - Reading time: 9 min - All posts: https://omniakey.com/blog/llms.txt --- Adicione cada modelo em `customModels` no arquivo `~/.factory/settings.json`, com `model`, `baseUrl`, `apiKey` e `provider`: use `anthropic` para Claude com o host puro, `openai` para GPT e `generic-chat-completion-api` para todo o resto. No Droid 1.0.0, Claude Sonnet 5.5, GPT-6.1 Terra e MiniMax M3.1 Flash corrigiram o mesmo bug em 33,7, 77,4 e 30,7 segundos. As três execuções passaram pela OmniaKey com uma única chave, e foi assim que chegamos a [Claude Sonnet 5.5](https://omniakey.com/pt-BR/claude-sonnet-5-5), [GPT-6.1 Terra](https://omniakey.com/pt-BR/gpt-6-1-terra) e [MiniMax M3.1 Flash](https://omniakey.com/pt-BR/minimax-m3-1-flash). Cada um recebeu a mesma função `median()` quebrada e a consertou. ## Resposta curta - **Onde fica.** `customModels` em `~/.factory/settings.json` (doc de configurações da Factory, verificada em 30 de outubro de 2026), com `model`, `baseUrl`, `apiKey` e `provider`. - **Qual provider.** `anthropic` para Claude, `openai` para modelos GPT, `generic-chat-completion-api` para todo o resto que fala Chat Completions. - **Onde entra o `/v1`.** `anthropic` usa o host puro, porque o Droid acrescenta `/v1/messages`; `openai` e `generic-chat-completion-api` usam uma URL terminada em `/v1`. - **O id para o `droid exec`.** `custom:`, o nome de exibição com hífens no lugar dos espaços e a posição contando de 0: `custom:Claude-Sonnet-5.5-[OmniaKey]-0`. - **O que as execuções mostraram.** Os três corrigiram o bug; 30,7 s para o Flash, 33,7 s para o Claude, 77,4 s para o GPT-6.1 Terra. ## Qual valor de provider usar? Escolha o provider pela API que o seu endpoint fala, não pelo nome do modelo. - `anthropic` envia requisições para a Anthropic Messages API. Use com Claude; a URL base da Anthropic é `https://api.anthropic.com`. - `openai` envia requisições para a OpenAI Responses API. Use com modelos GPT; a URL base da OpenAI é `https://api.openai.com/v1`. - `generic-chat-completion-api` envia requisições OpenAI Chat Completions. Use com a maioria dos outros modelos, gateways e servidores locais, com a URL `/v1` do próprio provedor. A Factory lista `generic-chat-completion-api` para OpenRouter, Fireworks, Together AI, Ollama, vLLM e a maioria dos provedores de código aberto, e recomenda esse valor a menos que você esteja chamando a API oficial da OpenAI ou da Anthropic (doc BYOK da Factory, verificada em 30 de outubro de 2026). Um gateway que também fala a Messages API ou a Responses API pode usar `anthropic` ou `openai`. Nossas entradas de Claude e GPT-6.1 Terra fizeram isso pela OmniaKey, e as duas rodaram; a OmniaKey serve modelos GPT em `POST /v1/responses` (doc da OmniaKey sobre compatibilidade com OpenAI, verificada em 30 de outubro de 2026). Um quarto valor, `bedrock-converse`, serve para modelos na API Converse do AWS Bedrock. A Factory avisa que só modelos Anthropic e OpenAI nas APIs oficiais são testados e comparados por completo, e que modelos com menos de 30 bilhões de parâmetros vão bem pior em programação agêntica (doc BYOK da Factory, verificada em 30 de outubro de 2026). ## O settings.json que usamos O Droid cria `~/.factory/settings.json` na primeira execução, então acrescente `customModels` ao arquivo que já está lá (doc de configurações da Factory, verificada em 30 de outubro de 2026). O nosso fica assim: ```json { "customModels": [ { "model": "claude-sonnet-5-5", "displayName": "Claude Sonnet 5.5 [OmniaKey]", "baseUrl": "https://api.omniakey.com", "apiKey": "${OMNIAKEY_API_KEY}", "provider": "anthropic", "maxOutputTokens": 16000 }, { "model": "gpt-6.1-terra", "displayName": "GPT-6.1 Terra [OmniaKey]", "baseUrl": "https://api.omniakey.com/v1", "apiKey": "${OMNIAKEY_API_KEY}", "provider": "openai", "maxOutputTokens": 16000 }, { "model": "minimax-m3.1-flash", "displayName": "MiniMax M3.1 Flash [OmniaKey]", "baseUrl": "https://api.omniakey.com/v1", "apiKey": "${OMNIAKEY_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16000 } ] } ``` - `model` é o id enviado à API; copie da lista de modelos do provedor. `displayName` é o seu rótulo: aparece em `/model` e forma o id `custom:`. - `baseUrl` é o host puro para `anthropic` e termina em `/v1` nos outros dois. - `apiKey: "${OMNIAKEY_API_KEY}"` lê a chave de uma variável de ambiente, então ela fica fora do arquivo (doc BYOK da Factory, verificada em 30 de outubro de 2026). - `provider` escolhe a API; um erro de digitação aqui gera o erro "Invalid provider" mais abaixo. - `maxOutputTokens: 16000` limita o tamanho de cada resposta. Uma chave e duas [URLs base](https://docs.omniakey.com/en/api/overview) cobrem os três modelos: o host puro da OmniaKey para o Claude, o host `/v1` para os outros dois. Se você já seguiu a [configuração da OmniaKey para agentes de código](https://docs.omniakey.com/en/coding), a mesma chave funciona aqui. A Factory diz que as chaves ficam locais e não sobem para os servidores da Factory (doc BYOK da Factory, verificada em 30 de outubro de 2026). Guias mais antigos colocam os modelos em `~/.factory/config.json`. A doc BYOK da Factory ainda diz que o Droid copia esses modelos para `settings.json` na inicialização. Um pull request no repositório da Factory no GitHub (#76) informa que uma mudança de código mesclada em 15 de outubro de 2026 removeu essa cópia, então coloque modelos novos direto no `settings.json`. ## Como escolher um modelo personalizado no Droid? No app, abra `/model` e olhe em Custom Models; na linha de comando, passe um id `custom:` para o `droid exec`. A doc da Factory diz que os modelos salvos aparecem ali com o `displayName` deles, e que você também pode adicionar um em `/settings` > Custom models ou `/model` > Manage custom models (verificada em 30 de outubro de 2026). O id do `droid exec` é `custom:`, depois o nome de exibição com espaços trocados por hífens, um hífen e a posição do modelo no `customModels`, contando de 0 (doc do `droid exec` da Factory, verificada em 30 de outubro de 2026). Os nossos saíram como `custom:Claude-Sonnet-5.5-[OmniaKey]-0`, `custom:GPT-6.1-Terra-[OmniaKey]-1` e `custom:MiniMax-M3.1-Flash-[OmniaKey]-2`. O índice segue a ordem do array, então inserir um modelo acima desloca todos os ids abaixo; copie o id de novo depois de editar o arquivo. `-r` / `--reasoning-effort` no `droid exec` não vale para modelos personalizados (doc do `droid exec` da Factory, verificada em 30 de outubro de 2026). Defina `reasoningEffort` na entrada. ## Três modelos no mesmo bug Dois arquivos, o mesmo comando, uma execução por modelo. `stats.py`: ```python def median(values): """Return the median of a non-empty list of numbers.""" ordered = sorted(values) mid = len(ordered) // 2 return ordered[mid] ``` `test_stats.py`: ```python from stats import median assert median([3, 1, 2]) == 2 assert median([4, 1, 3, 2]) == 2.5 assert median([5]) == 5 assert median([1.5, 2.5]) == 2.0 print("all tests passed") ``` O comando, com só o valor de `--model` mudando entre as execuções: ```bash droid exec --auto medium -o json --model "custom:Claude-Sonnet-5.5-[OmniaKey]-0" "python3 test_stats.py fails. Fix the bug in stats.py without changing the tests, run python3 test_stats.py again, and tell me in one sentence what you changed." ``` |Modelo|Tempo|Turnos|Tokens de saída| |-|-|-|-| |Claude Sonnet 5.5|33,7 s|3|702| |GPT-6.1 Terra|77,4 s|4|451| |MiniMax M3.1 Flash|30,7 s|4|525| Esses são os números do próprio Droid (`duration_ms`, `num_turns`, `output_tokens`). O Flash terminou mais rápido, em 30,7 s, o Claude usou menos turnos e o GPT-6.1 Terra levou mais tempo, 77,4 s. O Droid reportou o primeiro token depois de 8,7 s para o Claude, 17,8 s para o Terra e 7,0 s para o Flash. Os três corrigiram o bug sem mexer no `test_stats.py`, e os testes imprimiram `all tests passed`. A mudança do Claude: ```diff - return ordered[mid] + if len(ordered) % 2: + return ordered[mid] + return (ordered[mid - 1] + ordered[mid]) / 2 ``` O GPT-6.1 Terra pôs a mesma condição acima da linha de retorno antiga, e o MiniMax M3.1 Flash escreveu com `% 2 == 1`. As três respostas descreveram essa correção: fazer a média dos dois valores do meio quando a lista tem tamanho par. A [análise do MiniMax M3.1 Flash](https://omniakey.com/pt-BR/blog/minimax-m3-1-flash-review) cobre esse modelo em detalhe. O resultado JSON do Droid também imprimia `factory_credits` em toda execução, mesmo sem nunca termos feito login: 31.534 para o Claude Sonnet 5.5, 4.830 para o GPT-6.1 Terra e 835 para o MiniMax M3.1 Flash. A doc da Factory não explica o que o número mede nem como ele se relaciona com a franquia BYOK (verificada em 30 de outubro de 2026). ## Você precisa de conta ou plano da Factory? Nas nossas execuções, o `droid exec` com um modelo `custom:` não precisou de conta da Factory. Os modelos próprios da Factory e o app interativo pediram conta. O Droid CLI 1.0.0 saiu em 29 de outubro de 2026 (changelog da Factory, verificado em 30 de outubro de 2026). Numa pasta pessoal limpa, sem login na Factory, toda chamada `droid exec` com um modelo `custom:` rodou com a nossa própria chave. O mesmo comando sem `--model` parou na hora com "Authentication failed. Please log in using /login or set a valid FACTORY\_API\_KEY environment variable." ("Falha na autenticação. Entre com /login ou defina uma variável de ambiente FACTORY\_API\_KEY válida."). O changelog da Factory v0.236.0 (8 de outubro de 2026) trata de sessões retomadas: "Droid exec now resumes a session on your own model credentials without a Factory sign-in." ("O Droid exec agora retoma uma sessão com as suas próprias credenciais de modelo, sem login na Factory."). Iniciar o `droid` sem argumentos na mesma pasta parou em "Please login with your Factory account to continue." ("Entre com a sua conta da Factory para continuar."). Sem login não deu para experimentar modelos personalizados no app interativo ou no de desktop, e não testamos entrada de imagens, Bedrock, `apiKeyHelper`, `reasoningEffort`, ajustes de raciocínio, Windows, sessões com mais de uma tarefa nem o arquivo `config.json` antigo. Os planos Individual da Factory custam $20 (Pro), $100 (Plus) e $200 (Max) por mês; a página de preços acrescenta o Teams a $60 por mês por time mais $40 por assento, e não há plano individual gratuito (doc e página de preços da Factory, verificadas em 30 de outubro de 2026). A doc de preços dos planos Individual diz: "BYOK is free up to an allowance on all Individual plans. After that, usage is charged according to your specific plan." ("O BYOK é gratuito até uma franquia em todos os planos Individual. Depois disso, o uso é cobrado conforme o seu plano.") A Factory não diz qual é o tamanho dessa franquia nem como fica a cobrança depois. Modelos personalizados pessoais funcionam na CLI e no app de desktop, e não aparecem nos apps web e mobile hospedados da Factory (doc BYOK da Factory, verificada em 30 de outubro de 2026). ## Quais erros aparecem e o que resolve? Cada um veio de um único valor errado numa configuração que funcionava no resto, no Droid 1.0.0. 1. `anthropic` com `/v1` na URL base. O Droid imprimiu "Requested model was not found on the API provider" ("O modelo solicitado não foi encontrado no provedor de API") depois de 0,9 s, e o log dele mostrava `404` em `Invalid URL (POST /v1/v1/messages)`. O Droid acrescenta `/v1/messages` sozinho, então o nosso `/v1` duplicava o caminho. Correção: o host puro, `https://api.anthropic.com` ou `https://api.omniakey.com`. 2. `openai` com o host puro. O Droid imprimiu `404` e uma página nginx "404 Not Found" depois de 1,4 s; a Responses API fica em `/v1`. Correção: `https://api.openai.com/v1` ou `https://api.omniakey.com/v1`. 3. Um id de modelo com pontos, `claude-sonnet-5.5`, em vez de `claude-sonnet-5-5`. O endpoint respondeu `503` com o código `model_not_found` e a mensagem "No available channel for model claude-sonnet-5.5" ("Nenhum canal disponível para o modelo claude-sonnet-5.5"). O log do Droid marcava cada falha como "overloaded" e fez 10 tentativas ao longo de 259,7 segundos (cerca de 4 minutos e 20 segundos) antes de sair com essa mensagem. O texto é do gateway; as repetições são do Droid. Correção: copiar o id exato da lista de modelos do seu provedor. 4. `OMNIAKEY_API_KEY` vazia no shell que iniciou o Droid. O Droid recebeu `401` com "Invalid token" ("Token inválido") depois de 2,8 s. Correção: exporte a chave no shell de onde você inicia o `droid` e comece uma sessão nova. A lista de solução de problemas da Factory acrescenta duas. "Invalid provider" quer dizer que o valor está escrito errado ou com outra capitalização, e precisa ser exatamente `anthropic`, `openai`, `generic-chat-completion-api` ou `bedrock-converse`. Para um modelo que falta no seletor, a doc manda conferir a sintaxe JSON em `~/.factory/settings.json` e se cada entrada tem os campos obrigatórios (verificada em 30 de outubro de 2026). ## FAQ ### Onde fica o arquivo de configurações do Droid no Windows? `%USERPROFILE%\.factory\settings.json`, o mesmo arquivo que `~/.factory/settings.json` no macOS e no Linux (doc de configurações da Factory, verificada em 30 de outubro de 2026). Coloque `customModels` lá. ### Por que meu modelo personalizado não aparece em `/model`? Confira primeiro a sintaxe JSON em `~/.factory/settings.json`, depois os campos `model`, `baseUrl` e `provider`. O Droid detecta mudanças salvas por monitoramento de arquivo (doc BYOK da Factory, verificada em 30 de outubro de 2026). Segundo um relato no Desktop 0.184.0 com CLI 0.227.0, os modelos personalizados apareciam por um instante no seletor do desktop e depois sumiam, enquanto `droid exec --help` continuava listando os 14; essa issue está fechada agora (Factory-AI issue #40, verificada em 30 de outubro de 2026). ### Modelos personalizados leem imagens? Imagens vêm ligadas por padrão em `anthropic` e `openai`, e desligadas em `generic-chat-completion-api`, onde `noImageSupport` vale `true` (doc BYOK da Factory, verificada em 30 de outubro de 2026). Defina `noImageSupport: false` numa entrada genérica para permitir. Segundo um relato, as imagens eram removidas mesmo assim na CLI v0.205.1 com esse valor definido (Factory-AI issue #24, verificada em 30 de outubro de 2026). ### Dá para definir o esforço de raciocínio de um modelo personalizado? `-r` / `--reasoning-effort` no `droid exec` não vale para modelos personalizados. Defina `reasoningEffort` na entrada: o valor fixa o esforço padrão de um modelo que o Droid não reconhece e acrescenta off, low, medium e high ao seletor (doc BYOK da Factory, verificada em 30 de outubro de 2026). ### Modelos personalizados funcionam no app de desktop do Droid? Sim: modelos personalizados pessoais ficam disponíveis na CLI e no app de desktop, e continuam fora dos apps web e mobile hospedados. Os editores de modelo da CLI e do app de desktop salvam os dois em `~/.factory/settings.json` (doc BYOK da Factory, verificada em 30 de outubro de 2026). ## Fontes verificadas - [Doc BYOK da Factory](https://docs.factory.com/model-independence/byok.md), verificada em 30 de outubro de 2026 - [Doc de configurações da Factory](https://docs.factory.com/droid-cli/settings.md), verificada em 30 de outubro de 2026 - [Doc do droid exec da Factory](https://docs.factory.com/droid-exec/overview.md), verificada em 30 de outubro de 2026 - [Notas de versão da Factory](https://docs.factory.com/changelog/release-notes.md), verificadas em 30 de outubro de 2026 - [Planos Individual da Factory](https://docs.factory.com/pricing/individuals.md), verificados em 30 de outubro de 2026 - [Preços da Factory](https://factory.com/pricing), verificados em 30 de outubro de 2026 - [Factory-AI issue #40: modelos personalizados somem do seletor do desktop](https://github.com/Factory-AI/factory/issues/40), verificada em 30 de outubro de 2026 - [Factory-AI issue #24: imagens removidas](https://github.com/Factory-AI/factory/issues/24), verificada em 30 de outubro de 2026 - [Factory-AI pull request #76: migração do config.json](https://github.com/Factory-AI/factory/pull/76), verificada em 30 de outubro de 2026 A documentação da OmniaKey, verificada em 30 de outubro de 2026: [visão geral da API](https://docs.omniakey.com/en/api/overview) e [API compatível com OpenAI](https://docs.omniakey.com/en/api/openai-compatible).