404/Несовместимость путей: Base URL, префикс /v1 и клиенты с дублирующимися путями

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

При возникновении ошибки 404, сначала определите, это проблема с конкатенацией Base URL или проблема с аутентификацией/отключенной службой
Выберите правильный Base URL для каждого типа клиента (нужен ли /v1)
Распознайте две типичные проблемы: дублирование префикса (/v1/v1/...) и дублирование путей (/v1/chat/completions/responses)

Ваша текущая проблема

При подключении внешних клиентов возникает ошибка 404 Not Found:

Kilo Code не работает, логи показывают, что /v1/chat/completions/responses не найден
Claude Code подключается, но постоянно сообщает о несовместимости путей
Python OpenAI SDK выдает ошибку 404, хотя служба запущена

Корень проблемы не в квотах аккаунта или аутентификации, а в том, что клиент добавляет "свой путь" к указанному вами Base URL, в результате путь получается некорректным.

Когда использовать это руководство

Вы уверены, что reverse proxy запущен, но вызов любого API возвращает 404
Вы указали Base URL с путём (например, /v1/...), но не знаете, добавит ли клиент его снова
Ваш клиент имеет "свою логику конкатенации путей", и запрос выглядит не как стандартный OpenAI/Anthropic/Gemini

🎒 Подготовка

Сначала исключите проблемы с "службой не запущена/сбой аутентификации", иначе вы зря потратите время на неправильные действия.

Шаг 1: Убедитесь, что reverse proxy работает

macOS/LinuxWindows

bash

curl -i http://127.0.0.1:8045/healthz

powershell

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8045/healthz | Select-Object -ExpandProperty Content

Вы должны увидеть: HTTP 200, возвращает JSON (минимум содержит {"status":"ok"}).

Шаг 2: Убедитесь, что ошибка - 404 (не 401)

Если в режиме auth_mode=strict/all_except_health/auto(allow_lan_access=true) вы не указали ключ, скорее всего вы получите 401. Сначала проверьте код состояния, при необходимости пройдите Устранение неполадок 401 сбоя аутентификации.

Что такое Base URL?

Base URL - это "корневой адрес", который клиент использует при отправке запросов. Обычно клиент добавляет свой путь к API после Base URL, поэтому нужно ли указывать /v1 в Base URL, зависит от того, какой путь клиент добавит. Если вы выровняете итоговый путь запроса с маршрутами Antigravity Tools, вы не застрянете на ошибке 404.

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

Маршруты reverse proxy Antigravity Tools "жестко кодируют все пути" (см. src-tauri/src/proxy/server.rs), основные точки входа:

Протокол	Путь	Назначение
OpenAI	`/v1/models`	Список моделей
OpenAI	`/v1/chat/completions`	Chat Completions
OpenAI	`/v1/responses`	Совместимость с Codex CLI
Anthropic	`/v1/messages`	Claude Messages API
Gemini	`/v1beta/models`	Список моделей
Gemini	`/v1beta/models/:model`	Генерация контента
Health check	`/healthz`	Точка проверки работоспособности

Ваша задача: сделать так, чтобы "итоговый путь", собранный клиентом, совпадал с этими маршрутами.

Делайте вместе со мной

Шаг 1: Сначала отправьте запрос curl по "правильному пути"

Зачем Сначала убедитесь, что "протокол, который вы используете", действительно имеет соответствующий маршрут локально, чтобы не путать 404 с "проблемой модели/аккаунта".

macOS/LinuxWindows

bash

 # Протокол OpenAI: список моделей
curl -i http://127.0.0.1:8045/v1/models

 # Протокол Anthropic: messages API (здесь важно только увидеть 404/401, не обязательно чтобы запрос был успешным)
curl -i http://127.0.0.1:8045/v1/messages

 # Протокол Gemini: список моделей
curl -i http://127.0.0.1:8045/v1beta/models

powershell

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8045/v1/models | Select-Object -ExpandProperty StatusCode
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8045/v1/messages | Select-Object -ExpandProperty StatusCode
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8045/v1beta/models | Select-Object -ExpandProperty StatusCode

Вы должны увидеть: Эти пути минимум не должны возвращать 404. Если появляется 401, сначала настройте ключ по Устранение неполадок 401 сбоя аутентификации.

Шаг 2: Выберите Base URL в зависимости от "добавляет ли клиент сам /v1"

Зачем Проблема с Base URL, по сути, заключается в том, что "путь, который вы написали", и "путь, который добавляет клиент", накладываются друг на друга.

Что вы используете	Рекомендуемый Base URL	Какой маршрут вы используете
OpenAI SDK (Python/Node и т.д.)	`http://127.0.0.1:8045/v1`	`/v1/chat/completions`, `/v1/models`
Claude Code CLI (Anthropic)	`http://127.0.0.1:8045`	`/v1/messages`
Gemini SDK / клиенты в режиме Gemini	`http://127.0.0.1:8045`	`/v1beta/models/*`

Запоминание

OpenAI SDK обычно требует указать /v1 в Base URL; для Anthropic/Gemini чаще указывают только host:port.

Шаг 3: Обработка клиентов с "дублирующимися путями", таких как Kilo Code

Зачем В Antigravity Tools нет маршрута /v1/chat/completions/responses. Если клиент собирает этот путь, он обязательно вернет 404.

Следуйте рекомендациям из README:

Выбор протокола: приоритет отдайте протоколу Gemini
Base URL: укажите http://127.0.0.1:8045

Вы должны увидеть: Запросы будут идти по маршрутам /v1beta/models/..., больше не появится /v1/chat/completions/responses.

Шаг 4: Не указывайте Base URL на "конкретный путь ресурса"

Зачем Большинство SDK добавляют свой путь ресурса после Base URL. Если вы указали Base URL слишком глубоко, в итоге получится "двойной путь".

✅ Рекомендуется (для OpenAI SDK):

text

http://127.0.0.1:8045/v1

❌ Распространенная ошибка:

text

http://127.0.0.1:8045
http://127.0.0.1:8045/v1/chat/completions

Вы должны увидеть: После изменения Base URL на более короткий, путь запроса вернется к /v1/... или /v1beta/..., ошибка 404 исчезнет.

Контрольная точка ✅

Используйте эту таблицу для быстрой проверки, совпадает ли ваш "итоговый путь запроса" с маршрутами Antigravity Tools:

Путь, который вы видите в логах	Вывод
Начинается с `/v1/` (например, `/v1/models`, `/v1/chat/completions`)	Использует совместимые маршруты OpenAI/Anthropic
Начинается с `/v1beta/` (например, `/v1beta/models/...`)	Использует нативные маршруты Gemini
Появляется `/v1/v1/`	Base URL содержит `/v1`, клиент добавил его еще раз
Появляется `/v1/chat/completions/responses`	Клиент дублирует пути, текущая таблица маршрутов не поддерживает

Предупреждения о типичных ошибках

Ошибка 1: Дублирование префикса /v1

Симптом: Путь становится /v1/v1/chat/completions

Причина: Base URL уже содержит /v1, клиент добавил его еще раз.

Решение: Измените Base URL, чтобы он заканчивался только на /v1, не пишите дальше конкретный путь ресурса.

Ошибка 2: Клиенты с дублирующимися путями

Симптом: Путь становится /v1/chat/completions/responses

Причина: Клиент добавляет бизнес-путь поверх пути протокола OpenAI.

Решение: Сначала переключитесь на другой режим протокола клиента (например, для Kilo Code используйте Gemini).

Ошибка 3: Неправильный порт

Симптом: Connection refused или timeout

Решение: На странице "API 反代" Antigravity Tools подтвердите текущий порт прослушивания (по умолчанию 8045), порт в Base URL должен совпадать.

Краткий итог урока

Симптом	Самая частая причина	Что нужно изменить
Постоянно 404	Неправильная конкатенация Base URL	Сначала проверьте curl на `/v1/models`/`/v1beta/models`, чтобы не было 404
`/v1/v1/...`	Дублирование `/v1`	Для OpenAI SDK Base URL должен заканчиваться на `/v1`
`/v1/chat/completions/responses`	Клиент дублирует пути	Используйте протокол Gemini или настройте перезапись путей (не рекомендуется новичкам)

Следующий урок预告

Следующий урок: Прерывание потоковой передачи и проблема 0 токенов
Вы узнаете:
Почему потоковый ответ может неожиданно прерваться
Методы устранения неполадок ошибки 0 токенов
Механизм автоматического отступления в Antigravity

Приложение: Справка по исходному коду

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

Обновлено: 2026-01-23

Функция	Путь к файлу	Строки
Определение маршрутов reverse proxy (полная таблица маршрутов)	`src-tauri/src/proxy/server.rs`	120-193
`AxumServer::start()` (точка входа в создание маршрутов)	`src-tauri/src/proxy/server.rs`	79-216
`health_check_handler()`	`src-tauri/src/proxy/server.rs`	266-272
README: рекомендуемый Base URL для Claude Code	`README.md`	197-204
README: объяснение дублирования путей в Kilo Code и рекомендуемый протокол	`README.md`	206-211
README: пример base_url для Python OpenAI SDK	`README.md`	213-227

Ключевые функции:

AxumServer::start(): Запускает сервер reverse proxy Axum и регистрирует все внешние маршруты
health_check_handler(): Обработчик проверки работоспособности (GET /healthz)

Запуск с нуля

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

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

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

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

404/Несовместимость путей: Base URL, префикс /v1 и клиенты с дублирующимися путями

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

Ваша текущая проблема

Когда использовать это руководство

🎒 Подготовка

Шаг 1: Убедитесь, что reverse proxy работает

Шаг 2: Убедитесь, что ошибка - 404 (не 401)

Что такое Base URL?

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

Делайте вместе со мной

Шаг 1: Сначала отправьте запрос curl по "правильному пути"

Шаг 2: Выберите Base URL в зависимости от "добавляет ли клиент сам /v1"

Шаг 3: Обработка клиентов с "дублирующимися путями", таких как Kilo Code

Шаг 4: Не указывайте Base URL на "конкретный путь ресурса"

Контрольная точка ✅

Предупреждения о типичных ошибках

Ошибка 1: Дублирование префикса /v1

Ошибка 2: Клиенты с дублирующимися путями

Ошибка 3: Неправильный порт

Краткий итог урока

Следующий урок预告

Приложение: Справка по исходному коду

404/Несовместимость путей: Base URL, префикс /v1 и клиенты с дублирующимися путями ​

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

Ваша текущая проблема ​

Когда использовать это руководство ​

🎒 Подготовка ​

Шаг 1: Убедитесь, что reverse proxy работает ​

Шаг 2: Убедитесь, что ошибка - 404 (не 401) ​

Что такое Base URL? ​

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

Делайте вместе со мной ​

Шаг 1: Сначала отправьте запрос curl по "правильному пути" ​

Шаг 2: Выберите Base URL в зависимости от "добавляет ли клиент сам /v1" ​

Шаг 3: Обработка клиентов с "дублирующимися путями", таких как Kilo Code ​

Шаг 4: Не указывайте Base URL на "конкретный путь ресурса" ​

Контрольная точка ✅ ​

Предупреждения о типичных ошибках ​

Ошибка 1: Дублирование префикса /v1 ​

Ошибка 2: Клиенты с дублирующимися путями ​

Ошибка 3: Неправильный порт ​

Краткий итог урока ​

Следующий урок预告 ​

Приложение: Справка по исходному коду ​

404/Несовместимость путей: Base URL, префикс /v1 и клиенты с дублирующимися путями

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

Ваша текущая проблема

Когда использовать это руководство

🎒 Подготовка

Шаг 1: Убедитесь, что reverse proxy работает

Шаг 2: Убедитесь, что ошибка - 404 (не 401)

Что такое Base URL?

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

Делайте вместе со мной

Шаг 1: Сначала отправьте запрос curl по "правильному пути"

Шаг 2: Выберите Base URL в зависимости от "добавляет ли клиент сам /v1"

Шаг 3: Обработка клиентов с "дублирующимися путями", таких как Kilo Code

Шаг 4: Не указывайте Base URL на "конкретный путь ресурса"

Контрольная точка ✅

Предупреждения о типичных ошибках

Ошибка 1: Дублирование префикса /v1

Ошибка 2: Клиенты с дублирующимися путями

Ошибка 3: Неправильный порт

Краткий итог урока

Следующий урок预告

Приложение: Справка по исходному коду