Documentazione

Nanocoder

Nanocoder tratta un endpoint remoto come Ollama: una singola voce in nanocoder.providers con nome, URL di base, chiave ed elenco di modelli. sdkProvider è openai-compatible per impostazione predefinita, quindi non occorre dichiarare altro.

Una voce Custom Provider in nanocoder.providers dentro agents.config.json — name, baseUrl, apiKey, models — senza bisogno della riga sdkProvider, poiché il valore predefinito è openai-compatible.

agents.config.json

{
  "nanocoder": {
    "providers": [
      {
        "name": "Kunavo",
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "models": ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-sol"]
      }
    ]
  }
}

Kunavo non ha eseguito Nanocoder con questo endpoint. Tutti i campi sopra sono trascritti dalla pagina Custom Provider di Nanocoder; non provengono da una sessione completata da qualcuno qui. Questa è una guida alla configurazione, non un test di compatibilità. Esegui prima una piccola attività con limiti definiti e tieni disponibile un altro percorso durante la prova.

L'URL di base mantiene il suffisso /v1. La documentazione di Nanocoder chiarisce questo punto tramite esempi, non con una regola: la tabella dei campi descrive baseUrl soltanto come «URL dell'endpoint API», ma l'esempio nella pagina Custom Provider è "baseUrl": "https://my-api.example.com/v1" e tutte le pagine dei provider compatibili con OpenAI sul sito fanno lo stesso: https://openrouter.ai/api/v1, http://localhost:11434/v1. Se ometti il suffisso, si verifica un 404 sul percorso, non un 401 sulla chiave.

sdkProvider è volutamente assente qui sopra: la tabella dei campi indica che «il valore predefinito è openai-compatible», il formato di rete a cui Kunavo risponde qui. Gli altri valori documentati (google, anthropic, github-copilot) selezionano un SDK diverso e nessuno di essi serve per raggiungere un endpoint Chat Completions.

Tre percorsi di ricerca determinano quale configurazione prevale, nell'ordine: NANOCODER_PROVIDERS (o NANOCODER_PROVIDERS_FILE), poi agents.config.json nella directory di lavoro, infine il file per utente: ~/Library/Preferences/nanocoder/ su macOS, ~/.config/nanocoder/ su Linux e %APPDATA%\nanocoder\ su Windows. Prevale il primo file trovato; impostando NANOCODER_CONFIG_DIR vengono saltate del tutto le ricerche nel progetto e nella directory home. Se non viene inviata la chiave che hai modificato, controlla questo ordine di precedenza.

Non hai ancora una chiave? Crea un account Kunavo, genera una chiave (inizia con sk-kn-) e aggiungi credito da $10: le chiamate vengono pagate con quel saldo e le chiamate non riuscite non vengono addebitate. La dashboard si apre quindi sulla configurazione Nanocoder.

Passo dopo passo

Crea una chiave in /app/keys e copiala: viene mostrata una sola volta. Esportala come KUNAVO_API_KEY invece di inserirla nel file: Nanocoder sostituisce ricorsivamente $VAR, ${VAR} e ${VAR:-default} in tutte le stringhe di una voce provider e legge .env dalla directory di lavoro.
Esegui /settings providers all'interno di Nanocoder e seleziona Custom Provider. La procedura guidata chiede, nel proprio ordine, Provider name, Base URL, API key (optional), Model names e Request timeout; propone inoltre di recuperare l'elenco dei modelli dall'endpoint. Kunavo risponde con GET /v1/models, quindi l'elenco viene popolato automaticamente.
In alternativa, salta la procedura guidata e scrivi da te agents.config.json usando il blocco sopra. Tieni presente che le impostazioni vengono risolte file per file: un file a livello di progetto che definisce nanocoder.providers fornisce l'intero blocco, perciò le voci della configurazione globale non vengono unite a quelle del progetto.
Imposta una finestra di contesto. Nanocoder determina il limite nell'ordine seguente: /context-max, contextWindows[model], contextWindow, NANOCODER_CONTEXT_LIMIT e models.dev. Kunavo non è un provider models.dev, quindi, se manca uno dei primi quattro valori, il budget viene calcolato usando un valore di riserva che non corrisponde al tuo modello. I numeri sono disponibili su /models.
Apri /model, scegli uno degli ID che hai elencato — il selettore li mostra sotto name, il nome che hai specificato — ed esegui una piccola attività che debba chiamare uno strumento. Se le chiamate agli strumenti restituiscono dati malformati con un modello specifico, disableToolModels permette di disattivare l'opzione per quel modello anziché per l'intero provider.

Verificato rispetto a Pagina Custom Provider di Nanocoder 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.

Questa è la versione breve. La guida completa, con scelta del modello, costo di una sessione reale e modalità di errore, è in Nanocoder e OpenCode: quanto costa ciascuno, oltre al blocco provider.

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

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

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.

ID del modello	Kunavo ingresso / uscita	Dove si inserisce in Nanocoder
`claude-sonnet-5`	$1.40 / $7.00	il modello di lavoro predefinito per il ciclo di modifica ed esecuzione di un agente da terminale
`claude-haiku-4-5`	$0.70 / $3.50	sessioni lunghe con molti strumenti e rapida selezione dei file, in cui il costo dipende soprattutto dal numero di turni
`gpt-5-6-sol`	$2.00 / $12.00	un secondo parere da una famiglia di modelli diversa, con la stessa chiave
`claude-opus-5`	$3.50 / $17.50	l'unico refactoring complesso di una sessione, in cui un piano errato costa caro

La fatturazione è per token, usando un saldo prepagato senza canone mensile: vedi billing. In presenza di contesto ripetuto, che costituisce la maggior parte di ciò che invia un editor o un client di chat, prompt caching incide sulla spesa più della scelta del modello.

Domande frequenti

Nanocoder supporta un endpoint API personalizzato?

Sì, è una funzionalità documentata e ufficiale, non un campo privo di documentazione. La pagina Custom Provider di Nanocoder afferma che qualsiasi servizio che espone un'API compatibile con OpenAI può essere aggiunto come provider personalizzato e riporta l'oggetto da configurare: name, baseUrl, apiKey e models. Puoi aggiungerlo in modo interattivo con la procedura guidata /settings providers oppure modificando manualmente agents.config.json. Questa era la documentazione disponibile al 21 settembre 2026.

Dove inserisco la chiave API di Nanocoder?

Nel campo apiKey della voce provider, all'interno di agents.config.json. Nanocoder applica ricorsivamente la sostituzione delle variabili d'ambiente ai campi stringa nelle configurazioni dei provider; pertanto, la forma più sicura è "apiKey": "${KUNAVO_API_KEY}", con il valore esportato nella shell o in un file .env nella directory di lavoro. Le sostituzioni di ambiente tramite NANOCODER_PROVIDERS hanno la precedenza massima, seguite da agents.config.json a livello di progetto e poi da quello per utente. Se una modifica sembra non avere effetto, di solito è perché viene sovrascritta più in alto in quest'ordine.

Nanocoder richiede che baseUrl termini con /v1?

Per un endpoint compatibile con OpenAI, sì: per esempio https://api.kunavo.com/v1. La documentazione di Nanocoder non enuncia esplicitamente una regola sul suffisso; la tabella dei campi descrive baseUrl soltanto come URL dell'endpoint API. La questione è chiarita dagli esempi: quello nella pagina Custom Provider usa https://my-api.example.com/v1 e tutte le pagine dei provider compatibili con OpenAI sul sito riportano lo stesso suffisso. Se manca /v1, si verifica un 404 sul percorso anziché un errore di autenticazione.

Perché Nanocoder non mostra alcun costo o la dimensione di contesto errata per questi modelli?

Perché Nanocoder legge i metadati dei modelli da models.dev, dove non esiste una voce per un gateway di terze parti che il servizio non elenca. L'ordine documentato per il limite di contesto è: /context-max o --context-max, poi contextWindows[model], quindi contextWindow, poi NANOCODER_CONTEXT_LIMIT e infine models.dev. Imposta uno dei primi quattro valori nella voce del provider per ripristinare la misura corretta. In ogni caso, il costo per risposta è un calcolo del client sui token riportati: confrontalo con il registro del tuo provider, non con il piè di pagina.