# DeerFlow через RouterAI: super agent harness ByteDance на Claude, GPT и DeepSeek

DeerFlow 2.2.0 — open-source super agent harness от ByteDance: он оркестрирует субагентов, память, песочницы и навыки, превращая одиночный запрос в многоэтапный исследовательский или кодовый пайплайн. В феврале 2026 года вышла версия 2.0 — полная переработка с нуля; в октябре 2026 года выпущена версия 2.2.0 с поддержкой web-интерфейса для управления моделями и расширенными настройками субагентов. Исходный фреймворк Deep Research живёт на ветке `1.x` и не разделяет кода с новой версией.

Подключение к [RouterAI](https://routerai.ru "RouterAI") даёт DeerFlow доступ к Claude, GPT, DeepSeek, GLM, Qwen и Kimi через единый OpenAI-совместимый API — без VPN, с оплатой в рублях и [каталогом моделей](/models "каталогом моделей"), который можно выбрать прямо в конфиге.

## Требования {#trebovaniya}

- Python 3.12+
- Node.js 22+
- [`uv`](https://docs.astral.sh/uv/) (пакетный менеджер Python)
- API-ключ RouterAI из [личного кабинета](/settings/keys "личного кабинета")

Поддерживаются macOS, Linux и Windows (WSL). Docker рекомендуется, но не обязателен.

## Установка {#ustanovka}

Склонируйте репозиторий и запустите мастер настройки:

```bash
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup
```

Мастер задаст несколько вопросов: LLM-провайдер, поисковый инструмент и настройки sandbox. Он создаст `config.yaml` и запишет ключи в `.env`. Если вы хотите настроить конфиг вручную, запустите `make config` — он скопирует полный шаблон `config.example.yaml`.

После настройки запустите приложение:

```bash
# Docker (рекомендуется)
make docker-init   # однократная загрузка образа sandbox
make docker-start  # старт сервисов

# Локально
make install
make dev
```

Интерфейс откроется по адресу `http://localhost:2026`. При первом открытии DeerFlow попросит создать учётную запись администратора (email и пароль), после входа появится стартовая страница чата с полем ввода задачи и выбором модели:

![Стартовая страница DeerFlow на localhost:2026: поле ввода задачи и выбор модели](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/e5a6c78eb3bd2d801c976cbbda6c942c.png)

## Подключение к RouterAI {#podklyuchenie-k-routerai}

DeerFlow описывает каждую LLM в блоке `models:` файла `config.yaml`. Для OpenAI-совместимого API RouterAI используется класс `langchain_openai:ChatOpenAI`.

### Шаг 1: добавьте ключ в .env

Откройте `.env` в корне проекта и пропишите переменную:

```bash
ROUTERAI_API_KEY=sk-xxxxxxxxxxxxxxxx
```

Ключ не следует хранить прямо в `config.yaml`, если файл попадёт в git.

### Шаг 2: добавьте записи моделей в config.yaml

Откройте `config.yaml` и добавьте записи в блок `models:`. Для `langchain_openai:ChatOpenAI` поле называется `base_url` (не `api_base`; DeerFlow принимает оба варианта, но логирует предупреждение при `api_base`):

```yaml
models:
  - name: routerai-sonnet
    display_name: Claude Sonnet 5.5 via RouterAI
    use: langchain_openai:ChatOpenAI
    model: anthropic/claude-sonnet-5.5
    api_key: $ROUTERAI_API_KEY
    base_url: https://routerai.ru/api/v1
    context_window: 1000000
    max_tokens: 32000
    supports_thinking: false
    supports_vision: true

  - name: routerai-opus
    display_name: Claude Opus 5.5 via RouterAI
    use: langchain_openai:ChatOpenAI
    model: anthropic/claude-opus-5.5
    api_key: $ROUTERAI_API_KEY
    base_url: https://routerai.ru/api/v1
    context_window: 1000000
    max_tokens: 32000
    supports_thinking: false
    supports_vision: true

  - name: routerai-deepseek-flash
    display_name: DeepSeek V4.1 Flash via RouterAI
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v4.1-flash
    api_key: $ROUTERAI_API_KEY
    base_url: https://routerai.ru/api/v1
    context_window: 1048576
    max_tokens: 32000
    supports_thinking: false
    supports_vision: false
```

Так выглядит начало блока `models` в `config.yaml`:

![Фрагмент config.yaml: блок models с записями routerai-sonnet и routerai-deepseek-flash, поля base_url и api_key](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/7dde5f5474af94c23e70cac25ba421e0.png)

### Шаг 3: выберите модель и модель для сжатия истории

После перезапуска все записи из блока `models` появятся в селекторе моделей чата — выберите нужную там. Длинную историю DeerFlow сжимает автоматически; по умолчанию это делает та же модель, что ведёт задачу. Чтобы не тратить на сжатие дорогую модель, назначьте для него быструю в разделе `summarization`:

```yaml
summarization:
  enabled: true
  model_name: routerai-deepseek-flash
```

### Альтернатива: мастер make setup

Если вы ещё не запускали мастер, `make setup` позволит выбрать провайдер и ввести ключ в интерактивном режиме — он сам запишет нужные строки в `config.yaml` и `.env`.

Модели можно добавить и через веб-интерфейс, в настройках моделей: для RouterAI выберите вариант **Custom OpenAI-compatible**, укажите Base URL `https://routerai.ru/api/v1`, ключ и model ID. Перезапуск не нужен, а записи из `config.yaml` в интерфейсе остаются только для чтения. Это удобно для быстрой проверки, но для командного использования предпочтительнее `config.yaml` под контролем версий.

## Флаги reasoning и vision {#reasoning-flags}

Три опциональных флага на каждую модель управляют тем, как DeerFlow взаимодействует с провайдером:

| Флаг | Значение | Когда ставить |
|---|---|---|
| `supports_thinking: true` | модель принимает параметр для включения/выключения thinking | провайдер явно поддерживает этот параметр |
| `supports_vision: true` | модель принимает изображения в сообщениях | модель мультимодальная |
| `supports_reasoning_effort: true` | модель принимает `reasoning_effort` (low/medium/high) | модели серии o* и совместимые |

Для начала оставьте `supports_thinking: false`: так DeerFlow не отправляет переключатель рассуждений, и запрос гарантированно уходит в стандартном формате OpenAI. Флаг с блоком `when_thinking_enabled` имеет смысл включать, только если вы знаете, какой параметр рассуждений принимает выбранная модель, и проверили его коротким запросом.

Пример конфига для модели с reasoning effort (например, GPT-6.2 Astra):

```yaml
  - name: routerai-gpt62-astra
    display_name: GPT-6.2 Astra via RouterAI
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-6.2-astra
    api_key: $ROUTERAI_API_KEY
    base_url: https://routerai.ru/api/v1
    context_window: 1050000
    max_tokens: 32000
    supports_thinking: false
    supports_reasoning_effort: true
```

## Выбор модели {#vybor-modeli}

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

| Модель | id в каталоге | Для чего |
|---|---|---|
| Claude Sonnet 5.5 | `anthropic/claude-sonnet-5.5` | Основная: длинные исследования, сложные задачи кода |
| Claude Opus 5.5 | `anthropic/claude-opus-5.5` | Самые сложные аналитические пайплайны |
| GPT-6.2 Astra | `openai/gpt-6.2-astra` | Альтернатива Claude, поддержка reasoning effort |
| DeepSeek V4.1 Flash | `deepseek/deepseek-v4.1-flash` | Быстрые фоновые шаги, суммаризация |
| GLM-5.3 | `z-ai/glm-5.3` | Длинный контекст (1M токенов), исследования |
| Qwen4-Max | `qwen/qwen4-max` | Мультимодальные задачи с большим контекстом |
| Kimi K3.1 Pro | `moonshotai/kimi-k3.1-pro` | Флагманская open-weight модель с 1M контекстом |

DeerFlow хорошо работает с любой моделью с поддержкой tool calling. Без tool calling субагенты не смогут вызывать инструменты — агент вернёт пустой результат или завершится с ошибкой.

## Проверка подключения {#proverka-podklyucheniya}

После старта (`make dev` или `make docker-start`) откройте `http://localhost:2026` и дайте агенту короткую задачу, например:

> Кратко (в 3 пунктах) объясни, чем super agent harness отличается от обычного чат-бота.

В интерфейсе будет виден прогресс и итоговый ответ; выбранная модель (Claude Sonnet 5.5 via RouterAI) отображается в поле ввода:

![DeerFlow: агент отвечает на задачу на Claude Sonnet 5.5 via RouterAI](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/1af48d9e52795f919acd887acba0347a.png)

Расход токенов DeerFlow показывает в рабочем пространстве, если включён `token_usage.enabled: true` в `config.yaml` (по умолчанию `true`). Фактический расход всегда можно сверить в разделе [Биллинг](/settings/billing) личного кабинета RouterAI.

## Решение проблем {#reshenie-problem}

### 401 Unauthorized

Ключ не подхватился. Проверьте, что в `.env` есть строка `ROUTERAI_API_KEY=...` и что файл находится в корне репозитория (`deer-flow/.env`, не в `backend/.env`). После правки перезапустите сервис.

### 404 Not Found

Неверный `base_url`. Для RouterAI должен быть `https://routerai.ru/api/v1` — с `/v1` в конце. Без него запрос уходит на несуществующий путь.

### Модель не найдена / Provider does not exist

Имя модели не совпадает с каталогом RouterAI. Скопируйте id точно из [каталога](/models "каталога") — с префиксом провайдера, например `anthropic/claude-sonnet-5.5`, а не просто `claude-sonnet-5.5`.

### Пустой ответ инструментов

Модель не поддерживает tool calling. DeerFlow требует function calling для работы субагентов; выберите из каталога модель с поддержкой инструментов.

### После изменения config.yaml изменения не применяются

Нужен перезапуск: `Ctrl+C` и снова `make dev`, или `make docker-start` для Docker-режима. Мастер `make setup` можно запускать повторно — он предложит обновить конфиг.

## Что дальше {#chto-dalshe}

- [Каталог моделей](/models) — подберите модель под задачу
- [Аутентификация](/docs/guides/overview/authentication) — управление API-ключами
- [AionUi через RouterAI](/pages/aionui-routerai) — ещё один агентный фронтенд
- [Вайб-кодинг в Claude Code](/pages/vibe-coding-claude-code) — coding-агент CLI через RouterAI
- [Документация DeerFlow](https://github.com/bytedance/deer-flow/blob/main/docs/guide/configuration.md) — полный справочник по конфигурации
