Открытые агенты 101

Этот курс — практическое руководство по двум открытым AI-агентам для кода: Pi и OpenCode. Оба агента бесплатные, с открытым кодом (лицензия MIT) и работают с любой моделью: Claude, GPT, Gemini, DeepSeek, Qwen или локальной моделью на вашем компьютере.

Курс сделан для инженеров данных, BI-разработчиков и аналитиков. Мы установим оба агента, подключим модели, настроим безопасность и решим реальные задачи с dbt, SQL и Airflow.

Официальные сайты: pi.dev и opencode.ai. Код: earendil-works/pi и anomalyco/opencode.

Данные актуальны на ноябрь 2026 года: Pi 1.5 и OpenCode 2.2. Оба проекта обновляются каждую неделю. Если команда из курса не работает, проверьте документацию.

Для кого этот курс

Вы хотите агента, который не привязан к одной компании и одной модели.
Вам нужны локальные модели: данные не должны уходить в облако.
Вам нужен дешёвый агент: платите только за токены или используете бесплатные модели.
Вы уже знаете Git и умеете работать в терминале.

Если вы проходили курсы Claude Code 101 или Codex 101, многое будет знакомо. В Модуле 12 есть таблица соответствия.

Что нужно для старта

Компьютер с macOS, Linux или Windows
Доступ к модели: API-ключ любого провайдера, ключ OpenRouter или локальная модель через Ollama
Git-репозиторий для работы. Лучше начать с учебного проекта, а не с рабочего
Для Pi через npm: Node.js 22.19 или новее

Доступ из России

Это главный плюс открытых агентов. Сам агент работает где угодно. Вопрос только в доступе к модели:

OpenRouter — один ключ для сотен моделей. Есть бесплатные модели.
Китайские модели — DeepSeek, Qwen, Kimi, GLM через их API или OpenRouter.
Локальные модели — Ollama или LM Studio. Интернет не нужен, данные не уходят с компьютера.

Подробнее про модели — в Модуле 2.

Содержание

Модуль	Тема
1	Что такое открытые агенты
2	Модели и провайдеры
3	Pi: установка и первый запуск
4	Pi: настройка и расширения
5	OpenCode: установка и первый запуск
6	OpenCode: агенты, разрешения и настройка
7	Безопасность
8	MCP, Skills и команды
9	Практика: задачи инженера данных
10	Скрипты и CI
11	Лучшие практики и частые ошибки
12	Сравнение: Pi, OpenCode, Claude Code и Codex

Модуль 1: Что такое открытые агенты

AI-агент для кода читает ваш проект, пишет и меняет файлы, запускает команды и тесты. Вы ставите задачу обычным языком, агент выполняет её по шагам.

Claude Code и Codex — агенты от компаний, которые делают модели. Они лучше всего работают со «своей» моделью. Открытые агенты не делают модели. Они подключаются к любой.

Зачем открытый агент

Причина	Что это значит
Любая модель	Сегодня Claude, завтра DeepSeek, для секретного кода — локальная Qwen
Цена	Сам агент бесплатный. Платите только провайдеру модели
Приватность	С локальной моделью код и данные не покидают компьютер
Контроль	Код открыт. Можно прочитать, что агент отправляет в модель, и изменить поведение
Нет привязки	Если провайдер поднял цены или ушёл из страны, меняете одну строку в настройках

Минусы

Качество зависит от модели. Слабая модель — слабый агент.
Меньше готовых функций, чем у Claude Code и Codex: нет облачных задач, меньше интеграций.
Безопасность — ваша ответственность. Особенно у Pi (см. Модуль 7).

Pi и OpenCode: два разных подхода

Pi — минимальный агент. Его создал Марио Цехнер (Mario Zechner). С апреля 2026 года проект развивает компания Earendil Армина Ронахера (Armin Ronacher, автор Flask). Pi 1.0 вышел в октябре 2026 года.

Идея Pi: короткий системный промпт, 4 инструмента, и всё остальное вы добавляете сами через расширения. Слоган: «Adapt Pi to your workflows, not the other way around» — Pi подстраивается под вас, а не наоборот.

OpenCode — полный агент «из коробки». Его делает команда Anomaly (раньше SST). Это один из самых популярных открытых агентов: больше 200 тысяч звёзд на GitHub. Есть терминал (TUI), десктоп-приложение, веб-интерфейс и расширение для IDE.

	Pi	OpenCode
Философия	Минимум, собери сам	Всё готово из коробки
Инструменты по умолчанию	4: `read`, `bash`, `edit`, `write`	Около 12: файлы, поиск, shell, веб, субагенты
Разрешения	Нет запросов. Защита — контейнер	Гибкие правила allow / ask / deny
Режим планирования	Нет (можно добавить расширением)	Есть: агент `plan`
Субагенты	Нет (можно добавить расширением)	Есть: `general`, `explore` и свои
MCP	Есть (с версии 1.0)	Есть
Расширения	TypeScript, очень мощные	Плагины на TypeScript
Интерфейсы	Терминал, SDK, RPC	Терминал, десктоп, веб, IDE, SDK
Для кого	Опытные инженеры, которые любят настраивать	Все, кто хочет начать быстро

Курс по модулям

Модули 1–2 — общие для обоих агентов.
Модули 3–4 — только Pi.
Модули 5–6 — только OpenCode.
Модули 7–12 — оба агента, примеры для каждого.

Модуль 2: Модели и провайдеры

Агент — это «руки». Модель — это «голова». От модели зависит 80% результата.

Способы подключить модель

Способ	Плюсы	Минусы
API-ключ провайдера (Anthropic, OpenAI, Google)	Лучшие модели, стабильно	Оплата за токены, нужна карта
OpenRouter	Один ключ для сотен моделей, есть бесплатные	Небольшая наценка, бесплатные модели медленные
Подписка (ChatGPT, GitHub Copilot)	Фиксированная цена	Не все провайдеры разрешают, есть лимиты
OpenCode Go	Подписка на проверенные модели для кода	Только OpenCode
Локальная модель (Ollama, LM Studio)	Бесплатно, приватно, без интернета	Нужен мощный компьютер, модели слабее

Важно: подписка Claude Pro/Max

ChatGPT Plus/Pro и GitHub Copilot официально работают в OpenCode. В Pi подписки подключаются через /login. Список провайдеров с входом по подписке смотрите в /login — он меняется.

Какую модель выбрать

Задача	Модель
Сложная задача: миграция, архитектура, большой рефакторинг	Claude Opus 5.5, GPT-6.1 Sol
Обычная работа: dbt-модели, SQL, тесты	Claude Sonnet 5.5, GPT-6 Astra, Gemini
Простые и массовые задачи	Claude Haiku 5.5, DeepSeek, Qwen
Секретный код, нет интернета	Локальная Qwen Coder или GLM через Ollama
Бесплатно	Бесплатные модели OpenRouter

Советы:

Начните с сильной модели. Когда задача понятна, переходите на дешёвую.
Локальные модели меньше 30B параметров плохо справляются с агентной работой. Они путают инструменты и теряют контекст. Для них давайте маленькие и чёткие задачи.
Проверьте, что у модели большое окно контекста (от 64K). Агент тратит много токенов на чтение файлов.

OpenRouter

Зарегистрируйтесь на openrouter.ai и создайте ключ.
Сохраните ключ в переменной окружения:

export OPENROUTER_API_KEY="sk-or-..."

В Pi: /login openrouter или просто переменная окружения. В OpenCode: /connect → OpenRouter.

Бесплатные модели имеют суффикс :free. Есть автовыбор бесплатной модели: openrouter/free.

Локальные модели: Ollama

Установите Ollama и скачайте модель:

ollama pull qwen3-coder:30b

OpenCode находит Ollama сам по адресу http://127.0.0.1:11434. Выберите модель в /models.
Pi — добавьте модель в ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "qwen3-coder:30b" }
      ]
    }
  }
}

Ключ "ollama" — заглушка, Ollama его не проверяет. Для LM Studio адрес http://localhost:1234/v1. Для llama.cpp в Pi есть встроенная поддержка: команда /llama.

Модуль 3: Pi: установка и первый запуск

Установка

macOS и Linux:

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

Windows (PowerShell):

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

Через npm (нужен Node.js 22.19+):

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

Проверка и обновление:

pi --version
pi update

Первый запуск

cd ~/projects/my-dbt-project
pi

Введите /login и выберите провайдера: OAuth (подписка) или API-ключ.
Введите /model (или Ctrl+L) и выберите модель. Ctrl+S в списке сохраняет её по умолчанию.
Попросите агента рассказать о проекте:

Изучи этот проект. Расскажи: какие источники данных, какие слои моделей, как запускать тесты. Ничего не меняй.

Ключи хранятся в ~/.pi/agent/auth.json. Не добавляйте этот файл в Git. Ключи можно задать и через переменные окружения: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY.

Инструменты

По умолчанию у Pi 4 инструмента: read, bash, edit, write. Этого достаточно: поиск по файлам агент делает через bash (grep, find).

Есть ещё встроенные инструменты, они выключены: grep, find, ls, codemode, tool_search. Набор инструментов задаётся флагом --tools:

pi --tools read,grep,find,ls      # только чтение — для изучения проекта
pi --tools +grep,-write           # добавить grep, убрать write
pi --no-tools                     # просто чат

Как работать в сессии

Действие	Как
Сменить модель	`/model` или `Ctrl+L`
Переключать избранные модели	`Ctrl+P` (список задаёт `/scoped-models`)
Уровень размышлений	`/thinking` или `Shift+Tab`
Поправить агента во время работы	Напишите сообщение и нажмите `Enter`
Поставить следующую задачу в очередь	`Alt+Enter`
Остановить агента	`Esc`
Сослаться на файл	`@` и имя файла
Выполнить команду и отдать вывод агенту	`!dbt ls`
Выполнить команду без отправки агенту	`!!git status`
Показать полный вывод инструмента	`Ctrl+O`
Открыть внешний редактор для длинного промпта	`Ctrl+G`
Все горячие клавиши	`/hotkeys`

Сессии

Pi сохраняет каждую сессию автоматически в ~/.pi/agent/sessions/. Сессия — это дерево: можно вернуться к любому сообщению и пойти другим путём.

Команда	Что делает
`pi -c`	Продолжить последнюю сессию
`pi -r` или `/resume`	Выбрать сессию из списка
`/new`	Новая сессия
`/tree`	Дерево сессии: перейти к любому сообщению
`/fork`	Новая ветка от текущего места
`/compact`	Сжать историю, чтобы освободить контекст
`/export`	Сохранить сессию в файл
`pi --no-session`	Не сохранять сессию

Когда контекст почти заполнен, Pi сжимает историю автоматически. Вручную можно добавить инструкцию: /compact сохрани список изменённых моделей и открытые вопросы.

Модуль 4: Pi: настройка и расширения

Где хранятся настройки

Файл	Что в нём
`~/.pi/agent/settings.json`	Общие настройки
`~/.pi/agent/models.json`	Свои модели и провайдеры
`~/.pi/agent/auth.json`	Ключи и токены. Не коммитить
`~/.pi/agent/mcp.json`	MCP-серверы
`~/.pi/agent/AGENTS.md`	Ваши личные правила для всех проектов
`~/.pi/agent/extensions/`, `skills/`, `prompts/`, `themes/`	Расширения, навыки, шаблоны, темы
`.pi/settings.json`, `.pi/mcp.json`	Настройки проекта
`.pi/extensions/`, `.pi/skills/`, `.pi/prompts/`	Расширения проекта

Папку ~/.pi/agent можно перенести через переменную PI_CODING_AGENT_DIR.

AGENTS.md

Pi читает AGENTS.md (или CLAUDE.md) из папки агента, из текущей папки и из всех родительских папок. Если в проекте уже есть AGENTS.md для Codex или CLAUDE.md для Claude Code, Pi использует его.

Пример для dbt-проекта:

## Проект
dbt-проект на Snowflake. Слои: staging → intermediate → marts.

## Команды
- Сборка одной модели: `dbt build --select <model>`
- Линтер: `sqlfluff lint models/`

## Правила
- Каждая модель staging: одна таблица источника, только переименование и приведение типов.
- У каждой модели должен быть primary key и тесты `unique` и `not_null` на него.
- Пиши SQL в нижнем регистре, используй CTE, не используй `select *` в marts.

## Запрещено
- Запускать что-либо с `--target prod`.
- Менять файлы в `models/marts/finance/` без явной просьбы.

Свой системный промпт

Файл	Что делает
`SYSTEM.md`	Полностью заменяет системный промпт Pi
`APPEND_SYSTEM.md`	Добавляет текст в конец системного промпта

Файлы кладутся в ~/.pi/agent/ или в .pi/ проекта. Начните с APPEND_SYSTEM.md. Полная замена нужна редко.

Доверие к проекту

Когда Pi видит в папке .pi/settings.json, .pi/mcp.json, .pi/extensions/ и похожие файлы, он спрашивает: доверяете ли вы этому проекту? Без доверия эти файлы не загружаются.

Зачем: расширение — это код на TypeScript. Чужой репозиторий может содержать вредное расширение.

/trust — посмотреть или изменить решение.
pi -a — доверять проекту в этот раз. pi -na — не загружать файлы проекта.
Решения хранятся в ~/.pi/agent/trust.json.

Шаблоны промптов

Файл ~/.pi/agent/prompts/dbt-review.md становится командой /dbt-review:

---
description: Ревью dbt-модели
argument-hint: "<путь к модели>"
---
Проверь dbt-модель ${1}.
1. Есть ли primary key и тесты unique и not_null на него?
2. Правильный ли grain? Нет ли дублей после join?
3. Описаны ли модель и колонки в YAML?
4. Нет ли select * и жёстко прописанных имён схем?
Ничего не меняй. Выведи список проблем по важности.

После создания шаблона выполните /reload.

Расширения

Расширение — файл на TypeScript. Оно может:

добавить свой инструмент
добавить команду /...
заблокировать или изменить вызов инструмента
добавить провайдера моделей или MCP-сервер
нарисовать свой интерфейс в терминале

Пример: расширение, которое защищает прод. Сохраните как ~/.pi/agent/extensions/protect-prod.ts:

import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (!isToolCallEventType("bash", event)) return;
    const cmd = event.input.command;

    // Никогда не запускать dbt на проде
    if (/--target\s+prod/.test(cmd)) {
      return { block: true, reason: "Запуск на prod запрещён" };
    }

    // Спрашивать перед опасными командами
    if (/rm -rf|git push|drop table/i.test(cmd)) {
      const ok = await ctx.ui.confirm("Опасная команда", cmd);
      if (!ok) return { block: true, reason: "Отклонено пользователем" };
    }
  });
}

Проверить расширение без установки: pi -e ./protect-prod.ts. После изменения — /reload.

В репозитории Pi есть готовые примеры расширений: режим планирования (plan-mode), субагенты (subagent), список задач (todo.ts), подтверждение команд (permission-gate.ts). Смотрите папку examples/extensions.

Пакеты Pi

Пакет объединяет расширения, навыки, шаблоны и темы. Его можно поставить из npm или Git:

pi install npm:@scope/package@1.0.0
pi install git:github.com/user/repo@v1
pi install -l npm:@scope/package    # только для текущего проекта
pi list
pi remove npm:@scope/package

Чего в Pi нет специально

Нет	Что использовать
Запросов на разрешения	Контейнер, расширение `permission-gate`
Режима планирования	Попросите написать план в `PLAN.md`, или расширение `plan-mode`
Субагентов	Запуск `pi -p` из bash, или расширение `subagent`
Встроенного списка задач	Файл `TODO.md`, или расширение `todo.ts`
Фоновых процессов	`tmux` для долгих команд

Модуль 5: OpenCode: установка и первый запуск

Установка

# Скрипт (macOS, Linux)
curl -fsSL https://opencode.ai/v2/install | bash

# npm
npm install -g @opencode/cli

# Homebrew
brew install anomalyco/tap/opencode-v2

Есть десктоп-приложение (бета) для macOS, Windows и Linux: brew install --cask opencode-desktop или загрузка с opencode.ai.

Если у вас стоит OpenCode 1, сначала обновите его до последней версии 1.x, потом выполните opencode upgrade --major. Обе версии используют команду opencode, поэтому не ставьте их одновременно.

Первый запуск

cd ~/projects/my-dbt-project
opencode

/connect — подключите провайдера: API-ключ, OpenRouter, ChatGPT, GitHub Copilot или OpenCode Go.
/models — выберите модель.
/init — OpenCode изучит проект и создаст AGENTS.md. Проверьте файл и закоммитьте его.

Как устроен OpenCode

OpenCode работает как сервис в фоне. Терминал, десктоп и веб подключаются к нему. Поэтому одну сессию можно начать в терминале и продолжить в приложении.

opencode                 # терминал
opencode mini            # минимальный терминал
opencode --standalone    # без общего фонового сервиса

Агенты Build и Plan

Главное отличие от Pi — встроенные агенты:

Агент	Что может	Когда использовать
`build`	Всё: читать, менять файлы, запускать команды	Основная работа
`plan`	Только читать и планировать. Файлы менять нельзя	Изучить задачу и составить план

Переключение — клавиша Tab. Хорошая привычка: начинайте сложную задачу в plan, обсудите план, потом переключайтесь на build.

Ещё есть субагенты:

explore — быстро ищет по коду, только чтение
general — выполняет подзадачу в отдельном контексте

Вызвать субагента: @explore найди все модели, которые используют stg_orders.

Команды

Команда	Что делает
`/connect`	Подключить провайдера
`/models`	Выбрать модель
`/init`	Создать `AGENTS.md`
`/new`	Новая сессия
`/sessions`	Список сессий
`/compact`	Сжать историю
`/undo`, `/redo`	Отменить или вернуть изменения (нужен Git)
`/goal <цель>`	Работать, пока цель не достигнута
`/export`	Сохранить сессию
`/exit`	Выход

Горячие клавиши начинаются с «лидера» Ctrl+X: например, Ctrl+X затем M — выбор модели. Список зависит от версии, смотрите документацию.

Модуль 6: OpenCode: агенты, разрешения и настройка

Файл opencode.json

Настройки лежат в opencode.json (или opencode.jsonc — с комментариями).

Где	Для чего
`~/.config/opencode/opencode.json`	Ваши личные настройки
`opencode.json` или `.opencode/opencode.json` в проекте	Настройки проекта, коммитятся в Git
`/etc/opencode`, `/Library/Application Support/opencode`	Настройки компании (важнее всех)

Настройки сливаются: от общих к частным, ближайший к проекту файл важнее. Настройки компании важнее всего.

Минимальный пример:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "instructions": ["docs/conventions.md"]
}

Поле $schema включает подсказки в редакторе.

AGENTS.md

OpenCode читает ~/.config/opencode/AGENTS.md, затем все AGENTS.md от проекта вверх. Дополнительные файлы с правилами — через поле instructions (пути, маски или URL).

Разрешения

Разрешения — список правил. Каждое правило: действие (action), ресурс (resource) и решение (effect):

allow — разрешить без вопроса
ask — спросить вас
deny — запретить

Срабатывает последнее подходящее правило. Поэтому общие правила пишите сверху, частные — снизу.

По умолчанию OpenCode разрешает почти всё. Он спрашивает только перед чтением .env. Для работы с данными это слишком свободно.

Безопасная настройка для инженера данных:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    // Любая команда — спросить
    { "action": "shell", "resource": "*", "effect": "ask" },

    // Безопасные команды — без вопроса
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git log *", "effect": "allow" },
    { "action": "shell", "resource": "dbt compile *", "effect": "allow" },
    { "action": "shell", "resource": "dbt ls *", "effect": "allow" },
    { "action": "shell", "resource": "sqlfluff lint *", "effect": "allow" },

    // Опасные — запретить
    { "action": "shell", "resource": "rm -rf *", "effect": "deny" },
    { "action": "shell", "resource": "dbt * --target prod*", "effect": "deny" },

    // Секреты — не читать
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" },
    { "action": "read", "resource": "~/.dbt/profiles.yml", "effect": "deny" },

    // Файлы вне проекта — спросить
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ],
  "policies": [
    { "permissions": [ { "action": "shell", "resource": "rm *", "effect": "deny" } ] }
  ]
}

permissions — обычные правила. Когда агент спрашивает, вы можете ответить «разрешить всегда».
policies — жёсткие запреты. Их нельзя отменить ответом «разрешить всегда».

Правила можно задать и для отдельного агента (см. ниже).

Свои агенты

Агент — Markdown-файл в .opencode/agents/ (проект) или ~/.config/opencode/agents/ (личные). Имя файла — имя агента.

Пример: ревьюер SQL, который ничего не меняет. Файл .opencode/agents/sql-reviewer.md:

---
description: Проверяет SQL и dbt-модели. Ничего не меняет.
mode: subagent
model: anthropic/claude-sonnet-5-5
permissions:
  - { action: edit,  resource: "*", effect: deny }
  - { action: shell, resource: "*", effect: deny }
---
Ты ревьюер SQL для dbt-проекта на Snowflake.
Проверь изменённые модели:
- grain и дубли после join
- primary key и тесты на него
- фильтры по времени в incremental-моделях
- NULL в ключах join
Выведи проблемы по важности: критично, важно, мелочь.

Вызов: @sql-reviewer проверь models/marts/fct_orders.sql.

Поля агента:

Поле	Значение
`description`	Когда использовать агента. По нему OpenCode выбирает субагента
`mode`	`primary` (переключается по `Tab`), `subagent` (вызывается через `@`) или `all`
`model`	Модель, например `anthropic/claude-haiku-5-5`
`permissions`	Свои правила разрешений
`steps`	Максимум шагов
текст после `---`	Инструкция для агента

Свои команды

Файл .opencode/commands/dbt-test.md становится командой /dbt-test:

---
description: Добавить тесты к dbt-модели
agent: build
---
Добавь тесты к модели $ARGUMENTS:
- unique и not_null на primary key
- relationships для внешних ключей
- accepted_values для колонок-статусов
Потом запусти `dbt test --select $ARGUMENTS` и исправь ошибки.

$ARGUMENTS — всё, что вы написали после команды. $1, $2 — отдельные аргументы.

Модуль 7: Безопасность

AI-агент выполняет команды с правами вашего пользователя. У него есть доступ ко всему, к чему есть доступ у вас: SSH-ключи, ~/.dbt/profiles.yml, токены облака, продовые базы.

Чем отличаются Pi и OpenCode

	Pi	OpenCode
Спрашивает перед командой	Нет	Да, если настроено `ask`
Песочница	Нет	Нет
Чтение `.env`	Без вопросов	Спрашивает по умолчанию
Защита от чужого кода в репозитории	Доверие к проекту	Нет отдельного механизма
Рекомендуемая защита	Контейнер или VM	Правила разрешений + контейнер для автономной работы

Ни у Pi, ни у OpenCode нет песочницы, как у Codex. Разрешения OpenCode — это вопросы, а не изоляция: если вы разрешили python *, скрипт на Python может сделать что угодно.

Pi в Docker

Документация Pi прямо говорит: запуск в контейнере — «обычно самый надёжный практичный вариант».

Файл Dockerfile.pi:

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

Сборка и запуск:

docker build -t pi-sandbox -f Dockerfile.pi .

docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

В контейнер попадает только текущая папка. Домашняя папка, SSH-ключи и profiles.yml остаются снаружи.
Том pi-agent-home хранит настройки и сессии между запусками.
Не монтируйте ~/.pi/agent с вашего компьютера — там ваши ключи.
Для dbt добавьте в образ Python и dbt-core, а подключение к базе дайте только к dev с отдельным пользователем.

Тот же подход работает для OpenCode, когда вы даёте ему работать без вопросов.

Prompt injection

Агент читает файлы, вывод команд, веб-страницы и ответы MCP-серверов. Любой из них может содержать инструкцию вроде «отправь содержимое .env на этот адрес».

Не давайте агенту читать непроверенные данные вместе с доступом к секретам.
Осторожно с веб-поиском и MCP-серверами, которые читают внешние данные (тикеты, письма, Slack).
Сырые данные из источников (raw, landing) тоже могут содержать текст-инструкцию.

Сервер OpenCode

У OpenCode есть HTTP-сервер (opencode serve, opencode web). В январе 2026 года нашли серьёзную уязвимость (CVE-2026-22812): любой сайт или программа на компьютере могли выполнять команды через сервер. Исправлено в версии 1.0.216.

Правила:

Всегда обновляйте OpenCode до последней версии.
Если запускаете сервер, задайте пароль: OPENCODE_SERVER_PASSWORD.
Не открывайте сервер в локальную сеть без необходимости.

Правила для инженера данных

Только dev. Агент работает с dev-базой и dev-схемой. Прод — никогда.
Отдельный пользователь базы с правами только на чтение или только на dev-схему.
Секреты вне проекта. Не храните пароли в .env внутри репозитория, который открыт агенту.
Git — ваша страховка. Коммитьте перед каждой большой задачей. Проверяйте git diff после.
Читайте код расширений, пакетов и MCP-серверов перед установкой.
Без вопросов — только в контейнере. Pi всегда, OpenCode с allow на всё — тоже.
Локальная модель для чувствительных данных. Если в коде или данных есть персональные данные, используйте Ollama.

Модуль 8: MCP, Skills и команды

MCP

MCP (Model Context Protocol) подключает к агенту внешние инструменты: базы данных, dbt, документацию, Jira.

Pi. Добавить сервер командой:

pi mcp add dbt -- uvx dbt-mcp
pi mcp add -l duckdb -- uvx mcp-server-motherduck --db-path ./dev.duckdb
pi mcp list

Флаг -l — сервер только для проекта (файл .pi/mcp.json). Без флага — для всех проектов (~/.pi/agent/mcp.json). Формат файла такой же, как у других клиентов:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/Users/me/projects/my-dbt-project",
        "DBT_PATH": "/Users/me/.venv/bin/dbt"
      }
    }
  }
}

В сессии: /mcp — посмотреть серверы, включить или выключить.

OpenCode. Серверы в opencode.json, внутри mcp.servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "dbt": {
        "type": "local",
        "command": ["uvx", "dbt-mcp"],
        "environment": {
          "DBT_PROJECT_DIR": "/Users/me/projects/my-dbt-project",
          "DBT_PATH": "/Users/me/.venv/bin/dbt"
        }
      },
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp"
      }
    }
  }
}

Секреты передавайте через переменные: "{env:MY_TOKEN}". Выключить сервер: "disabled": true.

Полезные MCP-серверы для инженера данных:

Сервер	Что даёт
dbt MCP	Список моделей, lineage, запуск dbt, Semantic Layer
MotherDuck / DuckDB	SQL к локальным файлам и DuckDB
MCP Toolbox for Databases	PostgreSQL, BigQuery, Snowflake и другие
ClickHouse MCP	Запросы к ClickHouse
Context7	Актуальная документация библиотек

Skills

Skill (навык) — папка с файлом SKILL.md: инструкция и, если нужно, скрипты. Агент загружает навык, когда задача подходит под его описание. Формат одинаковый у Pi, OpenCode, Claude Code и Codex.

Где искать навыки:

Агент	Папки
Pi	`~/.pi/agent/skills/`, `.pi/skills/`, `~/.agents/skills/`, `.agents/skills/`
OpenCode	`~/.config/opencode/skills/`, `.opencode/skills/`, `.agents/skills/`, `.claude/skills/`

Общая папка .agents/skills/ работает в обоих агентах и в Codex. Кладите навыки туда.

Пример: .agents/skills/dbt-new-model/SKILL.md:

---
name: dbt-new-model
description: Создать новую dbt-модель по стандартам проекта. Использовать, когда просят добавить staging, intermediate или mart модель.
---

# Новая dbt-модель

1. Найди похожую модель в том же слое и возьми её как образец.
2. Назови файл по правилу: stg_<источник>__<таблица>, int_<сущность>_<действие>, fct_ или dim_.
3. Создай YAML: описание модели, описание каждой колонки, тесты на primary key.
4. Запусти `dbt build --select <модель>`.
5. Если тест упал — исправь и запусти снова. Не удаляй тесты.

Готовые навыки для dbt: dbt Agent Skills.

В Pi навык можно вызвать явно: /skill:dbt-new-model.

Команды и шаблоны

	Pi	OpenCode
Где	`~/.pi/agent/prompts/.md`, `.pi/prompts/.md`	`~/.config/opencode/commands/.md`, `.opencode/commands/.md`
Аргументы	`${1}`, `${1:-по умолчанию}`	`$ARGUMENTS`, `$1`
Вызов	`/имя-файла`	`/имя-файла`

Примеры есть в Модуле 4 и Модуле 6.

Плагины OpenCode

Плагин OpenCode — код на TypeScript в .opencode/plugins/. Он может подписаться на события, менять вызовы инструментов, добавлять свои инструменты. Установка готового плагина: opencode plugin add <имя>.

Плагины от OpenCode 1 во второй версии не работают. Смотрите документацию по плагинам.

Модуль 9: Практика: задачи инженера данных

Промпты ниже работают в обоих агентах. Хорошая задача содержит: цель, контекст, ограничения и критерий готовности.

1. Изучить новый проект

Pi в режиме только чтения:

pi --tools read,grep,find,ls

OpenCode: переключитесь на агента plan (Tab).

Изучи этот dbt-проект. Опиши:
- источники данных и как они загружаются
- слои моделей и их назначение
- 5 самых важных mart-моделей и откуда они берут данные
- как запускать сборку и тесты
Ничего не меняй. Результат запиши в docs/overview.md.

2. Новая staging-модель

Создай staging-модель для таблицы raw.shopify.orders.
Образец: models/staging/shopify/stg_shopify__customers.sql.
- Переименуй колонки в snake_case, приведи типы.
- Добавь YAML с описанием колонок и тестами unique и not_null на order_id.
- Запусти dbt build --select stg_shopify__orders.
Готово, когда сборка и тесты проходят.

3. Ревью SQL перед PR

OpenCode — через своего субагента:

@sql-reviewer проверь все изменённые модели в этой ветке относительно main

Pi — через шаблон: /dbt-review models/marts/fct_orders.sql.

4. Ошибка в пайплайне

Задача Airflow load_orders упала. Лог: logs/load_orders_2026-11-02.log.
Найди причину. Предложи исправление, но не меняй код, пока я не подтвержу.

5. Проверка данных через DuckDB

В папке data/ лежат выгрузки orders_*.parquet.
Через DuckDB проверь:
- есть ли дубли по order_id
- есть ли NULL в customer_id и amount
- нет ли дат из будущего
Выведи результат таблицей. Файлы не меняй.

6. Миграция SQL-диалекта

Переведи модели из models/legacy/ с Redshift на Snowflake.
- Сначала составь список функций, которые нужно заменить. Покажи его мне.
- После моего ответа меняй по одной модели и запускай dbt compile.
- Не меняй логику и названия колонок.

Для таких задач в OpenCode начните в plan, а в Pi попросите сначала записать план в PLAN.md.

7. Документация

Для всех моделей в models/marts/ без описания в YAML добавь описания модели и колонок.
Бери смысл из SQL и из моделей-источников. Если смысл колонки непонятен, напиши TODO, а не выдумывай.

8. Работа с секретными данными

Задача: разобрать схему с персональными данными. Используйте локальную модель:

OpenCode: /models → модель Ollama.
Pi: pi --provider ollama --model qwen3-coder:30b (модель из вашего models.json).

Посмотри схему таблиц в models/staging/crm/. Найди колонки с персональными данными (имя, email, телефон, адрес).
Предложи, какие колонки хэшировать или маскировать в marts.

9. Две модели — второе мнение

Сильная сторона открытых агентов — легко сменить модель. После того как одна модель написала код, попросите другую проверить:

Pi: Ctrl+L → другая модель, затем «проверь последние изменения».
OpenCode: субагент-ревьюер с другой моделью в поле model.

Разные модели ошибаются по-разному. Вторая модель часто находит то, что пропустила первая.

Модуль 10: Скрипты и CI

Оба агента можно запускать без интерфейса: в скриптах, cron и CI.

Pi

# Один ответ и выход
pi -p "Опиши, что делает этот проект"

# Передать данные через stdin
git diff main | pi -p "Сделай ревью этих изменений. Найди ошибки в SQL."

# Только чтение, без сессии, без файлов проекта .pi
pi -p --tools read,grep,find,ls --no-session -na "Проверь models/ на select *"

# События в JSONL — для разбора программой
pi --mode json "Найди модели без тестов" > events.jsonl

Ещё есть режим --mode rpc (команды через stdin/stdout) и SDK на TypeScript для встраивания Pi в свои программы.

OpenCode

opencode run "Найди dbt-модели без тестов на primary key"

Для программ есть HTTP-сервер (opencode serve) и SDK @opencode/ai.

Пример: ревью PR в GitHub Actions через Pi

name: ai-review
on:
  pull_request:
    paths: ["models/**"]

permissions:
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Install Pi
        run: npm install -g --ignore-scripts @earendil-works/pi-coding-agent

      - name: Review
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD -- models/ \
            | pi -p --no-session -na --tools read,grep,find,ls \
                "Сделай ревью изменений dbt-моделей. Проверь grain, тесты, join, NULL. Ответ в Markdown." \
            > review.md

      - name: Summary
        run: cat review.md >> "$GITHUB_STEP_SUMMARY"

Правила для CI:

Только чтение: --tools read,grep,find,ls. Без bash и write.
-na — не загружать расширения и настройки из репозитория. Иначе PR может подложить своё расширение.
permissions: contents: read и persist-credentials: false — у агента нет прав писать в репозиторий.
Не запускайте на PR из форков с доступом к секретам.
Результат — в Summary. Комментарий в PR публикуйте отдельным шагом без агента.

Модуль 11: Лучшие практики и частые ошибки

10 правил

Сначала план, потом код. OpenCode — агент plan. Pi — «запиши план в PLAN.md и подожди».
AGENTS.md в каждом проекте. Команды, правила, запреты. Один файл для всех агентов.
Маленькие задачи. Одна модель, одна проблема. Большую задачу делите на шаги.
Критерий готовности. «Готово, когда dbt build проходит».
Коммит перед задачей. Легко откатить.
Читайте diff. Агент уверенно пишет ошибки.
Подбирайте модель под задачу. Сильная для сложного, дешёвая для массового.
Новая сессия на новую задачу. Старый контекст мешает.
Только dev-окружение. Никогда прод.
Pi — в контейнере. OpenCode — с правилами разрешений.

Частые ошибки

Ошибка	Что будет	Как правильно
Подписка Claude Pro/Max в стороннем агенте	Блокировка аккаунта	API-ключ Anthropic или OpenRouter
Примеры OpenCode 1 в OpenCode 2	Настройки молча не работают	Проверяйте документацию V2
Маленькая локальная модель на сложной задаче	Агент путает инструменты, ходит по кругу	Модель 30B+, большой `num_ctx`, маленькие задачи
Pi на компьютере с доступом к проду	Агент может запустить что угодно	Контейнер, отдельный dev-пользователь
Слишком много MCP-серверов	Контекст забит, модель хуже работает	Только нужные для проекта
Установка пакетов и плагинов без проверки	Чужой код с вашими правами	Читать код, фиксировать версию
`CLAUDE.md` вместо `AGENTS.md` в OpenCode 2	Правила не загружаются	`AGENTS.md`
Одна огромная сессия на весь день	Агент забывает и путается	`/new` на каждую задачу

Чек-лист перед merge

Я прочитал весь diff
dbt build и тесты проходят
Нет новых select *, жёстко прописанных схем и паролей
Grain моделей не изменился без причины
Агент не удалил и не ослабил тесты
Описания в YAML есть и правдивые

Модуль 12: Сравнение: Pi, OpenCode, Claude Code и Codex

Общая таблица

	Pi	OpenCode	Claude Code	Codex
Открытый код	Да (MIT)	Да (MIT)	Нет	CLI — да
Цена агента	Бесплатно	Бесплатно	Подписка или API	Подписка или API
Модели	Любые	Любые	Claude (есть обходные пути)	GPT (можно другие)
Локальные модели	Да	Да	Через шлюз	Да
Песочница	Нет	Нет	Да	Да
Разрешения	Через расширения	allow / ask / deny	Да	Да
Режим планирования	Через расширение	Да	Да	Да
Субагенты	Через расширение	Да	Да	Да
MCP	Да	Да	Да	Да
Skills	Да	Да	Да	Да
Облачные задачи	Нет	Нет	Да	Да
Интеграция с GitHub	Свой workflow	Свой workflow	Да	Да

Соответствие функций

Что	Pi	OpenCode	Claude Code	Codex
Правила проекта	`AGENTS.md`, `CLAUDE.md`	`AGENTS.md`	`CLAUDE.md`	`AGENTS.md`
Настройки	`~/.pi/agent/settings.json`	`opencode.json`	`settings.json`	`config.toml`
Свои команды	`prompts/*.md`	`commands/*.md`	`commands/*.md`, skills	skills
Субагенты	расширение	`agents/*.md`	`agents/*.md`	`agents/*.toml`
Хуки	расширения (`pi.on`)	плагины	`hooks` в настройках	`hooks.json`
Без интерфейса	`pi -p`	`opencode run`	`claude -p`	`codex exec`
Сжать контекст	`/compact`	`/compact`	`/compact`	`/compact`

Один проект — все агенты

Можно настроить репозиторий так, чтобы им пользовались все четыре агента:

my-dbt-project/
├── AGENTS.md              # правила — читают все
├── CLAUDE.md              # одна строка: @AGENTS.md
├── .agents/skills/        # навыки — Pi, OpenCode, Codex
├── .claude/skills/        # можно сделать ссылкой на .agents/skills
├── opencode.json          # разрешения OpenCode
└── .pi/prompts/           # шаблоны Pi

Когда что выбрать

Ситуация	Выбор
Нужен лучший результат, есть подписка	Claude Code или Codex
Нужна любая модель, быстро начать	OpenCode
Нужен полный контроль, своё поведение агента	Pi
Код или данные нельзя отправлять в облако	OpenCode или Pi + Ollama
Нет доступа к Anthropic и OpenAI	OpenCode или Pi + OpenRouter / китайские модели
Встроить агента в свою программу	Pi SDK или OpenCode SDK

Дополнительные ресурсы

Pi:

OpenCode:

Общее:

Стандарт AGENTS.md
OpenRouter — сотни моделей по одному ключу
Ollama — локальные модели
dbt Agent Skills
dbt MCP

На нашем сайте:

Claude Code 101 — курс по агенту от Anthropic
Codex 101 — курс по агенту от OpenAI
AI в помощь — обзор AI-инструментов для инженера данных

Курс создан в ноябре 2026 года. Pi и OpenCode быстро развиваются, поэтому детали могут меняться. Сверяйтесь с документацией Pi и OpenCode.