Cline VS Code Custom OpenAI-Compatible Provider Setup: Complete Guide

Setting up a custom OpenAI-compatible provider in Cline within VS Code takes about 2–5 minutes: navigate to Settings → Providers, choose "OpenAI Compatible," enter your Base URL, API key, and model ID, then click Verify. This configuration lets you bypass Cline's default providers to cut API costs, keep prompts inside your own network, and reach models absent from the built-in catalog. The walkthrough below reflects official Cline documentation and community sources as of May 2026 (Cline OpenAI-Compatible docs).

Why Use a Custom OpenAI-Compatible Provider in Cline?

Cline is one of the most widely used agentic coding extensions; its GitHub star count changes frequently, so confirm the current number on the official repository (github.com/cline/cline), and it supports VS Code, JetBrains (Early Access), Cursor, and Windsurf (Cline docs). It operates in BYOK (bring-your-own-key) mode, meaning there is no agent subscription fee — you pay only the underlying model API price (cline.bot). That architecture makes the provider choice the single most important cost and performance lever.

Three reasons developers switch to a custom OpenAI-compatible endpoint:

• Cost: coding-agent loops burn tokens quickly; routing through cheaper models can dramatically reduce spend. Check current rates on the official pricing pages (OpenAI API pricing, DeepSeek pricing), and consult third-party benchmarks for DeepSeek V4 vs GPT API cost estimates.
• Privacy and compliance: you can point Cline at a self-hosted gateway inside your VPC so prompts never leave your infrastructure, which matters for regulated industries (Cline enterprise docs).
• Model availability: built-in providers only expose models they officially list; a custom endpoint can expose internal runtimes, local servers (vLLM, llama.cpp, LiteLLM), or third-party hubs (vLLM OpenAI-compatible server, llama.cpp server, LiteLLM OpenAI-compatible docs). For developers in China, a regional gateway also avoids the connectivity problems discussed in our OpenRouter Alternatives for Chinese Models guide.

Prerequisites and Compatibility Check

Before you start, confirm the following:

• VS Code: any stable release from the past year, with the Cline extension installed from the marketplace (VS Code Marketplace).
• A valid endpoint: an HTTP(S) URL implementing the OpenAI /v1/chat/completions schema (OpenAI API reference). Most gateways and open-source LLM servers support this protocol, including vLLM, llama.cpp, and LiteLLM (links above).
• A model ID: the exact identifier your provider uses; not all gateways expose a /models discovery endpoint, so the ID may not auto-fill.
• Authentication: an API key, or Azure AD credentials if your organization has enterprise identity enabled (docs.cline.bot).

As of May 2026, the setup flow is identical across Cline's VS Code, Cursor, and Windsurf builds; JetBrains (Early Access) shares the same configuration model — confirm current labels on the official Cline docs.

Accessing Cline's Provider Settings in VS Code

1. Open VS Code and click the Cline icon in the left activity bar.
2. Click the gear/settings icon at the top of the Cline panel.
3. Navigate to the Providers section. If the section is missing, update the extension to the current marketplace version.
4. Locate the API Provider dropdown — this control switches the entire connection profile.

Selecting the "OpenAI Compatible" Provider Type

In the API Provider dropdown, choose OpenAI Compatible. This is distinct from the built-in "OpenAI" option: selecting "OpenAI" locks Cline to https://api.openai.com/v1, while "OpenAI Compatible" accepts any endpoint implementing the same API schema. The official documentation explicitly states that the Base URL in this mode will not be https://api.openai.com/v1 (docs.cline.bot). After selection, Cline shows the core fields: Base URL, API Key, Model ID, and a Verify button. In some versions, the Model ID sits inside a collapsible "Model Configuration" block — do not skip it.

Configuring the Base URL and API Endpoint

The Base URL must include the /v1 path and no trailing slash. Correct examples:

• https://api.hefu.hk/v1 (HeFu gateway — one key for the full model catalog)
• https://gateway.example.com/v1
• http://localhost:8000/v1 (local runtime)
• https://api.example.com/openai/v1

The most common failure is omitting /v1 or adding a trailing slash, which produces 404 Not Found or model not found errors. If your provider uses a gateway-style setup with one unified key and URL, this single field replaces per-model endpoint management.

Setting Up API Key Authentication

Paste your API key into the API Key field. For shared or version-controlled workspaces, use environment-variable syntax $ENV_VAR_NAME instead of a literal string, so the key never lands in a committed file. Cline stores the key only locally and only the extension itself uses it (docs.cline.bot). In enterprise deployments, you can enable Azure AD Identity Authentication to skip the API key entirely; Cline automatically uses your Azure credentials (docs.cline.bot). If you are using a managed gateway such as HeFu's OpenAI-compatible endpoint, a single key grants access to every model in your plan; subscription and per-model rates are published on the official pricing page.

Choosing and Mapping Models

The Model Configuration block is the most easily overlooked part of the form, yet for custom endpoints it is more critical than for built-in providers. Built-in providers auto-populate model lists; a custom endpoint may only accept models you explicitly type. Enter the exact Model ID from your provider's documentation, assign a short custom display name if you manage multiple endpoints, and set an accurate context-window limit so Cline's token accounting matches reality (Cline docs).

On LiteLLM proxies, for example, the model ID is typically the model_name you defined in config.yaml rather than the upstream provider's name (LiteLLM docs). On HeFu's gateway, enter the exact IDs from the official model catalog; as of May 2026, the current model list and rates are published on the official models and pricing pages.

Advanced Settings: Timeouts, Headers, and Proxy

Depending on your network, you may need to adjust several optional parameters:

• Custom HTTP headers: some corporate gateways require extra tokens, such as a governance header like X-Coder-AI-Governance-Token (Coder docs v2.36.3). Cline passes your provider-defined headers with each request, and the receiving gateway can enforce policy on them.
• Request timeouts: reasoning models can take minutes on complex edits; if your endpoint is slow, increase the timeout in Cline's advanced settings.
• Proxy support: in restricted networks, configure the corporate proxy in VS Code's settings so Cline's outbound requests to your Base URL route correctly.

Testing the Connection with a Simple Prompt

Send a minimal prompt such as Reply with OK in the Cline chat panel. A successful response confirms that your Base URL, key, model ID, and headers are all correct. If the panel returns an error, test the endpoint independently with curl:

curl https://your-gateway/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","messages":[{"role":"user","content":"OK"}]}'

This isolates whether the problem is in Cline or in the endpoint itself.

Troubleshooting Common Setup Errors

Symptom	Likely cause	Fix
401 Unauthorized	Wrong API key, or key lacks permission for the model	Regenerate the key; verify model access; check $ENV_VAR value
404 Not Found	Base URL missing /v1, or wrong path	Re-read provider docs; remove trailing slash
Connection timeout	Firewall, proxy, or unreachable host	Test with curl; configure proxy; check regional blocks
Model not found	Model ID mismatch for that endpoint	Copy the exact ID from the provider's model list

The official Cline troubleshooting checklist covers additional edge cases, including certificate errors for self-signed local gateways.

Native Provider vs. Third-Party Gateway: Which Should You Choose?

When deciding between Cline's native single-endpoint configuration and a gateway such as OpenRouter, Requesty, or Eden AI, the trade-off is control versus convenience:

Dimension	Native OpenAI Compatible (single endpoint)	Gateway (OpenRouter / Requesty / Eden AI)
Setup time	~2–5 min: 4 fields + Verify, per endpoint	~1 min: one key + one Base URL for many models
Model discovery	Manual — only models on that endpoint	Automatic /models discovery; route per task
Cost governance	Local key storage; custom headers; enterprise policies	Budget caps, model whitelists, key expiry, unified usage stats
Privacy	Request goes directly to your chosen provider	Requests pass through the gateway's routing layer

As of May 2026, the Cline community is still requesting multiple independent OpenAI-compatible slots: GitHub Discussion #386 asks for separately saved Base URL/key/model profiles, with the option to use different providers in Plan vs. Act mode (github.com/cline/cline/discussions/386). Until that feature lands, the practical workaround is to place a lightweight gateway in front of several providers, using virtual keys with budget caps, expiry dates, and model whitelists. For Chinese users evaluating this option, our OpenRouter Alternatives for Chinese Models guide compares gateways by regional availability, and the DeepSeek V4 vs GPT API Cost comparison helps estimate cost differences.

Security, Limits, and Cost Management

Cline stores the API key only locally, and only the extension itself uses it (docs.cline.bot). Recommended practices:

• Rotate keys periodically and revoke unused ones.
• Prefer $ENV_VAR syntax over literal keys in shared workspaces.
• Set hard budget caps on the gateway side, not just in Cline, so an agent loop cannot produce unexpected bills.
• Monitor model-level usage in your provider dashboard; reasoning models differ significantly in price — see the 2026 DeepSeek V4 vs GPT pricing comparison.

For HeFu users, a single key unlocks the full catalog of OpenAI, Claude, DeepSeek, Kimi, Gemini, Qwen, GLM, Doubao, Hunyuan, Grok, and MiniMax models through one OpenAI-compatible endpoint; the exact model list and current rates are on the official models/pricing pages. The same endpoint also works in other clients — see our step-by-step guide to setting up HeFu as a custom provider in LobeChat for the parallel workflow.

FAQ

Why does the Verify button fail even though my endpoint is correct?

The three most common causes are a Base URL missing the /v1 path, a Model ID that does not match your provider's documentation (the Model Configuration block is easy to skip), and missing custom headers required by corporate gateways. Check Cline's official troubleshooting checklist, and test the endpoint independently with curl to isolate the issue.

Can I save multiple OpenAI-compatible providers and switch between them quickly?

As of May 2026, Cline ships a single OpenAI-compatible slot; the multi-slot feature is still an open community request. GitHub Discussion #386 asks for independent saved profiles while noting that the official implementation is not yet available (github.com/cline/cline/discussions/386). The workaround is placing a gateway in front of multiple providers, using virtual keys with budget caps, expiry dates, and model whitelists. If a provider already offers a dedicated Cline entry point, prefer that over the custom path.

Is my API key secure? Where does Cline send it?

Cline stores the key locally and only the extension uses it; with Azure AD Identity Authentication enabled, no key is used at all (docs.cline.bot). For any network endpoint, use an HTTPS Base URL so the key is transmitted only over TLS. Keep your key scoped to the models you need, monitor dashboard usage, and use $ENV_VAR syntax to keep it out of configuration files.

How do I revert to the default OpenAI provider?

Go to Settings → Providers and switch the API Provider dropdown back to "OpenAI" (or any built-in provider). Your previously entered custom Base URL, key, and model ID are ignored while a built-in provider is selected, so reverting is immediate and requires no uninstall. To return to your custom setup later, simply re-select "OpenAI Compatible" — the fields retain the saved values.

Which models can I use with a HeFu OpenAI-compatible endpoint in Cline?

The exact Model ID must come from HeFu's official models page; as of May 2026, the endpoint supports the model families listed there, and current rates are on the official pricing page. Do not rely on model names in third-party blog posts — copy the ID directly from the provider's catalog.