Factory Droid

Una voce customModels in ~/.factory/settings.json — model, baseUrl e provider — porta Droid su qualsiasi endpoint che supporti Anthropic Messages o 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 dopo passo

1. Crea una chiave su /app/keys e copiala: verrà mostrata una sola volta. Esportala come KUNAVO_API_KEY nella shell da cui avvii Droid, così la chiave non viene mai inserita in un file di configurazione.
2. Apri ~/.factory/settings.json (crealo se non esiste) e aggiungi l’array customModels qui sopra. Factory indica esattamente tre campi obbligatori: model, baseUrl e provider; displayName è l’etichetta mostrata dal selettore.
3. Controlla la grafia di provider. Deve essere esattamente uno tra anthropic, openai o generic-chat-completion-api; la sezione di risoluzione dei problemi di Factory indica un errore di battitura in questo campo come causa dell’errore "Invalid provider".
4. Esegui /model nella CLI. Le tue voci appariranno in una sezione Modelli personalizzati separata, sotto quelle di Factory, con l’etichetta displayName che hai impostato. Factory monitora il file di configurazione, quindi basta salvarlo: non occorre riavviare.
5. Assegna un’attività che legga e modifichi un file, invece di limitarti a un saluto. Droid si affida alle chiamate agli strumenti per quasi tutte le operazioni, ed è proprio questa funzionalità che un semplice turno di chat non verifica. Poi esegui /cost: è lì che Factory mostra le percentuali di cache hit. Kunavo supporta nativamente i marcatori cache_control di Anthropic, mentre la nota di Factory specifica che, con il provider generico Chat Completions, la memorizzazione nella cache «varia a seconda del provider e non può essere garantita».

Verificato rispetto a La pagina di Factory sui modelli personalizzati (BYOK) il 21 settembre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in 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"}]}'

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

A cosa non si applica un modello personalizzato in Droid

Tre limitazioni sono indicate nelle pagine ufficiali di Factory. Ognuna modifica le aspettative sulla configurazione qui sopra, non il suo funzionamento.

• Solo interfacce locali. La pagina BYOK di Factory specifica che i modelli personalizzati sono disponibili nella CLI Droid e nell’app desktop, che leggono il tuo settings.json, e che «non compaiono sulle piattaforme web o mobili ospitate da Factory». Le attività delegate tramite il prodotto ospitato continuano a usare inferenza fatturata da Factory, qualunque chiave tu abbia configurato qui.
• Un amministratore può disattivarla. I controlli aziendali di Factory documentano modelPolicy.allowCustomModels e allowedBaseUrls, che disattivano completamente il BYOK degli utenti oppure vincolano ogni modello personalizzato a un unico host approvato. Se usi una macchina gestita, verifica questo aspetto prima di cercare il problema nel file.
• Il costo del piano resta invariato. Una chiave configurata qui si aggiunge al piano e non lo sostituisce. La guida ai costi spiega quanto addebita Factory oltre la quota BYOK e a quanto ammonta tale quota; questa pagina non ricalcola questi importi.

Un dettaglio da conoscere prima di copiare una configurazione trovata altrove: Factory carica ancora il file legacy ~/.factory/config.json con i campi snake_case custom_models e base_url, integrandolo sotto settings.json; documenta inoltre che l’espansione di ${VAR_NAME} non si applica in quel file. Una chiave inserita come segnaposto verrà inviata letteralmente. Usa settings.json.