Paperclip через RouterAI: оркестрация команды AI-агентов

Paperclip — open-source (MIT) сервер на Node.js с React UI, который собирает команду AI-агентов в «компанию»: у агентов есть роли, начальники, задачи, бюджеты и общая история работы. Сами агенты — Claude Code, Codex, OpenCode, Hermes, Pi и другие — запускаются через адаптеры. Paperclip умеет подключать произвольный шлюз как Custom model provider, поэтому RouterAI подходит как единая точка доступа: работа из России без VPN, оплата в рублях, один ключ и один баланс на модели Anthropic, OpenAI, Google и DeepSeek из каталога.

Ниже — как запустить Paperclip, добавить RouterAI в Connectors и выбрать подключение на агенте, а также как направить на RouterAI адаптеры Claude Code, Codex, Pi, Hermes и OpenClaw.

Требования

• Node.js 24.11 или новее (для установки из исходников ещё pnpm 9.15+).
• Ключ RouterAI: создайте его в личном кабинете и пополните баланс.
• Установленные CLI агентов, которых хотите нанимать (Claude Code, Codex, Pi, Hermes и т. д.): Paperclip запускает их на той же машине.

Установка

Быстрый запуск через npx:

npx paperclipai@latest onboard --yes

Если конфигурация уже есть, повторный onboard её не перезапишет; для правки настроек используйте npx paperclipai configure. Для доступа из локальной сети есть флаги --bind lan и --bind tailnet.

Альтернатива — запуск из репозитория paperclipai/paperclip:

pnpm install
pnpm dev

UI и API поднимаются на http://localhost:3100, встроенная PostgreSQL создаётся автоматически. Для продакшена можно указать собственную Postgres. Запускайте Paperclip от обычного пользователя, не от root. При первом входе откройте UI, создайте аккаунт, заберите инстанс (Claim this instance) и пройдите мастер: организация, первый агент и шаг Connect a model. Шаг можно закончить позже: подключение RouterAI добавляется отдельно, в Connectors.

Подключение к RouterAI

Paperclip хранит маршрут и ключ как «AI-подключение» (AI connection), а затем вы выбираете его на совместимом агенте.

Формат API должен совпадать с harness

Это главное правило: формат API подключения определяется тем, какой harness (рантайм) запускает агента. Выбор модели другого провайдера harness не меняет.

Добавление подключения

1. Откройте Connectors в боковом меню (раздел Org), во вкладке All найдите Chat Completions API (для OpenCode и Hermes) или Messages API (для Claude Code) и нажмите Connect.
2. В поле Provider URL введите https://routerai.ru/api/v1 для Chat Completions или https://routerai.ru/api для Messages. Для удалённых адресов обязателен HTTPS; в URL нельзя вшивать ключ, параметры запроса и фрагмент.
3. Проверьте API format и Authentication: для RouterAI подходит Bearer token (для Messages Paperclip также поддерживает x-api-key).
4. Введите в поле API key ваш ключ sk-xxxxxxxxxxxxxxxx.
5. Под формой указано, кому доступно подключение: по умолчанию всей организации и всем агентам, это можно изменить кнопкой Change. Нажмите Connect.

В форме нет списка моделей: Paperclip не подтягивает каталог произвольного шлюза, поэтому id модели из каталога вы вводите на самом агенте. После подключения в карточке подключения, в блоке Provider settings, видны Destination, API format, Authentication и подсказка «Enter a model ID on the agent».

Выбор подключения на агенте

Откройте агента, затем Harness / Runtime в боковом меню агента. Выберите harness (например, OpenCode): под ним появится селектор Connection, в котором будет созданное подключение (в примере — «Company routerai.ru»). Кастомные подключения нужно выбирать явно: сделать их провайдером по умолчанию нельзя. При выборе Paperclip покажет окно Adopt Connections — подтвердите Use this binding when saved и нажмите Save changes. Для агента с harness Claude Code вместо селектора показан блок «Existing authentication — not managed by Connections» с кнопкой Choose a managed connection.

В поле Model введите id модели: выберите Use manual model и впишите точный id из каталога, например anthropic/claude-haiku-5.5. Для OpenCode picker добавляет префикс, и в поле будет paperclip/anthropic/claude-haiku-5.5; Claude, Codex и Hermes используют id как есть.

Адаптеры: как направить на RouterAI

Pi: PAPERCLIP_PI_PROVIDERS

Переменная содержит JSON в формате раздела providers из models.json Pi. Paperclip записывает его во временный models.json и указывает на него через PI_CODING_AGENT_DIR. Модели нужно перечислить явно:

{
  "routerai": {
    "baseUrl": "https://routerai.ru/api/v1",
    "apiKey": "{env:ROUTERAI_API_KEY}",
    "api": "openai-completions",
    "models": [
      {
 "id": "anthropic/claude-sonnet-5.5",
        "name": "Claude Sonnet 5.5",
        "reasoning": false,
 "input": ["text"],
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
        "contextWindow": 1000000,
        "maxTokens": 32000
      }
    ]
  }
}

Передайте её в окружение процесса Paperclip, а ключ положите в ROUTERAI_API_KEY: плейсхолдер {env:VAR} раскрывается на сервере. Тогда в адаптере Pi модель задаётся как routerai/anthropic/claude-sonnet-5.5 (формат provider/model). Допустимые значения api смотрите в документации Pi; в примере документации Paperclip для Anthropic-совместимого шлюза указано anthropic-messages, для RouterAI Messages (https://routerai.ru/api) используйте его.

OpenClaw

Если нужен OpenClaw с моделями через RouterAI, настройте провайдера в самом OpenClaw — см. статью про OpenClaw, — а в Paperclip укажите URL его Gateway.

Выбор модели

Цены из каталога RouterAI, ₽ за 1 млн токенов (вход / выход):

Цены меняются, актуальные — в каталоге. Разные роли можно вести на разных моделях: руководителя — на Sonnet, исполнителей рутины — на Haiku или DeepSeek.

Бюджеты и единый баланс

Paperclip считает токены и расход по компании, агентам, проектам, задачам, провайдерам и моделям, а бюджеты можно ставить на компанию, агента и проект: есть предупреждающие пороги и жёсткая остановка работы (hard stop). Остановка опирается на записанный расход, поэтому уже запущенная работа может её задержать. Сводка лежит в Audit → Budgets (Budget control plane), бюджеты агента и проекта задаются на их страницах. Когда агентов много, а моделей несколько, это удобно сочетать с одним ключом RouterAI: единый баланс в рублях, один счёт вместо отдельных аккаунтов у каждого провайдера, а лимиты на уровне агентов задаёт сам Paperclip.

Проверка подключения

Проверьте ключ запросом к каталогу:

curl https://routerai.ru/api/v1/models -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

Затем на странице агента Harness / Runtime нажмите Run test в блоке «Test your agent». Paperclip проверит команду harness, найдёт модель и отправит пробный запрос; в Test details видно настроенную модель и ответ.

Пробный запрос и задачи расходуют токены, поэтому сначала убедитесь, что выбраны нужные подключение и модель. Чтобы агент выполнял задачи (Assign Task, Run now), он не должен быть на паузе.

Решение проблем

• Подключение несовместимо с агентом. Формат API не соответствует harness: Claude Code требует Messages, OpenCode и Hermes — Chat Completions, Codex — Responses.
• Список моделей пуст. Paperclip не подтягивает каталог произвольного шлюза: выберите Use manual model в поле Model агента и введите id из каталога.
• Шлюз отклоняет ключ (401). Проверьте формат Authentication и переподключите подключение с действительным ключом: Reconnect заменяет credential и сохраняет endpoint и формат.
• Ошибка URL. Для удалённого адреса нужен HTTPS без ключа в URL, query и фрагмента. HTTP допустим только для localhost.
• Pi: model not found. Модель не перечислена в models внутри PAPERCLIP_PI_PROVIDERS или имя провайдера в --provider не совпадает с ключом JSON.

Что дальше

• Каталог моделей RouterAI — id, контекст и цены.
• OpenClaw через RouterAI — настройка агента и каналов.
• claude-mem через RouterAI — память для Claude Code и Codex.
• Herdr и AI-агенты через RouterAI — Claude Code и Codex в панелях.
• Документация Paperclip: Custom model providers и обзор адаптеров.

Инструкция проверена на Paperclip v2026.1106.0.