404/경로 호환성 문제: Base URL, /v1 접두사 및 중첩 경로 클라이언트
이 과정을 통해 할 수 있는 것
- 404 오류 발생 시 "Base URL 연결 문제"인지 "인증/서비스 미작동"인지 빠르게 판단
- 클라이언트 유형에 맞는 올바른 Base URL 선택(
/v1포함 여부) - 두 가지 고빈도 문제 식별: 중복 접두사(
/v1/v1/...)와 중첩 경로(/v1/chat/completions/responses)
현재 겪고 있는 문제
외부 클라이언트 연결 시 404 Not Found 오류가 발생하고, 원인이 Base URL 구성 문제인 것을 확인했습니다:
- Kilo Code 호출 실패, 로그에
/v1/chat/completions/responses를 찾을 수 없음 - Claude Code는 연결되지만 경로 호환성 문제가 지속됨
- Python OpenAI SDK가
404오류를 보고하지만 서비스는 이미 실행 중
이러한 문제의 근본 원인은 계정 할당량이나 인증이 아니라, 클라이언트가 "자신의 경로"를 작성한 Base URL 뒤에 연결하여 최종 경로가 잘못되기 때문입니다.
이 방법을 언제 사용해야 하나요?
- 리버스 프록시가 실행 중인 것을 확인했지만 모든 API 호출이 404를 반환
- Base URL을 경로가 포함된 형식(예:
/v1/...)으로 설정했지만 클라이언트가 다시 연결할지 확실하지 않음 - 사용 중인 클라이언트가 "자체 경로 연결 논리"를 가지고 있어, 요청 경로가 표준 OpenAI/Anthropic/Gemini와 다름
🎒 시작 전 준비
먼저 "서비스 미작동/인증 실패"를 배제하세요. 그렇지 않으면 잘못된 방향으로 계속 돌게 됩니다.
1단계: 리버스 프록시 실행 확인
curl -i http://127.0.0.1:8045/healthzInvoke-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 뒤에 연결한 다음 요청을 보냅니다. 따라서 Base URL에 /v1을 포함해야 할지는 클라이언트가 어떤 경로를 추가하는지에 따라 다릅니다. 최종 요청 경로를 Antigravity Tools의 라우팅에 맞추기만 하면 404 문제에 더 이상 막히지 않습니다.
핵심 원리
Antigravity Tools의 리버스 프록시 라우팅은 "전체 경로 하드코딩"입니다(참조: src-tauri/src/proxy/server.rs). 일반적인 진입점은 다음과 같습니다:
| 프로토콜 | 경로 | 용도 |
|---|---|---|
| OpenAI | /v1/models | 모델 목록 |
| OpenAI | /v1/chat/completions | 채팅 완성 |
| OpenAI | /v1/responses | Codex CLI 호환 |
| Anthropic | /v1/messages | Claude 메시지 API |
| Gemini | /v1beta/models | 모델 목록 |
| Gemini | /v1beta/models/:model | 콘텐츠 생성 |
| 헬스 체크 | /healthz | 활성 검사 엔드포인트 |
해야 할 일: 클라이언트가 연결한 "최종 경로"가 이러한 라우팅에 정확히 일치하도록 만드는 것입니다.
따라 해보세요
1단계: curl로 "올바른 경로"에 먼저 요청
이유 "사용하려는 프로토콜"이 로컬에 실제로 해당 라우팅이 있는지 먼저 확인하여 404를 "모델/계정 문제"로 오인하는 것을 방지합니다.
# OpenAI 프로토콜: 모델 목록
curl -i http://127.0.0.1:8045/v1/models
# Anthropic 프로토콜: 메시지 인터페이스(여기서는 404/401만 확인, 성공 필수 아님)
curl -i http://127.0.0.1:8045/v1/messages
# Gemini 프로토콜: 모델 목록
curl -i http://127.0.0.1:8045/v1beta/modelsInvoke-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단계: 클라이언트가 "/v1을 자체 연결하는지"에 따라 Base URL 선택
이유 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):
http://127.0.0.1:8045/v1❌ 일반적인 실수:
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 또는 시간 초과
해결: Antigravity Tools의 "API 리버스 프록시" 페이지에서 현재 수신 포트(기본값 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 Token 문제**를 학습합니다.
배울 내용:
- 스트리밍 응답이 예기치 않게 중단되는 이유
- 0 Token 오류의 문제 해결 방법
- Antigravity의 자동 대체 메커니즘
부록: 소스 코드 참조
클릭하여 소스 코드 위치 펼치기
업데이트 시간: 2026-01-23
| 기능 | 파일 경로 | 행 번호 |
|---|---|---|
| 리버스 프록시 라우팅 정의(전체 라우팅 테이블) | 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: Claude Code의 Base URL 권장 사항 | README.md | 197-204 |
| README: Kilo Code 중첩 경로 설명 및 권장 프로토콜 | README.md | 206-211 |
| README: Python OpenAI SDK의 base_url 예제 | README.md | 213-227 |
핵심 함수:
AxumServer::start(): Axum 리버스 프록시 서버를 시작하고 모든 대외 라우팅을 등록health_check_handler(): 헬스 체크 핸들러(GET /healthz)