Modelos personalizados no Factory Droid: use Claude e GPT com sua própria chave de API

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, GPT-6.1 Terra e 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:

{
  "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 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, 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:

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:

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:

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."

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:

-    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 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, verificada em 30 de outubro de 2026
• Doc de configurações da Factory, verificada em 30 de outubro de 2026
• Doc do droid exec da Factory, verificada em 30 de outubro de 2026
• Notas de versão da Factory, verificadas em 30 de outubro de 2026
• Planos Individual da Factory, verificados em 30 de outubro de 2026
• Preços da Factory, verificados em 30 de outubro de 2026
• Factory-AI issue #40: modelos personalizados somem do seletor do desktop, verificada em 30 de outubro de 2026
• Factory-AI issue #24: imagens removidas, verificada em 30 de outubro de 2026
• Factory-AI pull request #76: migração do config.json, verificada em 30 de outubro de 2026

A documentação da OmniaKey, verificada em 30 de outubro de 2026: visão geral da API e API compatível com OpenAI.