# Ruflo через RouterAI: оркестратор роя агентов с учётом токенов на своём endpoint

## Ruflo

Ruflo ([ruvnet/ruflo](https://github.com/ruvnet/ruflo), ранее Claude Flow) — оркестратор роёв агентов поверх CLI и MCP. Он работает рядом с Claude Code и Codex: маршрутизирует задачи между специализированными агентами, хранит память и показывает расход токенов и стоимость сессии в консоли `ruflo tui`.

Через RouterAI Ruflo получает доступ к Claude, DeepSeek, GLM и Qwen из [каталога моделей](/models): работа из России без VPN, оплата в рублях, один ключ на все модели. Подключение зависит от того, какую часть Ruflo вы используете: модели самих агентов задаёт Claude Code (Anthropic-совместимый путь), а страница AI в консоли Ruflo ходит на указанный вами OpenAI-совместимый endpoint.

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

- macOS, Linux или Windows (WSL)
- Node.js и npm (Ruflo запускается через `npx`)
- Claude Code и/или Codex CLI, если вы хотите оркестрировать их
- API-ключ из [личного кабинета](/settings/keys)

## Установка

Самый короткий путь — запуск через `npx` в каталоге проекта:

```bash
npx ruflo@latest --version
npx ruflo@latest init wizard
```

Альтернатива — установочный скрипт из документации: `curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash` (флаг `--full` добавляет MCP и диагностику).

`init wizard` — интерактивный мастер полной настройки. Он начинается с выбора пресета: Default (рекомендуемые настройки), Minimal (только базовые функции), Full (все возможности) или Custom (выбор компонентов по одному). Если диалог не нужен, есть неинтерактивные варианты: `ruflo init --minimal`, `--full`, `--codex` (для Codex CLI), `--dual` (Claude Code и Codex).

![Мастер RuFlo V3 Setup Wizard: выбор пресета Default, Minimal, Full или Custom](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/badf09b7b822735d6afbb5722fb45418.png)

Инициализация пишет конфигурацию прямо в проект:

| Что | Где |
| --- | --- |
| Настройки Claude Code и хуки | `.claude/settings.json` |
| Данные Ruflo (память, состояние роя) | `.claude-flow/` |
| MCP-серверы | `.mcp.json` |
| Инструкции агентам | `CLAUDE.md` (для Codex — `AGENTS.md`, `.agents/`) |

Перед правкой существующего `.claude/settings.json` Ruflo сохраняет резервную копию рядом с ним.

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

### Вариант 1. Endpoint-строка для консоли Ruflo

Страница AI в `ruflo tui` по умолчанию отправляет вопросы на `openrouter.ai` (ключ в `OPENROUTER_API_KEY`, модель по умолчанию `openrouter/auto`). Другие OpenAI-совместимые шлюзы подключаются через переменную `RUFLO_TUI_CONVO_TARGETS` или флаг `--convo-targets`. Синтаксис:

```text
endpoint:<name>=<https-base-url>|<KEY_ENV>|<model>;...
```

- `<name>` — произвольное имя endpoint;
- `<https-base-url>` — базовый адрес, только HTTPS; для RouterAI это `https://routerai.ru/api/v1`;
- `<KEY_ENV>` — **имя** переменной окружения с ключом, а не сам ключ;
- `<model>` — id модели из каталога.

Пошагово:

1. Экспортируйте ключ в том же терминале, где запускаете Ruflo:

```bash
export ROUTERAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
```

2. Задайте endpoint:

```bash
export RUFLO_TUI_CONVO_TARGETS='endpoint:routerai=https://routerai.ru/api/v1|ROUTERAI_API_KEY|anthropic/claude-sonnet-5.5'
```

3. Откройте консоль на странице AI:

```bash
npx ruflo tui --view ai
```

Ключ в интерфейсе не показывается: консоль пишет только, что переменная `ROUTERAI_API_KEY` задана. Каждый вопрос сначала выводится в карточку «Ask first» с тем, что именно уйдёт, и отправляется только после `y`. Лимит расхода задаёт `--max-spend-usd` (по умолчанию 0.5). Запросы идут только на `openrouter.ai` и на HTTPS-хосты из endpoint-строки, без редиректов.

Чтобы не вводить переменные каждый раз, добавьте обе строки `export` в `~/.zshrc` или `~/.bashrc`.

![Страница AI в ruflo tui: статус «ROUTERAI_API_KEY is set» и лимит расхода](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/0f9ab2b530dbdc10443db8e233f3b081.png)

### Вариант 2. Anthropic-совместимый путь для агентов

Сами агенты роя выполняются в Claude Code, а он читает стандартные переменные Anthropic. RouterAI поддерживает Anthropic Messages API по адресу `https://routerai.ru/api` (без `/v1`):

```bash
export ANTHROPIC_BASE_URL="https://routerai.ru/api"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxxxxxx"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-5.5"
claude
```

Эти переменные подхватывает Claude Code, а Ruflo работает с ним через хуки и MCP, поэтому рой использует модели RouterAI. О настройке обвязки агентов — в статье про [обвязку агентов и токены](/pages/obvyazka-agentov-tokeny-claude-code-codex-cline-opencode).

### Ограничения

- Часть экранов Ruflo берёт ключ только из переменной, названной в конфигурации (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` или `KEY_ENV` из endpoint-строки). Ключ, записанный в другом месте, они не увидят.
- Встроенный провайдер OpenRouter ходит только на `openrouter.ai`; для RouterAI используйте endpoint-строку.
- Managed-агенты (`managed_agent_*`) работают в облаке Anthropic через Claude Managed Agents beta и требуют `ANTHROPIC_API_KEY` с доступом к бете. Через RouterAI они не заведутся; локальные WASM-агенты (`wasm_agent_*`) ключа не требуют.
- Codex-режим страницы AI отправляет вопрос в OpenAI через Codex CLI, а не в RouterAI.

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

Идентификаторы сверены с [каталогом RouterAI](/models) на дату написания; актуальный список и цены смотрите в каталоге.

| Модель | Для чего |
| --- | --- |
| `anthropic/claude-sonnet-5.5` | Основная модель: планирование, роль queen в иерархическом рое, код |
| `anthropic/claude-opus-5.5` | Сложное планирование и архитектурные решения |
| `deepseek/deepseek-v4.1-flash` | Рутинные воркеры: массовые правки, тесты, документация |
| `z-ai/glm-5.3-flash` | Быстрые дешёвые воркеры |
| `qwen/qwen4-max` | Задачи с длинным контекстом (в каталоге указан контекст 1 млн токенов) |

Ruflo сам разделяет задачи по уровням: простые правки выполняет без вызова LLM (WASM), средние отправляет на дешёвые модели, сложные — на сильные. Поэтому сильную модель имеет смысл назначить планировщику, а лёгкую — воркерам.

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

1. Проверьте, что ключ работает:

```bash
curl -s https://routerai.ru/api/v1/models -H "Authorization: Bearer $ROUTERAI_API_KEY" | head -c 200
```

2. Инициализируйте тестовый проект (`npx ruflo@latest init wizard`) и запустите `claude` с переменными из варианта 2. Дайте одну небольшую задачу, например: «Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed».
3. Откройте консоль и страницу Cost:

```bash
npx ruflo tui --view cost
```

На ней видны бюджет и расход по Claude Code и Codex, а также число маршрутизаций по уровням haiku, sonnet и opus. Показатели, которые Ruflo не может измерить, отображаются как `n/a`; отсутствующий отчёт о стоимости не считается нулём.

![Страница Cost в ruflo tui: блоки Set a budget, Where it goes и Across providers](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/1e438f51bb9f25500631603af3fec74b.png)

4. Сверьте расход в [личном кабинете RouterAI](/settings/billing): списания по ключу должны соответствовать запросам сессии.

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

### Запросы уходят на openrouter.ai

Переменная `RUFLO_TUI_CONVO_TARGETS` не подхватилась: она задана в другом терминале или не экспортирована (`export`). Проверьте `echo $RUFLO_TUI_CONVO_TARGETS` в том же окне, где запускается `ruflo tui`, и синтаксис строки: `endpoint:<name>=<url>|<KEY_ENV>|<model>`.

### 401 Unauthorized

Имя переменной ключа в endpoint-строке не совпадает с окружением: например, в строке `ROUTERAI_API_KEY`, а экспортирован `ROUTERAI_KEY`. Либо ключ скопирован не полностью. Для Claude Code проверьте `ANTHROPIC_AUTH_TOKEN`.

### 404 Not Found

Неверный базовый адрес. Для endpoint-строки — `https://routerai.ru/api/v1` (с `/v1`), для `ANTHROPIC_BASE_URL` — `https://routerai.ru/api` (без `/v1`).

### Модель не найдена

Id должен точно совпадать с каталогом, в формате `провайдер/модель`, например `anthropic/claude-sonnet-5.5`.

### Не работают managed-агенты

Они требуют облака Anthropic и `ANTHROPIC_API_KEY` с доступом к бете, через RouterAI не поддерживаются. Используйте локальные агенты.

### 402 Payment Required

Недостаточно средств — пополните баланс в разделе [Биллинг](/settings/billing).

## Что дальше

- [Каталог моделей](/models) — подберите модели для планировщика и воркеров
- [Обвязка агентов и токены](/pages/obvyazka-agentov-tokeny-claude-code-codex-cline-opencode) — как агенты расходуют токены
- [Headroom через RouterAI](/pages/headroom-routerai) — сжатие контекста агента
- [Paperclip через RouterAI](/pages/paperclip-routerai) — ещё одна команда AI-агентов
- [Документация Ruflo](https://github.com/ruvnet/ruflo/blob/main/docs/USERGUIDE.md)

Мастер настройки и подключение Claude Code через RouterAI проверены на Ruflo 3.77.2 и Claude Code 2.1.327.
