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 и другие модели из каталога: работа из России без VPN, оплата в рублях.

Требования

macOS, Windows или Linux. Для настольного приложения на Linux нужны GTK 3 и WebKitGTK 4.1; без них ставится терминальная версия.
Ключ RouterAI: создайте его в личном кабинете и пополните баланс.
Агенты, которые вы хотите подключить: magpie показывает только установленные на этом компьютере. См. Claude Code и Codex.

Установка

Скрипт установки ставит приложение (на Linux без рабочего стола — терминальную версию):

curl -fsSL https://usemagpie.ai/install.sh | sh

Другие способы: готовый установщик на usemagpie.ai, go install github.com/yetone/magpie@latest или образ ghcr.io/yetone/magpie для сервера и NAS. Проверьте версию:

magpie --version

Установленный magpie обновляется сам. Всё, что дальше делается командами, доступно и в окне приложения, и в браузере (magpie web), и в терминальном интерфейсе (magpie tui).

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

RouterAI подключается как кастомный провайдер: ему нужны имя и адрес OpenAI-совместимого API. Ключ удобно передать из переменной окружения, тогда он не попадает в историю команд.

Через терминал

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 модели из списка, и среди них может не оказаться нужных. Поэтому выберите модели явно:

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

Чтобы magpie мог обращаться к моделям и по Anthropic Messages API, добавьте второй адрес: anthropic=https://routerai.ru/api. Идентификаторы моделей всегда берите из каталога RouterAI, с префиксом поставщика.

Через приложение или браузер

Если рабочего стола нет, откройте интерфейс в браузере: magpie web. Команда печатает ссылку с ключом доступа к странице; держите порт на локальном адресе или за VPN, потому что страница показывает ключи.

Откройте Providers → Add provider и внизу списка нажмите Custom provider.
В поле Name введите RouterAI.
В Base URL на вкладке OpenAI compatible вставьте https://routerai.ru/api/v1.
В поле API key вставьте ключ RouterAI. magpie хранит его в ~/.config/magpie/providers.json.
В поле Models перечислите id моделей через запятую или нажмите Fetch models и отметьте нужные, затем нажмите Add.

Форма Custom provider в magpie: имя RouterAI, адрес https://routerai.ru/api/v1, ключ-заглушка и список моделей

Подключение агентов

Каждая модель в magpie называется провайдер/модель, поэтому модель RouterAI выглядит как routerai/anthropic/claude-sonnet-5.5. Шлюз должен работать: его запускает приложение, а без него — команда magpie serve.

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, переключённые на них

Для программ, у которых есть только настройка адреса, шлюз тоже подходит: 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, контекст и цены в рублях смотрите в каталоге.

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

Проверьте провайдера, затем каждого агента коротким запросом:

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

Ограничения

Шлюз работает, пока запущен 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 +<id модели>.
Ошибка «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 — id, контекст и цены в рублях.
Claude Code через RouterAI и Codex через RouterAI — подключение без шлюза.
CC Switch через RouterAI — похожая задача: один профиль для Claude Code и Codex.
Документация magpie и справочник команд.

Инструкция проверена на magpie 0.1.3410, Claude Code 2.1.319 и Codex CLI 0.167.0.