Pi installeren en OmniProxy configureren

Pi is een kleine terminal-assistent—een programma dat rechtstreeks met je praat in de opdrachtregel, bestanden leest en taken voltooit. Het heeft standaard een korte systeemprompt en slechts enkele tools. Als je andere commando’s, workflows of interfaces nodig hebt, kun je deze later toevoegen via extensies. Extensies zijn componenten die mogelijkheden toevoegen aan Pi, en je kunt ze met anderen delen nadat je ze hebt gemaakt.

Subagents delegeren een deel van een taak aan een andere assistent, terwijl de plan-modus de stappen organiseert voordat de uitvoering begint. Geen van beide functies is standaard inbegrepen, maar je kunt Pi vragen ze te bouwen of pakketten te installeren die door anderen zijn gedeeld.

Voordat je begint

macOS en Linux gebruiken een installatiescript—één commando dat Pi automatisch downloadt en installeert. Gebruik op Windows het PowerShell-commando dat op de Pi-homepage wordt verstrekt. PowerShell is de opdrachtregelomgeving die bij Windows is inbegrepen. Je kunt Pi ook installeren in WSL, de Linux-omgeving die beschikbaar is binnen Windows.

Als je ervoor kiest om met npm te installeren, heb je Node.js 22.19 of nieuwer nodig. npm is de pakketbeheerder die bij Node.js wordt gebruikt en kan Pi vanaf de opdrachtregel installeren.

macOS Linux

install.sh

• curl het officiële script
• De installer pint de afhankelijkheden
• Update met pi update

Windows

install.ps1

• Officieel PowerShell-commando
• Git for Windows biedt Bash
• Je kunt ook WSL gebruiken

Node al geïnstalleerd

npm

• Vereist Node 22.19+
• De pakketnaam is pi-coding-agent
• Voeg --ignore-scripts toe

Pi installeren en voor de eerste keer opstarten

Open op macOS of Linux een terminal en voer uit:

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

Open op Windows PowerShell en voer uit:

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

Als Node.js 22.19 of nieuwer al is geïnstalleerd, kun je ook het alternatieve commando uit de Quickstart gebruiken:

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

Het installatiescript kan pauzeren om vragen te stellen in een interactieve terminal. Volg de aanwijzingen op het scherm om door te gaan. Als je al een compatibele versie van Node hebt, zal dit npm-commando geen vragen stellen. Om Pi in een andere directory te installeren, voeg je --prefix /your/directorytoe. Op 09-10-2026 installeerde dit Pi 1.1.0.

Een normale npm-installatie vereist geen dependency lifecycle-scripts, dit zijn scripts die pakketten automatisch uitvoeren tijdens de installatie. Het installatiescript pint afhankelijkheden; update Pi daarna met pi update. Gebruik voor een npm-installatie de updatemethode die door je pakketbeheerder wordt verstrekt. Nix-gebruikers moeten installeren vanuit de flake van Pi. Een flake is een Nix-configuratie die software en de afhankelijkheden ervan beschrijft, en pi update kan een Nix-installatie niet bijwerken.

Bevestig na installatie eerst dat je terminal Pi kan vinden:

pi --version

Op Windows wordt voor de meeste lokale gebruikers aanbevolen om Git for Windows te installeren als je wilt dat modellen Bash-commando’s uitvoeren. Bash is de commando-omgeving die Pi gebruikt om sommige commando’s uit te voeren. Pi controleert de shellPath instelling in ~/.pi/agent/settings.json, Git Bash onder Program Files, en vervolgens bash.exe op PATH, in die volgorde. shellPath specificeert de locatie van Bash, terwijl PATH de lijst met mappen is die het systeem doorzoekt naar commando’s.

Nadat je Pi hebt gestart, kun je !printf 'Bash is working\n' invoeren om het te controleren. Als je bestanden en tools al in WSL staan, installeer Pi dan in die Linux-omgeving door de Quickstart te volgen.

Ga vervolgens naar de map die je door Pi wilt laten inspecteren of waaraan je wilt werken, en start het:

cd /path/to/folder
pi

Deze map wordt het huidige werkbereik van Pi. Pi gebruikt het om bestanden en configuratie te ontdekken en om sessies te groeperen.

Verbindingswaarden ophalen uit OmniProxy

Verkrijg eerst deze drie waarden uit OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl is het API-eindpunt waarnaar Pi verzoeken stuurt en moet /v1 bevatten. apiKey is de sleutel die wordt gebruikt om toegang te krijgen tot de API. Model ID is de naam van het model dat moet worden aangeroepen en moet volledig worden gekopieerd uit de huidige modellijst van OmniProxy.

Stel api in op openai-completions, zoals getoond in het compatibele API-voorbeeld. Dit veld vertelt Pi welk API-formaat moet worden gebruikt bij het verzenden van verzoeken.

Kopieer de volledige model-ID, inclusief eventuele slashes in de naam. Op 09-10-2026 waren de twee referentie-ID’s in de documentatie van de provider gemini-3.8-flash en grok-4.7. Kopieer geen naam die niet in de lijst staat.

De toolconfiguratie invoeren

De aangepaste modelconfiguratie op gebruikersniveau van Pi wordt opgeslagen in models.json. Dit bestand bevindt zich in de agent-directory, die standaard ~/.pi/agentis, dus het volledige pad is ~/.pi/agent/models.json. Als de PI_CODING_AGENT_DIR omgevingsvariabele is ingesteld, gebruikt Pi de directory die door die variabele is opgegeven. Een omgevingsvariabele is een configuratiewaarde die door het systeem wordt geleverd zodat programma’s deze kunnen lezen.

Voer de configuratie in zoals getoond in het compatibele API-voorbeeld:

{
  "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 somt de verbonden services op, terwijl models de modellen opsomt die kunnen worden geselecteerd. Elke id van het model moet overeenkomen met de volledige Model ID in de huidige modellijst van OmniProxy. input geeft aan dat het model hier is geconfigureerd voor tekstinvoer.

apiKey kan worden ingevoerd als een letterlijke waarde, of als $NAME of ${NAME} zodat Pi het leest uit een omgevingsvariabele. Een waarde die begint met ! wordt behandeld als een commando en uitgevoerd voor elk verzoek. Commit geen echte sleutel naar een repository. Als de gateway geen sleutels valideert, kun je een tijdelijke tekenreeks invoeren die alleen op je lokale machine wordt gebruikt. Op 09-10-2026 las Pi het bestand met succes met deze configuratie.

Het openen van /model laadt dit bestand opnieuw. /model is de interface in Pi voor het bekijken en selecteren van modellen. Aangepaste modellen verschijnen niet in /model totdat Pi hun inloggegevens kan verwerken. Nadat je een model hebt geselecteerd, druk je op Ctrl+S om het op te slaan als het standaardmodel voor nieuwe sessies.

Bestand

models.json

• Standaarddirectory: ~/.pi/agent
• Voeg een item toe onder providers
• Stel api in op completions

Adres

baseUrl

• Inclusief /v1
• apiKey kan verwijzen naar een variabele
• De model-id moet exact zijn

Selecteer

/model

• Het openen ervan laadt het bestand opnieuw
• Selecteer het model dat je zojuist hebt toegevoegd
• Ctrl+S slaat het op als de standaard

Verifiëren met een echte taak

Na het voltooien van de configuratie kun je een niet-interactieve controle uitvoeren in een directory die bestanden bevat. Niet-interactieve modus betekent dat Pi deze ene taak voltooit en vervolgens afsluit in plaats van een lopend gesprek aan te gaan. Vervang de waarde na --model door de volledige ID uit de huidige OmniProxy-lijst:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

Hier, --tools read schakelt alleen de lees-tool in, en de taak instrueert Pi ook expliciet om het bestand niet te wijzigen. Op 09-10-2026 las Pi 1.1.0 de bestandsinhoud met succes. De eerste respons duurde ongeveer twee minuten.

Je kunt ook de interactieve modus gebruiken: ga naar de directory, voer piuit en selecteer vervolgens een model met /model. Een voorbeeldtaak in de Quickstart vraagt Pi om uit te leggen hoe de repository is georganiseerd en hoe de controles ervan kunnen worden uitgevoerd. Observeer of het de bestanden leest en een uitleg geeft, en bevestig vervolgens de bron en model-ID in de verzoeklogboeken van OmniProxy.

Opstarten

pi start op

• Ga eerst met cd naar de map
• pi --version geeft uitvoer
• De modelnaam verschijnt onderaan de interface

Taak

Het las de directory

• Vraag hoe de repository is georganiseerd
• Bekijk de bestanden die het opsomt
• Vertrouw niet alleen op een succesvolle configuratie-opslag

Logboeken

Zichtbaar in de gateway

• Bron is Pi
• Model-ID komt overeen
• Houd de sleutel op de lokale machine

Veelvoorkomende fouten

• pi kan niet worden gevonden: Open de terminal opnieuw en probeer pi --version opnieuw. Bevestig bij een npm-installatie dat de globale bin-directory op PATH staat.
• De aangepaste modellen verschijnen niet in /model: Bevestig dat models.json in ~/.pi/agent/staat, verifieer dat apiKey kan worden opgelost en open vervolgens /modelopnieuw.
• Windows meldt dat Bash niet kan worden gevonden: Installeer Git for Windows, of stel shellPath in ~/.pi/agent/settings.json. Backslashes in JSON moeten dubbel worden geschreven.
• Het verzoek wordt afgewezen: Controleer of api is openai-completions en dat baseUrl eindigt op /v1. Schakel geen extra compatibiliteitsopties in alleen omdat de service zichzelf als compatibel beschrijft.
• De model-ID is ongeldig: Kopieer deze opnieuw uit de huidige OmniProxy-lijst.

Officiële referenties

Zie voor installatiecommando’s de Pi website en Quickstart. Zie voor het modelbestand Choose a Model en Configuration. Zie voor de Windows-commando-omgeving Run Pi on Windows. Zie voor de model-ID’s die in de voorbeelden worden gebruikt de Gemini model list en xAI models page.

Vervang elke placeholder met waarden uit uw eigen OmniProxy-configuratie. Publiceer nooit een echte sleutel.

Een opgeslagen resultaat of HTTP 200 alleen bewijst geen volledige Agent-compatibiliteit. Controleer de bron en het model in het oproeprecord van OmniProxy.

Officiële bronnen · Pi ↗