Instalacja Pi i konfiguracja OmniProxy

Pi to niewielki asystent terminalowy, czyli program, z którym rozmawiasz bezpośrednio w wierszu poleceń i który może czytać pliki oraz wykonywać zadania. Ma krótki monit systemowy i niewiele domyślnych narzędzi. Jeśli potrzebujesz dodatkowych poleceń, procesów lub interfejsów, możesz dodać je później za pomocą rozszerzeń. Rozszerzenia to komponenty zwiększające możliwości Pi, którymi po przygotowaniu można także dzielić się z innymi.

Podagenci umożliwiają przekazanie części zadania innemu asystentowi, a tryb planowania pozwala najpierw uporządkować kroki, a dopiero potem rozpocząć ich wykonywanie. Te dwie funkcje nie są dostępne domyślnie. Możesz poprosić Pi o ich utworzenie albo zainstalować pakiety udostępnione przez innych.

Przygotowanie przed instalacją

W systemach macOS i Linux używa się skryptu instalacyjnego, czyli pojedynczego polecenia, które automatycznie pobiera i instaluje program. W systemie Windows należy użyć polecenia PowerShell dostępnego na stronie głównej Pi. PowerShell to środowisko wiersza poleceń wbudowane w Windows. Pi można również zainstalować w WSL, czyli środowisku Linux działającym w systemie Windows.

Jeśli wybierzesz instalację przez npm, najpierw przygotuj Node.js 22.19 lub nowszy. npm to używany wraz z Node.js menedżer pakietów, który pozwala instalować Pi z wiersza poleceń.

macOS Linux

install.sh

Oficjalny skrypt curl
Zależności są ustalane przez instalator
Aktualizuj przez pi update

Windows

install.ps1

Polecenie PowerShell z oficjalnej strony
Git for Windows zapewnia Bash
Możesz też wejść do WSL

Masz już Node

npm

Wymagany Node 22.19+
Nazwa pakietu to pi-coding-agent
Dodaj --ignore-scripts

Skrypt instalacyjny przypina wersje zależności. Instalacja przez npm nie przypina zależności pośrednich i wymaga dodania --ignore-scripts.

Instalacja i pierwsze uruchomienie

W systemie macOS lub Linux otwórz terminal i uruchom:

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

W systemie Windows otwórz PowerShell, a następnie uruchom:

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

Jeśli masz już zainstalowany Node.js 22.19 lub nowszy, możesz również użyć alternatywnego polecenia z przewodnika Quickstart:

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

Skrypt instalacyjny uruchomiony w terminalu interaktywnym może zatrzymać się i zadać pytania. W takim przypadku postępuj zgodnie z instrukcjami wyświetlanymi na ekranie. Jeśli masz już odpowiednią wersję Node, powyższe polecenie npm nie będzie zadawać pytań. Aby zainstalować program w innym katalogu, dodaj --prefix /twoj-katalog. W teście z 2026-10-09 w ten sposób zainstalowano Pi 1.1.0.

Standardowa instalacja przez npm nie wymaga skryptów cyklu życia zależności, czyli skryptów automatycznie wykonywanych przez pakiety podczas instalacji. Skrypt instalacyjny przypina wersje zależności, a późniejsze aktualizacje wykonuje się poleceniem pi update. W przypadku instalacji przez npm sposób aktualizacji zależy od używanego menedżera pakietów. Użytkownicy Nix powinni instalować Pi z jego flake. Flake to konfiguracja używana przez Nix do opisywania oprogramowania i zależności. Polecenie pi update nie aktualizuje instalacji Nix.

Po zakończeniu instalacji najpierw sprawdź, czy terminal może znaleźć Pi:

pi --version

Jeśli w systemie Windows modele mają wykonywać polecenia Bash, większości użytkowników korzystających z lokalnej instalacji zaleca się zainstalowanie Git for Windows. Bash to środowisko poleceń używane przez Pi do uruchamiania niektórych poleceń. Pi sprawdza kolejno ustawienie shellPath w pliku ~/.pi/agent/settings.json, Git Bash w Program Files oraz plik bash.exe dostępny w PATH. Ustawienie shellPath wskazuje lokalizację Bash, natomiast PATH to lista katalogów, w których system szuka poleceń.

Po uruchomieniu możesz wpisać !printf 'Bash is working\n', aby przeprowadzić test. Jeśli pliki i narzędzia znajdują się już w WSL, zainstaluj Pi w tym środowisku Linux zgodnie z przewodnikiem Quickstart.

Następnie przejdź do katalogu, którego pliki Pi ma przeglądać lub przetwarzać, i uruchom program:

cd /path/to/folder
pi

Ten katalog będzie bieżącym zakresem roboczym Pi. Służy do wykrywania plików i konfiguracji oraz grupowania sesji.

Pobieranie parametrów połączenia z OmniProxy

Najpierw przygotuj w OmniProxy następujące trzy wartości:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: skopiuj pełny identyfikator z bieżącej listy modeli OmniProxy

baseUrl to adres interfejsu, pod który Pi wysyła żądania. Musi kończyć się na /v1. apiKey to klucz używany do uzyskiwania dostępu do interfejsu. Model ID to nazwa wywoływanego modelu, którą należy w całości skopiować z bieżącej listy modeli OmniProxy.

W polu api wpisz wartość openai-completions z przykładu zgodnego interfejsu. To pole informuje Pi, w jakim formacie ma wysyłać żądania.

Identyfikator modelu należy skopiować w całości, zachowując także wszystkie ukośniki w nazwie. Na dzień 2026-10-09 dwa porównawcze identyfikatory w dokumentacji dostawców to gemini-3.8-flash i grok-4.7. Nie kopiuj nazw, których nie ma na liście.

Wprowadzanie konfiguracji narzędzia

Konfigurację niestandardowych modeli użytkownika Pi zapisuje się w pliku models.json. Plik znajduje się w katalogu agenta, którym domyślnie jest ~/.pi/agent, dlatego jego pełna lokalizacja to ~/.pi/agent/models.json. Jeśli ustawiono zmienną środowiskową PI_CODING_AGENT_DIR, Pi użyje wskazanego przez nią katalogu. Zmienna środowiskowa to wartość konfiguracyjna udostępniana programowi przez system.

Wprowadź ustawienia zgodnie z przykładem zgodnego interfejsu:

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

Pole providers zawiera listę podłączonych usług, a models — listę modeli dostępnych do wyboru. Wartość id każdego modelu musi odpowiadać pełnemu identyfikatorowi Model ID z bieżącej listy modeli OmniProxy. Pole input wskazuje, że skonfigurowano tutaj wejście tekstowe.

W polu apiKey możesz bezpośrednio wpisać wartość albo użyć $NAME lub ${NAME}, aby Pi odczytał ją ze zmiennej środowiskowej. Wartość zaczynająca się od ! będzie traktowana jako polecenie wykonywane przy każdym żądaniu. Nie zapisuj prawdziwego klucza w repozytorium. Jeśli brama nie sprawdza klucza, możesz wpisać ciąg zastępczy używany wyłącznie lokalnie. W teście z 2026-10-09 Pi odczytał plik przy takiej konfiguracji.

Otwarcie /model powoduje ponowne wczytanie tego pliku. /model to miejsce w Pi służące do przeglądania i wybierania modeli. Model niestandardowy nie pojawi się w /model, dopóki Pi nie będzie w stanie odczytać danych uwierzytelniających. Po wybraniu modelu naciśnij Ctrl+S, aby zapisać go jako model domyślny dla nowych sesji.

Plik

models.json

Domyślny katalog ~/.pi/agent
Dodaj wpis w providers
api używa completions

Adres

baseUrl

Zakończ adresem /v1
apiKey może być zmienną
Id modelu musi być dokładne

Wybór

/model

Po otwarciu ponownie wczyta plik
Wybierz przed chwilą dodany model
Ctrl+S zapisuje jako domyślny

Po zmodyfikowaniu pliku otwórz /model w Pi i sprawdź, czy model jest widoczny.

Weryfikowanie rzeczywistego zadania

Po zakończeniu konfiguracji możesz przeprowadzić jednorazowy test nieinteraktywny w katalogu zawierającym pliki. Tryb nieinteraktywny nie rozpoczyna ciągłej rozmowy — Pi kończy działanie po wykonaniu jednego zadania. Zastąp wartość po --model pełnym identyfikatorem z bieżącej listy OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Odczytaj pierwszy wiersz wskazanego przeze mnie pliku i nie modyfikuj pliku."

Opcja --tools read udostępnia wyłącznie narzędzie do odczytu, a treść zadania dodatkowo wyraźnie zabrania modyfikowania pliku. W teście z 2026-10-09 Pi 1.1.0 odczytał zawartość pliku. Pierwsza odpowiedź zajęła około dwóch minut.

Możesz również użyć trybu interaktywnego: przejdź do katalogu, uruchom pi, a następnie wybierz model za pomocą /model. Jedno z przykładowych zadań w przewodniku Quickstart polega na poproszeniu Pi o wyjaśnienie, jak jest zorganizowane repozytorium i jak uruchamiać kontrole. Sprawdź, czy Pi odczytał pliki i przedstawił wyjaśnienie, a następnie potwierdź źródło oraz identyfikator modelu w rejestrze wywołań OmniProxy.

Uruchomienie

pi się otwiera

Najpierw przejdź cd do folderu
pi --version wyświetla wynik
Na dole interfejsu widoczna jest nazwa modelu

Zadanie

Przeczytał katalog

Zapytaj, jak zorganizowane jest repozytorium
Sprawdź wymienione przez niego pliki
Nie patrz tylko na zapisanie konfiguracji

Rejestr

Brama go widzi

Źródło to Pi
Identyfikator modelu jest zgodny
Klucz pozostaje na komputerze lokalnym

Po wyświetleniu nazwy modelu u dołu interfejsu należy jeszcze wykonać rzeczywiste zadanie.

Typowe błędy

Nie można znaleźć pi: ponownie otwórz terminal i jeszcze raz uruchom pi --version. Przy instalacji przez npm upewnij się, że globalny katalog bin znajduje się w PATH.
Modelu niestandardowego nie ma w /model: upewnij się, że plik models.json znajduje się w ~/.pi/agent/ i że wartość apiKey może zostać odczytana, a następnie ponownie otwórz /model.
Windows zgłasza, że nie może znaleźć Bash: zainstaluj Git for Windows albo ustaw shellPath w pliku ~/.pi/agent/settings.json. Ukośnik odwrotny w JSON należy zapisać podwójnie.
Żądanie zostało odrzucone: sprawdź, czy api ma wartość openai-completions oraz czy baseUrl kończy się na /v1. Nie włączaj dodatkowych opcji zgodności tylko dlatego, że druga strona deklaruje zgodność.
Identyfikator modelu jest nieprawidłowy: skopiuj go ponownie z bieżącej listy OmniProxy.

Oficjalne materiały

Polecenia instalacyjne znajdziesz na stronie Pi oraz w przewodniku Quickstart. Informacje o pliku modeli zawierają strony Choose a Model i Configuration. Środowisko poleceń dla systemu Windows opisano na stronie Run Pi on Windows. Identyfikatory modeli użyte w przykładach można znaleźć na stronach Gemini — lista modeli i xAI — modele.

Zastąp każdy placeholder wartościami z własnej konfiguracji OmniProxy. Nigdy nie publikuj prawdziwego klucza.

Zapisany wynik lub HTTP 200 samo w sobie nie dowodzi pełnej kompatybilności Agenta. Sprawdź źródło i model w rejestrze połączeń OmniProxy.

Źródła oficjalne · Pi ↗