← Back to Blog

Override OpenAI Base URL in Cursor: The Complete Configuration Guide (2026)

2026-07-18·13 min read·CodeRouter Team
override openai base urlcursor custom model configurationcursor override openai base urlcustom model settings cursorcursor configuration guidecursor custom api endpointcursor byok setup

TL;DR — Cursor's "Override OpenAI Base URL" setting lets you redirect all OpenAI-format traffic through any OpenAI-compatible endpoint — your own proxy, a cost-saving router, or an alternative provider like DeepSeek. This guide walks through the full custom model configuration: what the override does, when you'd want it, step-by-step setup for the most common providers, the model settings that matter, and how to verify everything works. If you've already hit errors with the override, see our companion troubleshooting article for the specific failure modes.

What "Override OpenAI Base URL" Actually Does

Before configuring anything, it helps to understand the mechanism.

By default, when you use Cursor with your own OpenAI API key (BYOK), requests go directly to https://api.openai.com/v1. The Override OpenAI Base URL setting replaces that destination with any URL you choose — as long as the endpoint speaks the OpenAI chat completions protocol (POST /chat/completions with the standard request body).

This means you can point Cursor at:

The override applies to all traffic that would otherwise go to OpenAI. It does not affect Cursor's built-in subscription models or features like Tab autocomplete, which use Cursor's own backend regardless of your settings.

When to Use the Override

You'd configure the override when you want to:

  1. Use a cheaper or faster provider — route through DeepSeek V4, Gemini, or a mix
  2. Control costs with a router — let a smart proxy pick the right model per task
  3. Run models locally — point at Ollama or vLLM for offline or air-gapped development
  4. Comply with data policies — route through an auditing proxy before requests reach any provider
  5. Access multiple providers through one endpoint — instead of managing separate API keys for OpenAI, Anthropic, Google, and DeepSeek, use a single router that translates between protocols

When NOT to Use It

Skip the override if:

Step-by-Step: Cursor Custom Model Configuration

Step 1: Open Cursor Model Settings

  1. Open Cursor
  2. Press Cmd+Shift+J (macOS) or Ctrl+Shift+J (Windows/Linux) to open Settings
  3. Navigate to Models (in the sidebar or search for "models")
  4. Scroll to the API Keys section

You'll see fields for:

Step 2: Enter Your API Key

Put your API key in the OpenAI API Key field. Even if you're not using OpenAI directly, this is the field Cursor uses for the overridden endpoint's authentication.

For example:

Step 3: Enable and Set the Override URL

  1. Check the "Override OpenAI Base URL" checkbox
  2. Enter your endpoint URL in the field that appears

The URL format matters. Most providers expect the base URL without a trailing /chat/completions — Cursor appends the path automatically.

✅ Correct formats:
https://api.deepseek.com/v1
https://www.coderouter.io/api/v1
http://localhost:11434/v1
https://api.together.xyz/v1

❌ Wrong formats:
https://api.deepseek.com/v1/chat/completions  (Cursor appends this)
https://api.deepseek.com                       (missing /v1 path)

Step 4: Configure Model Names

This is the part most guides skip, and it's where custom model settings in Cursor get interesting.

After setting the override URL, you need to tell Cursor which model names to send. Go to the model dropdown in the chat panel — by default you'll see standard models like gpt-4o, claude-sonnet-4-6, etc.

The key insight: the model name Cursor sends in the request must be one that your endpoint recognizes. If your endpoint is DeepSeek, sending gpt-4o won't work. If it's a router, it depends on what the router supports.

To add custom models:

  1. In the Models settings, scroll to Model Names
  2. Click + Add Model
  3. Type the model identifier your endpoint expects — e.g., deepseek-chat, deepseek-reasoner, auto, or claude-sonnet-4-6
  4. The model will appear in Cursor's model dropdown for chat and Composer

Step 5: Verify the Connection

Click the Verify button next to your API key. Cursor will make a test request to your overridden endpoint.

⚠️ Important caveat: the Verify button checks basic connectivity and authentication, but it doesn't test every feature path. After verifying, actually run a chat message with your selected model to confirm end-to-end functionality.

Provider-Specific Setup Guides

DeepSeek (Direct)

DeepSeek's API is natively OpenAI-compatible, making it the simplest override.

| Setting | Value | |---|---| | OpenAI API Key | Your DeepSeek API key (sk-...) | | Override OpenAI Base URL | https://api.deepseek.com/v1 | | Model name to add | deepseek-chat or deepseek-reasoner |

Notes:

Ollama (Local Models)

Run models locally with zero API costs.

| Setting | Value | |---|---| | OpenAI API Key | ollama (any non-empty string) | | Override OpenAI Base URL | http://localhost:11434/v1 | | Model name to add | Whatever you've pulled — e.g., llama3.1, codestral, qwen2.5-coder |

Setup prerequisite:

# Install Ollama
brew install ollama   # macOS
# or curl -fsSL https://ollama.com/install.sh | sh

# Pull a coding model
ollama pull qwen2.5-coder:32b

# Ollama serves on localhost:11434 by default

Notes:

Together AI / Fireworks / Groq

These providers all offer OpenAI-compatible endpoints with their own model catalogs.

Together AI:

| Setting | Value | |---|---| | Override OpenAI Base URL | https://api.together.xyz/v1 | | Model names | meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo, etc. |

Fireworks:

| Setting | Value | |---|---| | Override OpenAI Base URL | https://api.fireworks.ai/inference/v1 | | Model names | accounts/fireworks/models/llama-v3p1-405b-instruct, etc. |

Groq:

| Setting | Value | |---|---| | Override OpenAI Base URL | https://api.groq.com/openai/v1 | | Model names | llama-3.1-70b-versatile, mixtral-8x7b-32768, etc. |

Multi-Provider Router (CodeRouter)

If you want access to models from multiple providers (OpenAI, Anthropic, Google, DeepSeek) through a single endpoint, a routing proxy is the cleanest approach.

| Setting | Value | |---|---| | OpenAI API Key | Your CodeRouter API key | | Override OpenAI Base URL | https://www.coderouter.io/api/v1 | | Model name to add | auto (phase-aware routing) or specific model IDs |

Why use a router instead of direct provider access:

  1. One endpoint, all models — Claude, GPT, DeepSeek, Gemini all accessible through the same override URL. No need to toggle settings when switching models
  2. Automatic model selection — auto mode analyzes each request and routes to the best model for the task (planning → Opus, implementation → Sonnet/DeepSeek)
  3. Cost optimization — smart routing can cut costs 50–80% while maintaining output quality
  4. Protocol translation — the router converts OpenAI-format requests to each provider's native API, so Anthropic models work without the 422 errors that plague direct override setups

This is particularly useful for the Cursor override because it sidesteps the biggest limitation: the override only speaks OpenAI protocol, but many top models (Claude, Gemini) use different APIs. A router bridges that gap.

Check CodeRouter's pricing for current rates — there's a free tier for trying it out.

Anthropic Models via the Override

Cursor has a dedicated Anthropic API Key field. If all you want is Claude with your own key, use that — don't use the OpenAI override.

But if you want Claude and other models through a single override endpoint, you need a translation layer. Cursor's override sends OpenAI-format requests. Anthropic's API expects a completely different schema (/v1/messages with a different body format). Sending OpenAI-shaped requests directly to https://api.anthropic.com will fail.

Your options:

  1. Use a router (CodeRouter, LiteLLM) that accepts OpenAI format and translates to Anthropic's API
  2. Run a local proxy like LiteLLM that does the same translation on your machine
  3. Don't mix — use the Anthropic BYOK field for Claude and the override for everything else (but be aware of the interaction bugs)

Advanced Custom Model Configuration Settings

Adjusting Model Parameters

Cursor passes standard OpenAI parameters in its requests. Depending on your endpoint, you can influence behavior through:

Managing Multiple Configurations

Cursor doesn't support multiple override URLs simultaneously. You can only have one active override at a time. If you need to switch between providers:

Option A: Switch manually — Change the URL and API key in settings when you want a different provider. Tedious but works.

Option B: Use a router — Point the override at one router endpoint and select models through the model dropdown. The router handles dispatching to different providers. This is the "set it and forget it" approach.

Option C: Use .cursor/settings.json — For per-project configuration, you can create a .cursor/settings.json file in your project root. This lets different projects use different endpoints:

{
  "openai.baseUrl": "https://www.coderouter.io/api/v1",
  "openai.model": "auto"
}

What the Override Doesn't Affect

Important to understand the boundaries of custom model settings in Cursor:

Only the chat/completion traffic that would normally go to OpenAI's API gets redirected.

Troubleshooting

Common Issues and Fixes

"422 Unprocessable Entity" errors

Your endpoint received a request it can't parse. Common causes:

Fix: Double-check the URL and model name. See our detailed 422 debugging guide.

"401 Unauthorized" errors

Authentication failed. Check:

Responses are empty or truncated

Override seems to have no effect

Claude models stopped working after setting the override

This is the most common issue. The override redirects Claude traffic through the OpenAI-format endpoint, where it fails because Anthropic uses a different API schema. See the full explanation and fix.

Verifying Traffic Flow

If you have access to your endpoint's logs, the most reliable way to debug is to check what's actually arriving:

  1. Make a chat request in Cursor
  2. Check your endpoint's request log for the incoming request
  3. Verify the model field matches what you expect
  4. Verify the Authorization header contains your key
  5. Check the response status code

For local setups (Ollama, LiteLLM), you can watch the terminal output in real time.

FAQ

Can I use the override with Cursor's free tier?

The override applies to BYOK (Bring Your Own Key) usage, which works on any Cursor tier including free. You provide your own API key and pay the provider directly — Cursor doesn't charge for BYOK requests.

Does the override work with Cursor's Agent/Composer mode?

Yes — Composer and the agent features use the same chat completions path. If you have the override set with a valid endpoint, agent mode will route through it. However, some internal agent capabilities may still use Cursor-hosted models for specific sub-tasks.

Can I use different models for different tasks?

Not through the override alone (it's one URL). But if you point the override at a router like CodeRouter with auto model selection, the router picks the best model per request — reasoning models for planning, faster models for implementation, cheaper models for routine edits.

Will the override work with future Cursor updates?

Cursor's override feature has been stable across updates, but the interaction with other settings (especially Anthropic BYOK) has had bugs. After any Cursor update, it's worth verifying your setup still works as expected. Check the Cursor changelog and the Cursor forum for known issues.

How is this different from the Anthropic/Google Base URL override?

Cursor also has override fields for Anthropic and Google base URLs. These work similarly but use the respective provider's native API format. The OpenAI base URL override is the most versatile because the OpenAI chat completions protocol has become the industry standard — virtually every alternative provider and proxy supports it.

Can I use this for compliance / request logging?

Yes — this is one of the strongest use cases. Point the override at a logging proxy that records every request/response, then forwards to the actual provider. You get a full audit trail of all LLM interactions from Cursor. Just make sure your proxy supports streaming responses.

What's the difference between this guide and the troubleshooting article?

This guide covers how to set up the override from scratch — the happy path. Our companion article covers what goes wrong — the specific failure modes when the override interacts with Anthropic BYOK keys, the 422 errors, and the auto-toggle bug.

Summary

Setting up Cursor's Override OpenAI Base URL is straightforward once you understand the model:

  1. Enter your API key in the OpenAI key field
  2. Enable the override and set your endpoint URL (with /v1 path, without /chat/completions)
  3. Add model names that your endpoint recognizes
  4. Verify with the button, then test with an actual chat message
  5. Avoid mixing the override with Anthropic BYOK keys unless you're using a router that handles the protocol translation

For the simplest multi-provider setup, point the override at a router like CodeRouter that translates between protocols automatically — one endpoint, one key, all models, no 422s.

Related: Cursor "Override OpenAI Base URL" Breaks Claude — What Works and What Doesn't · Cut Your Cursor Bill 83% in 12 Hours

Ready to Reduce Your AI API Costs?

CodeRouter routes every API call to the optimal model — automatically. Start saving today.

Get Started Free →

Related Articles

Kimi K3 for AI Coding Agents: Pricing, Benchmarks, and Where It Actually Fits in Your Routing Stack

2026-07-18 · 7 min read

Claude Code 401 With a Custom Base URL: ANTHROPIC_API_KEY vs ANTHROPIC_AUTH_TOKEN

2026-07-05 · 4 min read

Cursor "Override OpenAI Base URL" Breaks Claude Models — What Works and What Doesn't

2026-07-05 · 4 min read

Get weekly AI cost optimization tips

Join 2,000+ developers saving on LLM costs