Factory Droid

Uma entrada customModels em ~/.factory/settings.json — model, baseUrl e provider — coloca o Droid em qualquer endpoint que fale Anthropic Messages ou OpenAI Chat Completions.

// ~/.factory/settings.json  (Windows: %USERPROFILE%\.factory\settings.json)
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "Sonnet 5 [Kunavo]",
      "baseUrl": "https://api.kunavo.com",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "anthropic"
    },
    {
      "model": "gpt-5-6-sol",
      "displayName": "GPT-5.6 Sol [Kunavo]",
      "baseUrl": "https://api.kunavo.com/v1",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "generic-chat-completion-api"
    }
  ]
}

// Then, in the shell Droid starts from:
//   export KUNAVO_API_KEY=sk-kn-...
// ${VAR_NAME} expansion is a settings.json feature. It does NOT apply to the
// legacy ~/.factory/config.json, which Factory still loads and merges.

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez. Exporte-a como KUNAVO_API_KEY no shell de onde você inicia o Droid, para que a própria chave nunca seja gravada em um arquivo de configurações.
2. Abra ~/.factory/settings.json (crie-o se ainda não existir) e adicione o array customModels acima. A Factory marca exatamente três campos como obrigatórios — model, baseUrl e provider — e displayName é o rótulo exibido pelo seletor.
3. Confira a grafia de provider. O valor deve ser exatamente um de anthropic, openai ou generic-chat-completion-api; a seção de solução de problemas da Factory aponta um erro de digitação nesse campo como causa do erro "Invalid provider".
4. Execute /model na CLI. Suas entradas aparecem em uma seção separada Modelos personalizados, abaixo dos modelos próprios da Factory, identificadas pelo displayName definido por você. A Factory monitora o arquivo de configurações, então basta salvá-lo — não é necessário reiniciar.
5. Dê a ele uma tarefa que leia e edite um arquivo, em vez de apenas cumprimentá-lo. O Droid depende do uso de ferramentas para quase tudo o que faz, e um turno de conversa simples não exercita essa parte. Em seguida, execute /cost, onde a Factory informa as taxas de acerto do cache — a Kunavo oferece os marcadores cache_control da Anthropic de forma nativa, e a observação da própria Factory é que, no provedor genérico Chat Completions, o cache “varia de acordo com o provedor e não pode ser garantido”.

Verificado em Página de modelos personalizados (BYOK) da Factory em 21 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Factory Droid.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

O que um modelo personalizado não acessa no Droid

Há três limitações descritas nas próprias páginas da Factory, e cada uma altera o que você deve esperar da configuração acima, não se ela funciona.

• Disponível apenas em ambientes locais. A página BYOK da Factory informa que os modelos personalizados estão disponíveis na CLI do Droid e no aplicativo para desktop, que leem seu settings.json, e que eles “não aparecem nas plataformas web ou móveis hospedadas pela Factory”. O trabalho delegado por meio do produto hospedado continua sendo executado com inferência cobrada pela Factory, independentemente da chave configurada aqui.
• Um administrador pode desativá-lo. Os controles empresariais da Factory documentam modelPolicy.allowCustomModels e allowedBaseUrls, que desativam completamente o BYOK do usuário ou restringem todos os modelos personalizados a um único host aprovado. Em uma máquina gerenciada, confira isso antes de investigar o arquivo.
• A taxa do plano continua sendo cobrada. Uma chave aqui é um complemento, não uma substituição — o que a Factory cobra quando o uso ultrapassa a franquia BYOK, e qual é o limite dessa franquia, é assunto do guia de custos e não é recalculado nesta página.

Há uma armadilha que vale conhecer antes de copiar uma configuração de outro lugar: a Factory ainda carrega o arquivo legado ~/.factory/config.json com custom_models e base_url em snake_case, mesclando-o abaixo de settings.json, e documenta que a expansão de ${VAR_NAME} não se aplica a ele. Uma chave escrita como marcador nesse arquivo é enviada literalmente. Use settings.json.