← Вернуться к дневнику

Установка Pi Coding Agent 2026: npm, API-ключи и Claude/GPT/Gemini в TypeScript

AI Agent & DevTools · 2026.09.16 · ≈ 14 мин

Pi Coding Agent: установка npm, API-ключ и подключение Claude/GPT/Gemini в TypeScript

В комментариях 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 — не ещё одно чат-окно, а четыре способа открыть один и тот же агентный цикл. Измерения те же: вход, исполнение, контекст и целевая аудитория. Если запомнить только это, остальное — детали установки.

Четыре входа Pi Coding Agent
Инструмент / форма Вход Исполнительные возможности Контекст Целевая аудитория
Интерактивный TUIpi; /model, /login, /treeЧтение, запись, правка файлов, bash; можно ставить Skills / расширенияДерево сессий в ~/.pi/agent/sessions/; подгружает AGENTS.mdЕжедневная правка репозитория, когда нужно свернуть с курса на середине
Print / JSONpi -p "…"; --mode jsonРазовые задачи; удобно для скриптов и CIПо умолчанию пишет сессию; можно --no-sessionТем, кто вставляет агента в Makefile / GitHub Actions
RPCJSON-протокол через stdin/stdoutНе-Node хост поднимает тот же циклСессии и права держит хостТем, кто встраивает Pi в готовый шлюз или десктопную оболочку
TypeScript SDKcreateAgentSession() / 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 без переписывания скрипта.

Закрытый подписочный агент vs минимальный harness Pi Продукт = модель + вход связаны Одна подписка · одно окно Вход: IDE / официальный CLI Исполнение: смена модели ≈ смена набора Контекст: заперт в аккаунте вендора Ключи не слоями, workflow не в репозитории Продукт = harness + сменный бэкенд Claude GPT Gemini npm CLI · TUI / -p / RPC / SDK env · auth.json · setRuntimeApiKey Один цикл инструментов, модель — только бэкенд
Pi понижает «окно подписки» до источника ключей и поднимает harness, инструменты и контекст репозитория до сути продукта

Pi vs закрытые агенты: вход, исполнение, контекст

Если при выборе первым делом спрашивать «Claude сильнее или GPT?», реальная разница ускользает. Поставьте Pi, официальный CLI и IDE-агент в одну таблицу — по входу, исполнению, контексту и аудитории — и вывод почти сразу переворачивается. Жанр рейтингов — в статье Рейтинг лучших AI Coding Agent 2026; здесь мы не пересобираем места, а отвечаем на вопрос: стоит ли вынимать ключи из продукта.

Как выбирать между Pi и закрытым агентом (для решения)
Инструмент / форма Вход Исполнительные возможности Контекст Целевая аудитория
Pi Coding AgentTUI / -p / RPC / SDKЧетыре инструмента по умолчанию + расширения; модель переключается на летуAGENTS.md, дерево сессий, проектный .pi/Кому нужны несколько моделей и агент в виде скрипта репозитория
Claude Code / Codex CLIОфициальный терминал; подписка или ключ вендораГлубокая связка со своей моделью и workflowСессии и файлы правил вендораКто уже купил одну экосистему и хочет опыт из коробки
Cursor / IDE-агентБоковая панель редактора и встроенный diffЛучший опыт правки файлов, слабая скриптуемостьОткрытый репозиторий + аккаунт редактораИнтерактивная правка кода без пайплайнов
Свой Function CallingСвой HTTP / JSON-циклПолный контроль, но инструменты и сессии пишете самиСвоя схема и своё хранилищеКогда продукт и есть агент, а не «агент пишет код»
Меняется вход — меняется и структура счёта
Закрытый агент тарифицируется «за место в тарифе»; Pi — «за каждый вызов по счёту провайдера». Три ключа могут жить рядом, но у каждого нужны лимит и аудит. Личный ключ подписки ChatGPT в CI не коммитьте.

Выбор между 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 его уже нет.

Глобальная установка Pi CLI
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 перекрывает ключ только в процессе, на диск не пишет, и годится для тестов и мультитенантного хоста.

Три API-ключа (сначала export, потом запуск pi)
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
Минимальный пример ~/.pi/agent/auth.json (права 0600)
{
  "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 внезапно начал бить в личный ключ из домашнего каталога раннера.

Не кладите личный ключ подписки в репозиторий
В CI — Secrets репозитория или машинный 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 тупой».

Сводка по трём моделям (официальные ключи на 2026-09)
Провайдер Переменная окружения Ключ в auth.json Вход CLI Целевая аудитория
Anthropic ClaudeANTHROPIC_API_KEYanthropicpi --provider anthropic; /login может идти через Pro/MaxДлинный контекст и правка архитектуры; готовы доплатить за токены
OpenAI GPTOPENAI_API_KEYopenaipi --model openai/gpt-4o; либо /login через подписку CodexУже есть счёт OpenAI и те же ключи в существующих API-скриптах
Google GeminiGEMINI_API_KEYgooglepi --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 может взять полный набор; скрипт — нет.

Установка SDK в репозиторий (отдельно от глобального CLI)
npm init -y
npm install @earendil-works/pi-coding-agent
# в package.json добавьте "type": "module"
scripts/pi-review.ts: модель из окружения, одно ревью только на чтение
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.

Пример AGENTS.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, но не безопаснее.

Шаги внедрения

  1. Запишите то, чем нельзя поступиться: нужен только интерактив, только скрипт или оба входа; обязательны ли три модели на первой неделе; можно ли CI писать на диск.
  2. Поставьте CLI и сделайте холостой прогон: npm install -g --ignore-scripts @earendil-works/pi-coding-agent, pi --version, проверьте PATH.
  3. Подключите только один ключ: export или /login, затем pi -p "перечислите текущий каталог". Критерий приёмки — «воспроизводится», а не «ответ длиннее».
  4. Подключите вторую и третью: добавьте OPENAI_API_KEY / GEMINI_API_KEY, прогоните один и тот же промпт через /model или --provider, убедитесь, что правила берутся из AGENTS.md, а не из характера модели.
  5. Впишите SDK в репозиторий: зависимость проекта + один скрипт только на чтение scripts/pi-review.ts. Белый список инструментов зафиксируйте в коде.
  6. Выберите среду исполнения: локально — чтобы научиться командам; CI и длинные задачи — на постоянно включённый облачный Mac или self-hosted runner, логи без секретов, ключи не в артефактах.
  7. Потом расширения и наблюдаемость: 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.jsongoogle. 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 выбирались раздельно.

Hashvps · Mac Cloud

Мультимодельному агенту нужна стабильная облачная Mac

Нативный macOS, выделенный IPv4. CLI Pi и TypeScript-скрипты на постоянно включённом узле.

На главную
Акция