Jan Agent

Una riga `jan config set --base-url https://api.kunavo.com/v1` scrive Kunavo in ~/.jan/config.toml, e la CLI di anteprima Jan Agent — priva di motore di inferenza — usa quella chiave.

# Jan Agent is a preview on a nightly channel — check your build first.
jan --version

jan config set \
  --provider kunavo \
  --api-key sk-kn-... \
  --base-url https://api.kunavo.com/v1 \
  --model claude-sonnet-5 \
  --model claude-haiku-4-5 \
  --api-type openai

jan config list   # configured providers as JSON, keys redacted

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Verifica cosa stai configurando: jan --version. Anche Jan Desktop include una CLI avviata con jan, ma con un set di comandi diverso; prima di digitare il resto, verifica che jan config set --help elenchi --base-url.
3. Esegui il comando jan config set qui sopra. --provider è un ID a tua scelta, non un nome da un elenco predefinito: l’esempio di configurazione hardware locale nella documentazione usa --provider local; inoltre, --model può essere ripetuto e sostituisce l’elenco esistente invece di aggiungervi elementi.
4. Verifica che sia stato salvato con jan config list (le chiavi vengono oscurate) oppure con jan config path per il file stesso, quindi esegui jan cli models list per vedere cosa offre ogni provider. Un ID modello inserito manualmente resta disponibile anche quando l’endpoint smette di elencarlo; jan cli models refresh --provider kunavo considera invece autorevole l’elenco dell’endpoint.
5. Entra in una directory di progetto ed esegui jan, quindi seleziona il modello con /model. Per la prima esecuzione, preferisci jan --plan: è in sola lettura, quindi un’incompatibilità del protocollo emerge prima che venga scritto qualcosa sul disco.
6. Assegnagli un’attività che modifichi un file. Jan Agent è un agente, quindi la prima esecuzione dovrebbe verificare chiamate agli strumenti e streaming: sono le funzionalità che darebbero problemi per prime con un endpoint solo parzialmente compatibile, mentre un saluto non ne verifica nessuna.

Verificato rispetto a la pagina Provider di Jan Agent 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 Jan Agent.

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

Due cose diverse vengono chiamate chiave API Jan

Sono nello stesso file e hanno significati opposti, ed è per questo che jan config list può sembrare errato a chi si aspetta l’altra chiave.

Jan Desktop non fornisce nessuna delle due: non ha un account, quindi non c'è nulla da generare. Il suo server API locale accetta una chiave che inventi tu, che ha ancora un terzo significato e appartiene a un host diverso.

Cosa fornisce Jan Desktop e dove si ferma

Jan Agent legge le impostazioni dei provider da quattro fonti, ciascuna con precedenza su quelle elencate sopra; la seconda è quella che sorprende più persone.

1. ~/.jan/config.toml — la base e l'unico file che jan config set scrive.
2. settings.json di Jan Desktop — solo in eredità. Aggiunge i provider che non hai configurato in Agent, non sovrascrive quelli che hai configurato e non viene mai riscritto.
3. Un blocco [provider] nel file agent.toml di un progetto — una scelta esplicita per progetto, quindi prevale su entrambi. Di solito quel file viene sottoposto a commit, quindi tienine fuori api_key.
4. --provider / --api-key dalla riga di comando, oppure JAN_API_KEY / <PROVIDER>_API_KEY — l'opzione più esplicita e più temporanea.

Ci sono due conseguenze da conoscere prima di fare debug della cosa sbagliata. jan config list può non mostrare alcun provider mentre jan cli models list ne restituisce molti: il secondo include quelli ereditati da Desktop, che non sono memorizzati in ~/.jan/config.toml. Inoltre, un provider ereditato non viene mai aggiornato, perché qui non c'è una voce da riscrivere: se vuoi mantenere aggiornato l'elenco dei modelli di Kunavo, deve essere una voce jan config set a sé, come quella creata dal blocco qui sopra.

Quando due provider offrono lo stesso ID modello

Kunavo fornisce ID come claude-sonnet-5, così come una voce provider che punta direttamente al fornitore. Jan Agent deve sceglierne uno e l'ordine documentato è: prima una corrispondenza esatta nell'elenco models di un provider, poi un prefisso <provider>/<model> che identifica un provider configurato e, se più provider offrono lo stesso ID, prevale quello con credenziali rispetto al gemello senza chiave. Ecco perché kunavo/claude-sonnet-5 serve a specificare quale intendevi. Il qualificatore serve solo a Jan: viene rimosso prima dell'invio della richiesta, perché i servizi upstream rifiutano gli ID qualificati con il provider.

La stessa voce, dalla console

Se preferisci non digitare flag: /settings > providers gestisce le stesse voci ~/.jan/config.toml e a apre un modulo per aggiungerne una, con i campi name, base url, api key e models separati da spazi. Il modulo fa due cose che i flag non fanno: l'URL di base deve essere https:// (oppure http:// per un endpoint localhost), così una chiave non viene mai inviata tramite una connessione remota in testo non crittografato — Kunavo usa https://, quindi non è un problema — e, quando modifichi una voce, il campo della chiave API mostra (unchanged) e conserva quella memorizzata a meno che tu non inserisca un nuovo valore. Se lasci vuoto il campo, la chiave viene cancellata invece di restare invariata.