OpenHands

Settings → LLM → Advanced richiede tre campi — Custom Model, Base URL, API Key — con l'ID modello che include il prefisso openai/ e l'URL di base che conserva /v1.

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Apri Impostazioni → LLM e attiva l’interruttore Advanced. I tre campi appaiono nel seguente ordine: Custom Model, Base URL, API Key.
3. Inserisci l’ID del modello con il prefisso: openai/claude-sonnet-5, non claude-sonnet-5. Gli ID serviti da Kunavo sono quelli restituiti da GET /v1/models, lo stesso elenco da cui, secondo la documentazione ufficiale di OpenHands, va ricavato un ID personalizzato.
4. Incolla https://api.kunavo.com/v1 in Base URL e la tua chiave in API Key, quindi fai clic su Save Changes. OpenHands documenta che il salvataggio di un profilo locale convalida prima la configurazione rispetto al backend e blocca il salvataggio in caso di errore; quindi un errore qui è un rifiuto effettivo, non un problema cosmetico.
5. Verifica ciò a cui può accedere il backend, non il browser. L’URL di base deve essere risolvibile dalla macchina che esegue Agent Server: la documentazione specifica chiaramente che, se Agent Canvas è in esecuzione in Docker, 127.0.0.1 è il container. Un endpoint pubblico come quello di Kunavo è il caso semplice; un proxy aziendale davanti all’endpoint non lo è.
6. Avvia una nuova conversazione e assegnale un’attività che legga e modifichi un file. OpenHands specifica che un LLM salvato si applica alle nuove conversazioni e che quelle esistenti devono essere prima riavviate; inoltre, un’esecuzione che utilizza gli strumenti ti dice di più sull’abbinamento di quanto possa fare un semplice saluto.

Verificato rispetto a Pagina delle impostazioni del modello linguistico (LLM) di OpenHands 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 OpenHands.

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

Tre aspetti da conoscere prima di iniziare la diagnosi

OpenHands ha più componenti di una CLI a processo singolo, e due di essi possono sembrare l’endpoint LLM senza esserlo. Le informazioni seguenti provengono dalla documentazione ufficiale, consultata alla data riportata sopra:

1. La sandbox non è il modello. OpenHands esegue il tuo lavoro in una sandbox di agent-server e contatta il modello tramite la rete: sono due componenti distinti, con credenziali separate. Una chiave configurata qui autorizza le chiamate al modello. Non determina ciò a cui può accedere la sandbox, e un problema di rete della sandbox non si manifesta come un errore di autenticazione.
2. Gli agenti ACP sono del tutto separati. Agent Canvas può delegare il lavoro a Claude Code, Codex o Gemini CLI come agenti ACP, e la pagina Configure a Model specifica che questi «gestiscono autonomamente il proprio accesso ai modelli»: quindi un profilo LLM non reindirizza quel sottoprocesso. Se ti aspettavi traffico sulla tua chiave e non ne vedi, verifica quale agente è effettivamente in esecuzione. Il confronto tra OpenHands e Claude Code approfondisce questa distinzione, compresa la regola di priorità delle credenziali che la determina.
3. Profili e limite di 10 profili. Una configurazione salvata diventa un profilo LLM; quella salvata più di recente diventa attiva per le nuove conversazioni e i profili possono essere cambiati durante una conversazione senza perdere il contesto. È questo meccanismo che permette di usare con un’unica chiave un ID economico e uno costoso. La documentazione limita a 10 il numero di profili per account. Un Provider Connection memorizza una sola volta il provider, la chiave API e l’URL di base facoltativo per più profili; la stessa pagina specifica che il pannello è disponibile sui backend agent-server locali e nascosto su un backend OpenHands Cloud.