Installazione di Pi e configurazione di OmniProxy

Pi è un piccolo assistente per terminale, ovvero un programma che conversa direttamente con te dalla riga di comando, legge file e completa attività. Il suo prompt di sistema è breve e gli strumenti predefiniti sono pochi; quando servono altri comandi, flussi di lavoro o interfacce, è possibile aggiungerli tramite estensioni. Le estensioni sono componenti che ampliano le funzionalità di Pi e, una volta create, possono anche essere condivise con altre persone.

I sottoagenti consentono di affidare parte di un’attività a un altro assistente, mentre la modalità di pianificazione organizza prima i passaggi e avvia l’esecuzione in un secondo momento. Queste due funzioni non sono incluse per impostazione predefinita: puoi chiedere a Pi di crearle oppure installare pacchetti condivisi da altri utenti.

Preparazione all’installazione

Su macOS e Linux si utilizza uno script di installazione, cioè un singolo comando che scarica e installa automaticamente il programma. Su Windows si utilizza il comando PowerShell disponibile nella pagina iniziale di Pi; PowerShell è l’ambiente a riga di comando incluso in Windows. In alternativa, puoi installare Pi in WSL, l’ambiente Linux integrato in Windows.

Se scegli l’installazione tramite npm, devi prima installare Node.js 22.19 o una versione successiva. npm è il gestore di pacchetti usato con Node.js e consente di installare Pi dalla riga di comando.

macOS Linux

install.sh

• Script ufficiale con curl
• Le dipendenze sono fissate dall'installer
• Per aggiornare usa pi update

Windows

install.ps1

• Comando PowerShell dal sito ufficiale
• Git for Windows fornisce Bash
• Puoi anche entrare in WSL

Node già installato

npm

• È richiesto Node 22.19+
• Il nome del pacchetto è pi-coding-agent
• Aggiungi --ignore-scripts

Installazione e primo avvio

Su macOS o Linux, apri il terminale ed esegui:

curl -fsSL https://pi.dev/install.sh | sh

Su Windows, apri PowerShell ed esegui:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Se hai già installato Node.js 22.19 o una versione successiva, puoi anche usare il comando alternativo indicato nel Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

In un terminale interattivo, lo script di installazione potrebbe fermarsi per porre alcune domande; segui le istruzioni visualizzate. Se è già presente una versione compatibile di Node, il comando npm non pone domande. Per installare Pi in un’altra directory, aggiungi --prefix /tua/directory. Il 2026-10-09, questa procedura ha installato Pi 1.1.0.

Una normale installazione tramite npm non richiede gli script del ciclo di vita delle dipendenze, cioè gli script eseguiti automaticamente dai pacchetti durante l’installazione. Lo script di installazione blocca le versioni delle dipendenze; successivamente, usa pi update per aggiornare Pi. Per un’installazione tramite npm, il metodo di aggiornamento dipende dal gestore di pacchetti utilizzato. Gli utenti Nix devono installare Pi dal relativo flake; un flake è la configurazione con cui Nix descrive software e dipendenze, e pi update non può aggiornare un’installazione Nix.

Al termine dell’installazione, verifica innanzitutto che Pi sia accessibile dal terminale:

pi --version

Su Windows, se vuoi consentire al modello di eseguire comandi Bash, per la maggior parte degli utenti locali è consigliabile installare Git for Windows. Bash è l’ambiente di comando utilizzato da Pi per eseguire alcuni comandi. Pi cerca, nell’ordine, il valore shellPath in ~/.pi/agent/settings.json, Git Bash in Program Files e infine bash.exe nel PATH. shellPath specifica la posizione di Bash, mentre PATH è l’elenco di directory in cui il sistema cerca i comandi.

Dopo l’avvio, puoi digitare !printf 'Bash is working\n' per eseguire una verifica. Se i file e gli strumenti si trovano già in WSL, installa Pi in quell’ambiente Linux seguendo il Quickstart.

Entra quindi nella cartella che vuoi far esaminare o elaborare da Pi e avvialo:

cd /path/to/folder
pi

Questa cartella diventa l’ambito di lavoro corrente di Pi: viene utilizzata per individuare file e configurazioni e per raggruppare le sessioni.

Ottenere i parametri di connessione da OmniProxy

Prepara innanzitutto questi tre valori in OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copia l’ID completo dall’elenco attuale dei modelli di OmniProxy

baseUrl è l’indirizzo dell’interfaccia a cui Pi invia le richieste e deve terminare con /v1. apiKey è la chiave utilizzata per accedere all’interfaccia. Model ID è il nome del modello da chiamare e deve essere copiato integralmente dall’elenco attuale dei modelli di OmniProxy.

Nel campo api, inserisci openai-completions, come nell’esempio dell’interfaccia compatibile. Questo campo indica a Pi quale formato di interfaccia utilizzare per inviare le richieste.

Copia l’intero ID del modello, mantenendo anche le barre presenti nel nome. Al 2026-10-09, i due ID di riferimento presenti nella documentazione dei fornitori erano gemini-3.8-flash e grok-4.7. Non copiare nomi che non compaiono nell’elenco.

Inserire la configurazione dello strumento

La configurazione personalizzata dei modelli a livello utente di Pi si trova in models.json. Questo file si trova nella directory agent, che per impostazione predefinita è ~/.pi/agent; il percorso completo è quindi ~/.pi/agent/models.json. Se è impostata la variabile d’ambiente PI_CODING_AGENT_DIR, Pi utilizza invece la directory specificata dalla variabile. Una variabile d’ambiente è un valore di configurazione fornito dal sistema affinché un programma possa leggerlo.

Compila il file seguendo l’esempio dell’interfaccia compatibile:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers elenca i servizi collegati, mentre models elenca i modelli selezionabili. L’id di ogni modello deve corrispondere al Model ID completo presente nell’elenco attuale dei modelli di OmniProxy; input indica che il modello è configurato per l’input testuale.

Puoi inserire direttamente il valore letterale di apiKey oppure usare $NAME o ${NAME}, in modo che Pi lo legga da una variabile d’ambiente. Un valore che inizia con ! viene interpretato come comando ed eseguito a ogni richiesta. Non inviare la chiave reale a un repository. Se il gateway non verifica la chiave, puoi inserire una stringa segnaposto usata soltanto sul computer locale. Il 2026-10-09, il file è stato letto correttamente con questa configurazione.

Aprendo /model, Pi ricarica il file. /model è il punto di accesso usato in Pi per visualizzare e selezionare i modelli. I modelli personalizzati non compaiono in /model finché Pi non riesce a interpretare le credenziali. Dopo aver selezionato un modello, premi Ctrl+S per salvarlo come modello predefinito delle nuove sessioni.

File

models.json

• Directory predefinita ~/.pi/agent
• Aggiungi una voce in providers
• api usa completions

Indirizzo

baseUrl

• Impostalo fino a /v1
• apiKey può contenere una variabile
• L'id del modello deve essere preciso

Selezione

/model

• Dopo l'apertura ricarica il file
• Seleziona il modello appena configurato
• Ctrl+S salva come predefinito

Verificare un’attività reale

Dopo aver completato la configurazione, puoi eseguire una verifica non interattiva in una directory contenente file. In modalità non interattiva, Pi non avvia una conversazione continuativa e termina dopo aver completato la singola attività. Sostituisci il valore dopo --model con l’ID completo presente nell’elenco attuale di OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Leggi la prima riga del file specificato senza modificare il file."

In questo caso, --tools read abilita esclusivamente lo strumento di lettura e l’attività richiede esplicitamente di non modificare il file. Il 2026-10-09, Pi 1.1.0 ha letto il contenuto del file. La prima risposta ha richiesto circa due minuti.

Puoi anche utilizzare la modalità interattiva: entra nella directory, esegui pi e seleziona il modello con /model. Un’attività di esempio del Quickstart chiede a Pi di spiegare come è organizzato il repository e come eseguire i controlli. Verifica che legga i file e fornisca una spiegazione, quindi controlla nei registri delle chiamate di OmniProxy l’origine e l’ID del modello.

Avvio

pi si apre

• Esegui prima cd nella cartella
• pi --version produce un output
• Il nome del modello è in fondo all'interfaccia

Attività

Ha letto la directory

• Chiedi come è organizzato il repository
• Controlla i file elencati
• Non limitarti a verificare il salvataggio della configurazione

Registri

Visibile dal gateway

• La fonte è Pi
• L'ID del modello corrisponde
• La chiave resta sul computer locale

Errori comuni

• pi non viene trovato: riapri il terminale e riprova con pi --version. Se hai usato npm, verifica che la directory bin globale sia inclusa nel PATH.
• Il modello personalizzato non compare in /model: verifica che models.json si trovi in ~/.pi/agent/, che apiKey possa essere interpretata, quindi riapri /model.
• Windows segnala che Bash non è disponibile: installa Git for Windows oppure imposta shellPath in ~/.pi/agent/settings.json. In JSON, ogni barra rovesciata deve essere scritta due volte.
• La richiesta viene rifiutata: verifica che api sia openai-completions e che baseUrl termini con /v1. Non attivare opzioni di compatibilità aggiuntive soltanto perché il servizio dichiara di essere compatibile.
• L’ID del modello non è valido: copialo nuovamente dall’elenco attuale di OmniProxy.

Riferimenti ufficiali

I comandi di installazione sono disponibili nel sito di Pi e nel Quickstart. Per il file dei modelli, consulta Choose a Model e Configuration. Per l’ambiente di comando di Windows, consulta Run Pi on Windows. Gli ID dei modelli usati negli esempi sono disponibili nell’elenco dei modelli Gemini e nella pagina dei modelli xAI.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · Pi ↗