Запуск обратного прокси: подключение первого клиента (проверка /healthz + конфигурация SDK)

В этом уроке мы запустим локальный обратный прокси (API Proxy) с помощью Antigravity Tools: запустим сервис, выполним проверку /healthz, а затем подключим SDK для выполнения первого запроса.

Чему вы научитесь

Запускать и останавливать сервис обратного прокси на странице API Proxy
Использовать GET /healthz для проверки работоспособности и подтверждения «правильный порт, сервис действительно работает»
Понять взаимосвязь между auth_mode и API Key: какие пути требуют аутентификации, какой header передавать
Выполнить первый реальный запрос с помощью любого клиента (OpenAI / Anthropic / Gemini SDK)

Ваша текущая ситуация

Вы уже установили Antigravity Tools и добавили учетную запись, но не знаете, «успешно ли запустился обратный прокси»
При подключении клиента легко возникают ошибки 401 (нет key) или 404 (Base URL неправильно склеен/дублируется путей)
Вы не хотите гадать, вы хотите кратчайший замкнутый цикл: запуск → проверка → первый успешный запрос

Когда использовать этот метод

Вы только что установили Antigravity Tools и хотите подтвердить, «может ли локальный шлюз работать с внешними запросами»
Вы изменили порт, включили доступ к локальной сети или изменили режим аутентификации и хотите быстро проверить, что конфигурация не рухнула
Вы хотите подключить нового клиента/новый SDK и сначала проверить на минимальном примере, чтобы он заработал

🎒 Подготовка к началу

Предварительные условия

Вы уже установили и можете открыть Antigravity Tools.
У вас есть хотя бы одна доступная учетная запись; иначе при запуске обратного прокси вернется ошибка "Нет доступных учетных записей, сначала добавьте учетную запись".

В этом уроке будут постоянно встречаться несколько слов

Base URL: «корневой адрес запроса» клиента. Способ склеивания URL у разных SDK разный: некоторым нужен /v1, некоторым нет.
Проверка работоспособности: минимальный запрос для подтверждения доступности сервиса. В этом проекте конечная точка проверки — GET /healthz, возвращающий {"status":"ok"}.

Основная идея

При запуске обратного прокси Antigravity Tools будет привязывать адрес прослушивания и порт в соответствии с конфигурацией:
- allow_lan_access=false — привязка к 127.0.0.1
- allow_lan_access=true — привязка к 0.0.0.0
Вам не нужно сначала писать какой-либо код. Сначала используйте GET /healthz для проверки, чтобы подтвердить «сервис запущен».
Если вы включили аутентификацию:
- auth_mode=all_except_health будет исключать /healthz
- auth_mode=strict — все пути требуют API Key

Следуйте за нами

Шаг 1: подтвердите порт, доступ к локальной сети, режим аутентификации

Почему Сначала вы должны определить, «какой адрес (host/port) будет использовать клиент», а также «нужно ли передавать key», иначе далее 401/404 будет сложно устранять.

В Antigravity Tools откройте страницу API Proxy и уделите внимание этим 4 полям:

port: по умолчанию 8045
allow_lan_access: по умолчанию выключено (только локальный доступ)
auth_mode: опционально off/strict/all_except_health/auto
api_key: по умолчанию будет сгенерирован sk-..., и UI будет проверять, что он начинается с sk- и длина не менее 10

Вы должны увидеть

В правом верхнем углу страницы есть кнопка Start/Stop (запуск/остановка обратного прокси), поле ввода порта будет отключено, когда сервис работает

Рекомендуемая конфигурация для новичков (сначала заставьте работать, потом добавляйте безопасность)

Сначала заставьте работать: allow_lan_access=false + auth_mode=off
Если нужно предоставить доступ к локальной сети, включите allow_lan_access=true, затем переключите auth_mode на all_except_health (по крайней мере не открывайте «голый API» для всей LAN)

Шаг 2: запустите сервис обратного прокси

Почему Кнопка Start в GUI вызывает команду запуска на бэкенде для запуска Axum Server и загрузки пула учетных записей; это предварительное условие «предоставления API внешним миру».

Нажмите кнопку Start в правом верхнем углу страницы.

Вы должны увидеть

Статус меняется с stopped на running
Рядом отображается текущее количество активных учетных записей (active accounts)

Если запуск не удался, две самые частые ошибки

"Нет доступных учетных записей, сначала добавьте учетную запись": это означает, что пул учетных записей пуст, а распределение z.ai не включено.
"Не удалось запустить сервер Axum: не удалось привязать адрес <host:port>: ...": порт занят или нет прав (попробуйте другой порт).

Шаг 3: выполните проверку /healthz (кратчайший замкнутый цикл)

Почему/healthz — это самый стабильный «подтверждающий работоспособность». Он не зависит от модели, учетной записи или преобразования протокола, только проверяет, доступен ли сервис.

Замените <PORT> на порт, который вы видите в UI (по умолчанию 8045):

macOS/LinuxWindows

bash

curl -sS "http://127.0.0.1:<PORT>/healthz"

powershell

curl.exe -sS "http://127.0.0.1:<PORT>/healthz"

Вы должны увидеть

json

{"status":"ok"}

Как проверить, если нужна аутентификация?

Когда вы переключите auth_mode на strict, все пути требуют key (включая /healthz).

bash

curl -sS "http://127.0.0.1:<PORT>/healthz" \
  -H "Authorization: Bearer <API_KEY>"

Рекомендуемый способ записи заголовка аутентификации (совместим с большим количеством форм):

Authorization: Bearer <proxy.api_key> или Authorization: <proxy.api_key>
x-api-key: <proxy.api_key>
x-goog-api-key: <proxy.api_key>

Шаг 4: подключите первого клиента (выберите один из OpenAI / Anthropic / Gemini)

Почему/healthz только показывает, «сервис доступен»; реальный успех подключения — это когда SDK отправляет настоящий запрос.

OpenAI SDK (Python)Claude Code / Anthropic CLIGemini SDK (Python)

python

import openai

client = openai.OpenAI(
    api_key="<API_KEY>",
    base_url="http://127.0.0.1:8045/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-flash",
    messages=[{"role": "user", "content": "Здравствуйте, пожалуйста, представьтесь"}],
)

print(resp.choices[0].message.content)

bash

export ANTHROPIC_API_KEY="<API_KEY>"
export ANTHROPIC_BASE_URL="http://127.0.0.1:8045"
claude

python

import google.generativeai as genai

genai.configure(
    api_key="<API_KEY>",
    transport="rest",
    client_options={"api_endpoint": "http://127.0.0.1:8045"},
)

model = genai.GenerativeModel("gemini-3-flash")
resp = model.generate_content("Привет")
print(resp.text)

Вы должны увидеть

Клиент получает непустой текстовый ответ
Если включен Proxy Monitor, вы также увидите эту запись запроса в мониторинге

Контрольная проверка ✅

GET /healthz возвращает {"status":"ok"} (или эквивалентный JSON)
Страница API Proxy показывает running
Один из выбранных вами примеров SDK возвращает содержимое (не 401/404 и не пустой ответ)

Предупреждения

401: чаще всего проблема в неправильной аутентификации

Вы включили auth_mode, но клиент не передает key.
Вы передали key, но имя заголовка неправильное: этот проект одновременно совместим с Authorization/x-api-key/x-goog-api-key.

404: чаще всего Base URL неправильно склеен или «дублирование путей»

Для OpenAI SDK в примере обычно требуется, чтобы base_url заканчивался на /v1 (см. пример Python в README проекта).
Некоторые клиенты могут «дублировать путь». Например, в README явно упоминается: в режиме OpenAI у Kilo Code могут быть сгенерированы неверные пути вроде /v1/chat/completions/responses, что вызовет 404.

Доступ к локальной сети — это не «включил и всё готово»

Когда вы включаете allow_lan_access=true, сервис привязывается к 0.0.0.0. Это означает, что другие устройства в той же локальной сети могут получить доступ через ваш IP + порт.

Если вы собираетесь так делать, по крайней мере включите auth_mode и установите надежный api_key.

Итог урока

После запуска обратного прокси сначала проверяйте /healthz, затем конфигурируйте SDK
auth_mode определяет, какие пути требуют key; all_except_health исключает /healthz
При подключении SDK проще всего ошибиться с тем, нужно ли /v1 в Base URL

Предупреждение к следующему уроку

В следующем уроке мы подробно разберем OpenAI-совместимый API, включая совместимые границы /v1/chat/completions и /v1/responses.
Перейдите к OpenAI-совместимый API: стратегия реализации /v1/chat/completions и /v1/responses.

Приложение: ссылки на исходный код

Нажмите, чтобы раскрыть расположение исходного кода

Дата обновления: 2026-01-23

Тема	Путь к файлу	Строка
Запуск/остановка/статус обратного прокси	`src-tauri/src/commands/proxy.rs`	42-178
Проверка доступности пула учетных записей перед запуском (ошибка при отсутствии учетных записей)	`src-tauri/src/commands/proxy.rs`	81-91
Регистрация маршрутов (включая `/healthz`)	`src-tauri/src/proxy/server.rs`	120-194
Возвращаемое значение `/healthz`	`src-tauri/src/proxy/server.rs`	266-272
Промежуточное ПО аутентификации (совместимость заголовков / исключение `/healthz`)	`src-tauri/src/proxy/middleware/auth.rs`	14-78
Логика фактического разбора `auth_mode=auto`	`src-tauri/src/proxy/security.rs`	19-30
Значения ProxyConfig по умолчанию (порт 8045, по умолчанию только локальный)	`src-tauri/src/proxy/config.rs`	174-257
Вывод адреса привязки (127.0.0.1 vs 0.0.0.0)	`src-tauri/src/proxy/config.rs`	281-291
UI: кнопка запуска/остановки вызывает `start_proxy_service/stop_proxy_service`	`src/pages/ApiProxy.tsx`	624-639
UI: область конфигурации порта/локальной сети/аутентификации/API key	`src/pages/ApiProxy.tsx`	868-1121
Пример подключения Claude Code / Python в README	`README.md`	197-227

Запуск с нуля

Что делать при возникновении ошибки

Руководство по обновлению без ошибок

Подключите вашу AI платформу

Обновите систему до производственного уровня

Запуск обратного прокси: подключение первого клиента (проверка /healthz + конфигурация SDK)

Чему вы научитесь

Ваша текущая ситуация

Когда использовать этот метод

🎒 Подготовка к началу

Основная идея

Следуйте за нами

Шаг 1: подтвердите порт, доступ к локальной сети, режим аутентификации

Шаг 2: запустите сервис обратного прокси

Шаг 3: выполните проверку /healthz (кратчайший замкнутый цикл)

Шаг 4: подключите первого клиента (выберите один из OpenAI / Anthropic / Gemini)

Контрольная проверка ✅

Предупреждения

Итог урока

Предупреждение к следующему уроку

Приложение: ссылки на исходный код

Запуск обратного прокси: подключение первого клиента (проверка /healthz + конфигурация SDK) ​

Чему вы научитесь ​

Ваша текущая ситуация ​

Когда использовать этот метод ​

🎒 Подготовка к началу ​

Основная идея ​

Следуйте за нами ​

Шаг 1: подтвердите порт, доступ к локальной сети, режим аутентификации ​

Шаг 2: запустите сервис обратного прокси ​

Шаг 3: выполните проверку /healthz (кратчайший замкнутый цикл) ​

Шаг 4: подключите первого клиента (выберите один из OpenAI / Anthropic / Gemini) ​

Контрольная проверка ✅ ​

Предупреждения ​

Итог урока ​

Предупреждение к следующему уроку ​

Приложение: ссылки на исходный код ​

Запуск обратного прокси: подключение первого клиента (проверка /healthz + конфигурация SDK)

Чему вы научитесь

Ваша текущая ситуация

Когда использовать этот метод

🎒 Подготовка к началу

Основная идея

Следуйте за нами

Шаг 1: подтвердите порт, доступ к локальной сети, режим аутентификации

Шаг 2: запустите сервис обратного прокси

Шаг 3: выполните проверку /healthz (кратчайший замкнутый цикл)

Шаг 4: подключите первого клиента (выберите один из OpenAI / Anthropic / Gemini)

Контрольная проверка ✅

Предупреждения

Итог урока

Предупреждение к следующему уроку

Приложение: ссылки на исходный код