Modelli personalizzati in Factory Droid: Claude e GPT con la tua API key

Aggiungi ogni modello a customModels in ~/.factory/settings.json con model, baseUrl, apiKey e provider: usa anthropic per Claude con il solo host, openai per GPT e generic-chat-completion-api per tutto il resto. Su Droid 1.0.0, Claude Sonnet 5.5, GPT-6.1 Terra e MiniMax M3.1 Flash hanno corretto lo stesso bug in 33.7, 77.4 e 30.7 secondi.

Tutte e tre le esecuzioni sono passate da OmniaKey con una sola chiave, ed è così che abbiamo raggiunto Claude Sonnet 5.5, GPT-6.1 Terra e MiniMax M3.1 Flash. Ognuno ha ricevuto la stessa funzione median() difettosa e l'ha corretta.

Risposta breve

• Dove va. customModels in ~/.factory/settings.json (documentazione delle impostazioni di Factory, verificata 30 ottobre 2026), con model, baseUrl, apiKey e provider.
• Quale provider. anthropic per Claude, openai per i modelli GPT, generic-chat-completion-api per tutto il resto che parla Chat Completions.
• Dove va /v1. anthropic vuole il solo host, perché Droid aggiunge /v1/messages; openai e generic-chat-completion-api vogliono un URL che finisce con /v1.
• L'ID per droid exec. custom:, il nome visualizzato con gli spazi al posto dei trattini, poi la posizione a partire da 0: custom:Claude-Sonnet-5.5-[OmniaKey]-0.
• Cosa hanno mostrato le nostre esecuzioni. Tutti e tre hanno corretto il bug; 30.7 s per Flash, 33.7 s per Claude, 77.4 s per GPT-6.1 Terra.

Quale valore di provider usare?

Scegli il provider in base all'API che parla il tuo endpoint, non in base al nome del modello.

• anthropic invia richieste all'API Anthropic Messages. Usalo per Claude; il base URL di Anthropic è https://api.anthropic.com.
• openai invia richieste all'API OpenAI Responses. Usalo per i modelli GPT; il base URL di OpenAI è https://api.openai.com/v1.
• generic-chat-completion-api invia richieste OpenAI Chat Completions. Usalo per quasi tutti gli altri modelli, gateway e server locali, con l'URL /v1 del fornitore.

Factory elenca generic-chat-completion-api per OpenRouter, Fireworks, Together AI, Ollama, vLLM e la maggior parte dei fornitori open source, e lo consiglia se non chiami l'API ufficiale di OpenAI o di Anthropic (documentazione BYOK di Factory, verificata 30 ottobre 2026).

Un gateway che parla anche l'API Messages o l'API Responses può usare anthropic o openai. Le nostre voci Claude e GPT-6.1 Terra lo facevano, tramite OmniaKey, ed entrambe hanno funzionato; OmniaKey serve i modelli GPT su POST /v1/responses (documentazione dell'API compatibile OpenAI di OmniaKey, verificata 30 ottobre 2026).

Il quarto valore, bedrock-converse, serve ai modelli sull'API Converse di AWS Bedrock. Factory avverte che solo i modelli Anthropic e OpenAI sulle rispettive API ufficiali sono testati e confrontati per intero, e che i modelli sotto i 30 miliardi di parametri vanno decisamente peggio nel coding agentico (documentazione BYOK di Factory, verificata 30 ottobre 2026).

Il settings.json che abbiamo usato

Droid crea ~/.factory/settings.json al primo avvio, quindi aggiungi customModels al file che c'è già (documentazione delle impostazioni di Factory, verificata 30 ottobre 2026). Il nostro è questo:

{
  "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 è l'ID inviato all'API; copialo dall'elenco modelli del fornitore. displayName è la tua etichetta: compare in /model e costruisce l'ID custom:.
• baseUrl è il solo host per anthropic, e finisce con /v1 per gli altri due.
• apiKey: "${OMNIAKEY_API_KEY}" legge la chiave da una variabile d'ambiente, così resta fuori dal file (documentazione BYOK di Factory, verificata 30 ottobre 2026).
• provider sceglie l'API; un errore di battitura qui dà l'errore "Invalid provider" qui sotto.
• maxOutputTokens: 16000 limita la lunghezza di ogni risposta.

Una chiave e due base URL coprono tutti e tre i modelli: il solo host di OmniaKey per Claude, l'host /v1 per gli altri due. Se hai seguito la guida di OmniaKey per configurare un coding agent, la stessa chiave funziona anche qui.

Factory dice che le chiavi restano locali e non vengono caricate sui server di Factory (documentazione BYOK di Factory, verificata 30 ottobre 2026). Le guide più vecchie mettono i modelli in ~/.factory/config.json. La documentazione BYOK di Factory dice ancora che Droid li copia in settings.json all'avvio. Una pull request nel repository GitHub di Factory (#76) dice che una modifica di codice unita il 15 ottobre 2026 ha rimosso quella copia, quindi metti i modelli nuovi direttamente in settings.json.

Come si sceglie un modello personalizzato in Droid?

Nell'app apri /model e guarda sotto Custom Models; da riga di comando passa un ID custom: a droid exec.

La documentazione di Factory dice che i modelli salvati compaiono lì con la loro etichetta displayName, e puoi aggiungerne uno anche da /settings > Custom models o /model > Manage custom models (verificata 30 ottobre 2026).

L'ID di droid exec è custom:, poi il nome visualizzato con gli spazi diventati trattini, poi un trattino e la posizione del modello in customModels a partire da 0 (documentazione di droid exec di Factory, verificata 30 ottobre 2026). I nostri sono usciti come custom:Claude-Sonnet-5.5-[OmniaKey]-0, custom:GPT-6.1-Terra-[OmniaKey]-1 e custom:MiniMax-M3.1-Flash-[OmniaKey]-2.

L'indice segue l'ordine dell'array, quindi inserire un modello sopra un altro sposta tutti gli ID sotto di lui; ricopia l'ID dopo aver modificato il file.

-r / --reasoning-effort in droid exec non si applica ai modelli personalizzati (documentazione di droid exec di Factory, verificata 30 ottobre 2026). Imposta reasoningEffort nella voce.

Tre modelli sullo stesso bug

Stessi due file, stesso comando, un'esecuzione per modello. 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")

Il comando, con solo il valore di --model che cambia tra un'esecuzione e l'altra:

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

Sono i numeri di Droid (duration_ms, num_turns, output_tokens). Flash ha finito per primo a 30.7 s, Claude ha usato meno turni, e GPT-6.1 Terra è stato il più lento a 77.4 s. Droid ha riportato il primo token dopo 8.7 s per Claude, 17.8 s per Terra e 7.0 s per Flash. Tutti e tre hanno corretto il bug senza toccare test_stats.py, e i test hanno stampato all tests passed.

La modifica di Claude:

-    return ordered[mid]
+    if len(ordered) % 2:
+        return ordered[mid]
+    return (ordered[mid - 1] + ordered[mid]) / 2

GPT-6.1 Terra ha aggiunto lo stesso ramo sopra la vecchia riga di return, e MiniMax M3.1 Flash l'ha scritto con % 2 == 1. Tutte e tre le risposte descrivevano la stessa correzione: fare la media dei due valori centrali per una lista di lunghezza pari. La recensione di MiniMax M3.1 Flash tratta quel modello più in dettaglio.

Il risultato JSON di Droid ha stampato anche factory_credits a ogni esecuzione, anche se non avevamo mai fatto l'accesso: 31,534 per Claude Sonnet 5.5, 4,830 per GPT-6.1 Terra e 835 per MiniMax M3.1 Flash. La documentazione di Factory non spiega cosa misuri quel numero né come si leghi alla quota BYOK (verificata 30 ottobre 2026).

Serve un account o un piano Factory?

Nelle nostre esecuzioni, droid exec con un modello custom: non ha chiesto un account Factory. I modelli di Factory e l'app interattiva sì.

Droid CLI 1.0.0 è uscito il 29 ottobre 2026 (changelog di Factory, verificato 30 ottobre 2026). In una cartella home pulita, senza accesso a Factory, ogni chiamata droid exec con un modello custom: è girata sulla nostra chiave. Lo stesso comando senza --model si è fermato subito con "Authentication failed. Please log in using /login or set a valid FACTORY_API_KEY environment variable." (autenticazione non riuscita; accedi con /login oppure imposta una variabile d'ambiente FACTORY_API_KEY valida). Il changelog v0.236.0 di Factory (8 ottobre 2026) copre le sessioni riprese: "Droid exec now resumes a session on your own model credentials without a Factory sign-in." (Droid exec ora riprende una sessione con le credenziali del tuo modello, senza accesso a Factory.)

Avviare droid senza argomenti nella stessa cartella si fermava a "Please login with your Factory account to continue." (accedi con il tuo account Factory per continuare). Senza accesso non abbiamo potuto provare i modelli personalizzati nell'app interattiva o desktop, e non abbiamo testato input di immagini, Bedrock, apiKeyHelper, reasoningEffort o le impostazioni di thinking, Windows, sessioni più lunghe di un compito, né il vecchio file config.json.

I piani Individual di Factory costano $20 (Pro), $100 (Plus) e $200 (Max) al mese; la pagina dei prezzi aggiunge Teams a $60 al mese per team più $40 per posto, e non c'è un piano individuale gratuito (documentazione e pagina dei prezzi di Factory, verificate 30 ottobre 2026).

La documentazione dei prezzi Individual dice: "BYOK is free up to an allowance on all Individual plans. After that, usage is charged according to your specific plan." (BYOK è gratuito fino a una quota su tutti i piani Individual. Dopo, l'uso viene addebitato secondo il tuo piano.) Factory non dice quanto sia grande quella quota né come sia fatto l'addebito dopo.

I modelli personalizzati personali funzionano nella CLI e nell'app desktop, e non compaiono nelle app web e mobile ospitate di Factory (documentazione BYOK di Factory, verificata 30 ottobre 2026).

Quali errori incontri e cosa li risolve?

Ognuno è nato da un solo valore sbagliato in una configurazione per il resto funzionante, su Droid 1.0.0.

1. anthropic con /v1 nel base URL. Droid ha stampato "Requested model was not found on the API provider" (modello richiesto non trovato sul provider API) dopo 0.9 s, e il suo log mostrava 404 su Invalid URL (POST /v1/v1/messages). Droid aggiunge /v1/messages da sé, quindi il nostro /v1 lo raddoppiava. Correzione: il solo host, https://api.anthropic.com o https://api.omniakey.com.

2. openai con il solo host. Droid ha stampato 404 e una pagina "404 Not Found" di nginx dopo 1.4 s; l'API Responses vive sotto /v1. Correzione: https://api.openai.com/v1 o https://api.omniakey.com/v1.

3. Un ID modello con i punti, claude-sonnet-5.5, invece di claude-sonnet-5-5. L'endpoint ha risposto 503 con codice model_not_found e il messaggio "No available channel for model claude-sonnet-5.5" (nessun canale disponibile per il modello claude-sonnet-5.5). Il log di Droid ha etichettato ogni errore come "overloaded" e ha fatto 10 tentativi in 259.7 secondi (circa 4 minuti e 20 secondi) prima di uscire con quel messaggio. Le parole sono del gateway, i tentativi sono di Droid. Correzione: copia l'ID esatto dall'elenco modelli del fornitore.

4. OMNIAKEY_API_KEY vuota nella shell che ha avviato Droid. Droid ha ricevuto 401 con "Invalid token" (token non valido) dopo 2.8 s. Correzione: esporta la chiave nella shell da cui lanci droid, poi avvia una nuova sessione.

L'elenco di risoluzione problemi di Factory ne aggiunge due. "Invalid provider" significa che il valore è scritto male o con maiuscole diverse, e deve essere esattamente anthropic, openai, generic-chat-completion-api o bedrock-converse. Per un modello che manca nel selettore, la documentazione dice di controllare la sintassi JSON in ~/.factory/settings.json e che ogni voce abbia i campi obbligatori (verificata 30 ottobre 2026).

Domande frequenti

Dove sta il file delle impostazioni di Droid su Windows?

%USERPROFILE%\.factory\settings.json, lo stesso file di ~/.factory/settings.json su macOS e Linux (documentazione delle impostazioni di Factory, verificata 30 ottobre 2026). Metti lì customModels.

Perché il mio modello personalizzato non compare in /model?

Controlla prima la sintassi JSON in ~/.factory/settings.json, poi i campi model, baseUrl e provider. Droid rileva le modifiche salvate osservando il file (documentazione BYOK di Factory, verificata 30 ottobre 2026). Secondo una segnalazione, su Desktop 0.184.0 con CLI 0.227.0 i modelli personalizzati comparivano per poco nel selettore desktop e poi sparivano, mentre droid exec --help ne elencava ancora tutti e 14; quel problema ora è chiuso (Factory-AI issue #40, verificata 30 ottobre 2026).

I modelli personalizzati possono leggere le immagini?

Le immagini sono attive per impostazione predefinita per anthropic e openai e disattivate per generic-chat-completion-api, dove noImageSupport vale true per impostazione predefinita (documentazione BYOK di Factory, verificata 30 ottobre 2026). Imposta noImageSupport: false su una voce generic per abilitarle. Secondo una segnalazione, le immagini venivano comunque rimosse su CLI v0.205.1 con quel valore impostato (Factory-AI issue #24, verificata 30 ottobre 2026).

Posso impostare il reasoning effort per un modello personalizzato?

-r / --reasoning-effort in droid exec non si applica ai modelli personalizzati. Imposta reasoningEffort nella voce: fissa lo sforzo predefinito per un modello che Droid non riconosce e aggiunge off, low, medium e high al selettore (documentazione BYOK di Factory, verificata 30 ottobre 2026).

I modelli personalizzati funzionano nell'app desktop di Droid?

Sì: i modelli personalizzati personali sono disponibili nella CLI e nell'app desktop, e restano fuori dalle app web e mobile ospitate. Gli editor dei modelli nella CLI e nell'app desktop salvano entrambi in ~/.factory/settings.json (documentazione BYOK di Factory, verificata 30 ottobre 2026).

Fonti verificate

• Documentazione BYOK di Factory, verificata 30 ottobre 2026
• Documentazione delle impostazioni di Factory, verificata 30 ottobre 2026
• Documentazione di droid exec di Factory, verificata 30 ottobre 2026
• Note di rilascio di Factory, verificata 30 ottobre 2026
• Piani Individual di Factory, verificata 30 ottobre 2026
• Prezzi di Factory, verificata 30 ottobre 2026
• Factory-AI issue #40: i modelli personalizzati spariscono dal selettore desktop, verificata 30 ottobre 2026
• Factory-AI issue #24: immagini rimosse, verificata 30 ottobre 2026
• Factory-AI pull request #76: migrazione da config.json, verificata 30 ottobre 2026

La documentazione di OmniaKey, verificata 30 ottobre 2026: Panoramica API e API compatibile OpenAI.