How to Point Cursor, Claude Code, and Codex at a Custom API Endpoint

Every major AI coding tool in 2026 supports custom API endpoints. That means you can point Cursor, Claude Code, OpenAI Codex, and Zed at your own gateway — whether that's a self-hosted proxy, a commercial LLM router, or a unified API layer — and route every request through a single base URL. This gives you provider fallback, cost tracking, model-level access control, and a single API key to manage across your team.

This guide covers the exact configuration steps for each tool, the common gotchas that trip up first-time setups, and a production checklist for teams deploying custom endpoints at scale.

OpenAI-compatible means a provider exposes a chat-completions endpoint whose request and response shape matches the OpenAI API contract closely enough that an unmodified OpenAI SDK call works against it after swapping three values: API key, base URL, and model name. The minimum surface in practice is POST /v1/chat/completions with messages, model, and an OpenAI-shaped streaming response.

Why Use a Custom API Endpoint

Before diving into configuration, here's why teams replace default provider URLs with a custom endpoint:

• Multi-provider fallback. If OpenAI returns a 429 or 503, your router can automatically retry through Anthropic, DeepSeek, or DashScope — without changing your code. See our model fallback routing guide for the full pattern.
• Unified billing. One invoice instead of five. One set of API keys instead of one per provider.
• Model-level access control. Decide which models each team or project can use, enforce budget caps, and audit every request.
• Cost optimization. Route cheap tasks to affordable models and expensive tasks to frontier models — through a single base_url. Our cost optimization strategies guide covers this in depth.
• Observability. See every request, latency, token count, and error in one dashboard instead of checking five provider consoles.

If you only use one provider and don't need routing, a custom endpoint adds complexity without benefit. But the moment you use two or more providers — or want team-level controls — a gateway pays for itself quickly.

Step 1: Cursor Custom API Endpoint Configuration

Cursor supports custom OpenAI-compatible endpoints through its built-in settings UI. The configuration lives in Cursor Settings → Models.

Setup Steps

1. Open Cursor and press Cmd+Shift+J (macOS) or Ctrl+Shift+J (Windows/Linux) to open Cursor Settings.
2. Navigate to the Models section.
3. Toggle OpenAI API Key to enabled and enter your gateway API key.
4. Toggle Override OpenAI Base URL to enabled.
5. Enter your custom endpoint URL — for example, https://your-gateway.example.com/v1.
6. Add your custom model names in the model list. Click + Add Model and type the model ID your gateway expects (e.g., gpt-5.6-terra, claude-opus-4, deepseek-v4-flash).
7. Click Verify to confirm the connection works.

Cursor-Specific Gotchas

HTTP/2 compatibility. If you see connection errors after setting the base URL, go to Cursor Settings → Network → HTTP Compatibility Mode and switch to HTTP/1.1. Many reverse proxies and gateways don't support HTTP/2, and Cursor defaults to it. This is the single most common failure point reported on Cursor's community forum.

Not all features use your key. Even with a custom API key enabled, some Cursor features — including Tab Completion and Apply from Chat — still use Cursor's own backend models. Your custom endpoint only handles chat and agent requests for models you've explicitly added.

Model ID mapping. Cursor sends the exact model ID you typed in the model list. If your gateway expects openai/gpt-5.6-terra but you typed gpt-5.6-terra, the request will fail. Match the ID your gateway expects.

Subagent limitation. Custom models configured via base URL override may not be available in Cursor's subagent flows. If your background agents silently fall back to Cursor-managed models, this is a known limitation as of mid-2026.

Step 2: Claude Code Custom Endpoint Configuration

Claude Code supports custom endpoints through environment variables. The two key variables are:

Setup Steps

Option A: Shell environment (quick start)

export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"
export ANTHROPIC_API_KEY="your-gateway-key"
claude

Option B: Claude Code settings file (persistent)

Add the variables to ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com/v1",
    "ANTHROPIC_API_KEY": "your-gateway-key"
  }
}

Option C: Managed settings for teams

For enterprise deployments, distribute a managed settings file with your gateway URL baked in. Claude Code's LLM gateway documentation describes how to push this through your configuration management system so every developer gets the same endpoint automatically.

Claude Code Gotchas

Native Anthropic format vs OpenAI-compatible. Claude Code speaks the Anthropic Messages API by default, not OpenAI's chat completions format. If your gateway only handles OpenAI-compatible requests, you need a gateway that can translate between the two formats — or use a provider like Anthropic directly.

OPENAI_BASE_URL for OpenAI models in Claude Code. If you want Claude Code to call OpenAI models (via the --model flag with an OpenAI model ID), set OPENAI_BASE_URL instead. Claude Code uses the right base URL variable depending on which provider the model belongs to.

AWS Bedrock and Google Vertex. Claude Code also supports CLAUDE_CODE_USE_BEDROCK=1 and CLAUDE_CODE_USE_VERTEX=1 environment variables for cloud-hosted Claude. If you're routing through AWS or Google, use those instead of ANTHROPIC_BASE_URL.

Step 3: OpenAI Codex CLI Custom Endpoint Configuration

OpenAI's Codex CLI reads its configuration from ~/.codex/config.toml. Custom endpoints are set up as named model providers.

Setup Steps

1. Install Codex CLI:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

2. Create or edit ~/.codex/config.toml:

model = "gpt-5.6-terra"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://your-gateway.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"

[projects."/path/to/your/project"]
trust_level = "trusted"

3. Set your API key:

export MY_GATEWAY_API_KEY="your-gateway-key"

4. Run Codex:

codex

Codex Gotchas

wire_api setting. Codex supports two wire formats: "responses" (OpenAI's newer Responses API) and "chat_completions" (the standard /v1/chat/completions). If your gateway only handles chat completions, set wire_api = "chat_completions". Getting this wrong produces cryptic 404 errors because Codex tries to POST to /v1/responses instead.

Profiles for multiple endpoints. Codex supports named profiles in config.toml. You can define multiple [model_providers.*] blocks and switch between them with codex --profile <name>. This is useful when you have separate gateways for dev and production.

Stream idle timeout. For long-running reasoning requests, increase stream_idle_timeout_ms in your provider config. The default may be too short for models that think for 30+ seconds before responding:

[model_providers.my-gateway]
stream_idle_timeout_ms = 120000
stream_max_retries = 5

Step 4: Zed Editor Custom Endpoint Configuration

Zed supports custom OpenAI-compatible providers through its settings JSON.

Setup Steps

1. Open Zed Settings (Cmd+, on macOS).
2. Navigate to Agent Settings and add a custom OpenAI-compatible provider.
3. Or edit ~/.config/zed/settings.json directly:

{
  "language_models": {
    "openai": {
      "api_url": "https://your-gateway.example.com/v1",
      "available_models": [
        {
          "name": "gpt-5.6-terra",
          "display_name": "GPT-5.6 Terra (via Gateway)",
          "max_tokens": 128000
        }
      ]
    }
  }
}

4. Set the API key via the OPENAI_API_KEY environment variable or through Zed's credential storage.

Zed Gotchas

Provider-specific blocks. Zed has separate configuration blocks for different providers (openai, anthropic, google). If your gateway handles multiple providers through one base URL, configure it under the openai block since that's the one that supports custom api_url.

Model availability. You must explicitly list available models in the available_models array. Zed doesn't auto-discover models from the gateway.

Common Issues Across All Tools

Auth Header Format

Most coding tools send the API key as a Bearer token in the Authorization header:

Authorization: Bearer sk-your-key-here

If your gateway expects a different auth scheme (e.g., a custom header like X-Api-Key), you'll need a thin proxy layer in front that translates the header. Most commercial gateways and routers accept standard Bearer tokens.

Model ID Mapping

The model ID your tool sends must exactly match what your gateway expects. Common mismatches:

Streaming Compatibility

All four tools default to streaming responses (stream: true). Your gateway must support Server-Sent Events (SSE) streaming. If it only supports non-streaming, you'll see timeout errors or empty responses. Check your gateway's documentation for streaming support.

Rate Limits and Retries

When routing through a gateway, you get the gateway's rate limits, not the underlying provider's. If your gateway has a 60 RPM limit and your Cursor agent sends 80 requests per minute, you'll hit 429 errors even if the provider would allow it. Configure your gateway's rate limits to match your expected usage. See our rate limit comparison for provider-by-provider details.

Production Checklist for Teams

Before rolling out custom endpoints to your team, verify each item:

• Gateway is accessible from all developer machines (VPN, firewall rules, DNS).
• SSL certificate is valid and trusted. Self-signed certs cause silent failures in most tools.
• API key rotation is possible without updating every developer's local config. Use environment variables or a secrets manager.
• Model IDs are documented. Publish a list of available model IDs and which provider backs each one.
• Fallback behavior is tested. Simulate a provider outage and confirm your gateway routes to the backup.
• Streaming works end-to-end. Send a long prompt and verify tokens arrive incrementally.
• HTTP/1.1 mode is enabled in Cursor if your gateway doesn't support HTTP/2.
• Cost monitoring is in place. Check that your gateway's dashboard shows per-model, per-user token usage.
• Rate limits are configured to match your team size and usage patterns.
• Timeout values are appropriate for reasoning models that may think for 60+ seconds.

TheRouter Integration Note

TheRouter routes OpenAI-compatible requests through configured providers and supports provider/model routing and fallback. To point any of the coding tools above at TheRouter:

1. Use your TheRouter base URL as the custom endpoint (e.g., https://api.therouter.ai/v1).
2. Use your TheRouter API key as the API key.
3. Use model IDs from TheRouter's model catalog — these map to the underlying providers automatically.

TheRouter handles model-to-provider resolution, so you don't need to worry about provider prefixes. A single base_url gives you access to OpenAI, Anthropic, DeepSeek, DashScope, and other providers through one endpoint. For the full migration walkthrough, see our OpenAI-to-TheRouter migration guide.

FAQ

Can I use the same custom endpoint for all four tools?

Yes, if your gateway speaks the OpenAI-compatible chat completions format. Cursor, Codex, and Zed all use the OpenAI wire format. Claude Code uses the Anthropic format by default, so your gateway needs to handle both — or you configure Claude Code to use an OpenAI-compatible model through OPENAI_BASE_URL.

Will my gateway see all my code?

Yes. Every prompt your coding tool sends — including file contents, instructions, and context — passes through your gateway. Choose a gateway you trust with your codebase. For security considerations, see our coding agent governance guide.

What happens if my gateway goes down?

Most tools will show a connection error and stop working until the gateway is back. They don't automatically fall back to the provider's direct endpoint. Some gateways support health checks and automatic failover to backup endpoints — configure those at the gateway level, not in the coding tool.

Does this work with local models (Ollama, vLLM)?

Yes. Any endpoint that speaks the OpenAI chat completions format works. Point the base URL at http://localhost:11434/v1 for Ollama or your vLLM server's URL. Model IDs must match what your local server serves.

---

Sources: Cursor Settings & Custom API Keys (retrieved 2026-07-29), Claude Code environment variables (retrieved 2026-07-29), Claude Code LLM gateway docs (retrieved 2026-07-29), OpenAI Codex CLI advanced configuration (retrieved 2026-07-29), LiteLLM Codex tutorial (retrieved 2026-07-29), Zed API access docs (retrieved 2026-07-29), Cursor forum: Override Base URL issues (retrieved 2026-07-29), Cursor forum: Subagent limitation (retrieved 2026-07-29)