Pi

Un blocco provider personalizzato in ~/.pi/agent/models.json — baseUrl, api e gli ID dei modelli — porta l'agente di programmazione da terminale Pi di Earendil su Claude e GPT tramite una sola chiave.

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Impostalo come variabile d'ambiente KUNAVO_API_KEY. Nel campo apiKey, Pi risolve "$NAME" o "${NAME}", oltre ad accettare un valore letterale o un prefisso !command. Usa la forma con parentesi graffe quando dopo il nome della variabile c'è del testo letterale.
3. Crea o modifica ~/.pi/agent/models.json e incolla il blocco qui sopra. Un provider non integrato richiede baseUrl e un valore api a livello di provider o di modello: il codice sorgente di Pi rifiuta di caricare il modello senza questi valori; tutto il resto è facoltativo. Aprendo /model il file viene ricaricato.
4. Avvia pi, esegui /model e scegli uno degli ID che hai dichiarato. Se non compaiono nell'elenco, controlla la chiave prima di intervenire sul JSON: consulta la nota sull'ordine di risoluzione qui sopra.
5. Assegnagli un'attività che legga e modifichi un file reale. Pi si affida quasi sempre alle chiamate agli strumenti, quindi una prima esecuzione che interagisce con il filesystem ti dirà molto più di un saluto e farà emergere eventuali incompatibilità nello streaming o nello schema degli strumenti: è proprio questa la categoria che Kunavo non ha testato per te.

Verificato rispetto a La documentazione di Pi: Choose a Model il 1 ottobre 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 Pi.

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

L’altra opzione: anthropic-messages

Fino all'aggiornamento della documentazione del 22 settembre 2026, Pi documentava quattro valori per api di un provider personalizzato: openai-completions, openai-responses, anthropic-messages e google-generative-ai. La pagina aggiornata sui modelli non ne elenca nessuno: mostra openai-completions in un esempio e descrive il caso come «Un endpoint compatibile con OpenAI, Anthropic o Google». Nel codice sorgente di Pi alla versione v0.99.2 il campo è tipizzato come stringa libera e viene inoltrato a una delle dieci implementazioni integrate corrispondenti: le quattro precedenti, più openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream e pi-messages. Solo i primi quattro sono mai stati documentati per un provider personalizzato; nessuno degli altri sei è stato testato qui e questa pagina non afferma che funzionino con endpoint di terze parti.

anthropic-messages è uno dei quattro valori documentati e Kunavo risponde sia all'interfaccia Anthropic Messages sia a quella compatibile con OpenAI. Quindi è possibile configurare questa route. Questa pagina non inserisce però nel blocco da incollare un URL di base per tale route: la documentazione di Pi non ha mai definito quel campo in modo univoco per questa api. Fino al 22 settembre veniva mostrato in due modi: https://proxy.example.com/v1 in un esempio e https://proxy.example.com senza parentesi in un altro. L'aggiornamento della documentazione di quel giorno ha rimosso entrambe le forme senza sceglierne una. Se scegli questa route, prova una delle due; se la prima chiamata restituisce 404 invece di 401, è quella la riga da modificare.

Nello schema compat di Pi ci sono tre campi per questa api che è utile conoscere prima di arrivarci (codice sorgente, v0.99.2). Prima, però, è bene citare la regola della documentazione che li riguarda tutti: le impostazioni di compatibilità «devono descrivere differenze verificate nel comportamento di richiesta o risposta dell'endpoint. Non abilitarle basandosi soltanto sul fatto che un endpoint dichiari la compatibilità con OpenAI o Anthropic».

1. compat.supportsEagerToolInputStreaming — per un backend che rifiuta lo streaming anticipato dell'input per ogni strumento.
2. compat.supportsStrictTools — indica se l'endpoint accetta definizioni degli strumenti con schema JSON rigoroso; un modello personalizzato non eredita l'impostazione dichiarata da un modello Anthropic integrato.
3. compat.supportsMidConvoEffort — modifica il livello di ragionamento nel corso della conversazione. Stabilire se questo endpoint è idoneo è una questione da verificare in esecuzione, e Kunavo non l'ha fatto eseguendo alcuna prova.

Il blocco openai-completions in cima a questa pagina non usa nessuna delle tre impostazioni: è questo il motivo concreto per cui conviene partire da lì, non la pretesa che funzioni meglio.