Agent2API: как поднять локальный шлюз и подключить Claude Code, Codex и другие клиенты

01Что такое Agent2API и зачем он нужен

Agent2API — это приложение на Rust, которое поднимает локальный HTTP-шлюз (по умолчанию порт 3065) и даёт единый API для моделей. Клиент — Claude Code, Codex, Cline, любой SDK — обращается к одному адресу, а шлюз решает, в какой аккаунт провайдера отправить запрос, какую модель подставить и что делать при ошибке. Формат запросов совместим с OpenAI и Anthropic, поэтому перенастройка клиента сводится к замене base_url.

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

02Что шлюз умеет и чем отличается от альтернатив

Функционально Agent2API — это не только прокси. Внутри есть маршрутизация с приоритетами аккаунтов, балансировка, привязка сессии (session affinity) и автоматический переход на резервный аккаунт при ошибке. Отдельно ведутся отчёты: объём запросов, доля успешных, расход токенов, попадание в кэш и тепловая карта активности за год. Для отладки это полезнее, чем логи клиента, потому что видно картину по всем инструментам сразу.

• Единый каталог моделей — маппинг «имя модели у клиента → модель у провайдера».
• Приоритет и отказоустойчивость — при лимите или ошибке запрос уходит на следующий аккаунт.
• Ключи шлюза — отдельные ключи с ограничением области; без ключа /v1 не обслуживает запросы.
• Прокси для выходов — выбор пула прокси на уровне аккаунта.
• Фоновое обслуживание — обновление каталога моделей, поддержание сессий, проверки входа по расписанию провайдера.
• Мобильная панель — веб-интерфейс адаптирован, ставится как PWA.

03Установка: Docker, сервер или десктоп

Выбор формы зависит от того, где вы работаете. На машине с графикой проще десктопное приложение: шлюз живёт внутри процесса, окно сворачивается в трей, есть импорт логинов локальных клиентов. На сервере без графики — пакет сервера, он регистрируется как служба и не требует WebView. Если Docker уже есть — один контейнер.

docker run -d --name agent2api --restart unless-stopped \
  -p 3065:3065 -v ./data:/data aimodcc/agent2api:latest

curl http://127.0.0.1:3065/health

# панель: http://127.0.0.1:3065/
# Gateway Keys -> создать ключ -> скопировать

# Linux-сервер: установка службой systemd
tar -xzf agent2api-server-linux-amd64.tar.gz
cd agent2api-server-linux-amd64
sudo bash install.sh

systemctl status agent2api
# обновление без потери данных
sudo bash install.sh --upgrade

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

После создания ключа клиенту нужны две вещи: base_url вида http://127.0.0.1:3065/v1 и ключ шлюза в поле api_key. Всё остальное — выбор модели, лимиты, резервные аккаунты — настраивается на стороне шлюза, поэтому один и тот же конфиг работает для нескольких инструментов.

# переменные окружения для OpenAI-совместимого клиента
export OPENAI_BASE_URL="http://127.0.0.1:3065/v1"
export OPENAI_API_KEY="<ключ шлюза из панели>"

# Anthropic-совместимый клиент
export ANTHROPIC_BASE_URL="http://127.0.0.1:3065"
export ANTHROPIC_AUTH_TOKEN="<ключ шлюза>"

# проверка запроса
curl http://127.0.0.1:3065/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

Для серверной формы адрес меняется на IP машины, а доступ по локальной сети стоит закрывать ключом: сервер слушает 0.0.0.0, и без авторизации вы отдаёте чужой квоты всем в сети. На десктопе шлюз по умолчанию доступен только локально, но панель умеет открываться по сети — включайте это осознанно.

05Риски: лицензия, правила провайдеров и доступ

Ключевой сценарий Agent2API — использовать аккаунты и подписки, которые у вас уже есть, вместо поштучной оплаты токенов. Экономия здесь реальная, но и оговорок хватает: условия провайдеров могут запрещать обращения через сторонний шлюз или совместное использование аккаунта, а лицензия AGPL-3.0 требует раскрытия исходников при предоставлении доступа по сети.

• Правила провайдеров. Перед подключением аккаунта прочитайте условия: часть сервисов ограничивает автоматизацию и передачу доступа третьим лицам.
• AGPL-3.0. Если вы даёте доступ к изменённой версии по сети, исходники придётся открыть. Для личного шлюза вопрос не возникает.
• Ключи и панель. Не выставляйте панель в интернет без ключа и проверки: в ней хранятся учётные данные аккаунтов.
• Прокси. Пул прокси помогает при региональных ограничениях, но не делает использование аккаунта законным, если это запрещено условиями.
• Единая точка отказа. Упал шлюз — встали все клиенты сразу. Держите резервный прямой конфиг хотя бы у одного инструмента.

06Отчёты и обслуживание

Панель показывает объём запросов, долю успешных, расход токенов и попадание в кэш, а также тепловую карту активности за 365 дней. Для команд это заменяет ручной сбор логов: видно, какой клиент сколько тратит и на какой модели сидит. Отдельный график — тренд попадания в кэш за сутки: если он падает, растёт стоимость одного и того же запроса.

Фоновые задачи шлюза включают обновление каталога моделей и поддержание сессий аккаунтов; у части провайдеров есть собственные окна проверок. Это значит, что после обновления версии стоит зайти в панель и убедиться, что аккаунты в статусе «рабочий», а не «требует входа»: иначе клиент получит отказ, хотя шлюз формально запущен.

07Стоит ли ставить

Если у вас один клиент и один ключ, шлюз не нужен: лишняя сущность в цепочке. Если клиентов два и больше, а аккаунтов провайдеров несколько — Agent2API окупается временем: один адрес, один ключ, одна панель с расходом. Минусы — молодость проекта, AGPL и необходимость самому следить за правилами провайдеров.