Установка 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: скопируйте полный идентификатор из текущего списка моделей OmniProxy

baseUrl — адрес API, на который Pi отправляет запросы; он должен заканчиваться на /v1. apiKey — ключ для доступа к API. Model ID — имя вызываемой модели, которое необходимо полностью скопировать из текущего списка моделей OmniProxy.

В поле api укажите openai-completions, как в примере совместимого интерфейса. Это поле сообщает Pi, в каком формате отправлять запросы.

Идентификатор модели нужно копировать целиком, сохраняя в имени все косые черты. На 2026-10-09 в документации поставщиков в качестве двух сопоставляемых идентификаторов использовались gemini-3.8-flash и grok-4.7. Не копируйте эти имена, если их нет в списке.

Заполнение конфигурации инструмента

Пользовательская конфигурация моделей Pi хранится в файле models.json. Этот файл находится в каталоге agent, который по умолчанию расположен по адресу ~/.pi/agent, поэтому полный путь — ~/.pi/agent/models.json. Если задана переменная среды PI_CODING_AGENT_DIR, Pi будет использовать указанный в ней каталог. Переменную среды можно рассматривать как значение конфигурации, предоставляемое системой программе.

Заполните файл по примеру совместимого интерфейса:

{
  "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 полным идентификатором из текущего списка 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 объяснить структуру репозитория и порядок запуска проверок. Убедитесь, что Pi прочитала файлы и предоставила объяснение, а затем проверьте источник и идентификатор модели в журнале вызовов 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. Не включайте дополнительные параметры совместимости только потому, что сервис заявляет о совместимости.
Недействительный идентификатор модели: повторно скопируйте его из текущего списка OmniProxy.

Официальные материалы

Команды установки приведены на сайте Pi и в Quickstart. О файле моделей рассказывается в разделах Choose a Model и Configuration. Командная среда Windows описана в Run Pi on Windows. Использованные в примерах идентификаторы моделей приведены в списке моделей Gemini и на странице моделей xAI.

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

Сохранённый результат или HTTP 200 сами по себе не доказывают полную совместимость Агента. Проверьте источник и модель в журнале вызовов OmniProxy.

Официальные источники · Pi ↗