Configurazione dell'API Cherry Studio: aggiungere un provider personalizzato, indirizzo e modello

Per configurare la propria API in Cherry Studio, il percorso è 設定 → 模型供應商 → 新增供應商: inserisci la chiave API, immetti un URL di base in ciascuno dei campi OpenAI e Anthropic di «端點設定», salva, fai clic su «同步模型» per importare i modelli e usa «檢查» per confermare.Questa pagina si basa sulla v2.1.4 pubblicata il 30 settembre 2026 e riporta i nomi dei menu esattamente come nell'interfaccia cinese tradizionale di Cherry Studio. La v2 ha modificato radicalmente la schermata per aggiungere un provider; le guide dell'epoca della v1 che indicavano «類型選 OpenAI» non corrispondono più all'interfaccia.

Questa pagina riguarda la versione desktop di CherryHQ/cherry-studio (AGPL-3.0, supporto per Windows, macOS e Linux). Alla verifica del 1º ottobre 2026 il repository non era archiviato e l'ultima versione era v2.1.4. L'app con lo stesso nome sull'App Store è un prodotto non correlato di un altro sviluppatore. Inoltre, la documentazione ufficiale di Cherry Studio è in cinese semplificato; passando all'interfaccia in cinese tradizionale, «提供商／服務商» viene visualizzato come «供應商». Non lasciarti confondere dalla differenza nei nomi quando confronti l'interfaccia con la documentazione.

Configurazione passo passo

設定 → 模型供應商 → 新增供應商
  （對話框標題：新增自訂供應商）

  供應商名稱                 Kunavo
  API 金鑰                   sk-kn-...
  端點設定
    OpenAI Chat Completions  https://api.kunavo.com/v1
    Anthropic Messages       https://api.kunavo.com
  更多選項
    OpenAI Responses         https://api.kunavo.com/v1   （選填）
    影像產生基礎 URL           https://api.kunavo.com/v1   （選填）
    Google Gemini            留空

→ 儲存 → 在模型清單按「同步模型」→ 加入要用的模型 → 「檢查」

1. Apri Impostazioni → Provider di modelli e fai clic su Aggiungi provider. La finestra visualizzata si intitola «Aggiungi provider personalizzato». Per servizi di tipo Coding Plan, più account o progetti separati, puoi usare «Inizia dal predefinito (facoltativo)» in alto per creare una configurazione a partire da un preset esistente.
2. Inserisci Nome provider e Chiave API.
3. Le Impostazioni degli endpoint contengono già per impostazione predefinita i campi OpenAI Chat Completions e Anthropic Messages; devi configurare almeno un endpoint testuale. Compilandoli entrambi, saranno disponibili modelli anche per gli Agent oltre alla chat e per le funzioni che usano il formato Anthropic.
4. Espandi Altre opzioni: troverai anche OpenAI Responses, Google Gemini, l'URL di base per la generazione di immagini e l'URL di base per la modifica delle immagini. Lascia vuoti i campi che non utilizzi.
5. Dopo aver salvato, verifica che il provider sia nello stato Abilitato. La documentazione ufficiale specifica che un provider configurato ma non abilitato non mostra i modelli nel menu: è la causa più comune quando «la chiave non produce alcun effetto».
6. Nell'elenco dei modelli fai clic su Sincronizza modelli, aggiungi quelli da usare e poi fai clic su Verifica per testarli.

Come inserire l'indirizzo: solo l'URL di base

Secondo il codice sorgente della v2.1.4, ogni campo deve contenere l'URL di base: se manca il segmento della versione, viene aggiunto automaticamente /v1 (e non viene duplicato se è già presente), quindi viene aggiunto il percorso fisso del campo. Sotto ogni campo viene mostrato il «Percorso della richiesta», cioè l'URL finale inviato.

Due errori comuni: incollare un URL completo contenente /chat/completions o /messages, causando la duplicazione del percorso e un 404; oppure aggiungere # alla fine. L'interfaccia lo indica chiaramente: «Aggiungi # alla fine per disabilitare l'aggiunta automatica della versione API». Se lo aggiungi a un endpoint standard, /v1 scompare.

Configuralo correttamente e riduci la bolletta

Oltre alla chat, Cherry Studio chiama modelli anche in background. Secondo la descrizione dell'interfaccia, il modello rapido è «un modello per attività semplici come denominare le conversazioni ed estrarre parole chiave per la ricerca»; l'avviso consiglia di «scegliere un modello leggero ed evitare i modelli di ragionamento». Inserendo qui un modello economico, eviti di usare quello costoso per ogni conversazione. Anche il modello di traduzione si configura separatamente. Se chiedi contemporaneamente a più modelli, ciascuno invia una richiesta e viene addebitato separatamente. L'importo mostrato nelle statistiche d'uso dell'app è una stima calcolata sui prezzi pubblici e risulterà più alto quando usi un percorso scontato; modificando il prezzo unitario nelle impostazioni del modello con quello effettivo, il calcolo sarà corretto. Per maggiori dettagli, consulta Cherry Studio API cost in inglese.

Note sull'uso di Kunavo e sui pagamenti a Taiwan

• Ambito della verifica: le impostazioni sopra sono state ricavate dal codice sorgente e dalla documentazione ufficiale di Cherry Studio; Kunavo non ha collegato effettivamente Cherry Studio ai propri endpoint. Mantieni il percorso attualmente funzionante e prova questa configurazione in aggiunta.
• Solo chat e immagini: Kunavo non dispone di modelli di embedding; per la ricerca vettoriale della knowledge base devi usare un altro provider o un modello di embedding locale. La documentazione ufficiale afferma che, in assenza di un modello di embedding, la knowledge base continua a funzionare con la ricerca per parole chiave BM25.
• Strumenti MCP: gli strumenti aggiunti in Impostazioni → Server MCP funzionano solo con modelli che supportano le chiamate agli strumenti; i modelli Claude e GPT aggiunti sopra le supportano.
• Pagamento: ricarica prepagata, addebito in base ai token, nessun canone mensile. Ricarica minima $10, checkout tramite Stripe; a Taiwan sono disponibili carte di credito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. JKoPay e LINE Pay non sono disponibili. Consulta le informazioni sulla fatturazione, quindi puoi creare un account e generare una chiave. La pagina di configurazione in inglese è la guida all'integrazione di Cherry Studio.

Domande frequenti

Verifica del 1º ottobre 2026: API GitHub (CherryHQ/cherry-studio, v2.1.4), stringhe dell'interfaccia cinese tradizionale della v2.1.4 (zh-tw.json), codice sorgente della schermata per aggiungere un provider e documentazione ufficiale di Cherry Studio. Kunavo non ha eseguito Cherry Studio con i propri endpoint.