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

Codewhale — open-source агент для терминала на Rust (лицензия MIT, репозиторий 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, Open Interpreter, MiMoCode.

Требования

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

Установка

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

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

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

Есть также пакеты для winget и сборка через cargo; актуальные команды смотрите в README. После установки доступны команда codewhale и короткий алиас codew.

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

cd ~/projects/invoices
codewhale

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

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

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

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

export ROUTERAI_API_KEY=sk-xxxxxxxxxxxxxxxx

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

Способ 1. Через /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.

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

Способ 2. Через конфиг

Форма записывает настройки в ~/.codewhale/config.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" задаёт протокол. В документации конфигурации этот формат описан вместе с примерами для LM Studio и собственных шлюзов; для RouterAI он проверен на установке 0.10.2.

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

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

Выбор модели

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

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

Первая сессия

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

Команды /receipts и /undo, режимы подтверждений

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

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

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

Расход токенов и как его ограничить

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

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

• Дешёвая модель для рутины (deepseek/deepseek-v4.1-flash), дорогая — для сложных правок. Цены на токены указаны в каталоге.
• Режим 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 нет.
• Новая тема — новая сессия: длинная история при каждом запросе уходит модели заново.

Типичные ошибки

Запросы уходят на неверный адрес. В 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 по каталогу: нужен полный id вместе с префиксом (anthropic/…, openai/…, deepseek/…, z-ai/…).

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

Другие инструменты, которые подключаются к RouterAI, собраны на странице интеграций.