Cursor は広く使われている AI コードエディターです。内蔵モデルの枠とは別に、独自の API キーと Base URL を入力できます。日本国内のチームにとって、Cursor を統一された OpenAI 互換ゲートウェイに接続すると、アクセス経路を固定し、請求を集約し、モデルを切り替えやすくなります。

本記事では実際の操作順に沿って、準備、設定、確認、制限、チーム導入の要点を説明します。バージョンによってメニュー名が異なる場合があるため、現在インストールされている Cursor Settings を基準にしてください。

注記：Cursor は Anysphere, Inc. の商標です。本記事は技術的な説明のみを目的としており、Cursor／Anysphere と資本関係、代理関係、提携関係はありません。画面、プラン、課金ルールは Cursor の公式ページを基準にしてください。

一、まず 2 種類の「Cursor API」を区別する

1 つ目は Cursor プラットフォーム自身が公開している API です。Cloud Agents や管理インターフェースなどがあり、キーは Cursor アカウントで作成し、Cursor のサービスを呼び出すために使います。2 つ目は「独自モデルキー（BYOK）」です。Cursor にモデル提供元のキーを入力し、エディターがあなたのアカウントでモデルを呼び出します。本記事で扱うのは 2 つ目です。

見落としやすい前提が 1 つあります。Cursor のモデルリクエストは Cursor のサーバーを経由して転送され、あなたの PC から直接接続するわけではありません。そのため Base URL はパブリックインターネットから到達できるアドレスである必要があります。社内ネットワークからのみ到達できるゲートウェイでは、Cursor 側でタイムアウトが発生します。ZSQH AI Gateway はパブリックインターネット経由で利用できるサービスであるため、通常この制限に該当しません。

二、キー、Base URL、モデル名を準備する

開始前に 3 つを用意します。API キー、互換アドレス、正確なモデル ID です。

  1. ZSQH AI Gateway の登録ページを開き、登録してコンソールにログインします。
  2. 「API キー」に進み、新しいキーを作成します。名前は用途が分かるように、たとえば cursor-work-pc とします。
  3. 上限額と有効期限を設定します。個人アカウントでも、異常な消費を避けるために設定をおすすめします。
  4. キーをコピーし、パスワードマネージャーに保存します。コンソールでは通常、完全な表示は 1 回だけです。
  5. モデル料金を開き、使用するモデル ID を控えます。価格とモデルは変更されるため、ページの現在の表示を基準にしてください。

3 つの設定の書き方は次のとおりです。

Base URL: https://ai.zhongshangqihang.com/v1
API Key:  sk-...（コンソールで作成し、パスワードマネージャーにのみ保存）
Model:    「モデル料金」ページに現在表示されているモデル ID を使用

Base URL は OpenAI 互換アドレスを使用し、末尾は /v1 です。Anthropic のルートアドレスを入力したり、自分で /chat/completions を追加したりしないでください。パスの重複が発生しやすくなります。

三、Cursor に設定を入力する

一般的な経路は Cursor Settings → Models → API Keys です。バージョンによって項目の増減はありますが、中心となる手順はほぼ同じです。

  1. Cursor Settings を開きます。ショートカットは通常 Cmd/Ctrl + , です。
  2. Models に進み、API Keys の領域を展開します。
  3. OpenAI API Key を開き、作成したキーを貼り付けて Save をクリックします。
  4. Override OpenAI Base URL を開き、https://ai.zhongshangqihang.com/v1 を入力します。
  5. + Add Custom Model（バージョンによっては + Add model）をクリックし、料金ページのモデル ID を入力して、そのモデルを有効にします。
  6. 会話のモデル選択でこのモデルを選び、簡単なリクエストを送信します。

Override OpenAI Base URL が見つからない場合、現在のバージョンまたはプランが、OpenAI 互換トラフィックをカスタムアドレスへ向ける機能に対応していません。この場合は繰り返し試さず、バージョンを上げるか、このスイッチに対応したインストールパッケージに変更してください。

モデル名はルーティングの識別子であり、メモではありません。大文字・小文字、ハイフン、バージョン接尾辞をゲートウェイと一致させてください。間違えると、通常はモデルが存在しない、404、またはリクエスト拒否として現れます。

四、モデルの選び方

Cursor には複数のカスタムモデルを追加できますが、リクエストが成功するかは、ゲートウェイが同名モデルを提供しているか、対応する呼び出し方式をサポートしているかによって決まります。

利用場面 推奨する階層 入力方法 注意点
日常の質問、小さな修正 軽量で高速なモデル 料金ページのモデル ID をコピー 遅延は低いが、複雑なリファクタリング能力は限られる
複数ファイルの修正、Agent 主力コードモデル 料金ページのモデル ID をコピー ツール呼び出しに対応している必要がある
アーキテクチャ設計、難問の調査 高性能モデル 料金ページのモデル ID をコピー コストが高いため、必要なときだけ使う
Tab 補完 Cursor 内蔵モデル カスタムキーを経由しない BYOK は補完をカバーしない

Agent モードは Responses API やツール呼び出しに依存する場合があります。ゲートウェイが Chat Completions のみに対応していると、一部の Agent 機能が失敗します。その場合は、まず通常の会話で確認し、モデルの問題か機能の非互換かを判断してください。

また、Auto、Composer、Tab 補完は必ずしもあなたのキーを通りません。Cursor のヘルプページによると、Tab 補完は常に内蔵モデルを使用し、Auto モードも Cursor 自身がルーティングする場合があります。カスタムモデルは「明示的に選択したときだけ有効になる」経路と考えるほうが実態に合っています。

五、設定が有効か確認する

Cursor が返信したかどうかだけでは不十分です。返信が内蔵経路から来ている可能性があります。次の順序で確認してください。

  1. 空の新しい会話を作成し、履歴による干渉を避けます。
  2. モデル選択でカスタムモデルを明示的に選び、Auto は使いません。
  3. 短いリクエストを送ります。たとえば 10 行以内のコードを説明させる、などです。
  4. ゲートウェイのコンソールで利用量またはリクエストログを開き、同じ時刻、同じモデル、同じキーの記録があることを確認します。
  5. 確認結果を記録します。ログに記録がなければ、リクエストはゲートウェイに到達していません。Base URL とスイッチの確認に戻ってください。

よくあるエラーは次のように切り分けます。

  • 401 または 403：キーが間違っている、無効化されている、または枠を使い切っている。
  • 404：Base URL のパスが違う、またはモデル名が存在しない。
  • 429：レート制限に達した、またはキーの上限額に達した。
  • タイムアウト：エンドポイントに到達できない、またはネットワーク経路に問題がある。
  • Agent だけ失敗する：インターフェース機能の不一致の可能性があり、キーの問題とは限らない。

六、知っておくべき制限

  • BYOK が主にカバーするのはチャットモデルです。Tab 補完は引き続き Cursor 内蔵モデルを使用します。
  • バージョンによって OpenAI キーの対応範囲が異なります。Cursor のヘルプページでは、OpenAI の独自キーは推論を含まない標準チャットモデルのみをカバーし、推論モデルや一部の新機能は利用できない場合があると説明されています。
  • リクエストは Cursor のサーバーを経由して転送されるため、カスタムエンドポイントはパブリックインターネットから到達できる必要があります。
  • 独自キーのリクエストが Cursor のゼロデータ保持ポリシーの対象になるとは限りません。データの取り扱いはモデル提供元とゲートウェイによって決まります。データ保持に厳格な要件があるチームは、事前に評価してください。
  • チーム版や Enterprise 版では、独自キーを使っても Cursor の規則に基づくプラットフォーム費用が別途発生する場合があります。詳細は Cursor の課金ページを基準にしてください。
  • Cursor は更新が速く、メニュー名、対応モデル、課金ルールが変わる可能性があります。

七、チーム導入の手順

  • まず小規模な試行を行います。開発者を 3〜5 名選び、主力モデルを 1 つに統一して 1 週間運用します。
  • 3 種類のデータを記録します。リクエスト成功率、平均遅延、1 人 1 日あたりの消費量です。
  • ゲートウェイでメンバーごとに個別のキーを作成し、人ごとに上限を設定します。共有キーは使いません。
  • モデル対応表を維持します。Cursor に入力する名前、ゲートウェイ側の対応、失敗時の切り替え先をまとめます。
  • 設定を社内ドキュメントに記載します。Base URL、モデル ID、よくあるエラーの対処を含めます。
  • コストを観察してから、どのメンバーが独自キーを使い、どのメンバーがプラン枠を使い続けるかを決めます。価格はモデル料金を基準にしてください。
  • 退職、PC の変更、プロジェクト終了の際は、その日のうちに対応するキーを無効化します。

八、セキュリティチェックリスト

  • 1 用途に 1 キー。デバイス間で使い回さない。
  • 上限額と有効期限を設定する。
  • キーをコード、.env、スクリーンショット、チケットに書かない。
  • 共有 PC にキーを長期保存しない。
  • 定期的にローテーションする。漏えいが疑われる場合は、先に無効化してから調査する。
  • チームはゲートウェイ経由に統一し、リクエストログを残して監査できるようにする。
  • 機密リポジトリでは、データが PC の外に出るか、どのサービスに流れるかを事前に確認する。

九、よくある質問

Cursor は任意の OpenAI 互換インターフェースに対応していますか？

必ずしも対応しているわけではありません。使えるかどうかは、Cursor のバージョンに Override OpenAI Base URL があるか、およびインターフェースが実際に呼び出すパスとパラメータに互換性があるかによります。まず通常の会話で確認し、その後 Agent 機能を試してください。

自分のキーを入力したのに、なぜサブスクリプションが必要と表示されるのですか？

独自キーはすべての機能を解放するものではありません。一部のエディター機能、チーム管理、内蔵モデルは引き続きプランの制限を受けます。Cursor の現在のプラン規則を基準にしてください。

Tab 補完で自分のキーが消費されないのはなぜですか？

Cursor のヘルプページによると、Tab 補完は常に Cursor 内蔵モデルを使用し、独自キーを通りません。これは製品設計であり、設定ミスではありません。

Base URL はルートアドレスと /v1 のどちらを入力しますか？

OpenAI 互換プロトコルを使う場合は /v1 まで入力します。/chat/completions は付けないでください。パスの重複や 404 が発生しやすくなります。

チームで 1 つのキーを共有できますか？

技術的には可能ですが、おすすめしません。共有キーではメンバーごとの利用量を区別できず、漏えい時の特定も難しくなります。1 人 1 キーにして、上限とログを組み合わせるほうが安全です。

次のステップ

まずZSQH AI Gateway に登録し、Cursor 専用のキーを作成して、本記事に従って Base URL とモデルを入力してください。通常の会話が通ったら、モデル料金を見て主力モデルと上限を調整します。

関連情報：