CursorをOpenRouterに接続する方法：設定、機能の境界、トラブルシューティング
CursorをOpenRouterへ設定し、Activityで経路を確認する方法を解説します。Chat、Agent、Tab、toolsを個別に検証し、エンドポイント、モデル、クレジット、レート制限の問題を切り分けます。
目次
最初に結論です。Cursorで返答が得られても、すべての機能がOpenRouterを使っている証拠にはなりません。 2026年10月4日時点で、OpenRouterはCursor連携をBetaとし、専用Base URL https://openrouter.ai/api/v1/cursor の使用を求めています。OpenRouterのモデルを手動で選んだ場合、ChatとAgentのモデル呼び出しはこの経路を利用できます。一方、Tab CompletionはカスタムAPI Keyを使わず、tool callingは専用エンドポイントとモデルのtools対応の両方が必要です。
正しい受け入れ確認は「Keyを入れて返答を見る」だけではありません。設定を確認 → モデルを手動選択 → 最小リクエスト → OpenRouter Activityの一致記録 → Agentとtoolsを個別確認という証拠の流れを作ります。本稿は現行の公式ドキュメントに基づき、特定アカウント、API Key、リクエストログ、Cursorバージョンでの完全な実機検証を行ったとは主張しません。
どの機能がカスタムKeyを使うのか
| Cursor機能 | OpenRouter経由の見込み | 重要な境界 | 確認方法 |
|---|---|---|---|
| Chat / Askで手動選択したモデル | 通常は経由する | OpenRouterのOpenAI-compatible経路で利用可能なモデルに限る | 最小プロンプトを送り、Activityの時刻とモデルを照合 |
| Agentで手動選択したモデル | モデル呼び出しは通常経由するが、全内部処理は未証明 | 公式ガイドはAgentでのモデル選択を示すが、全補助リクエストは説明しない | Activity記録とCursor上のtool動作を別々に見る |
| Tab Completion | 経由しない | Cursor内蔵モデルを使い続ける | Tab候補をOpenRouter有効化の証拠にしない |
| Agentのtool calling | 条件付き | /cursorとtools対応モデルが必要 | Chat確認後に読み取り専用タスクで検証 |
| 自動モデル選択 | 受け入れ確認には不向き | 別モデルや別経路が選ばれる可能性 | Autoを使わず追加モデルを明示選択 |
特に、モデルへのリクエストとツールの実行は別です。OpenRouterのtool calling資料では、モデルがツール呼び出しを提案し、クライアントが実行して結果をモデルへ返します。Activity記録はモデル呼び出しがOpenRouterを通った証拠になりますが、ファイル読み取りやローカルコマンド自体がOpenRouter上で実行された証拠ではありません。
設定前に用意するもの
Cursor Settings→Models→API Keysを開ける現行Cursor。- 自分のOpenRouter API Key。チャット、リポジトリ、スクリーンショット、サポート投稿には貼らないでください。
- 現在のOpenRouterカタログからコピーした正確なModel ID。
- Agentのtoolsを試す場合は、tool対応モデルの絞り込みで確認したモデル。
Cursorのバージョンにより、ボタン名は有効化、保存、確認、検証などに変わります。ただし対応関係は同じです。OpenRouterのKeyをOpenAI API Key、専用URLをOverride OpenAI Base URL、モデルを完全なOpenRouter IDとして設定します。
正しい順序で設定する
1. API Key設定を開く
Cursor Settings → Modelsへ進み、API Keysを展開してOpenAI API KeyとOverride OpenAI Base URLを探します。
2. OpenRouter Keyを入力する
OpenRouterアカウントで作成したKeyをOpenAI API Keyへ貼り付けます。入力先はCursorの設定画面だけにします。現在のクライアントが表示する保存、有効化、検証操作を完了してください。
3. Cursor専用エンドポイントを使う
Override OpenAI Base URLを有効にし、次を入力します。
https://openrouter.ai/api/v1/cursor
汎用のhttps://openrouter.ai/api/v1へ置き換えたり、/chat/completionsを追加したりしないでください。専用/cursorはCursorのリクエスト形式を正規化します。汎用エンドポイントではtool callsや一部形式が失敗する可能性があります。
4. 正確なModel IDを追加する
Modelsで+ Add modelを選び、現在のモデルページから完全なIDをコピーします。router aliasを使う場合も表示どおりの完全な記法を使います。製品名、略称、古い記事のIDから推測しないでください。
5. モデルを手動選択する
ChatまたはAgentへ戻り、追加したモデルを明示的に選びます。最初の確認では自動選択を使わないでください。返答だけでは、どの経路を通ったか分からないためです。
設定が有効だと証明する方法
コードや秘密情報を含まない最小のChatリクエストを送ります。固定の短い文だけ返すよう依頼する程度で十分です。直後にOpenRouter Activityを開き、次を確認します。
- 時刻がテストと一致する。
- 記録されたモデルがCursorで選んだModel IDと一致する。
- リクエストが成功し、usage情報がある。
- 社内記録にAPI Key、完全なPrompt、機密コードを残していない。
Cursorの返答は弱い証拠で、Activityの一致記録がより強い経路証拠です。 返答があっても記録がなければ、「経路未確認」と扱ってください。
チームで記録する場合は、時刻、モデル、状態、必要なRequest ID、Cursorバージョン、テストモードだけを残します。Betaの挙動が変わったときに再確認しやすくなります。
Chat、Agent、Tab、toolsを分けて試す
Chat：最初に基準を作る
モデルを手動選択し、短く決定的なプロンプトを送ります。対応するActivity記録が出て初めてChat合格です。ここで失敗する間はAgentへ進まないでください。Agentはコンテキスト、権限、ツールという変数を増やします。
Agent：モデル経路とオーケストレーションを分ける
破棄可能、または簡単に戻せるテストリポジトリを使います。まずREADMEを読んで改善案を出すなど、書き込みや危険なコマンドを伴わない作業を依頼します。次の二つを別々に確認します。
- OpenRouter Activityにモデルリクエストがある。
- Cursorが期待したファイル読み取りなどのtool動作を表示する。
一つ目はモデル経路、二つ目はCursor Agentのオーケストレーションを示します。公式資料はAgentの全バックグラウンド要求が常に同じカスタムKeyを使うとは証明していません。一回の成功を全内部トラフィックへ一般化しないでください。
Tab：Activityに出ないのが正常
Tab候補はCursorのTab Completionだけを確認します。公式資料では、カスタムKeyはchat models向けで、Tabは内蔵モデルを使います。「ChatはActivityに出るがTabは出ない」は正常です。
Tools：エンドポイントとモデル能力を同時確認
Chat合格後、カタログでtools対応が明示されたモデルを選びます。テストリポジトリで、ファイル一覧取得や小さなファイル読み取りなどの読み取り専用タスクを依頼します。テキストChatは動くのにtoolsが失敗する場合、次を順に確認します。
- Base URLが正確に
https://openrouter.ai/api/v1/cursorか。 - 選択モデルが
toolsを明示的にサポートするか。 - Cursorが別モデルへ自動切替していないか。
- Cursor内でtool権限を拒否していないか。
- 別のtool対応モデルでも再現するか。
症状別トラブルシューティング
| 症状 | 主な原因 | 最初の低コスト確認 | 修正後の再テスト |
|---|---|---|---|
| Key拒否・認証失敗 | 無効、失効、余分な空白、別ProviderのKeyとURLを混在 | 有効なKeyを再コピーしProviderを確認 | セッション再起動後に最小ChatとActivity確認 |
| Model not found / 404 | ID誤り、alias不足、互換経路で未提供 | 現行カタログから完全IDをコピー | 手動選択して同じPromptを再送 |
| Chatは動くがAgent toolsは失敗 | 汎用/api/v1またはtools非対応モデル | /cursorとsupported_parameters=toolsを確認 | 読み取り専用タスクとActivityを再確認 |
| Chatは動くがTabが記録されない | TabはカスタムKeyを使わない | KeyやURLを変えない | ChatとTabを別機能として受け入れる |
| 402 | クレジット、Key上限、in-flight budget不足 | Key/credit画面とerror metadataを確認 | 待機、リクエスト縮小、クレジット追加後に再試行 |
| 429 | OpenRouterまたはupstream providerの制限 | Retry-Afterとrate-limit headersを確認し即再送しない | Exponential backoff後に再試行、または別経路を選ぶ |
| Cursorは返答するがActivityなし | 内蔵モデル、Auto、設定未反映 | 追加モデルを手動選択しKeyとURLを再確認 | セッション再起動後に最小リクエスト |
| 必要な項目が見つからない | Cursorバージョン、プラン、UI変更 | Cursor更新と現行BYOK資料を確認 | 現行UIで同じ項目関係を作り再試験 |
429ではOpenRouterのlimits資料に従い、Retry-Afterを守ってexponential backoffを使います。Keyを増やしても全体容量を確実に回避できません。toolsの問題は、Agentの高度な設定より先にエンドポイントとモデル能力を直します。
BYOKはCursorからOpenRouterへの直接接続ではない
CursorのBYOK資料では、最終Promptの組み立てのためリクエストはCursor backendを経由します。機密コードを扱うチームはCursorと選択Providerの両方のデータ方針を確認してください。診断用スクリーンショットに実Key、顧客データ、非公開コードを含めず、匿名化した最小再現を使います。
プラン、課金、UIは変わり得ます。Production導入前に公式ページを再度開き、その日の挙動を確認してください。
BetterTokenは別の設定経路
OpenRouterではなく別のOpenAI-compatible gatewayが必要な場合、BetterTokenには独立したCursor設定ガイドがあります。Base URLはhttps://www.bettertoken.ai/v1で、BetterTokenのAPI KeyとModel IDを組み合わせます。
OpenRouter KeyをBetterToken endpointへ入れたり、BetterToken Keyをhttps://openrouter.ai/api/v1/cursorへ入れたりしないでください。Providerを切り替えたら、最小Chatと該当ダッシュボードのusage確認をやり直します。
最終的な受け入れ順序
一つのモデルを設定 → 手動選択 → 最小Chat → Activity記録 → Agentとtools → Tabは別の内蔵機能として確認の順に進めます。これなら問題をendpoint、Key、モデル、tools、credit、rate limitのどこかへ明確に切り分けられます。
