How to Use OpenRouter with Cline

US monthly search volume for the keyword "cline openrouter" sits around 40 queries, with a keyword difficulty of 18 [DataForSEO]. That is a quiet signal next to what the products actually support. Official Cline authorization docs list OpenRouter as a bring-your-own-key (BYOK) cloud provider built for multiple models and competitive pricing, and OpenRouter documents Cline as a supported coding agent that can reach hundreds of models through a single API key [Cline Docs - Authorization; OpenRouter Quickstart; OpenRouter Cline app page]. The gap this guide fills is not "does the pairing exist?" It is "how do you wire it correctly, including the Gemini caching exception and cost discipline when one key can call almost anything?"

Cline is a provider-agnostic coding agent that runs in your editor. It can read the repo, edit files, run terminal commands, and use MCP tools, with you approving steps along the way. Using OpenRouter with Cline means selecting OpenRouter as the API provider, pasting an OpenRouter key, and choosing any routed model so Cline can call many providers through one gateway. You keep Cline's agent loop and editor UX. You change only how inference is billed and which model family answers each turn.

That design matters for agent work more than for chat autocomplete. A single Cline task often issues many model calls: plan, list files, read files, propose edits, run tests, fix failures. Each step re-sends growing context. Direct Anthropic, OpenAI, or Gemini keys work well when you are locked to one vendor. OpenRouter is the practical choice when you want to:

• Switch models without creating a new provider account for every experiment
• Compare Claude-class, GPT-class, Gemini-class, and open-weight routes under one balance
• Keep a single secret in Cline Settings instead of rotating a stack of provider keys
• Fall back across providers when one upstream is slow or rate-limited (OpenRouter handles routing and fallbacks on its side)

Cline also offers other auth paths: usage-billing sign-in, ClinePass at $9.99/month for curated open coding models with higher rate limits, and local runtimes such as Ollama or LM Studio with no cloud key [Cline Docs - Authorization]. OpenRouter is the BYOK multi-model lane. Choose it when you want catalog breadth and pass-through pricing rather than a fixed subscription model list or fully local inference.

Official Cline documentation reduces OpenRouter setup to credential acquisition, provider selection, key paste, model choice, and an optional custom base URL [Cline Docs - OpenRouter]. OpenRouter's own Cline page matches that flow: create an account, add credits, generate a key, then configure Cline [OpenRouter Cline app page]. Follow these numbered steps end to end, then run a verify prompt so you know the gateway works before a long agent task burns tokens.

1. Create an OpenRouter account and API key

Sign in at openrouter.ai with Google or GitHub. Open the keys page (openrouter.ai/keys or the settings keys path OpenRouter documents for apps), create a key if none exists, and copy it once into a password manager. Treat the key like any cloud credential: do not commit it, do not paste it into tickets, and rotate it if it leaks.

Add credits on the OpenRouter side before you rely on Cline for a multi-step refactor. OpenRouter charges based on the underlying model's pricing, so an empty balance fails mid-task the same way a dead card fails a CI job.

2. Install Cline and open Settings

In VS Code (or a compatible editor), install the official Cline extension from the marketplace, open the Cline panel from the Activity Bar, then click the settings icon (gear) in the Cline panel [Cline Docs - Authorization].

3. Select OpenRouter as the API provider

In Cline Settings:

1. Set API Provider to OpenRouter.
2. Paste your key into the OpenRouter API Key field.
3. Choose a model from the Model dropdown.
4. Leave Use custom base URL unchecked unless you deliberately route through a proxy. Official docs say leave custom base URL blank for most users [Cline Docs - OpenRouter].

4. Pick a first model you can afford to test

Browse openrouter.ai/models for current prices, context windows, and caching support. For a first smoke test, prefer a mid-cost model with solid tool use rather than the absolute cheapest slug or the most expensive flagship. You are validating connectivity and tool loops, not maxing benchmark scores yet.

5. Verify with a short prompt test

Open a non-critical file and send a bounded task, for example: "Add a one-line docstring to this function only. Summarize the change before editing." Approve the plan if Cline asks, watch one tool cycle complete, and confirm the edit lands. If the request fails immediately, check key paste, OpenRouter balance, and that the provider is still set to OpenRouter. If the model answers but ignores tools, switch models before debugging your repo.

That verify step is the featured path: provider set, key accepted, model selected, one successful agent turn. Do not start a multi-file rewrite until that loop works.

Most "paste key and go" guides stop after the model dropdown. Agent sessions need one more layer of care: prompt caching behavior and model fit for multi-step tool use.

Why Gemini via OpenRouter needs a manual checkbox

OpenRouter passes caching requests to underlying models that support caching. For most models, caching should activate automatically when the model supports it. Gemini models via OpenRouter are the documented exception. Because of response delays sometimes observed with Google's caching mechanism when accessed through OpenRouter, Cline requires a manual step: you must check Enable Prompt Caching in the provider settings specifically for Gemini models. For non-Gemini models on OpenRouter, that checkbox is not required for caching [Cline Docs - OpenRouter].

If you run long Gemini sessions without that toggle, you can still get completions, but you miss the caching path Cline documents for that route. That is expensive in agent mode, where system prompts, rules, and early tool results repeat every turn. When you switch away from Gemini, do not assume the same toggle is required for Claude or GPT-class routes; follow the model page and Cline's note above.

Check the OpenRouter Models page for which models advertise caching. Caching is not universal across the catalog. A cheap model without cache support can still cost more over a long Cline session than a slightly higher base price with cache hits.

Choosing models for agent loops, not chat demos

Cline is not a single-shot autocomplete box. Prefer models that:

• Follow tool schemas for file edits and terminal commands
• Hold a plan across several tool turns without inventing paths
• Fit your budget for repeated context on long tasks

Practical evaluation prompts:

• Tool fidelity: "List files in this folder, open the two most relevant ones, then propose a three-step fix. Do not invent paths."
• Edit discipline: "Change only function X. Leave neighboring helpers untouched. Summarize the diff before applying."

If the model invents files, rewrites unrelated modules, or drops the plan after the first tool result, change the model slug in the dropdown before blaming Cline. Keep a short team list of approved OpenRouter model IDs for daily work, spike work, and cheap triage so people are not free-handing the entire catalog on production code.

Custom base URL

Official Cline OpenRouter docs include an optional custom base URL for advanced proxy setups. Leave it blank unless your org requires a fixed egress URL or a private gateway in front of OpenRouter. A wrong base URL produces auth or routing failures that look like a bad API key.

OpenRouter pricing is pass-through: you pay according to the underlying model rates listed on the OpenRouter Models page [Cline Docs - OpenRouter]. That is convenient and dangerous. Convenience means one balance and one invoice surface. Danger means a teammate can switch Cline from a thrifty open-weight route to a flagship model with a long context and burn the budget during a single refactor.

Treat the OpenRouter key as a metered shared resource, not as unlimited model freedom.

Budget practices that work with Cline

• Default model policy: Document a default model for everyday Cline tasks and a short allowlist for escalations. Store the policy in the repo (for example a short team doc) so the dropdown choice is not tribal knowledge.
• Task scoping: Prefer small Cline tasks over one infinite thread. New task when the goal changes. Smaller transcripts mean fewer repeated tokens even before caching.
• Cache-aware model choice: Prefer routes that support caching for multi-step agent work. On Gemini-via-OpenRouter, enable the manual prompt caching checkbox before long sessions.
• Balance alerts: Keep credits topped up enough for a workday of agent loops, but not so high that a mis-set model can empty the account unnoticed. Rotate keys if someone leaves the team.
• Hybrid with local: For private or low-stakes edits, point Cline at Ollama or LM Studio (no API key; local base URL) and reserve OpenRouter for harder slices [Cline Docs - Authorization]. Switch provider only for the hard step, then switch back.

What not to do

• Do not share one production OpenRouter key across personal side projects and company Cline installs without usage visibility.
• Do not leave the model dropdown on the last experimental slug from a weekend test.
• Do not assume "cheapest model" is cheapest for agents. Tool thrashing and missing cache support can erase list-price savings.

Compare OpenRouter BYOK with Cline's other billing lanes when you set policy. Cline usage-billing centralizes credits inside Cline. ClinePass is a flat $9.99/month subscription for curated open coding models and higher rate limits [Cline Docs - Authorization]. OpenRouter wins when you need catalog breadth and per-model price shopping. ClinePass or usage-billing can win when you want simpler product-side billing and fewer external dashboards. Many teams use OpenRouter for power users and a simpler path for everyone else.

Keep OpenRouter-powered Cline work reviewable

Run Cline through OpenRouter for multi-model inference, then drop review packs into a Fast.io workspace with MCP access, version history, and Intelligence Mode search. Organizations start with a 14-day free trial.

Start 14-Day Trial

OpenRouter answers where tokens run. It does not answer where artifacts live after Cline finishes. By default, Cline edits the project on your local disk. That is fine for solo work on one laptop. It breaks down when you change machines, need a teammate to review intermediate dumps, or want an agent-readable store that is not a random folder.

Common options each have tradeoffs. Local disk stays private but does not travel. Git is excellent for source history, yet it is a poor live drop zone for design notes, binary fixtures, and half-finished agent exports. Object storage such as Amazon S3 holds blobs well but needs extra work for human review, permissions, and search. Consumer drives (Google Drive, Dropbox) are familiar, but they are not built as an MCP-native coordination layer for agents that upload, search, and hand off continuously.

Fast.io sits in that coordination layer as an intelligent workspace for agentic teams. Humans use the browser UI; agents use the API or MCP server. Organization-owned workspaces hold files with per-file version history and an append-only audit log. Enable Intelligence Mode so files are indexed for hybrid search (full-text, semantic, and metadata) and citation-backed chat. Use tasks and approvals for review instead of scrolling chat history. For structured extraction from PDFs, scans, or spreadsheets the agent collects, use Metadata Views rather than hand-built OCR rules: you describe fields in natural language, and the system builds a typed, filterable view.

Cline can call external tools through MCP. Fast.io exposes Streamable HTTP at /mcp and legacy SSE at /sse. Point Cline's MCP configuration at the Fast.io server so the agent can write reports, patches, and review packs into a durable workspace instead of only the local tree. Teammates open the same workspace, comment on files, and take ownership when the agent is done. Ownership transfer is the product path when an agent bootstraps structure and a human claims the org.

Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo. Every organization starts with a 14-day free trial that requires a credit card. Production org work runs on a paid subscription after the trial. Agent-oriented onboarding, including MCP connection context, starts from /storage-for-agents/ and pricing at /pricing/.

A clean end-to-end loop looks like this:

1. Configure Cline with OpenRouter (provider, key, model; Gemini caching if needed).
2. Run the agent against your local repo for code edits.
3. Ask Cline (via MCP) to upload release notes, diagrams, or review packs to a Fast.io workspace.
4. Teammates review with version history and comments; Intelligence Mode answers "what changed?" with citations.
5. Escalate or downgrade OpenRouter models as cost and difficulty require, without changing where shared files live.

Inference stays flexible through OpenRouter. Persistence and handoff stay shared through the workspace.

When the pairing fails, isolate whether the problem is Cline settings, OpenRouter account state, model choice, or the task itself.

Unauthorized or rejected key

Re-copy the key from OpenRouter, confirm there are no extra spaces, and confirm Cline's API Provider is still OpenRouter. Create a new key if the old one was rotated or leaked. For Cline account-session issues (usage-billing sign-in), official troubleshooting covers re-sign-in and org membership at app.cline.bot [Cline Docs - Authorization]. BYOK OpenRouter failures are usually key or balance, not Cline login.

Empty model list or model call errors

Confirm the OpenRouter account has credits. Open the Models page and verify the slug still exists. Try a different mid-tier model to separate "this model is bad for tools" from "the gateway is down."

Works in chat, fails as an agent

The model may complete prose but mishandle tool schemas. Switch to a model known for tool use, shorten the task, and avoid stuffing the first turn with huge file dumps. Start a new Cline task if the transcript is already huge.

Gemini sessions feel slow or expensive

Confirm Enable Prompt Caching is checked for Gemini-via-OpenRouter [Cline Docs - OpenRouter]. Compare cost against a non-Gemini model with automatic caching. Long delays can also be upstream load; try another model route rather than hammering retries.

Custom base URL regressions

If you recently enabled a custom base URL, disable it and retest against the default OpenRouter endpoint. Only reintroduce a proxy when you can prove DNS, TLS, and auth headers on that path.

MCP or storage errors after coding works

OpenRouter only covers inference. Failures uploading artifacts point at MCP server config, network access to the workspace endpoint, or permissions on the target workspace, not at the OpenRouter key. Fix MCP and workspace auth separately from the model provider.

When in doubt, re-run the five-step verify prompt on a throwaway file. If that works, the gateway is fine and the failure is task size, model choice, or an external tool.