Встановлення Pi та налаштування OmniProxy

Pi — це компактний термінальний асистент, тобто програма, з якою можна спілкуватися безпосередньо в командному рядку, доручати їй читати файли та виконувати завдання. Він має коротку системну підказку й небагато стандартних інструментів; за потреби інші команди, робочі процеси чи інтерфейси можна додати за допомогою розширень. Розширення — це компоненти, які надають Pi додаткові можливості; створеними розширеннями також можна ділитися з іншими.

Субагент дає змогу передати частину завдання іншому асистентові, а режим планування передбачає спочатку впорядкувати кроки й лише потім почати виконання. Ці дві можливості не входять до стандартного набору функцій, але можна попросити Pi створити їх або встановити пакет, яким поділилися інші.

Підготовка до встановлення

У macOS і Linux використовується інсталяційний скрипт — одна команда, яка автоматично завантажує та встановлює програму. У Windows використовується команда PowerShell, наведена на головній сторінці Pi; PowerShell — це вбудоване у Windows середовище командного рядка. Pi також можна встановити у WSL, тобто в середовищі Linux усередині Windows.

Якщо ви обираєте встановлення через npm, спочатку підготуйте Node.js 22.19 або новішої версії. npm — це менеджер пакетів, який використовується разом із Node.js і дає змогу встановити Pi з командного рядка.

macOS Linux

install.sh

Використовуйте офіційний скрипт через curl
Версії залежностей фіксує інсталятор
Для оновлення використовуйте pi update

Windows

install.ps1

Команда PowerShell з офіційного сайту
Git for Windows надає Bash
Також можна використовувати WSL

Node уже встановлено

npm

Потрібен Node 22.19+
Назва пакета — pi-coding-agent
Додайте --ignore-scripts

Інсталяційний скрипт фіксує версії залежностей. Встановлення через npm не фіксує непрямі залежності та потребує параметра --ignore-scripts.

Встановлення та перший запуск

У macOS або Linux відкрийте термінал і виконайте:

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

У Windows відкрийте PowerShell і виконайте:

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

Якщо вже встановлено Node.js 22.19 або новішої версії, можна також скористатися альтернативною командою з Quickstart:

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

В інтерактивному терміналі інсталяційний скрипт може зупинитися й поставити запитання — у такому разі продовжуйте відповідно до підказок на екрані. Якщо відповідна версія Node уже встановлена, ця команда npm не ставитиме запитань. Щоб установити програму в інший каталог, додайте --prefix /ваш-каталог. Станом на 2026-10-09 таким способом було встановлено Pi 1.1.0.

Для звичайного встановлення через npm не потрібні скрипти життєвого циклу залежностей, тобто скрипти, які пакети автоматично виконують під час встановлення. Інсталяційний скрипт фіксує версії залежностей; надалі для оновлення використовуйте pi update. Спосіб оновлення встановлення через npm залежить від менеджера пакетів, яким ви користуєтеся. Користувачам Nix слід установлювати Pi з його flake; flake — це конфігурація Nix для опису програмного забезпечення та залежностей, і команда pi update не може оновити встановлення через Nix.

Після завершення встановлення спочатку переконайтеся, що термінал знаходить Pi:

pi --version

Якщо у Windows потрібно, щоб модель виконувала команди Bash, більшості користувачів локальної системи рекомендовано встановити Git for Windows. Bash — це командне середовище, яке Pi використовує для виконання частини команд. Pi послідовно шукає shellPath у ~/.pi/agent/settings.json, Git Bash у Program Files, а потім bash.exe у PATH. Параметр shellPath задає розташування Bash, а PATH — це список каталогів, у яких система шукає команди.

Після запуску можна ввести !printf 'Bash is working\n', щоб виконати перевірку. Якщо файли та інструменти вже розташовані у WSL, установіть Pi в цьому середовищі Linux відповідно до Quickstart.

Далі перейдіть до папки, файли якої Pi має переглядати або обробляти, і запустіть програму:

cd /path/to/folder
pi

Ця папка стане поточною робочою областю Pi: у ній програма шукатиме файли й конфігурацію, а також використовуватиме її для групування сеансів.

Отримання параметрів підключення з OmniProxy

Спочатку підготуйте в OmniProxy такі три значення:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Скопіюйте повний ID із поточного списку моделей OmniProxy

baseUrl — це адреса API, на яку Pi надсилатиме запити; вона має закінчуватися на /v1. apiKey — ключ для доступу до API. Model ID — назва моделі, яку потрібно викликати; її слід повністю скопіювати з поточного списку моделей OmniProxy.

У полі api вкажіть openai-completions, як у прикладі сумісного API. Це поле повідомляє Pi, у якому форматі API надсилати запити.

Скопіюйте ID моделі повністю, зберігши також усі скісні риски в назві. Станом на 2026-10-09 у документації постачальників як два контрольні ID використовувалися gemini-3.8-flash і grok-4.7. Не копіюйте назви, яких немає у списку.

Заповнення конфігурації інструмента

Користувацька конфігурація моделей Pi зберігається у файлі models.json. Цей файл розташований у каталозі agent, стандартним шляхом до якого є ~/.pi/agent, тому повний шлях — ~/.pi/agent/models.json. Якщо задано змінну середовища PI_CODING_AGENT_DIR, Pi використовуватиме вказаний у ній каталог; змінну середовища можна розуміти як значення конфігурації, яке система надає програмі для зчитування.

Заповніть файл за прикладом сумісного API:

{
  "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 містить список підключених сервісів, а models — список доступних для вибору моделей. Поле id кожної моделі має точно відповідати повному Model ID із поточного списку OmniProxy, а input означає, що тут налаштовано текстове введення.

Значення apiKey можна вказати безпосередньо або записати у форматі $NAME чи ${NAME}, щоб Pi зчитував його зі змінної середовища. Значення, що починається з !, вважатиметься командою та виконуватиметься під час кожного запиту. Не додавайте справжній ключ до репозиторію. Якщо шлюз не перевіряє ключ, можна вказати рядок-заповнювач, який використовується лише локально. Станом на 2026-10-09 файл у такий спосіб було успішно прочитано.

Після відкриття /model цей файл буде завантажено повторно. /model — це розділ Pi для перегляду та вибору моделей. Користувацькі моделі не з’являться в /model, доки Pi не зможе розпізнати облікові дані. Після вибору моделі натисніть Ctrl+S, щоб зберегти її як стандартну модель для нових сеансів.

Файл

models.json

Типовий каталог — ~/.pi/agent
Додайте запис до providers
Для api використовуйте completions

Адреса

baseUrl

Завершіть адресу на /v1
Для apiKey можна вказати змінну
id моделі має бути точним

Вибір

/model

Після відкриття файл буде перезавантажено
Виберіть щойно додану модель
Натисніть Ctrl+S, щоб зберегти як типову

Після редагування файлу відкрийте /model у Pi та переконайтеся, що модель з’явилася.

Перевірка на реальному завданні

Після завершення налаштування можна виконати неінтерактивну перевірку в каталозі, де є файли. Неінтерактивний режим означає, що постійний діалог не запускається: Pi завершує роботу після виконання одного завдання. Замініть значення після --model повним ID із поточного списку OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Прочитай перший рядок указаного тобою файлу й не змінюй файл."

Параметр --tools read надає доступ лише до інструмента читання, а в самому завданні також прямо зазначено не змінювати файл. Під час перевірки 2026-10-09 Pi 1.1.0 прочитав вміст файлу. Перша відповідь надійшла приблизно за дві хвилини.

Також можна скористатися інтерактивним режимом: перейдіть до каталогу, запустіть pi, а потім виберіть модель через /model. Один із прикладів завдань у Quickstart — попросити Pi пояснити, як організовано цей репозиторій і як запускати перевірки. Переконайтеся, що він прочитав файли та надав пояснення, а потім перевірте джерело й ID моделі в журналі викликів OmniProxy.

Запуск

pi запускається

Спочатку виконайте cd до папки
pi --version виводить результат
У нижній частині інтерфейсу є назва моделі

Завдання

Він прочитав каталог

Запитайте, як організовано репозиторій
Перегляньте перелічені ним файли
Не обмежуйтеся повідомленням про збереження налаштувань

Журнал

Шлюз бачить запит

Джерело — Pi
ID моделі збігається
Ключ залишається на локальному комп’ютері

Навіть після появи назви моделі в нижній частині інтерфейсу потрібно виконати одне реальне завдання.

Поширені помилки

Не вдається знайти pi: перезапустіть термінал і знову виконайте pi --version. Якщо програму встановлено через npm, переконайтеся, що глобальний каталог bin додано до PATH.
Користувацької моделі немає в /model: переконайтеся, що файл models.json розташований у ~/.pi/agent/, а значення apiKey можна розпізнати, після чого знову відкрийте /model.
Windows повідомляє, що не може знайти Bash: установіть Git for Windows або задайте shellPath у ~/.pi/agent/settings.json. У JSON кожну зворотну скісну риску потрібно записувати двічі.
Запит відхилено: перевірте, чи значення api дорівнює openai-completions, а baseUrl закінчується на /v1. Не вмикайте додаткові параметри сумісності лише тому, що інша сторона заявляє про сумісність.
Недійсний ID моделі: повторно скопіюйте його з поточного списку OmniProxy.

Офіційні довідкові матеріали

Команди встановлення наведено на сайті Pi та в Quickstart. Інформацію про файл моделей дивіться в Choose a Model і Configuration. Відомості про командне середовище Windows наведено в Run Pi on Windows. ID моделей, використані в прикладах, наведено в списку моделей Gemini і на сторінці моделей xAI.

Замістіть усі заповнювачі значеннями з вашої власної конфігурації OmniProxy. Ніколи не публікуйте справжній ключ.

Збережений результат або HTTP 200 самі по собі не доводять повну сумісність Агента. Перевірте джерело та модель у журналі викликів OmniProxy.

Офіційні джерела · Pi ↗