# magpie через RouterAI: один локальный шлюз для Claude Code, Codex, Zed и VS Code magpie — локальный шлюз между ИИ-агентами и провайдерами моделей (автор — yetone, лицензия MIT, приложение для macOS, Windows и Linux, есть терминальная версия и образ Docker). Каждый агент хранит модель в своём файле, в своём формате и со своими ключами. magpie собирает всё в один список: вы добавляете провайдера один раз, а потом выбираете для Claude Code, Codex, Zed или VS Code любую модель из этого списка. Агенты обращаются не к провайдеру, а к шлюзу на `127.0.0.1:3425`, который понимает OpenAI Chat, OpenAI Responses, Anthropic Messages и Gemini и переводит запросы между ними. У RouterAI и так один ключ на все модели, но шлюз добавляет удобства поверх него: модель меняется сразу во всех агентах одной командой или из меню, настройки хранятся в одном месте, а `magpie usage` показывает токены по агентам и моделям. Через RouterAI это Claude, GPT, Gemini, DeepSeek и другие модели из [каталога](/models): работа из России без VPN, оплата в рублях. ## Требования * macOS, Windows или Linux. Для настольного приложения на Linux нужны GTK 3 и WebKitGTK 4.1; без них ставится терминальная версия. * Ключ RouterAI: [создайте его в личном кабинете](https://routerai.ru/settings/keys) и пополните баланс. * Агенты, которые вы хотите подключить: magpie показывает только установленные на этом компьютере. См. [Claude Code](/pages/vibe-coding-claude-code) и [Codex](/pages/vibe-coding-codex). ## Установка Скрипт установки ставит приложение (на Linux без рабочего стола — терминальную версию): ```bash curl -fsSL https://usemagpie.ai/install.sh | sh ``` Другие способы: готовый установщик на [usemagpie.ai](https://usemagpie.ai), `go install github.com/yetone/magpie@latest` или образ `ghcr.io/yetone/magpie` для сервера и NAS. Проверьте версию: ```bash magpie --version ``` Установленный magpie обновляется сам. Всё, что дальше делается командами, доступно и в окне приложения, и в браузере (`magpie web`), и в терминальном интерфейсе (`magpie tui`). ## Подключение к RouterAI RouterAI подключается как кастомный провайдер: ему нужны имя и адрес OpenAI-совместимого API. Ключ удобно передать из переменной окружения, тогда он не попадает в историю команд. ### Через терминал ```bash export ROUTERAI_API_KEY="sk-xxxxxxxxxxxxxxxx" magpie provider add RouterAI url=https://routerai.ru/api/v1 key="$ROUTERAI_API_KEY" ``` magpie запросит список моделей RouterAI и создаст провайдера с id `routerai` (id берётся из имени). Если не указать `models=`, агентам открываются только первые 24 модели из списка, и среди них может не оказаться нужных. Поэтому выберите модели явно: ```bash magpie provider models routerai anthropic/claude-sonnet-5.5 anthropic/claude-haiku-5.5 openai/gpt-5.5 deepseek/deepseek-v4-flash google/gemini-3.1-pro-preview magpie provider test routerai ``` Список в команде заменяет текущий целиком; добавить одну модель и оставить остальные можно так: `magpie provider models routerai +openai/gpt-5.4-mini`. Команда `provider test` отправляет один короткий запрос и показывает задержку. ![Терминал: провайдер RouterAI добавлен командой magpie provider add, выбраны модели, провайдер проверен командой test](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/1cfc8f96e4df81ce84cbdb81889e0f43.png) Чтобы magpie мог обращаться к моделям и по Anthropic Messages API, добавьте второй адрес: `anthropic=https://routerai.ru/api`. Идентификаторы моделей всегда берите из [каталога RouterAI](/models), с префиксом поставщика. ### Через приложение или браузер Если рабочего стола нет, откройте интерфейс в браузере: `magpie web`. Команда печатает ссылку с ключом доступа к странице; держите порт на локальном адресе или за VPN, потому что страница показывает ключи. 1. Откройте **Providers → Add provider** и внизу списка нажмите **Custom provider**. 2. В поле **Name** введите `RouterAI`. 3. В **Base URL** на вкладке **OpenAI compatible** вставьте `https://routerai.ru/api/v1`. 4. В поле **API key** вставьте ключ RouterAI. magpie хранит его в `~/.config/magpie/providers.json`. 5. В поле **Models** перечислите id моделей через запятую или нажмите **Fetch models** и отметьте нужные, затем нажмите **Add**. ![Форма Custom provider в magpie: имя RouterAI, адрес https://routerai.ru/api/v1, ключ-заглушка и список моделей](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/c3425a5e31d8fe662e0808ba11ed831f.png) ## Подключение агентов Каждая модель в magpie называется `провайдер/модель`, поэтому модель RouterAI выглядит как `routerai/anthropic/claude-sonnet-5.5`. Шлюз должен работать: его запускает приложение, а без него — команда `magpie serve`. ```bash magpie claude routerai/anthropic/claude-sonnet-5.5 magpie codex routerai/openai/gpt-5.5 magpie ls ``` * **Claude Code.** magpie записывает адрес шлюза и модели в блок `env` файла `~/.claude/settings.json`; к основной модели добавляется суффикс `[1m]`, а слоты haiku и sonnet заполняются моделями из списка. Пока Claude Code работает через magpie, он не входит в claude.ai: лимиты подписки в `/usage` и коннекторы недоступны. * **Codex.** magpie добавляет в `~/.codex/config.toml` провайдера `magpie` и каталог моделей, и они появляются в списке Codex. Список читается при запуске, поэтому после смены модели перезапустите Codex. * **Zed.** `magpie zed <модель>` добавляет OpenAI-совместимого провайдера `magpie` в `~/.config/zed/settings.json`, и модели появляются в выборе Zed. * **VS Code.** `magpie vscode <модель>` добавляет группу Custom Endpoint `magpie` в настройки чата VS Code (нужна версия 1.122 или новее; вход в Copilot не требуется). Выбрать модель можно и мышью: страница **Agents** в приложении (в терминале — `magpie tui`). Вернуть агента к его прежним настройкам: `magpie claude default`, `magpie codex default`. ![Список моделей RouterAI в magpie и агенты Claude Code и Codex, переключённые на них](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/6fd65c7afa296da6ba3b34b1abc5ec84.png) Для программ, у которых есть только настройка адреса, шлюз тоже подходит: `OPENAI_BASE_URL=http://127.0.0.1:3425/v1` с `OPENAI_API_KEY=magpie` или `ANTHROPIC_BASE_URL=http://127.0.0.1:3425` с `ANTHROPIC_API_KEY=magpie`. Локально шлюз принимает любой ключ, настоящий ключ RouterAI лежит только в magpie. ## Выбор модели | Модель | Для чего | | ------ | -------- | | `anthropic/claude-sonnet-5.5` | Основная модель для кода и агентных задач, контекст 1 000 000 токенов | | `anthropic/claude-haiku-5.5` | Быстрые правки и мелкие вопросы, дешёвая; хорошо подходит на слот haiku в Claude Code | | `openai/gpt-5.5` | Основная модель для Codex, контекст 1 050 000 | | `deepseek/deepseek-v4-flash` | Дешёвые массовые задачи, контекст 1 048 576 | | `google/gemini-3.1-pro-preview` | Большие репозитории и длинные документы, контекст 1 048 576 | Актуальные id, контекст и цены в рублях смотрите в [каталоге](/models). ## Проверка подключения Проверьте провайдера, затем каждого агента коротким запросом: ```bash magpie provider test routerai claude -p "Run npm test, answer in one line" --allowedTools Bash codex exec "Run npm test, answer in one line" magpie usage today ``` Оба агента отвечают через один шлюз, а `magpie usage today` показывает вызовы по агентам и моделям: Claude Code на `routerai/anthropic/claude-sonnet-5.5`, Codex на `routerai/openai/gpt-5.5`. ![Claude Code и Codex отвечают на один и тот же запрос через шлюз magpie и RouterAI](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/9e53a0ba975b144a6897d80b30122390.png) ## Ограничения * Шлюз работает, пока запущен magpie (приложение, `magpie serve` или контейнер). Если его остановить, агенты, переключённые на magpie, не получат ответа. * Агентам доступны только модели, которые вы выбрали в провайдере. Без явного списка magpie открывает первые 24 из более чем 400. * Скрытие секретов (маскирование ключей, паролей и email в запросах) в magpie по умолчанию выключено. Включается в **Settings → Privacy**. Модель при этом видит метки вместо значений. * В Docker шлюз принимает любой ключ только изнутри контейнера. Для запросов с хоста и из сети нужен ключ шлюза (**Gateway → Gateway keys**). ## Решение проблем * **`magpie: no supported agents found on this machine`.** magpie не нашёл установленных агентов. Установите Claude Code или Codex и повторите `magpie ls`. * **Нужной модели нет в списке агента.** Она не выбрана в провайдере: добавьте её командой `magpie provider models routerai +`. * **Ошибка «model not found».** Id указан без префикса поставщика. Нужно `anthropic/claude-sonnet-5.5`, а не `claude-sonnet-5.5`; для агента — `routerai/anthropic/claude-sonnet-5.5`. * **`provider test` или агент отвечает 401.** Неверный ключ или пустой баланс: проверьте их в личном кабинете RouterAI, замените ключ командой `magpie provider key routerai sk-xxxxxxxxxxxxxxxx`. * **Агент пишет, что не может подключиться к `127.0.0.1:3425`.** Шлюз не запущен: откройте приложение или выполните `magpie serve`. * **Codex показывает старые модели.** Он читает список при запуске: закройте и откройте Codex заново. ## Что дальше * [Каталог моделей RouterAI](/models) — id, контекст и цены в рублях. * [Claude Code через RouterAI](/pages/vibe-coding-claude-code) и [Codex через RouterAI](/pages/vibe-coding-codex) — подключение без шлюза. * [CC Switch через RouterAI](/pages/cc-switch-routerai) — похожая задача: один профиль для Claude Code и Codex. * [Документация magpie](https://usemagpie.ai/docs/start) и [справочник команд](https://github.com/yetone/magpie/blob/main/docs/reference.md). Инструкция проверена на magpie 0.1.3410, Claude Code 2.1.319 и Codex CLI 0.167.0.