Paperclip — оркестрация команд AI-агентов как автономной компании

Paperclip — платформа с открытым исходным кодом для управления командой ИИ-агентов как организацией: с ролями, подчинением, задачами, бюджетами, согласованиями и журналом запусков. Она подходит, когда агентов уже несколько и нужен единый контрольный слой вместо набора разрозненных терминалов.

Что Paperclip берёт под контроль

Paperclip координирует существующие агентные среды, включая Claude Code, OpenAI Codex, Gemini CLI, Cursor, OpenCode и другие рантаймы. Сама платформа не создаёт модели и не заменяет кодинг-агента: она определяет, кто получает задачу, когда запускается, сколько может потратить и где остаётся история работы.

Основные сущности:

• Компания — изолированная организация с целью, агентами, задачами и общим бюджетом.
• Агент — роль с инструкциями, руководителем, адаптером и собственным лимитом расходов.
• Задача — отслеживаемая единица работы со статусом, приоритетом, исполнителем и обсуждением.
• Heartbeat — отдельный запуск агента. Он может начаться по таймеру, назначению задачи, комментарию, ручной команде или автоматизации.
• Адаптер — соединение между Paperclip и средой, в которой фактически работает агент.
• Согласование — точка остановки, где решение должен принять человек.

Как проходит задача от назначения до результата

1. Вы создаёте компанию, формулируете цель и добавляете проекты.
2. Для каждого агента задаёте роль, руководителя, инструкции, адаптер и бюджет.
3. Работа оформляется задачей. Агент получает её через назначение или делегирование.
4. Перед началом агент выполняет checkout — закрепляет задачу за собой. Если она уже занята другим агентом, сервер возвращает конфликт 409.
5. Адаптер запускает выбранную агентную среду и передаёт ей контекст задачи.
6. Во время прогона Paperclip записывает состояние, стенограмму, использование токенов, стоимость и затронутые задачи.
7. Агент обновляет статус задачи, оставляет результат или объясняет причину блокировки.

Checkout нужен для защиты от двойной работы. Повторный checkout той же задачи её владельцем идемпотентен, но конфликт 409 означает, что задачу следует оставить другому исполнителю, а не захватывать повторно.

Возможности для управления агентами

Конфигурации агентов версионируются. Если изменение сломало запуск, предыдущую конфигурацию можно восстановить; откат также сохраняется как новая ревизия.

Поддерживаемые адаптеры

Актуальная документация перечисляет локальные адаптеры для Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Pi и Hermes. В продукте также есть OpenClaw Gateway, Process и HTTP, но в списке настройки агента они помечены как Coming soon; фактическая доступность зависит от версии и конфигурации инстанса.

В v2026.831.0 появился адаптер kimi_local для Kimi Code. Он использует общий ACP-движок, а при отсутствии необходимых условий может перейти к запуску через headless CLI.

Выбор адаптера определяет:

• доступные модели;
• рабочую директорию;
• способ управления сессией;
• параметры песочницы и подтверждений;
• поддержку навыков и инструкционных файлов.

Локальные адаптеры могут использовать набор файлов с инструкциями. Для сложной роли документация рекомендует разделять обязанности, характер, порядок действий и заметки об инструментах между AGENTS.md, SOUL.md, HEARTBEAT.md и TOOLS.md. Узкому агенту обычно достаточно одного AGENTS.md.

Установка и первый запуск

Для актуального стабильного канала используйте:

npx paperclipai@latest onboard

При установке из исходного кода сначала убедитесь, что используется Node.js 24.11.0 или новее. Требование было повышено в v2026.831.0; инструкции, рассчитанные на старые версии Node.js, текущему релизу не соответствуют.

Проверка результата

1. Завершите мастер первоначальной настройки и откройте созданную организацию.
2. Создайте или подключите первого агента и проверьте конфигурацию адаптера.
3. Назначьте агенту небольшую тестовую задачу с однозначным критерием готовности.
4. Откройте активный прогон: стенограмма должна обновляться во время исполнения.
5. После завершения проверьте статус задачи, итоговый комментарий, модель, токены и стоимость в сведениях о запуске.
6. Откройте журнал активности и убедитесь, что запуск связан с агентом и причиной пробуждения.

Материал основан на официальной документации и релизных заметках; приведённая установка не проверялась автором на отдельном тестовом инстансе.

Рутины вместо постоянного опроса

Для большинства агентов интервальный heartbeat лучше оставить выключенным, а пробуждение по запросу (Wake on demand) — включённым. Тогда агент запускается после назначения, комментария, ручной команды или срабатывания рутины, но не тратит токены на регулярную проверку пустого инбокса.

Рутина создаёт или повторно открывает задачу и назначает её выбранному агенту. Поддерживаются два основных триггера:

• расписание cron с явно сохранённым часовым поясом;
• подписанный webhook для внешних событий.

Политика параллельности определяет, что делать с новым срабатыванием, пока предыдущее ещё выполняется: объединить, пропустить или поставить в очередь. Политика catch-up управляет пропущенными окнами после простоя планировщика.

Таймер самого агента оправдан, когда он опрашивает систему без webhook, например почтовый ящик или сторонний API. В таком случае выбирайте максимально допустимый интервал.

Полезные сценарии

Собрать несколько кодинг-агентов в один борд

Создайте проект для каждого репозитория, назначьте агентам конкретные зоны ответственности и перенесите работу в задачи с критериями приёмки. Оставьте интервальные heartbeat выключенными: назначения сами разбудят исполнителей.

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

Запускать регулярные отчёты без пустых прогонов

Создайте рутину, добавьте cron-расписание в нужном часовом поясе и назначьте агента. Для внешнего события используйте подписанный webhook.

Проверка: каждое срабатывание создаёт отслеживаемую задачу, а в истории рутины видны источник, статус и время запуска. Настройте coalesce или skip, если новый интервал может наступить до завершения старого.

Ограничить расходы автономной команды

Установите общий месячный бюджет компании и меньшие лимиты для отдельных агентов. Следите за расходами по запускам и переводите повторяемую работу на подходящие по цене модели.

Проверка: при 80% использования появляется предупреждение, а при достижении лимита агент автоматически ставится на паузу и перестаёт получать новые heartbeat. Бюджеты компании и агента действуют независимо.

Выдавать секреты только во время работы

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

Агент сначала получает список разрешённых псевдонимов через GET /api/agents/me/secrets, а затем запрашивает конкретное значение:

POST /api/agents/me/secrets/{key}/value

Проверка: успешное чтение связано с конкретным агентом и проверенным активным запуском и отражается в журнале безопасности и активности. Тестовые токены для навыков и агенты низкого доверия не получают доступ к этому API.

Что изменилось после v2026.722.0

Ограничения и случаи, когда платформа не подходит

• Самостоятельно размещаемый инстанс нужно устанавливать и обновлять; управляемые среды исполнения документированы отдельно, но их возможности зависят от развёртывания.
• Быстрый темп разработки требует читать Upgrade Guide перед каждым обновлением.
• Агенты могут запускать код и обращаться к внешним системам в зависимости от адаптера и выданных прав. Права, песочницы и секреты нужно ограничивать под конкретную роль.
• Paperclip добавляет организационный слой, поэтому для одного агента его настройка часто избыточна.
• Интервальные heartbeat способны создавать шум и лишние расходы. Для обычной работы используйте событийные пробуждения и рутины.
• Возможности адаптеров различаются: перед наймом агента проверьте модель, окружение, навыки и режим исполнения на целевом инстансе.

Официальные ссылки

• Документация Paperclip
• Ключевые понятия
• Управление агентами
• Heartbeats и рутины
• API секретов
• GitHub-репозиторий
• Релизы

Следующий шаг

Хватит считать агента помощником — оформляйте его на работу

Связанные материалы

• Блог: Топ-агенты вместо топ-менеджеров
• База знаний: GitHub Projects — управление задачами AI-агентов

Если у вас уже несколько агентов, Paperclip стоит рассматривать как отдельный слой управления задачами, расходами и доступами. Сначала проверьте его на одном проекте и двух агентах, прежде чем переносить всю команду.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov