Пошаговое руководство: подключаем всех агентов одним ключом и объединяем доступ к API через шлюз на базе magpie с открытым исходным кодом (на примере Claude Code, Codex, Pi и Hermes)

Примечание автора: это пошаговая инструкция, которую можно повторить от начала до конца. Выполнив её, вы получите конфигурацию по принципу «один ключ, один адрес шлюза — подключайте столько агентов, сколько установлено». В дальнейшем, чтобы сменить модель или обновить ключ, достаточно будет внести изменения в одном месте.

Перед началом разберитесь, что предстоит сделать

• Цель: все программные агенты на вашем компьютере будут использовать один API-ключ и один адрес вышестоящего сервера. В статье мы рассмотрим Claude Code, Codex, Pi и Hermes — подключите те, которые у вас установлены.
• Время: около 30 минут (не считая регистрации и загрузки файлов).
• Что понадобится: токен APIYI (подойдёт и любой прокси-сервис API с совместимостью с OpenAI или Anthropic, а также официальный ключ), компьютер с доступом к командной строке и как минимум один установленный агент.
• Сложность: ★★☆☆☆. Достаточно уметь щёлкать мышью и копировать текст — вводить команды не придётся.

План руководства

За три минуты: что именно делает magpie

Если вам нужно только «сделать по инструкции», этот раздел можно пропустить. Но потратьте три минуты на чтение — дальше будет проще разбираться с проблемами.

Требования разных Agent-инструментов к моделям сильно различаются. Если настраивать всё вручную, для каждого инструмента придётся поддерживать отдельный набор параметров. Для примера возьмём четыре самых распространённых:

magpie (репозиторий github.com/yetone/magpie, слоган — “Every agent’s model. One place.”) решает именно эту задачу: в одном окне можно управлять тем, какой Agent использует какую модель и какой Key читает, а magpie сам вносит изменения в родные настройки инструментов.

Коротко о разделении обязанностей:

• magpie отвечает за распределение: решает, какую модель использовать Claude Code и Codex
• Шлюз отвечает за протоколы: преобразует запросы в форматах Anthropic, OpenAI и Gemini и перенаправляет их настоящему поставщику модели

Поэтому лучше, чтобы ваш шлюз поддерживал несколько протоколов

Идеальный вариант — «magpie отвечает за распределение, шлюз — за протоколы». Если шлюз поддерживает только формат, совместимый с OpenAI, для Claude Code придётся дополнительно добавлять слой преобразования протокола. Цепочка станет длиннее, а форматы вызова инструментов будут чаще расходиться.

Решение APIYI — один токен для работы с тремя основными протоколами: для вызовов можно использовать один и тот же Key в форматах OpenAI, Anthropic и Gemini (точный список поддерживаемых возможностей смотрите в консоли). Тогда для magpie достаточно настроить один upstream, и все Agent-инструменты подключатся к нему напрямую — не придётся отдельно поддерживать аккаунты и счета у разных поставщиков.

Какой из трёх способов выбрать

Ручная настройка — самый прямой путь. Но чем больше инструментов, тем больше файлов, в которых разбросаны Key, и тем дороже обходятся их ротация и поиск ошибок. Скрипт с переменными окружения не требует дополнительных зависимостей и умещается в несколько десятков строк, но не позволяет назначать разные модели разным Agent. Если нужно, например, чтобы «Claude Code работал с Claude, Codex — с GPT, а Hermes — с недорогой моделью», удобнее всего централизованное решение вроде magpie.

Шаг 1. Получите API-ключ и скопируйте его

1.1 Создайте токен в консоли APIYI

Создайте токен в консоли APIYI (apiyi.com) и скопируйте его.

На этом шаге ничего вводить в командную строку не нужно. За всё время настройки этот API-ключ понадобится только один раз: вставьте его в панель «Поставщики» в magpie (шаг 3). После этого magpie сам создаст файлы конфигурации для каждого агента. Вам не придётся задавать переменные окружения через export или менять config.toml, settings.json и другие файлы.

🚀 Ещё нет токена? Зарегистрируйтесь на APIYI apiyi.com и получите тестовый баланс. С одним токеном можно проверить несколько инструментов, которыми вы пользуетесь постоянно, а потом решить, какие модели оставить на будущее.

1.2 Сохраните под рукой два адреса

На шаге 3 нужно будет выбрать, какой адрес указать:

✅ Проверка шага: токен скопирован, и вы знаете, какой адрес указать на шаге 3.

Шаг 2. Установите magpie и познакомьтесь с двумя страницами

Исходный код magpie, способ установки и формат конфигурации описаны в README официального репозитория (github.com/yetone/magpie). Проект развивается довольно быстро, поэтому команды установки и названия полей могут меняться с версиями. А вот скриншоты интерфейса и порядок действий ниже останутся актуальными надолго.

После установки и запуска вы увидите окно с навигацией слева. В этом руководстве понадобятся только две страницы: Agent (какую модель использует каждый агент) и Поставщики (где хранится API-ключ).

① Пункт Agent в боковом меню — это общая панель управления всеми агентами:

Рис. 1 · Страница Agent: в каждой строке — отдельный инструмент. Переключатель справа включает его интеграцию с magpie, а выпадающий список рядом позволяет выбрать модель

На этой странице нужно найти три элемента:

② Пункт Поставщики в боковом меню — здесь добавляется API-ключ провайдера. Подробнее об этом — в следующем разделе.

Если вы хотите сначала разобраться, как устроены файлы конфигурации magpie, загляните в README официального репозитория и посмотрите на структуру providers и agents. Вкратце, нужно дать провайдеру имя, указать base_url и API-ключ, а затем назначить модель каждому агенту. Но для повседневной настройки достаточно нажимать кнопки в окне: magpie сам создаст файлы конфигурации для инструментов, и это надёжнее, чем вручную править YAML.

✅ Проверка шага: окно открывается, а в боковом меню видны пункты Agent и «Поставщики».

Шаг 3. Добавьте свой ключ в раздел «Поставщики»

3.1 Откройте страницу поставщиков

Нажмите «Поставщики» в меню слева (красная рамка ① на рисунке 2), а затем — «+ Добавить поставщика» в правом верхнем углу страницы (красная рамка ②):

Рис. 2 · Страница поставщиков: откройте раздел «Поставщики» в левом меню. Кнопка «+ Добавить поставщика» в правом верхнем углу — единственный способ добавить поставщика

Уже добавленные поставщики отображаются здесь в виде карточек. Во второй строке карточки указаны адрес и количество доступных моделей (например, api.apiyi.com · 11 моделей). Чтобы проверить, работает ли подключение, посмотрите, есть ли в этой строке число.

3.2 Какой тип поставщика выбрать

После нажатия «+ Добавить поставщика» откроется панель с несколькими группами вариантов (рис. 3):

Рис. 3 · Панель добавления поставщика: пять типов источников — подписка, поставщик, сервис-прокси API, локальная машина и magpie на другом компьютере

Группы на панели соответствуют пяти типам ключей:

Если вы используете APIYI, его совместимая с OpenAI конечная точка относится к стандартному типу сервиса-прокси API. Выберите соответствующий вариант в группе «Сервис-прокси API». Если же у вас собственный ключ, совместимый с OpenAI или Anthropic, нажмите внизу «+ Пользовательский поставщик» (красная рамка на рис. 3) и укажите адрес и ключ. Для адреса используйте https://api.apiyi.com/v1 (для запросов в нативном формате Anthropic — https://api.apiyi.com).

Ниже показана полная панель настроек поставщика. Вас интересуют всего четыре строки:

Рис. 4 · Страница настройки поставщика APIYI: сначала выберите протокол и укажите адрес в поле Base URL, добавьте ключи в Accounts и отметьте модели, доступные агентам, в разделе Models**

На этом рисунке как раз показано, как работает описанная выше схема «один токен — несколько протоколов». Адрес везде один — https://api.apiyi.com: выберите Anthropic Compatible, чтобы Claude Code использовал нативную конечную точку; выберите OpenAI Compatible, чтобы Codex, Pi и Hermes использовали конечную точку /v1; для Gemini работает тот же принцип. Не нужно настраивать трёх поставщиков и заводить три ключа.

Сохраните настройки и вернитесь к списку поставщиков. Убедитесь, что во второй строке карточки указано количество моделей, а переключатель включён. Надпись · N моделей означает, что ключ и адрес работают — это и есть проверка подключения, запускать отдельные команды не нужно.

✅ Проверка шага: в списке поставщиков появилась ваша карточка с надписью вроде · N моделей, а не «Не настроено».

Шаг 4. Подключите установленные агенты

Вернитесь на страницу «Агент» и выполните одни и те же три действия для каждого установленного инструмента. Здесь перечислены все агенты, которые magpie умеет подключать. Список постоянно пополняется; для неустановленных инструментов появится пометка «CLI не найден». Подключите каждый установленный инструмент. В таблице ниже для примера показаны четыре самых распространённых:

1. Включите переключатель справа (он должен сменить серый цвет на яркий).
2. Выберите модель в списке справа от переключателя (если не выбирать, будет использоваться модель по умолчанию; выбранная модель будет записана в конфигурацию самого инструмента).
3. Перезапустите инструмент, следуя подсказке (для Codex, Claude Code, Pi и Hermes обычно нужно перезапустить процесс, чтобы он загрузил новую конфигурацию).

Рис. 5 · Откройте список моделей. Первый пункт — «По умолчанию»: агент использует собственную модель, минуя magpie. У остальных моделей есть пометка «Через magpie». Выберите нужную — и агент будет обращаться к этой модели у поставщика

Вот несколько распространённых статусов. Если вы видите их, значит, всё идёт как надо:

• Подключён: конфигурация сохранена и вступит в силу после перезапуска инструмента
• Не подключён · использует собственные настройки XXX: переключатель выключен или модель не выбрана
• Можно использовать только собственные модели XXX, подключение через magpie недоступно: этот инструмент (например, Cursor) по устройству поддерживает только собственные модели. Это ограничение, а не ошибка конфигурации
• CLI не найден: инструмент не установлен или его нет в PATH. Установите его либо добавьте путь в PATH, а затем попробуйте снова

💡 Чтобы назначить разным агентам разные модели — например, Claude для Claude Code, GPT для Codex и недорогую модель для Hermes, — выберите их здесь отдельно. Это одно из главных преимуществ magpie перед скриптами, которые настраивают переменные среды.

✅ Проверка шага: переключатели всех установленных инструментов включены, а в строках состояния больше не отображается «Не подключён».

Шаг 5. Проверьте каждый агент на простом запросе

Настроить всё — ещё не значит закончить. Убедитесь, что каждый агент действительно работает: отправьте ему самое простое задание.

Чтобы проверить, что запросы действительно проходят через шлюз, проще всего открыть консоль APIYI и посмотреть расход или журнал этого токена. Если появились новые записи о вызовах, значит запросы всех агентов поступают на один и тот же API-ключ.

✅ Проверка пройдена: каждый агент отвечает, а в консоли видны соответствующие записи о вызовах.

Дополнение: какую модель выбрать, если не уверены

💡 Попробуйте выполнить одну и ту же задачу в разных агентах и с разными моделями. С единым API-ключом для переключения достаточно поменять имя модели, а сравнить затраты будет легко.

Шаг 6 (необязательный): какие именно настройки magpie меняет за вас

Этот раздел не нужен, чтобы всё заработало, и его можно пропустить. В обычной работе эти файлы трогать не придётся: когда на шаге 4 вы включили переключатель, magpie уже записал все настройки, которые описаны ниже. Они приведены здесь по двум причинам: чтобы вы знали, где искать проблему, и могли вручную скопировать настройки, если однажды решите отказаться от magpie.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Оригинальный эндпоинт Anthropic
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Необязательно: указать модель по умолчанию (сверьтесь со списком моделей в консоли)
# export ANTHROPIC_MODEL="<название модели Claude>"
claude

Можно также добавить эти настройки в поле env файла ~/.claude/settings.json. Тогда они не будут зависеть от текущего сеанса терминала.

Codex: секция провайдера в ~/.codex/config.toml

# ~/.codex/config.toml
model = "<название модели серии GPT>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # Эндпоинт, совместимый с OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Если выбранная модель не поддерживает Responses, замените на "chat"

wire_api — здесь чаще всего ошибаются: новые версии Codex по умолчанию используют протокол Responses. Если для этой модели на стороне шлюза доступен только Chat Completions, нужно указать chat.

Pi и Hermes: настройка собственного провайдера, совместимого с OpenAI

Принцип тот же: укажите https://api.apiyi.com/v1 в base_url, а в качестве ключа используйте переменную APIYI_API_KEY. Структура настроек зависит от версии — сверяйтесь с официальной документацией соответствующего инструмента:

// Pi: укажите провайдера в настройках пользовательской модели (структура зависит от официальной документации Pi)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<название модели>" }]
    }
  }
}

# Hermes: запустите hermes model и выберите пользовательский эндпоинт, совместимый с OpenAI,
# затем введите данные ниже по подсказкам (или добавьте их в файл .env / config в каталоге настроек Hermes)
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <название модели>

#!/usr/bin/env bash
# agents-env.sh — запасной вариант без magpie: один ключ для всех агентов
# Использование: source agents-env.sh
: "${APIYI_API_KEY:?Сначала выполните export APIYI_API_KEY}"

# Claude Code (протокол Anthropic)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Общие переменные для Codex, Pi, Hermes и других инструментов, совместимых с OpenAI
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Проверка соединения
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Все агенты используют один и тот же шлюз"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-ваш-токен" | head -c 300

Если что-то пошло не так: четыре частые ошибки

Всегда проверяйте настройки снизу вверх: сначала убедитесь, что шлюз и токен работают (на карточке поставщика отображается · N моделей), затем проверьте настройки самого агента и только после этого — слой сопоставления magpie. Так вы за три шага поймёте, где проблема: на стороне вышестоящего сервиса, в самом инструменте или в общей конфигурации.

Часто задаваемые вопросы

Краткая памятка на пять минут

• Разделение задач: magpie управляет сопоставлением моделей, шлюз пересылает запросы в нужном формате — каждый отвечает за своё.
• Один ключ: выберите сервис-прокси API с поддержкой нескольких протоколов — все агенты будут использовать один API-ключ, а счёт будет один.
• Порядок настройки: создайте ключ в панели управления → вставьте его в раздел «Провайдеры» → включите нужные агенты → проверьте каждый по очереди. Всё можно сделать в интерфейсе, без командной строки.
• Порядок диагностики: шлюз → нативные настройки агента → слой сопоставления magpie. Проверяйте снизу вверх.
• Главное для Claude Code: используйте ANTHROPIC_AUTH_TOKEN, а в base_url не добавляйте /v1.
• Главное для Codex: значение wire_api должно соответствовать протоколу, который поддерживает модель.
• Запасной вариант: скрипт с переменными окружения (agents-env.sh) тоже позволит всем агентам использовать один API-ключ.

Если вы работаете с тремя и более агентами, стоит потратить полчаса и настроить эту схему. В дальнейшем для смены модели или ротации ключа достаточно будет внести одно изменение. Для начала можно получить тестовый баланс через APIYI на apiyi.com, проверить несколько постоянно используемых инструментов, а затем подобрать модели для каждого агента под конкретные задачи.

Дополнительные материалы

• 📘 Поддерживает ли Workbuddy вызовы в нативном формате Claude? 3 основные причины и проверка 6 типов ошибок content: Если хотите разобраться, чем нативный формат Anthropic отличается от совместимого с OpenAI, загляните сюда. Здесь же объясняется, почему на шаге 2 этой статьи «Claude Code должен использовать нативный эндпоинт».
• 📊 claude-sonnet-5-5 и claude-opus-5-5: Opus быстрее, а Sonnet теперь просто дешевле? 6 наборов данных о том, как выбрать модели для корпоративных Agent с длинным контекстом: Прочитайте эту статью, прежде чем на шаге 4 распределять модели между Agent. Так вы решите, кому назначить Opus, а кому — более дешёвую модель.
• ⚠️ Какова параллельность gemini-4-argon в AI Studio? 5 причин частых ошибок 429 и 6 шагов для их устранения: Если несколько Agent одновременно обращаются с одним API-ключом и упираются в ограничение частоты запросов, пройдите эти 6 шагов.
• 🧭 Ошибка OpenAI «model not found»? GPT-5.5 отключили в ChatGPT 14 октября: проверка в 5 шагов и альтернативы: Если на шаге 5 при проверке появляется сообщение «модель не найдена», сначала убедитесь, что это имя модели ещё действительно.

📚 Справочные материалы

1. GitHub — magpie: официальный репозиторий проекта
2. Ссылка: github.com/yetone/magpie
3. Примечание: инструкции по установке, формат конфигурации и обновления версий смотрите в README.
4. Официальная документация Claude Code: переменные окружения и настройки
5. Ссылка: docs.anthropic.com/en/docs/claude-code
6. Примечание: официальное описание переменных, таких как ANTHROPIC_BASE_URL.
7. Репозиторий OpenAI Codex CLI: настройки config.toml и model_providers
8. Ссылка: github.com/openai/codex
9. Примечание: описание пользовательских провайдеров и параметра wire_api.
10. Центр документации APIYI: эндпоинты разных протоколов и список моделей
11. Ссылка: docs.apiyi.com
12. Примечание: инструкции по подключению к эндпоинтам протоколов OpenAI, Anthropic и других.

Автор: техническая команда APIYI
Обсуждение технических вопросов: делитесь опытом настройки magpie в комментариях. Больше материалов по подключению — в центре документации APIYI: docs.apiyi.com