# Polza.AI Proxy: локальный прокси для упрямых клиентов

> Некоторые IDE и CLI не дают задать дополнительные параметры запроса. Прокси принимает их запросы у вас на машине, дописывает нужные поля и отправляет дальше.

- Одна зависимость
- Работает локально
- Выбор провайдера моделей
- Подходит для Claude Code

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

Нужен он далеко не всегда. Большинство интеграций из документации спокойно принимают адрес и ключ в настройках — там прокси только усложнит схему. Его область — упрямые клиенты и тонкая настройка выбора провайдера.

Код открыт, зависимость одна, работает локально: запросы не уходят никуда, кроме самого API Polza.

## Когда нужен прокси

В большинстве случаев он не нужен: достаточно вписать адрес Polza в настройки инструмента. Прокси решает частные задачи, которые иначе не решаются вовсе.

- **Клиент не даёт задать параметры.** Некоторые IDE и CLI отправляют жёстко заданное тело запроса: добавить своё поле через интерфейс невозможно. Решение: Прокси дописывает поля по дороге.
- **Нельзя выбрать провайдера модели.** Одна и та же модель бывает у нескольких провайдеров, но выбрать порядок из клиента не получится. Решение: Правила выбора задаются в конфиге прокси.
- **Клиент требует ключ, которого нет.** Инструмент может ожидать ключ определённого формата и не принимать ваш. Решение: Прокси подставляет ваш ключ сам.
- **Настройки размазаны по инструментам.** Одни и те же параметры приходится повторять в каждом клиенте отдельно. Решение: Один конфиг на все подключённые клиенты.
- **Непонятно, что уходит на сервер.** Когда ответ странный, трудно понять, какое тело запроса сформировал клиент. Решение: Логирование тел запросов одним флагом.
- **Ключ в настройках каждого клиента.** Чем больше инструментов, тем больше мест, где лежит один и тот же ключ. Решение: Ключ хранится в одном конфиге прокси.

## Как запустить Polza.AI Proxy

Клонировать, настроить, запустить. Нужен Node.js 20 или новее, зависимость всего одна.

Что нужно:

- **Node.js 20 или новее.** Проверяется командой node --version. На более старых версиях прокси не запустится.
- **Ключ Polza.** Кладётся в конфиг в поле polzaApiKey. Можно оставить пустым, если клиент передаёт собственный ключ.
- **Свободный порт.** По умолчанию 8787. Если занят, поменяйте в конфиге или освободите — иначе прокси не поднимется.

### 1. Установите

Репозиторий клонируется с GitHub, зависимости ставятся обычным npm install. Тянется только fastify, ничего лишнего.

Терминал · установка:

```
$ git clone https://github.com/polza-ai/api-proxy.git
$ cd api-proxy && npm install

# требуется Node.js 20+
```

### 2. Настройте конфиг

Скопируйте шаблон в `config.json` и заполните. Если файла нет, при запуске стартует интерактивный мастер настройки.

config.json:

```
"port":        8787,
"host":        "127.0.0.1",
"polzaApiKey": "ваш-api-ключ",
"inject":      {}
```

### 3. Запустите

Команда `npm start` поднимет прокси. При успешном старте появится баннер с версией, адресом прослушивания и апстримом.

Проверка:

```
$ npm start
$ curl http://127.0.0.1:8787/health
  {"ok":true}
```

### 4. Подключите клиент

В настройках инструмента укажите адрес прокси вместо адреса Polza. Для Claude Code это делается в `settings.json` переменными окружения:

Claude Code · settings.json:

```
"env": {
  "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
  "ANTHROPIC_AUTH_TOKEN": "любой-placeholder",
  "ANTHROPIC_API_KEY": ""
}
```

**Зачем нужны инъекции.** Главный сценарий — выбор провайдера. Одна и та же модель может обслуживаться разными провайдерами, и через секцию inject задаётся порядок обращения и разрешены ли запасные варианты. Клиент об этом ничего не знает: он шлёт обычный запрос, а поля дописываются по дороге. Важная деталь: если клиент сам передал такое поле, прокси его не перетирает.

## Что умеет прокси

Небольшой локальный сервис с узкой, но полезной ролью.

- **Прозрачный форвардинг.** Принимает OpenAI-совместимые запросы и отправляет их дальше, не меняя логику работы клиента.
- **Выбор провайдера.** Порядок провайдеров и разрешение запасных вариантов задаются в конфиге и применяются к каждому запросу.
- **Подстановка ключа.** Если ключ задан в конфиге, клиент может передавать любой placeholder — прокси подставит ваш.
- **Отладка запросов.** Флаг логирования показывает, какое тело уходит на сервер, — удобно, когда поведение клиента непонятно.
- **Только локально.** По умолчанию слушает 127.0.0.1, то есть доступен лишь с вашей машины.
- **Одна зависимость.** Из внешнего — только fastify. Запускается быстро и не тянет за собой половину npm.

- **Скорее нет.** Если ваш инструмент позволяет вписать Base URL и ключ — а это большинство интеграций, — прокси не нужен. Просто укажите адрес Polza напрямую.
- **Скорее да.** Если клиент не даёт задать нужные поля, требует ключ чужого формата или вам важно управлять выбором провайдера для каждого запроса.

## Чем прокси отличается от прямого подключения

Два способа связать инструмент с API, и выбирать между ними стоит по возможностям клиента, а не по вкусу.

- **Прямое подключение.** Адрес и ключ прямо в настройках инструмента. Проще, надёжнее, ничего не надо поддерживать. Так работает большинство интеграций.
- **Через прокси.** Нужен, когда клиент не даёт задать поля или требуется управлять выбором провайдера. Добавляет один локальный сервис в схему.
- **Свой скрипт-обёртка.** Максимальная свобода и максимум поддержки: логику, обработку ошибок и логи придётся писать самому.

## Напрямую или через прокси

|  | Напрямую | Через прокси |
| --- | --- | --- |
| Настройка | Адрес и ключ в клиенте | Плюс запуск локального сервиса |
| Дополнительные поля | Только если клиент умеет | Дописываются автоматически |
| Выбор провайдера | Недоступен из клиента | Задаётся в конфиге |
| Ключ | В настройках каждого клиента | В одном конфиге прокси |
| Отладка | Что ушло — не видно | Логирование тел запросов |
| Когда применять | Почти всегда | Когда клиент упрямый |

## Сколько это стоит

Прокси бесплатный и с открытым кодом, работает на вашей машине. Платите только за токены моделей по ценам каталога, в рублях.

- **Ничего сверху.** Прокси не берёт комиссию и не меняет тарификацию: он лишь передаёт запросы дальше с дописанными полями.
- **Экономия на выборе провайдера.** Настроив порядок провайдеров, вы получаете предсказуемую цену запроса там, где иначе всё решалось бы за вас.
- **Расход виден как обычно.** Запросы идут по вашему ключу, поэтому статистика по моделям и ключам в кабинете остаётся полной.

- [anthropic/claude-sonnet-5](https://polza.ai/models/anthropic/claude-sonnet-5.md) — через Claude Code и прокси
- [anthropic/claude-opus-4.7](https://polza.ai/models/anthropic/claude-opus-4.7.md) — сложные задачи
- [openai/gpt-5.5](https://polza.ai/models/openai/gpt-5.5.md) — универсальная
- [deepseek/deepseek-v4-flash](https://polza.ai/models/deepseek/deepseek-v4-flash.md) — экономичная

## Если прокси не работает

Четыре причины, на которые приходится почти вся переписка с поддержкой.

- **Не запускается или отвечает 502.** Проверьте polzaApiKey в конфиге: без ключа прокси стартует, но получит 401 от апстрима. Убедитесь, что порт свободен и Node.js не ниже 20.
- **Инъекции не применяются.** Они работают на chat/completions, completions и responses. Включите логирование тел запросов и проверьте, что уходит на сервер.
- **Клиент не видит прокси.** В настройках инструмента должен стоять адрес прокси, а не адрес Polza. Проверьте порт и то, что сервис действительно запущен.
- **Проверка здоровья не отвечает.** Запрос на /health должен вернуть {"ok":true}. Если ответа нет, прокси не поднялся — смотрите вывод команды запуска.

## Частые вопросы

### Что такое Polza.AI Proxy?

Локальный OpenAI-совместимый прокси. Он принимает запросы от IDE и CLI, которые не умеют задавать дополнительные параметры, дописывает нужные поля и передаёт запрос дальше на API Polza.

### Нужен ли он мне?

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

### Что нужно для запуска?

Node.js 20 или новее и ключ Polza. Зависимость всего одна — fastify.

### Какой адрес указывать в клиенте?

http://127.0.0.1:8787 вместо адреса Polza. Порт меняется в конфиге, по умолчанию 8787.

### Как подключить Claude Code?

В settings.json задать ANTHROPIC_BASE_URL на адрес прокси, в ANTHROPIC_AUTH_TOKEN положить любой placeholder, а ANTHROPIC_API_KEY оставить пустым.

### Прокси возвращает 502

Чаще всего не заполнен polzaApiKey в конфиге — тогда апстрим отвечает 401. Проверьте также, что порт свободен и что версия Node.js не ниже 20.

### Инъекции не применяются

Они работают на эндпоинтах chat/completions, completions и responses. Включите логирование тел запросов и посмотрите, что уходит. Если клиент сам передал поле, прокси его не перезаписывает.

### Можно ли открыть доступ по сети?

В конфиге есть параметр host: значение 0.0.0.0 заставит слушать все интерфейсы. По умолчанию стоит 127.0.0.1, и для локальной работы это правильнее.

## Читать дальше

- [API нейросетей: единый ключ для ChatGPT, Claude и 400+ моделей](https://polza.ai/blog/api-neyrosetei.md)
- [Российский API нейросетей без VPN](https://polza.ai/blog/rossiyskiy-api-dlya-neyrosetey-bez-vpn-polnyy-gayd-2026.md)
- [Агрегатор нейросетей: что это и лучшие сервисы 2026](https://polza.ai/blog/agregator-nejrosetej.md)

## Ссылки

- Документация: https://polza.ai/docs/integracii/proxy
- Страница: https://polza.ai/integrations/proxy
- Обновлено: 2026-09-26