How to Connect Cursor to OpenRouter: Setup, Feature Boundaries, and Troubleshooting
Configure Cursor for OpenRouter, prove routing with Activity records, test Chat, Agent, Tab, and tools separately, and troubleshoot endpoint, model, credit, and rate-limit failures.
Contents
The key point is simple: a successful reply in Cursor does not prove that every Cursor feature is using OpenRouter. As of October 4, 2026, OpenRouter still labels its Cursor integration as Beta and requires the dedicated base URL https://openrouter.ai/api/v1/cursor. Model requests in Chat and Agent can use that route when you manually select an OpenRouter model. Tab completion does not use your custom API key, and tool calling works only when both the endpoint and the selected model support it.
The right acceptance test is therefore not “paste a key and get an answer.” It is a chain of evidence: correct settings → manually selected model → minimal request → matching OpenRouter Activity record → separate Agent and tool checks. This guide is based on the current official documentation. It does not claim access to a live account, API key, request log, or a complete end-to-end test of one specific Cursor build.
Which Cursor features actually use the custom key?
| Cursor feature | Expected OpenRouter routing | Important boundary | Best verification method |
|---|---|---|---|
| Manually selected model in Chat or Ask | Usually yes | The model must be available through OpenRouter’s OpenAI-compatible path | Send a minimal prompt and match time plus model in Activity |
| Manually selected model in Agent | The model call usually routes; not every internal action is proven | OpenRouter documents model selection in the Agent panel, but not every auxiliary request | Observe both the Activity record and Cursor’s visible tool actions |
| Tab completion | No | Cursor and OpenRouter say Tab continues to use Cursor’s built-in models | Never use Tab suggestions as proof that OpenRouter is active |
| Agent tool calling | Conditional | Use the dedicated /cursor endpoint and a model that supports tools | Establish Chat first, then run a read-only Agent task and check Activity |
| Automatic model selection | Poor acceptance-test evidence | The client may choose a different path or model | Turn automatic selection off and choose the added model explicitly |
The most important distinction is between a model request and tool execution. OpenRouter’s tool-calling documentation explains that the model proposes a tool call; the client executes the tool and sends the result back. An Activity record can prove that the model request reached OpenRouter, but it does not by itself prove that a file read, terminal command, or other local action ran on OpenRouter.
What to prepare before setup
You need four things:
- A current Cursor client with access to
Cursor Settings→Models→API Keys. - Your own OpenRouter API key. Do not paste it into chat, a repository, screenshots, or support messages.
- An exact Model ID copied from the current OpenRouter catalog rather than guessed from a display name.
- For Agent tools, a model confirmed in the tool-capable model filter.
Cursor’s labels can change between versions. Your build may show an enable, save, confirmation, or verification control. The relationship between the fields is what matters: the OpenRouter key belongs in OpenAI API Key, the dedicated endpoint belongs in Override OpenAI Base URL, and the model must use an exact OpenRouter ID.
Configure Cursor in the correct order
1. Open the API key settings
Go to Cursor Settings → Models, expand API Keys, and locate OpenAI API Key plus Override OpenAI Base URL.
2. Enter the OpenRouter key
Paste the key created in your OpenRouter account into OpenAI API Key. Enter it only in Cursor’s settings UI. Complete whichever save, enable, or validation action your current client presents.
3. Use the dedicated Cursor endpoint
Enable Override OpenAI Base URL and enter:
https://openrouter.ai/api/v1/cursor
Do not replace it with the generic https://openrouter.ai/api/v1, and do not append /chat/completions. OpenRouter says the dedicated /cursor endpoint normalizes Cursor’s request format. With the generic endpoint, tool calls and some request shapes may fail.
4. Add the exact model ID
In Models, choose + Add model and copy the complete ID from the current OpenRouter model page. If you use a router alias, copy its full current syntax as shown in the catalog. Do not rely on a marketing name, abbreviation, or an ID copied from an old tutorial.
5. Select the model manually
Return to the Chat or Agent panel and explicitly select the model you just added. Do not use automatic selection for the first acceptance test, because a reply alone would not reveal which route handled it.
How to prove the setup is active
Start with one minimal Chat request that does not expose code or secrets, such as asking for a fixed short response. Immediately open OpenRouter Activity and check:
- the timestamp matches your test;
- the recorded model matches the Model ID selected in Cursor;
- the request succeeded and produced usage data;
- your internal test note does not contain the API key, full prompt, or sensitive code.
A response in Cursor is weak evidence; a matching Activity entry is stronger routing evidence. If Cursor responds but Activity has no corresponding request, mark the route as unconfirmed and investigate before calling the setup complete.
Record only the time, model, status, and a necessary request identifier. For team rollouts, also record the Cursor version and test mode so a future Beta behavior change can be retested cleanly.
Test Chat, Agent, Tab, and tools separately
Chat: establish a baseline first
Manually select the OpenRouter model and send a short deterministic prompt. Chat passes only after a matching Activity record appears. If this fails, do not move on to Agent yet; Agent adds model, tool, permission, and context variables.
Agent: verify the model request without overstating the route
Use a disposable or easily reversible repository. Ask Agent to perform a low-risk task, such as reading a README and proposing improvements, before allowing writes or destructive commands. Check two independent signals:
- OpenRouter Activity contains the model request.
- Cursor visibly reports the expected file-read or other tool action.
The first proves model routing. The second proves Cursor’s Agent orchestration is working. One does not prove the other. The official material does not establish that every background or helper request in Agent always uses the same custom key, so do not extrapolate all internal traffic from one successful run.
Tab: use the correct expectation
Typing code and seeing a Tab suggestion tests Cursor’s Tab system only. The official docs say custom keys work with chat models while Tab continues to use Cursor’s built-in models. “Chat appears in OpenRouter Activity, but Tab does not” is expected behavior, not a routing defect.
Tool calling: validate endpoint and model support together
After plain Chat passes, choose a model whose catalog data includes tools. In a test repository, ask Agent for a read-only action such as listing files or reading a small file. If tools fail while text Chat works, check these items in order:
- the base URL is exactly
https://openrouter.ai/api/v1/cursor; - the selected model explicitly supports
tools; - Cursor did not switch to another model automatically;
- the tool permission was not denied inside Cursor;
- a second known tool-capable model shows the same failure.
Troubleshoot by symptom
| Symptom | Likely cause | Cheapest first check | Retest after the fix |
|---|---|---|---|
| Key rejected or authentication failure | Invalid, revoked, whitespace-padded key, or provider/key mismatch | Recopy the active OpenRouter key and confirm the endpoint belongs to the same provider | Restart the session, send the minimal Chat request, and check Activity |
| Model not found or 404 | Wrong Model ID, incomplete alias syntax, or an unavailable compatible endpoint | Copy the complete current ID from the catalog | Select it manually and repeat the same prompt |
| Chat works but Agent tools fail | Generic /api/v1 endpoint or a model without tool support | Check the /cursor suffix and supported_parameters=tools | Run one read-only tool task and inspect Activity |
| Chat works but Tab is absent from Activity | Tab does not use the custom key | Do not change the key or endpoint | Accept Chat and Tab as separate features |
| 402 response | Insufficient account credits, per-key cap, or in-flight budget | Review the OpenRouter key/credit page and error metadata | Wait for in-flight requests, reduce the request, or add credit, then retry |
| 429 response | OpenRouter platform limit or upstream provider throttling | Inspect Retry-After and rate-limit headers; do not resend immediately | Wait with exponential backoff, then retry or choose another available route |
| Cursor replies but Activity has no record | Built-in model, automatic routing, or settings not applied | Manually select the added model and reopen the key/base URL settings | Restart the session and repeat the minimal request |
| Required fields are missing from settings | Cursor version, account plan, or UI behavior changed | Update Cursor and open the current Cursor BYOK documentation | Recreate the same field relationship in the current UI and retest |
For 429 errors, follow the OpenRouter limits guide, honor Retry-After, and use exponential backoff. Creating more keys is not a reliable way to bypass globally governed capacity. For tool failures, fix the endpoint and model capability before changing advanced Agent settings.
BYOK is not a direct browser-to-OpenRouter connection
Cursor’s BYOK documentation says requests still pass through Cursor’s backend for final prompt construction. Teams handling sensitive code should therefore review both Cursor’s current data practices and the selected provider’s policies. Do not put real keys, customer data, or private source code into troubleshooting screenshots; use a sanitized minimal reproduction when possible.
Plans, billing rules, and UI availability can change. This article does not treat a present limitation as permanent. Before a production rollout, reopen the official Cursor and OpenRouter pages and confirm the behavior for that date.
BetterToken is a separate configuration path
If your goal is an OpenAI-compatible gateway rather than OpenRouter specifically, BetterToken documents a separate Cursor setup. Its base URL is https://www.bettertoken.ai/v1, and it must be paired with a BetterToken API key and BetterToken Model ID.
Do not pair an OpenRouter key with the BetterToken endpoint, or a BetterToken key with https://openrouter.ai/api/v1/cursor. The two configurations are independent. When switching providers, repeat the minimal Chat request and verify usage in the corresponding provider’s dashboard.
Final acceptance order
Use this sequence: configure one model → select it manually → send one minimal Chat request → find the Activity record → test Agent and tools → accept Tab as a separate built-in feature. By adding only one variable at a time, failures resolve to a specific layer—endpoint, key, model, tool capability, credit, or rate limit—instead of becoming a vague “Cursor does not work” problem.
