Pi installeren en OmniProxy configureren

Pi is een kleine terminal-assistent—een programma dat direct met je praat in de opdrachtregel, bestanden leest en taken uitvoert. Het heeft een korte systeem-prompt en standaard slechts een paar tools. Als je andere opdrachten, workflows of interfaces nodig hebt, kun je deze later toevoegen via extensies. Extensies zijn componenten die mogelijkheden toevoegen aan Pi, en je kunt ze delen met anderen 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 opdracht die Pi automatisch downloadt en installeert. Gebruik op Windows de PowerShell-opdracht die op de Pi-homepage staat. 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 te installeren met npm, heb je Node.js 22.19 of later nodig. npm is de pakketbeheerder die wordt gebruikt met Node.js en kan Pi installeren vanaf de opdrachtregel.

macOS Linux

install.sh

• curl het officiële script
• Het installatieprogramma zet de afhankelijkheden vast
• Bijwerken met pi update

Windows

install.ps1

• Officiële PowerShell-opdracht
• 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 starten

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 later al is geïnstalleerd, kun je ook de alternatieve opdracht 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 deze npm-opdracht geen vragen stellen. Om Pi in een andere map te installeren, voeg je toe --prefix /your/directory. 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 zet afhankelijkheden vast; werk Pi daarna bij met pi update. Gebruik voor een npm-installatie de update-methode van je pakketbeheerder. 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.

Controleer na de installatie eerst of 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-opdrachten uitvoeren. Bash is de opdrachtomgeving die Pi gebruikt om sommige opdrachten 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 opdrachten.

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 Pi moet inspecteren of waaraan moet worden gewerkt, en start het:

cd /path/to/folder
pi

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

Verbindingswaarden verkrijgen van OmniProxy

Verkrijg eerst deze drie waarden van 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 OmniProxy-modellijst.

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-map, 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 map 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 bevat de verbonden services, terwijl models de modellen bevat die kunnen worden geselecteerd. De id van elk model moet overeenkomen met de volledige Model-ID in de huidige OmniProxy-modellijst. 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 opdracht en uitgevoerd voor elk verzoek. Commit geen echte sleutel naar een repository. Als de gateway sleutels niet valideert, kun je een tijdelijke aanduiding (placeholder) invoeren die alleen op je lokale machine wordt gebruikt. Op 09-10-2026 las Pi het bestand succesvol 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 oplossen. 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

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

Adres

baseUrl

• Voeg /v1 toe
• 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 standaard

Verifiëren met een echte taak

Na het voltooien van de configuratie kun je een niet-interactieve controle uitvoeren in een map met bestanden. Niet-interactieve modus betekent dat Pi deze enkele taak voltooit en vervolgens afsluit in plaats van een doorlopend 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 succesvol. De eerste reactie duurde ongeveer twee minuten.

Je kunt ook de interactieve modus gebruiken: ga naar de map, 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 checks moeten 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.

Starten

pi start

• Eerst cd naar de map
• pi --version produceert uitvoer
• De modelnaam verschijnt onderaan de interface

Taak

Het las de map

• 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-map 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 installatie-opdrachten de Pi-website en Quickstart. Zie voor het modelbestand Kies een model en Configuratie. Zie voor de Windows-opdrachtomgeving Pi uitvoeren op Windows. Zie voor de model-ID’s die in de voorbeelden worden gebruikt de Gemini-modellijst en xAI-modellenpagina.

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

Een opgeslagen resultaat of HTTP 200 alleen bewijst niet volledige agentcompatibiliteit. Controleer de bron en het model in de verzoeklog van OmniProxy.

Officiële bronnen · Pi ↗