Configurazione dei modelli di Pi Coding Agent: /login, models.json e provider personalizzato

La configurazione dei modelli del coding agent Pi è suddivisa in tre livelli: accedi ai provider integrati con /login (abbonamento o chiave API) oppure imposta una variabile d'ambiente; inserisci in ~/.pi/agent/models.json gli endpoint non integrati da Pi ma compatibili con le API OpenAI/Anthropic/Google; usa un'estensione solo per servizi che richiedono autenticazione o protocolli speciali. Dopo aver scelto, cambia modello con /model.Questo articolo, basato sulla documentazione di Pi revisionata il 22 settembre 2026 e sul codice sorgente v0.99.2 pubblicato il 30 settembre 2026, spiega come configurare ogni livello, l'ordine di lettura delle chiavi (modificato con la revisione), tre valori predefiniti dei modelli personalizzati che causano errori silenziosi e un esempio completo per collegare un endpoint compatibile con OpenAI.

Innanzitutto verifica quale Pi stai usando. Questa pagina riguarda l'agente di coding da terminale pubblicato da Earendil su pi.dev, il cui repository è earendil-works/pi (in precedenza badlogic/pi-mono), con licenza MIT. Non è il chatbot Pi di Inflection (pi.ai), la criptovaluta Pi Network, Raspberry Pi né Oh My Pi di un altro autore.

Scegli prima il metodo di connessione

La documentazione dei modelli di Pi inizia proprio con questa tabella di corrispondenza:

Pi include un catalogo dei modelli e può aggiungere dati di catalogo più recenti da pi.dev; offline utilizza la cache, mentre per forzare un aggiornamento puoi eseguire pi update --models. Ti serve una configurazione di modello personalizzata solo quando Pi non include il provider o l'endpoint che ti occorre.

Selezionare un modello in Pi

• /model: cerca e seleziona un modello. Vengono mostrati solo i modelli per i quali il provider dispone già di un'autenticazione utilizzabile.
• Premi Ctrl+S su un modello: lo salvi come modello predefinito per le nuove sessioni.
• /thinking: scegli il livello di ragionamento del modello attuale. Pi mostra solo i livelli supportati da quel modello; premi Ctrl+S per salvarlo come predefinito di avvio.
• Ctrl+P: alterna i modelli disponibili; /scoped-models controlla l'elenco di alternanza e lo salva.

La sessione registra i cambi di modello e di livello di ragionamento e li ripristina quando la riapri, ma non modifica il predefinito delle nuove sessioni.

Ordine di lettura delle chiavi (modificato con la revisione)

Quando sono configurate più fonti di chiavi, l'ordine indicato dalla documentazione di Pi è: --api-key a runtime → credenziali memorizzate in auth.json → apiKey in models.json → variabile d'ambiente del provider (oppure credenziali d'ambiente della piattaforma cloud). Perciò una vecchia chiave salvata con /login ha la precedenza su quella appena inserita nel file; è la causa più comune della situazione “ho modificato la configurazione ma viene ancora usato il vecchio account”. /logout può rimuovere le credenziali salvate. Attenzione: prima della revisione del 22 settembre, la documentazione indicava la variabile d'ambiente prima di models.json; le guide online precedenti potrebbero seguire ancora l'ordine vecchio.

Un altro malinteso comune: se un modello non compare in /model, nella maggior parte dei casi si tratta di un problema di autenticazione, non di un errore nel JSON. La documentazione dice che i modelli personalizzati possono essere caricati da models.json, ma rimarranno “non disponibili” finché Pi non avrà risolto le credenziali.

models.json: esempio completo per un endpoint compatibile con OpenAI

L'esempio di Pi usa Ollama locale: la chiave fittizia serve solo a rendere il modello disponibile, perché Ollama non la verifica:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Per collegare un endpoint che richiede autenticazione, come Kunavo, procedi così:

{
  "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
        }
      ]
    }
  }
}

• baseUrl e api sono obbligatori.Possono essere definiti al livello del provider o del modello; secondo il codice sorgente v0.99.2, se manca uno dei due Pi non carica il modello.
• api non è una scelta tra quattro opzioni.Prima della revisione del 22 settembre, la documentazione di Pi elencava quattro valori per i provider personalizzati: openai-completions, openai-responses, anthropic-messages, google-generative-ai. Dopo la revisione la documentazione non elenca più i valori; nella tabella precedente indica solo “endpoint compatibile con OpenAI, Anthropic o Google” e gli esempi usano soltanto openai-completions. Il codice sorgente v0.99.2 definisce api come una stringa arbitraria e la affida all'implementazione corrispondente tra dieci implementazioni integrate: i quattro valori precedenti più openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream, pi-messages. Solo i primi quattro sono mai stati documentati come modalità d'uso dei provider personalizzati; gli altri sei non sono stati testati qui e questa pagina non sostiene che possano collegarsi a endpoint di terze parti.
• Il baseUrl di openai-completions deve includere /v1.La documentazione non lo stabilisce in una singola frase, ma tutti gli esempi di endpoint compatibili includono il percorso di versione. Senza /v1 otterrai un 404, non un errore di autenticazione.
• Non inserire la chiave direttamente nel codice.apiKey e i valori degli header possono usare $NAME o ${NAME} per riferirsi a variabili d'ambiente, contenere un valore diretto oppure usare !指令 per recuperarlo; la documentazione dice che il comando in models.json viene eseguito a ogni richiesta e non viene memorizzato nella cache. Mantieni riservati auth.json e qualsiasi comando che recuperi una chiave.
• Non è necessario riavviare dopo una modifica.Quando apri /model, il file viene riletto. Gli elementi con lo stesso ID in models aggiungono o sostituiscono i modelli di quel provider; per modificare i metadati di un modello integrato senza sostituire l'intero catalogo, usa modelOverrides.

Tre valori predefiniti che causano errori silenziosi

La revisione della documentazione del 22 settembre ha rimosso la tabella dei campi, ma i valori predefiniti sono ancora nel codice sorgente (provider-composer.ts di v0.99.2). Se non li compili, ai modelli personalizzati vengono applicati questi valori:

Inoltre, reasoning ha come predefinito false e input supporta per impostazione predefinita solo il testo. L'esempio Kunavo precedente compila già contesto e limite di output in base al listino e non include cost, perché fissare i prezzi nel file li rende rapidamente obsoleti; per mostrare i costi in fondo, inserisci tu i prezzi per milione di token secondo il listino. Pi supporta anche promptCache (dichiara in secondi la durata della cache del provider, per il riscaldamento della cache); la documentazione consiglia di scegliere l'estremità più conservativa dell'intervallo pubblico.

anthropic-messages: è supportato, ma non è chiaro quale baseUrl usare

anthropic-messages è uno dei quattro valori elencati dalla documentazione precedente per i provider personalizzati e Kunavo offre anche un'interfaccia Anthropic Messages, quindi il percorso api: "anthropic-messages" esiste. Tuttavia la documentazione di Pi non ha mai chiarito se il baseUrl di questo tipo debba includere /v1: prima della revisione, un esempio usava https://proxy.example.com/v1 e un altro mostrava https://proxy.example.com senza percorso; dopo la revisione entrambi gli esempi sono stati rimossi e la questione resta aperta. Se scegli questo percorso, prova una delle due forme e, se la prima richiesta restituisce 404 (non 401), modifica questa riga. In compat sono presenti anche alcuni interruttori pensati per endpoint non originali (come supportsEagerToolInputStreaming e supportsStrictTools), ma la documentazione ricorda che una configurazione compatibile dovrebbe descrivere “differenze di comportamento verificate”, non attivare opzioni solo perché l'endpoint dichiara compatibilità con OpenAI o Anthropic. L'esempio openai-completions precedente evita questi problemi: questo, e non una maggiore velocità, è il vero motivo per cui si consiglia di iniziare da lì.

Spiegazione onesta e pagamenti

Quanto sopra è una guida alla configurazione ricavata dalla documentazione e dal codice sorgente di Pi. Kunavo non ha eseguito il proprio endpoint con Pi: non ha eseguito sessioni, streaming o interazioni con strumenti, né verificato quale modello riceva infine la richiesta. Mantieni il percorso che funziona già e prova a Pi un'attività che legga e scriva file reali; Pi dipende quasi interamente dalle chiamate agli strumenti, quindi una prima esecuzione di questo tipo è il modo migliore per individuare problemi di streaming o di formato degli strumenti. La pagina completa di configurazione in inglese è la guida all'integrazione di Pi; il confronto tra i diversi percorsi a pagamento (incluso il gateway Radius di Earendil) è in prezzi del coding agent Pi.

Kunavo utilizza un saldo prepagato con addebito a consumo dei token e senza canone mensile. La ricarica minima è $10; il checkout passa da Stripe e a Taiwan sono accettate carte di credito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. JkoPay e LINE Pay non sono tra i metodi disponibili. Per maggiori dettagli, consulta le istruzioni sulla fatturazione; quando sei pronto puoi creare un account e generare una chiave.

Domande frequenti

Verificato il 1° ottobre 2026: pi.dev/docs/latest/models (Choose a Model) e la pagina providers; src/core/model-config.ts e provider-composer.ts nel tag v0.99.2 di earendil-works/pi; e le informazioni sulla versione ottenute tramite l'API GitHub. Nello stesso giorno sono stati verificati separatamente, per il campo api: quali valori sono attualmente elencati nella pagina models (solo openai-completions nell'esempio Ollama), il tipo di api in model-config.ts di v0.99.2 (stringa arbitraria, righe 191 e 233), l'instradamento dei modelli personalizzati in provider-composer.ts (riga 579) e BUILTIN_APIS in packages/ai/src/compat.ts (riga 180, dieci valori in totale). Kunavo non ha effettivamente provato il proprio endpoint con Pi.