404/パス互換性：Base URL、/v1 プレフィックスと重なりパスクライアント
学んだ後できること
- 404 が発生したとき、まず「Base URL 連結問題」か「認証/サービス未起動」かを判断できる
- クライアントタイプに応じて正しい Base URL を選択できる（
/v1をつけるかどうか） - 2 つの高頻度の罠を識別できる：重複プレフィックス（
/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 に連結した結果、パスが歪んでしまったことです。
この方法をいつ使うか
- リバースプロキシが起動済みなのに、どのインターフェースを呼んでも 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) モードで key なしで呼び出した場合、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 認証失敗トラブルシューティング に従って key を設定してください。
第 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 は通常、Base URL に /v1 を含める必要があります。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）