В комментариях Pi называют «ещё одним заменителем Claude Code». Ставите пакет — и сразу видите: sub-agent и plan mode сюда сознательно не положили. Настоящая боль в другом: ключи всё ещё заперты внутри чужой подписки, а смена модели равна смене всего рабочего процесса. Дальше проверяем, чего не хватает в 2026 году: более толстой IDE — или минимального harness, который умеет менять Claude, GPT и Gemini и встраивается в TypeScript-репозиторий.
По состоянию на 16 сентября 2026 года Pi Coding Agent (npm: @earendil-works/pi-coding-agent) — это минимальный терминальный coding harness: интерактивный TUI, print/JSON, RPC и TypeScript SDK. Статья разбирает установку через npm, API-ключ и auth.json, переключение трёх провайдеров и путь, как вписать SDK в репозиторий — по входу, исполнению и контексту, а не в жанре «кто умнее».
Почему «ещё один IDE-агент» не решает мультимодельность
В 2026 году у большинства команд боль не в том, что «агента нет». Боль в том, что ключи, модель и среда исполнения склеены в одном продукте. Claude Code живёт на подписке Anthropic, Codex CLI — на ChatGPT, Cursor прячет выбор модели внутри аккаунта редактора. Днём хочется править архитектуру в Claude, вечером прогонять тесты через Gemini, в выходные писать commit message в GPT — и каждый раз приходится менять окно, права и контекст. Это не каприз «попробовать новую модель». Это ежедневный налог на переключение, который никто не ставит в квартальный отчёт, но который съедает вечер пятницы.
Закрытый агент обещает «просто открой и пиши». На практике вы покупаете не интеллект, а связку: биллинг + окно + правила + история сессий. Пока команда сидит на одной подписке, связка удобна. Как только появляется вторая задача с другим ценовым профилем — дешёвый обход репозитория, длинный рефакторинг, ночной обзор PR — выясняется, что «просто сменить модель» означает заново собрать привычки. Люди начинают держать три терминала, три набора правил и три способа сказать агенту «не трогай .env».
Pi ломает эту предпосылку. Официальная позиция — минимальный harness: по умолчанию модели дают четыре инструмента, read, write, edit и bash. Sub-agent, plan mode, гейт прав и MCP — то, что «у других встроено», — выносятся в расширения, Skills или Pi Package и добавляются по вашему workflow. Модель здесь сменный бэкенд, а не суть продукта. Если вам нужен толстый планёр из коробки, Pi покажется худым. Если вы уже устали от того, что смена бэкенда ломает скрипты, худоба — это и есть продукт.
Асимметричный вывод: водораздел не в том, кто сильнее — Claude, GPT или Gemini, а в том, умеет ли harness считать модель сменным исполнительным бэкендом и встраиваться в ваш TypeScript-проект. Усиливать нужно вход (CLI / SDK / RPC), слои учётных данных и постоянно включённый узел исполнения — а не ставить ещё одну более толстую IDE. Концептуальный разбор «что такое harness» — в статье Omnigent Agent Harness 2026: разбор; здесь только практика: как поставить Pi, подключить три ключа и вписать цикл в репозиторий.
Ещё одно наблюдение, которое редко попадает в обзоры: IDE-агент отлично выглядит на демо, потому что diff рядом с курсором. Он плохо масштабируется в ночной обзор, в Makefile и в self-hosted runner, потому что вход — боковая панель человека, а не процесс, который можно вызвать из скрипта. Если ваша команда уже пишет «агент должен прогнать lint и оставить комментарий», спор про шрифты в чате закончился. Нужен harness с несколькими входами на одном и том же цикле инструментов.
Что такое Pi: четыре входа минимального harness
Сначала классификация, потом команды. Pi — не ещё одно чат-окно, а четыре способа открыть один и тот же агентный цикл. Измерения те же: вход, исполнение, контекст и целевая аудитория. Если запомнить только это, остальное — детали установки.
| Инструмент / форма | Вход | Исполнительные возможности | Контекст | Целевая аудитория |
|---|---|---|---|---|
| Интерактивный TUI | pi; /model, /login, /tree | Чтение, запись, правка файлов, bash; можно ставить Skills / расширения | Дерево сессий в ~/.pi/agent/sessions/; подгружает AGENTS.md | Ежедневная правка репозитория, когда нужно свернуть с курса на середине |
| Print / JSON | pi -p "…"; --mode json | Разовые задачи; удобно для скриптов и CI | По умолчанию пишет сессию; можно --no-session | Тем, кто вставляет агента в Makefile / GitHub Actions |
| RPC | JSON-протокол через stdin/stdout | Не-Node хост поднимает тот же цикл | Сессии и права держит хост | Тем, кто встраивает Pi в готовый шлюз или десктопную оболочку |
| TypeScript SDK | createAgentSession() / ModelRuntime | Те же инструменты и каталог моделей, что у CLI | По умолчанию видит cwd и ~/.pi/agent; путь auth можно сменить | Тем, кто пишет в репозитории пайплайны ревью, правок и обходов |
На сайте философия сформулирована прямо: меняйте harness, а не свой workflow. Расширения — модули TypeScript: регистрируют инструменты, slash-команды, горячие клавиши и виджеты TUI. Skills подгружаются по необходимости, чтобы сразу не раздувать prompt cache. Пакеты ставятся как pi install npm:@scope/pkg или pi install git:host/user/repo. Полный список возможностей смотрите на pi.dev и в описании npm-пакета: номера версий плывут, форма команд стабильнее, чем «имя модели на конкретный месяц».
Практический смысл четырёх входов простой. Человек днём работает в TUI: видит дерево сессий, меняет модель на лету, может остановить агента и дать новую инструкцию. Ночью тот же цикл должен пробежать без клавиатуры — тогда вход -p или SDK. Если у вас уже есть шлюз на другом языке, RPC позволяет не переписывать цикл на Node. Ошибка новичков — поставить только TUI и решить, что «Pi не для CI». Не поставили второй вход, а не «агент слабый».
Ещё одна деталь, которую стоит зафиксировать до установки: Pi не обещает заменить продуктовую оркестровку нескольких ролей. Это coding harness на одном цикле «прочитай — правь — запусти». Если вам нужен класс с учителем и учеником или IM-клон на сутки, это другой слой. Здесь речь о том, чтобы один и тот же набор инструментов пережил смену Claude на Gemini без переписывания скрипта.
Pi vs закрытые агенты: вход, исполнение, контекст
Если при выборе первым делом спрашивать «Claude сильнее или GPT?», реальная разница ускользает. Поставьте Pi, официальный CLI и IDE-агент в одну таблицу — по входу, исполнению, контексту и аудитории — и вывод почти сразу переворачивается. Жанр рейтингов — в статье Рейтинг лучших AI Coding Agent 2026; здесь мы не пересобираем места, а отвечаем на вопрос: стоит ли вынимать ключи из продукта.
| Инструмент / форма | Вход | Исполнительные возможности | Контекст | Целевая аудитория |
|---|---|---|---|---|
| Pi Coding Agent | TUI / -p / RPC / SDK | Четыре инструмента по умолчанию + расширения; модель переключается на лету | AGENTS.md, дерево сессий, проектный .pi/ | Кому нужны несколько моделей и агент в виде скрипта репозитория |
| Claude Code / Codex CLI | Официальный терминал; подписка или ключ вендора | Глубокая связка со своей моделью и workflow | Сессии и файлы правил вендора | Кто уже купил одну экосистему и хочет опыт из коробки |
| Cursor / IDE-агент | Боковая панель редактора и встроенный diff | Лучший опыт правки файлов, слабая скриптуемость | Открытый репозиторий + аккаунт редактора | Интерактивная правка кода без пайплайнов |
| Свой Function Calling | Свой HTTP / JSON-цикл | Полный контроль, но инструменты и сессии пишете сами | Своя схема и своё хранилище | Когда продукт и есть агент, а не «агент пишет код» |
Выбор между Claude Code и Codex на удалённом Mac разобран в статье Claude Code против Codex: удалённая среда разработки Mac. Те материалы отвечают, какой официальный CLI взять. Здесь — как ставить harness, когда вы уже решили, что моделей будет несколько и цикл должен жить в TypeScript.
Есть соблазн «оставить Cursor для правок, а Pi поставить рядом на всякий случай». Так можно, если вы честно делите задачи: интерактивный diff — в редакторе, воспроизводимый обзор — в скрипте. Плохо, когда оба инструмента пишут в одни и те же файлы без общих правил. Тогда AGENTS.md у Pi и правила Cursor расходятся, и вы снова спорите с двумя характерами моделей вместо одного контракта репозитория.
Свой Function Calling имеет смысл, когда агент — часть продукта: вы сами рисуете схему инструмента, сами храните сессию, сами решаете, что показывать пользователю. Для «починить тест в этом репозитории» писать цикл с нуля — налог, который Pi как раз снимает. Если команда уже держит внутренний шлюз к моделям, Pi всё равно может остаться coding-слоем: шлюз отдаёт ключ, harness крутит read/bash.
Установка через npm и настройка API-ключа
Глобальный CLI: сначала диалог, потом встраивание
Официально рекомендуют глобальную установку с --ignore-scripts. Для обычной работы Pi не нужны lifecycle-скрипты зависимостей; пропуск скриптов уменьшает сюрпризы цепочки поставок. Версию Node берите по локальному LTS: поле engines в пакете обновляется, не превращайте минор из чужого блога в пункт договора. На облачном Mac имеет смысл сначала зафиксировать Node в образе или .nvmrc, потом ставить глобальный пакет: иначе утром pi есть в интерактивной сессии, а ночью в launchd/PATH его уже нет.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent # или: pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent # или: bun add -g --ignore-scripts @earendil-works/pi-coding-agent # альтернативный установщик: curl -fsSL https://pi.dev/install.sh | sh pi --version
После установки сделайте две вещи: убедитесь, что pi есть в PATH, и что у выбранного провайдера есть хотя бы один ключ или один проход /login. Без учётных данных TUI откроется, но в каталоге моделей не будет ни одного запускаемого пункта. Это частая «поломка», на которую жалуются как на баг агента: на самом деле не настроен слой ключей. Проверка занимает минуту: pi --list-models должен показать хоть одну строку, иначе дальше нет смысла спорить про промпты.
Глобальный CLI — вход для человека. Не ждите, что та же команда автоматически станет версией для CI. В репозитории позже появится отдельная зависимость SDK: человек обновляет глобальный пакет, когда удобно, скрипт живёт на версии из package.json. Если смешать эти два ритма, вы получите «у меня локально работает, в Actions — другой каталог моделей».
Как слоить ключи: переменные окружения, auth.json, разовое перекрытие
Официальный порядок разбора учётных данных: ключ командной строки --api-key → ~/.pi/agent/auth.json → переменные окружения процесса → ключ кастомного провайдера в models.json. В интерактиве /login записывает OAuth или API-ключ в auth.json (права файла 0600). auth.json важнее переменных окружения и подходит для «эта машина долго живёт с этим ключом»; переменные — для CI и разовых опытов. setRuntimeApiKey в SDK перекрывает ключ только в процессе, на диск не пишет, и годится для тестов и мультитенантного хоста.
export ANTHROPIC_API_KEY=sk-ant-... export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... # в auth.json соответствующий ключ — google pi # интерактив: /login — выбор провайдера; /model или Ctrl+L — смена; Ctrl+S — сохранить как стартовый default
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
Поле key умеет интерполяцию $ENV_VAR и чтение через команду вроде !op read 'op://…' (кэш внутри процесса). На удалённой или безголовой машине браузерный callback в духе OpenRouter часто не проходит: официально нужно вставить в приглашение логина итоговый redirect URL или код авторизации — на облачном Mac по SSH это почти норма. Таблицу провайдеров смотрите в providers.md.
Слои ключей легко запутать, если относиться к ним как к «просто env». Практичное правило: ноутбук разработчика — переменные в shell profile или 1Password; общая облачная машина — auth.json с 0600 и без git; CI — Secrets репозитория, которые попадают в процесс только на время job. Runtime-ключ SDK — для одной задачи внутри вашего сервиса, не для «командного конфига». Если три слоя пересечь без схемы, вы не поймёте, почему ночной job внезапно начал бить в личный ключ из домашнего каталога раннера.
auth.json; на машине разработки — переменные окружения или 1Password. Runtime-ключ SDK годится для разовой задачи, не как «общий конфиг команды» в git.
Подключаем Claude, GPT и Gemini
Pi держит для каждого встроенного провайдера каталог моделей, которые умеют вызывать инструменты. Настроенный каталог обновляется сам, принудительно — pi update --models. Аутентификация может быть подпиской (Claude Pro/Max, ChatGPT Plus/Pro Codex, GitHub Copilot) или API-ключом. Переключение — /model, Ctrl+L; часто используемые модели крутит Ctrl+P; список цикла задаёт /scoped-models.
Имеет смысл сразу решить, что для вас «подключить модель». Это не строка в блоге и не скриншот чужого /model. Это: ключ проходит, каталог не пустой, одна и та же инструкция отрабатывает на двух бэкендах, а правила берутся из AGENTS.md, а не из характера модели. Если вторая модель «отвечает иначе», сначала проверьте инструменты и системный слой, а не делайте вывод, что «Gemini тупой».
| Провайдер | Переменная окружения | Ключ в auth.json | Вход CLI | Целевая аудитория |
|---|---|---|---|---|
| Anthropic Claude | ANTHROPIC_API_KEY | anthropic | pi --provider anthropic; /login может идти через Pro/Max | Длинный контекст и правка архитектуры; готовы доплатить за токены |
| OpenAI GPT | OPENAI_API_KEY | openai | pi --model openai/gpt-4o; либо /login через подписку Codex | Уже есть счёт OpenAI и те же ключи в существующих API-скриптах |
| Google Gemini | GEMINI_API_KEY | google | pi --provider google; конкретный ID — через --list-models | Дешёвый обход репозитория или уже открытый проект в консоли Gemini |
pi --list-models claude pi --list-models gpt pi --list-models gemini pi --provider anthropic --thinking high "Перепишите циклы в src/ в тестируемые функции" pi --model openai/gpt-4o -p "В трёх предложениях суммируйте входные модули этого репозитория" pi --provider google -p "Только чтение: перечислите файлы тестов без покрытия" # смена внутри сессии, без переустановки # /model или Ctrl+L # Ctrl+P цикл по scoped-списку
Идентификаторы моделей плывут вместе с обновлением каталога. В официальных примерах мелькали claude-opus-4-5, claude-sonnet-4-5, gpt-4o, gpt-5.1; на практике ориентируйтесь на pi --list-models и getAvailable() в SDK, не вшивайте снимок из блога в прод-скрипт. Кастомные шлюзы (Ollama, vLLM, корпоративный прокси) идут через ~/.pi/agent/models.json, если с той стороны говорят на одном из API: OpenAI, Anthropic или Google. OAuth и закрытый протокол — через расширение, CLI лучше не патчить.
Если вам на самом деле нужно «сами пишем HTTP, сами разбираем JSON», это слой Function Calling, а не слой harness. Сверьте со статьями Function Calling и JSON API и руководство по API GPT-5.6: там вы бьёте в провайдера напрямую; здесь Pi крутит цикл инструментов за вас, а вы только меняете бэкенд.
Короткое правило выбора бэкенда на первую неделю, без религиозных споров. Claude — когда задача длинная и дорогая ошибка архитектуры. GPT — когда ключ уже живёт в ваших скриптах и вы хотите один счёт. Gemini — когда нужно дешево просмотреть много файлов и не жалко отбросить слабый проход. Pi как раз для того, чтобы это правило сменить завтра, не переписывая scripts/pi-review.ts.
Практика в TypeScript-проекте
CLI закрывает задачу «человек командует в терминале»; SDK — «скриптом репозитория тоже можно командовать». SDK лежит в том же npm-пакете, отдельно ставить нечего. Минимальный контур: зависимость в проекте → три ключа только в окружении → ModelRuntime выбирает модель → createAgentSession отправляет одну задачу только на чтение → dispose().
Имеет смысл сразу договориться о границе прав в коде, а не в чате. Ревью и обход репозитория почти никогда не должны получать write/edit по умолчанию. Иначе ночной job «просто посмотреть тесты» однажды перепишет конфиг. Белый список инструментов в createAgentSession — это и есть контракт. Человек в TUI может взять полный набор; скрипт — нет.
npm init -y npm install @earendil-works/pi-coding-agent # в package.json добавьте "type": "module"
import {
createAgentSession,
ModelRuntime,
SessionManager,
} from "@earendil-works/pi-coding-agent";
const runtime = await ModelRuntime.create();
if (process.env.ANTHROPIC_API_KEY) {
await runtime.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY);
}
if (process.env.OPENAI_API_KEY) {
await runtime.setRuntimeApiKey("openai", process.env.OPENAI_API_KEY);
}
if (process.env.GEMINI_API_KEY) {
await runtime.setRuntimeApiKey("google", process.env.GEMINI_API_KEY);
}
const preferred =
runtime.getModel("anthropic", "claude-opus-4-5") ??
runtime.getModel("openai", "gpt-4o") ??
(await runtime.getAvailable())[0];
if (!preferred) {
throw new Error("Нет доступной модели: сначала export одного из трёх ключей или выполните pi --list-models");
}
const { session } = await createAgentSession({
model: preferred,
thinkingLevel: "low",
tools: ["read", "bash"],
sessionManager: SessionManager.inMemory(),
modelRuntime: runtime,
});
try {
session.subscribe((event) => {
if (
event.type === "message_update" &&
event.assistantMessageEvent.type === "text_delta"
) {
process.stdout.write(event.assistantMessageEvent.delta);
}
});
await session.prompt(
"Только чтение: перечислите TypeScript-точки входа в текущем каталоге и укажите место, где с наибольшей вероятностью нет тестов. Файлы не менять."
);
} finally {
session.dispose();
}
В этом фрагменте инструменты специально сужены до read + bash, сессия живёт в памяти и на диск не садится. Скрипт ревью в CI не должен по умолчанию иметь write/edit. Для постоянной сессии возьмите SessionManager.create(process.cwd()); чтобы делить с CLI тот же долгоживущий ключ, не вызывайте setRuntimeApiKey — пусть runtime читает ~/.pi/agent/auth.json. Если нужен свой путь auth, направьте authPath / modelsPath в каталог приложения, чтобы несколько сервисов не дрались за один файл в домашнем каталоге. Семантика событий SDK, steer и followUp — в sdk.md.
AGENTS.md: правила репозитория для всех моделей
При старте Pi склеивает ~/.pi/agent/AGENTS.md, файлы AGENTS.md (или CLAUDE.md) в родительских каталогах и в текущем. Если на уровне есть AGENTS.override.md, загружается только он. Это точка, где «смена модели не меняет правила»: Claude, GPT и Gemini читают одни и те же входы, тестовые команды и красные линии. Системный промпт заменяют через .pi/SYSTEM.md, дописывают через APPEND_SYSTEM.md.
# Правила этого репозитория для Pi - Пакетный менеджер: npm. Не менять самовольно на pnpm. - Проверки: npm test && npm run lint - Красные линии: не коммитить .env, auth.json, *.pem - По умолчанию только чтение; write/edit — только если пользователь явно сказал «можно менять файлы»
Безголовый CI не покажет диалог доверия к проекту. Если сохранённого решения trust нет, неинтерактивный режим следует глобальному defaultProjectTrust: ask (по умолчанию) и never игнорируют проектные ресурсы .pi/, доверяет только always. Разово перекрывают --approve / --no-approve. Когда засовываете Pi в self-hosted runner, сначала пропишите политику доверия в образ машины, потом спорьте про модель. Слои GitHub Actions и облачного Mac-раннера — в статье GitHub Actions macOS самостоятельный Runner и облачный Mac.
Отдельно про логи. Print-режим и подписка на события SDK легко вываливают фрагменты промпта и пути файлов. Ключ в лог лучше не попадёт, если вы не печатаете env сами, но содержимое репозитория — да. Для публичного Actions включите маскирование секретов и не гоняйте агента по каталогам с прод-конфигами «на всякий случай». Минимальный контур ревью должен видеть исходники приложения, а не связку деплоя.
Как выбирать по сценарию
Настоящий вопрос не «ставить ли Pi», а какое у вас первое ограничение: интерактивная правка кода, агент в виде скрипта или опыт официального CLI одной экосистемы из коробки.
| Ваша ситуация | Рекомендация | Причина |
|---|---|---|
| Днём Claude, вечером Gemini, без смены окна | TUI Pi + три ключа + /model | Водораздел — сменный бэкенд, а не ещё одна IDE |
| Ревью / правки нужно оформить скриптом репозитория | SDK в зависимостях проекта; в CI — pi -p или tsx scripts/pi-review.ts | Вход — скрипт, не чат; белый список инструментов живёт в коде |
| Уже купили Claude или ChatGPT и нужен только официальный workflow | Оставайтесь на Claude Code / Codex; не платите налог harness за «мультимодель» | Без второго ключа преимущество Pi не включается |
| Продукт сам требует свой агентный протокол | Function Calling + своя сессия; Pi максимум как внутренний помощник по коду | Pi — coding harness, не рантайм вашего продукта |
| Агент 7×24, ноутбук засыпает вместе с крышкой | Постоянный узел облачного Mac + машинный auth.json + print/SDK | Длинный цикл инструментов плохо переносит сон; среда исполнения ломается раньше имени модели |
Почему Cloud Mac стал слоем исполнения агентов — продуктовый разбор в статье Cloud Mac как стандарт iOS-разработки и слой агентов. Здесь добавляется слой на самом узле: npm, ключи, смена модели и TypeScript-скрипт.
Если сомневаетесь между «оставить официальный CLI» и «переехать на Pi на этой неделе», задайте один вопрос: появится ли второй счёт в ближайший месяц. Нет — оставайтесь. Да, и вы уже хотите один AGENTS.md на всех — ставьте harness, но не выкидывайте привычный CLI в первый день. Неделя параллельной работы дешевле, чем большой взрыв «теперь всё через Pi».
Рекомендуемые комбинации
Инструменты можно складывать. Pi закрывает задачу «coding harness со сменной моделью»; он не даст вам Mac, который не засыпает, и не оплатит три счета провайдеров.
- Личная ежедневная связка: глобальный
pi+ANTHROPIC_API_KEYпо умолчанию + два запасных ключа +AGENTS.mdв репозитории. В интерактиве модель меняетеCtrl+L, правила не меняются. - Связка TypeScript-репозитория: глобальный CLI — человеку, в
devDependenciesещё раз SDK — скриптам. Ревью идёт только на чтение; запись в файлы — отдельная команда с ручным подтверждением. - Связка CI:
pi -pили скрипт SDK + GitHub Actions Secrets + self-hosted macOS runner. Политику доверия зафиксируйте--approve, ключи в лог не печатайте. - Связка мультипровайдерного шлюза: OpenRouter / Cloudflare AI Gateway — один ключ на несколько моделей; переключение по-прежнему через
/modelв Pi. Удобно командам, которые не хотят разбрасывать три заводских ключа по каждой машине. - Минимальная проверка: только CLI, только один ключ в export, команда
pi -p "перечислите ts-файлы в текущем каталоге". Четыре такта (установка → учётные данные → одна задача → воспроизводимость) — и только потом вторая модель и SDK.
Мультиагентный класс или IM-клон — не домашняя территория Pi: там нужны оркестровка и шлюз, см. OpenMAIC и эра мультиагентного сотрудничества. Pi лучше подходит для сюжета «один и тот же цикл чтения-правки-запуска, сменили бэкенд — продолжили».
Типичная рабочая неделя после минимальной проверки выглядит так. Понедельник: TUI и один ключ, правите привычные файлы. Среда: тот же промпт на втором провайдере, сверяете, что красные линии не поехали. Пятница: скрипт только на чтение в Actions на constantly-on узле. Если пятница ломается, причина почти всегда PATH, trust или секрет — не «модель глупая».
Частые заблуждения
- Считать Pi бесплатным клоном Claude Code. Sub-agent и plan mode сюда сознательно не клали. Нужную функцию добавляйте расширением или Package, а не жалуйтесь, что «ядро слишком худое», и не ждите следующей IDE.
- Сунуть три ключа в один dotenv, который уедет в git. На машине разработки — shell profile или 1Password; в CI — Secrets; на общей машине —
auth.jsonс0600. Runtime-ключ SDK на диск не садится и не заменяет машинные учётные данные. - Вшить идентификатор модели из блога в прод. Каталог обновляется. Скрипт должен вызывать
getAvailable()или--list-models, а стабильный префикс провайдера оставить как запасной путь. - В CI выдать агенту
write/editпо умолчанию. Для ревью и обхода — белый список только на чтение; запись в файлы — отдельный человеческий засов. - В безголовом режиме ждать диалог trust. Сначала задайте
defaultProjectTrustили передайте--approve, иначе проектные Skills просто не загрузятся. - Гонять длинный SDK-цикл на ноутбуке, который засыпает. Дерево сессий можно поднять снова, но побочные эффекты bash, оборванного сном, сами не откатятся. Длинные задачи — на постоянно включённый узел.
Отдельно стоит миф «раз ключи слоями, безопасность решена». Слои только уменьшают шанс случайно закоммитить секрет. Они не заменяют аудит счетов, ротацию и принцип наименьших прав. Если раннер один на всю компанию и на нём лежат все три ключа без изоляции job, вы собрали единую точку отказа красивее, чем dotenv, но не безопаснее.
Шаги внедрения
- Запишите то, чем нельзя поступиться: нужен только интерактив, только скрипт или оба входа; обязательны ли три модели на первой неделе; можно ли CI писать на диск.
- Поставьте CLI и сделайте холостой прогон:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent,pi --version, проверьте PATH. - Подключите только один ключ: export или
/login, затемpi -p "перечислите текущий каталог". Критерий приёмки — «воспроизводится», а не «ответ длиннее». - Подключите вторую и третью: добавьте
OPENAI_API_KEY/GEMINI_API_KEY, прогоните один и тот же промпт через/modelили--provider, убедитесь, что правила берутся изAGENTS.md, а не из характера модели. - Впишите SDK в репозиторий: зависимость проекта + один скрипт только на чтение
scripts/pi-review.ts. Белый список инструментов зафиксируйте в коде. - Выберите среду исполнения: локально — чтобы научиться командам; CI и длинные задачи — на постоянно включённый облачный Mac или self-hosted runner, логи без секретов, ключи не в артефактах.
- Потом расширения и наблюдаемость: plan mode / MCP / гейт прав — когда понадобится Package. Сначала измерьте расход, откат при ошибке и ручной перехват, потом наращивайте возможности.
Не перескакивайте через третий шаг. Команды часто ставят сразу три ключа, SDK и runner — и потом не могут сказать, какой слой сломался. Один ключ и одна воспроизводимая команда -p отсекают половину тикетов ещё до разговора про модели.
FAQ
Как связаны Pi Coding Agent и Claude Code?
Claude Code — официальный coding workflow Anthropic: модель и вход склеены. Pi — сторонний минимальный harness: можно взять ключ Anthropic или подписку Claude и одновременно подключить OpenAI и Gemini. Он не заменяет «глубокую официальную интеграцию»; он заменяет сюжет «сменил модель — сменил весь набор инструментов».
Обязательно ли сразу настраивать Claude, GPT и Gemini?
Нет. Одного ключа достаточно, чтобы пройти приёмку установки. Смысл второго ключа: один и тот же AGENTS.md и один белый список инструментов, а бэкенд меняется под задачу. Пока второго счёта нет, не расширяйте эксплуатацию ради слова «мультимодель».
Конфликтуют ли глобальная установка npm и SDK в проекте?
Они не дерутся за одну команду, но версии могут разъехаться. Договорённость: человек работает глобальным CLI, скрипты фиксируют версию в package.json. Если оба читают один и тот же ~/.pi/agent, не перекрывайте долгоживущий машинный ключ runtime-ключом внутри скрипта — если только это не осознанный тест.
Почему переменная Gemini — не GOOGLE_API_KEY?
В официальной таблице ключ Gemini API записан как GEMINI_API_KEY, а ключ в auth.json — google. Vertex идёт через ADC и переменные проекта/региона, это не тот же путь, что ключ Gemini из AI Studio. Ориентир — providers.md, не бытовая догадка про имя переменной.
Можно ли ставить на Windows и на безголовый облачный Mac?
Да. Глобальный npm-пакет кроссплатформенный; на сайте есть ещё install.sh и установщик PowerShell. На безголовой машине используйте pi -p, RPC или SDK, не рассчитывайте на TUI. OAuth в духе OpenRouter по SSH требует вставки callback. На облачном Mac сначала зафиксируйте версию Node, PATH и права auth.json.
Зачем тогда облачный Mac, если npm ставится и локально?
Локальной машины хватает, чтобы выучить команды. Её не хватает на ночное ревью, длинную правку после закрытой крышки и CI в том же окружении, что Xcode и подпись. Pi отвязал модели, но bash и файловые инструменты по-прежнему привязаны к той машине, где крутится процесс.
Итог
Установка Pi Coding Agent на поверхности — это npm, переменные окружения и три идентификатора моделей. По-настоящему нужно посадить слои: harness отдельно от модели, ключи отдельно от репозитория, интерактивный вход отдельно от скриптового. Рабочая схема сентября 2026 года: глобальный CLI — человеку, SDK — репозиторию, AGENTS.md — всем бэкендам, постоянно включённый узел — длинным задачам.
Асимметричный вывод остаётся в силе: водораздел не в том, кто сильнее — Claude, GPT или Gemini, а в том, умеете ли вы считать модель сменным бэкендом. Сначала прогоните один pi -p на одном ключе, потом добавьте вторую модель и TypeScript-скрипт; когда понадобится слой исполнения, перенесите процесс с засыпающего ноутбука на облачный Mac. Усиливать нужно вход, учётные данные и узел — а не следующего IDE-агента.
Pi отвязал модели, но bash по-прежнему привязан к машине
Ревью через SDK, обходы в print-режиме и ночные правки требуют хоста, который не засыпает: стабильная версия Node, воспроизводимый PATH, права auth.json зафиксированы, логи можно аудировать. Hashvps даёт нативный облачный Mac на macOS с выделенным IPv4 — чтобы повесить CLI Pi, TypeScript-скрипты и цепочку Xcode на один постоянно включённый узел: счета моделей оставить провайдерам, исполнение — в дата-центре.
Сначала стабилизируйте слой исполнения агента, потом решайте, какую модель сменить — смотрите тарифы и регионы Hashvps, чтобы npm, ключи и узел облачного Mac выбирались раздельно.