# 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 из [каталога](/models).

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

## Требования

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

## Установка

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

```bash
npx paperclipai@latest onboard --yes
```

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

Альтернатива — запуск из репозитория [paperclipai/paperclip](https://github.com/paperclipai/paperclip):

```bash
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 не меняет.

| Формат подключения | Совместимый harness | Provider URL для RouterAI |
| --- | --- | --- |
| Chat Completions API | OpenCode, Hermes | `https://routerai.ru/api/v1` |
| Messages API (Anthropic Messages) | Claude Code | `https://routerai.ru/api` |
| Responses API | Codex | зависит от поддержки Responses API на стороне шлюза |

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

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 модели из [каталога](/models) вы вводите на самом агенте. После подключения в карточке подключения, в блоке **Provider settings**, видны Destination, API format, Authentication и подсказка «Enter a model ID on the agent».

![Форма Connect Chat Completions API: Provider URL, API format, Authentication, API key](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/664cd86cfc60f093460554fad976aa6d.png)

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

Откройте агента, затем **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 как есть.

![Агент CEO: harness OpenCode, Connection «Company routerai.ru», модель paperclip/anthropic/claude-haiku-5.5](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/346ee8e46af20f395150e08f0e6da9fd.png)

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

| Адаптер | Что делать |
| --- | --- |
| Claude Code (`claude_local`) | Подключение формата Messages API с URL `https://routerai.ru/api`, модель вида `anthropic/claude-sonnet-5.5`. Paperclip также учитывает `ANTHROPIC_BASE_URL` из `env` агента или сервера. |
| Codex (`codex_local`) | Нужен формат Responses API. Выбирайте его только если используемый шлюз его поддерживает. |
| OpenCode (`opencode_local`) | Подключение Chat Completions, URL `https://routerai.ru/api/v1`, модель с префиксом `paperclip/`. |
| Hermes (`hermes_local`) | Подключение Chat Completions. Адаптер не имеет поля модели в Paperclip: Hermes берёт модель из `~/.hermes/config.yaml`. |
| Pi (`pi_local`) | У Pi нет флага base URL, поэтому провайдер описывается через переменную `PAPERCLIP_PI_PROVIDERS` (см. ниже). |
| OpenClaw (`openclaw_gateway`) | Paperclip подключается к вашему экземпляру OpenClaw по WebSocket (`ws://` или `wss://`); модели настраиваются в самом OpenClaw. |

### Pi: PAPERCLIP_PI_PROVIDERS

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

```json
{
  "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](/pages/openclaw-web-telegram-routerai-claude-gpt-5-deepseek-mistral), — а в Paperclip укажите URL его Gateway.

## Выбор модели

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

| Модель | Для чего | Вход / выход |
| --- | --- | --- |
| `anthropic/claude-sonnet-5.5` | основная модель для кодовых агентов, CTO/инженеры | 214,92 / 1074,60 |
| `anthropic/claude-haiku-5.5` | быстрые и дешёвые рутинные роли | 10,75 / 53,73 |
| `openai/gpt-5.4-mini` | недорогая модель OpenAI для Chat Completions-агентов | 80,60 / 483,57 |
| `deepseek/deepseek-v4-flash` | массовые простые задачи, минимальная цена | 10,21 / 20,42 |
| `google/gemini-3.1-pro-preview` | длинный контекст (1 048 576) и ревью | 214,92 / 1289,52 |

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

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

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

![Audit → Budgets: Budget control plane, инциденты и приостановленные агенты](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/e9bdb7a56bd07e8809f28ed0bf21c52a.png)

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

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

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

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

![Run test: Connection successful, настроенная модель paperclip/anthropic/claude-haiku-5.5 и ответ Hello](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/984b85763ad0bc42870a3c4c89bd6111.png)

Пробный запрос и задачи расходуют токены, поэтому сначала убедитесь, что выбраны нужные подключение и модель. Чтобы агент выполнял задачи (**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](/models) — id, контекст и цены.
* [OpenClaw через RouterAI](/pages/openclaw-web-telegram-routerai-claude-gpt-5-deepseek-mistral) — настройка агента и каналов.
* [claude-mem через RouterAI](/pages/claude-mem-routerai) — память для Claude Code и Codex.
* [Herdr и AI-агенты через RouterAI](/pages/herdr-desktop-ai-agents-routerai) — Claude Code и Codex в панелях.
* [Документация Paperclip: Custom model providers](https://docs.paperclip.ing/connectors/custom-model-providers/) и [обзор адаптеров](https://docs.paperclip.ing/reference/adapters/overview/).

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