# Codewhale через RouterAI: Rust-агент для терминала с любым Base URL (Claude, GPT, DeepSeek, GLM)

[Codewhale](https://codewhale.net) — open-source агент для терминала на Rust (лицензия MIT, репозиторий [codewhale-hq/CodeWhale](https://github.com/codewhale-hq/CodeWhale)). Он читает проект, правит файлы и запускает команды, а перед рискованными действиями спрашивает разрешение. В комплекте больше 40 встроенных провайдеров, по умолчанию агент работает с DeepSeek, а любой OpenAI-совместимый endpoint подключается как custom provider со своим Base URL.

Через RouterAI Codewhale получает Claude, GPT, DeepSeek и GLM по одному ключу: работа из России без VPN, оплата в рублях. Ниже: установка, подключение двумя способами (через `/provider` и через конфиг), выбор модели, команды `/receipts` и `/undo`, режимы подтверждений и контроль расхода токенов. Версия, на которой всё проверено: Codewhale 0.10.2. Похожие терминальные агенты: [FuXi](/pages/fuxi-routerai), [Open Interpreter](/pages/open-interpreter-routerai), [MiMoCode](/pages/vibe-coding-mimocode).

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

- Linux, macOS или Windows с терминалом.
- Git-репозиторий, в котором будет работать агент.
- Ключ RouterAI из личного кабинета на [routerai.ru](https://routerai.ru) и баланс в рублях.
- Id модели из [каталога RouterAI](/models).

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

По README доступны несколько способов, выберите один:

```bash
# скрипт установки
curl -fsSL https://codewhale.net/install.sh | sh

# через npm
npm install -g codewhale
```

Есть также пакеты для winget и сборка через `cargo`; актуальные команды смотрите в [README](https://github.com/codewhale-hq/CodeWhale). После установки доступны команда `codewhale` и короткий алиас `codew`.

Перейдите в git-репозиторий проекта и запустите агент:

```bash
cd ~/projects/invoices
codewhale
```

Без настроенного провайдера на стартовом экране будет надпись `no model connected · run /provider`, а в нижней строке `model not connected`.

![Первый запуск Codewhale в git-репозитории: версия 0.10.2, ветка master, подсказка run /provider](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/187648fe4ec55bf8e62782b2f15fcb32.png)

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

В Codewhale custom provider — это OpenAI-совместимый endpoint с тремя параметрами: Base URL, имя переменной окружения с ключом и модель. Для RouterAI они такие:

| Поле | Значение |
|---|---|
| Base URL | `https://routerai.ru/api/v1` |
| API key env | `ROUTERAI_API_KEY` (имя переменной, не сам ключ) |
| Model | `anthropic/claude-sonnet-5.5` |

Сначала положите ключ в переменную окружения в той же оболочке, из которой запускаете агент:

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

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

### Способ 1. Через /provider {#cherez-provider}

1. Запустите `codewhale` и введите `/provider` (или нажмите `F3`).
2. В окне Provider нажмите `A` (browse all). В полном списке выберите строку **Custom (OpenAI-compatible)**.
3. В форме **Custom provider** заполните поля: **Name** — `routerai`, **Base URL** — `https://routerai.ru/api/v1`, **Default model** — `anthropic/claude-sonnet-5.5`, **API key env** — `ROUTERAI_API_KEY`. Между полями переходите клавишей `Tab`.
4. Нажмите `Enter`: провайдер сохранится и сразу станет активным. Агент покажет заметку `Provider switched: deepseek → routerai`.

![Форма Custom provider в Codewhale: Name, Base URL, Default model и API key env заполнены значениями для RouterAI](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/fc3cf79bbac7e9acc56040cc44f54f52.png)

Форма подсказывает: `Store an env var name, not a raw key` — то есть в конфиг попадает имя переменной, а не сам ключ.

![Окно /provider в режиме browse all: список провайдеров, среди них Custom (OpenAI-compatible)](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/67e755c706fedad532ea51c052c3729b.png)

### Способ 2. Через конфиг {#cherez-konfig}

Форма записывает настройки в `~/.codewhale/config.toml`. То же самое можно написать руками:

```toml
provider = "routerai"

[providers.routerai]
kind = "openai-compatible"
base_url = "https://routerai.ru/api/v1"
model = "anthropic/claude-sonnet-5.5"
api_key_env = "ROUTERAI_API_KEY"
```

Таблица называется так, как вы назвали провайдера в поле **Name**, а выбирается она строкой `provider = "<имя>"` или флагом `--provider <имя>`. Параметр `kind = "openai-compatible"` задаёт протокол. В [документации конфигурации](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/CONFIGURATION.md) этот формат описан вместе с примерами для LM Studio и собственных шлюзов; для RouterAI он проверен на установке 0.10.2.

Если у вас старый конфиг с `provider = "custom"`, Codewhale переносит такой endpoint в таблицу `[providers.custom]`. Для нового подключения удобнее именованная таблица, как выше.

По умолчанию custom-таблица отправляет запросы Chat Completions на `<base_url>/chat/completions`. Это то, что нужно для RouterAI.

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

Id модели в Codewhale — это id из каталога RouterAI вместе с префиксом разработчика. Полный список и цены — на странице [/models](/models), список также отдаёт `GET https://routerai.ru/api/v1/models`. По документации Codewhale список моделей для custom provider берётся из живого `GET /v1/models`, поэтому все модели каталога доступны в переключателе `/model`.

| Задача | Id модели |
|---|---|
| Дешёвая модель на каждый день (аналог умолчания Codewhale) | `deepseek/deepseek-v4.1-flash` |
| Сбалансированный вариант для кода | `z-ai/glm-5.3` |
| Сложные правки и рефакторинг | `anthropic/claude-sonnet-5.5` |
| Модель OpenAI для больших задач | `openai/gpt-6.1-terra` |

Модель можно сменить в сессии командой `/model` или поменять строку `model` в таблице провайдера. Все четыре id присутствуют в каталоге на момент написания; прежде чем переносить id в конфиг, сверьтесь со страницей [/models](/models), потому что каталог обновляется.

## Первая сессия {#pervaya-sessiya}

Когда провайдер подключён, нижняя строка показывает `routerai · anthropic/claude-sonnet-5.5`. Дайте агенту небольшую задачу, например: «Запусти npm test и объясни одной фразой, что проверяют тесты». Перед запуском команды Codewhale покажет диалог подтверждения; нажмите `y`, чтобы разрешить один раз.

![Сессия Codewhale на демо-проекте: тесты прошли, модель anthropic/claude-sonnet-5.5 отвечает через routerai](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/8720e8ed6da60c73619d3bbb63bd551d.png)

## Команды /receipts и /undo, режимы подтверждений {#komandy-i-rezhimy}

Что агент сделал за сессию, видно командой `/receipts`: она перечисляет выполненные команды, изменённые файлы и сбои, и отмечает, какие из них вы одобрили. После выхода то же самое покажет `codewhale receipts --last`. Команда `/undo` откатывает ваш последний запрос целиком, включая все файлы, которые он изменил.

![Команда /receipts: сессия, модель, выполненная команда и пометка approved by you](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/20a9e1892b9bc1442dba052f5775a25a.png)

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

| Переключатель | Как менять | Варианты |
|---|---|---|
| Режим | `Tab` при пустом вводе или `/mode` | **Plan** только читает и ищет, **Work** правит файлы и запускает команды, **Operate** идёт к цели, пока не проверит результат или не потребует вашего ввода |
| Разрешения | `Shift+Tab` | **Ask** применяет правки файлов в репозитории без вопросов и спрашивает перед командами оболочки, не являющимися только чтением; **Auto-Review** отдаёт рутинные вызовы правилам и модели-ревьюеру; **Full Access** не спрашивает вообще и отключает песочницу |

В диалоге подтверждения команды: `1` / `y` — разрешить один раз, `2` / `a` — разрешить на эту беседу, `3` / `d` / `n` — отказать, `Esc` — остановить ход. Для первых запусков на новой модели оставьте **Ask**, а **Full Access** включайте только в изолированной среде.

## Расход токенов и как его ограничить {#raskhod-tokenov}

В нижней строке Codewhale показывает заполнение контекста (`context 5%`) и стоимость сессии, а `/cost` выводит подробности. На custom provider стоимость отображается как `cost: unknown (billing basis unknown)`, так как цены RouterAI агенту неизвестны. Реальные списания смотрите в личном кабинете RouterAI.

Что снижает расход:

- Дешёвая модель для рутины (`deepseek/deepseek-v4.1-flash`), дорогая — для сложных правок. Цены на токены указаны в [каталоге](/models).
- Режим **Plan** для разведки по проекту: он ничего не меняет и не гоняет команды.
- Автосжатие контекста: порог задаёт `auto_compact_threshold_percent` в `settings.toml` (по умолчанию 80, допустимо от 10 до 100), а `/compact` и `Ctrl+L` сжимают историю вручную. Если выставить `auto_compact` в off, автосжатие отключится.
- Ограничение длины ответа: переменная окружения `CODEWHALE_MAX_OUTPUT_TOKENS`. Без неё Codewhale запрашивает до 65536 токенов на ответ; ключа `max_output_tokens` в `config.toml` нет.
- Новая тема — новая сессия: длинная история при каждом запросе уходит модели заново.

## Типичные ошибки {#oshibki}

**Запросы уходят на неверный адрес.** В Base URL должен быть только `https://routerai.ru/api/v1`. Не дописывайте `/chat/completions`: Codewhale добавляет путь сам. Если у таблицы стоит `wire = "responses"`, он обращается к `<base_url>/responses`.

**Ключ не найден.** Форма `/provider` хранит имя переменной, а не ключ. Если `ROUTERAI_API_KEY` не задана в оболочке, из которой вы запустили `codewhale`, или пуста, для custom provider это громкая ошибка, а не тихий возврат к другому ключу. Выполните `export` в той же оболочке или добавьте строку в `~/.bashrc`, затем перезапустите агент.

**Ключ в repo-local конфиге игнорируется.** Файл `.codewhale/config.toml` внутри репозитория может задавать только безопасные настройки. Если в нём есть `api_key`, `base_url`, `providers` или `provider`, Codewhale игнорирует эти ключи и берёт настройки из `~/.codewhale/config.toml`. Подключение к RouterAI храните только в пользовательском конфиге, чтобы не отправить ключ в репозиторий.

**Модель не найдена.** Проверьте id по [каталогу](/models): нужен полный id вместе с префиксом (`anthropic/…`, `openai/…`, `deepseek/…`, `z-ai/…`).

**Агент остался на DeepSeek.** После сохранения формы в строке состояния должно быть `routerai · …`. Если там `deepseek`, выберите провайдера через `/provider` или добавьте в конфиг строку `provider = "routerai"`.

Другие инструменты, которые подключаются к RouterAI, собраны на странице [интеграций](/docs/integrations).