How to Use OpenRouter With Any Coding Agent or AI Tool
OpenRouter ·
On this page
OpenRouter sits between your coding tool and the model providers it calls. Your tool still sends the requests. OpenRouter handles the provider relationships, the model catalog, usage visibility, billing, and routing behind one API key.
That matters the moment you use more than one tool, model, or provider. Without it, you juggle a separate key, a separate billing dashboard, and a separate config path for OpenAI, Anthropic, Google, and everyone else. With it, every supported tool uses the same sk-or-... key, the same model slug format, and the same base URL.
Connect a tool once and you can switch models by editing one string, watch all your spend in one place, and keep an agent running when a provider falls over. Here’s the setup pattern and the tools that already speak it.
Three setup moves that work everywhere
Any tool that speaks the OpenAI Chat Completions API works with OpenRouter, because OpenRouter exposes that same API. You change two values, the base URL and the key, then pick a model, and the rest of your code stays put. That single endpoint fronts 300+ models across 60+ providers.
The three moves:
- Get a key. Create one on your keys page. OpenRouter keys start with
sk-or-, which is how a tool knows it’s talking to OpenRouter and not OpenAI directly. Store it in an environment variable, not in source. A plainsk-...key is an OpenAI key and won’t route. - Point the base URL at
https://openrouter.ai/api/v1. Because the API is OpenAI-compatible, the official OpenAI SDKs work once you swap this one value. - Pick a model slug in
provider/modelform, likeopenai/gpt-4ooranthropic/claude-sonnet-4. The slug is the only thing you change to switch models. Browse the catalog at openrouter.ai/models.
Most tools expose these settings in different places, an environment variable, a config file, or a settings screen, but the values are identical everywhere. Here’s the same call three ways.
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-4",
"messages": [{"role": "user", "content": "Refactor this function."}]
}'import os
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
resp = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Refactor this function."}],
)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
});
const resp = await client.chat.completions.create({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "Refactor this function." }],
});Those two use the OpenAI SDK, which most projects already have installed. OpenRouter also ships its own SDKs that make the same call with no base URL to set: openrouter for Python and @openrouter/sdk for TypeScript.
from openrouter import OpenRouter
import os
with OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"]) as client:
resp = client.chat.send(
model="anthropic/claude-sonnet-4",
messages=[{"role": "user", "content": "Refactor this function."}],
)import { OpenRouter } from "@openrouter/sdk";
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY,
});
const resp = await client.chat.send({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "Refactor this function." }],
});Two optional headers, HTTP-Referer and X-Title, let you label your app so it shows up in OpenRouter’s rankings. Neither is required for a working request. See app attribution for the details.
Which coding agents and AI tools support OpenRouter
The same key works across every tool below, so once you have one, you’re done provisioning for the whole list. The terminal agents read config files or environment variables; the editors and extensions configure in a settings panel.
| Tool | How it connects | Setup |
|---|---|---|
| Claude Code (Anthropic’s terminal agent) | Environment variables, via OpenRouter’s Anthropic-compatible endpoint | Guide |
| Codex CLI (OpenAI’s open-source terminal agent) | ~/.codex/config.toml with model_provider = "openrouter" | Guide |
| OpenClaw (open-source agent, formerly Moltbot/Clawdbot) | ~/.openclaw/openclaw.json, or OPENROUTER_API_KEY | Guide |
| Hermes Agent (Nous Research’s open-source CLI agent) | ~/.hermes/config.yaml, with the key in ~/.hermes/.env | Guide |
| Cursor (AI code editor) | In-app settings: custom OpenAI base URL plus key | Guide |
| Cline (VS Code agent extension) | Extension settings: OpenRouter provider | Page |
| Kilo Code (VS Code agent extension) | Extension settings: OpenRouter provider | Page |
| SillyTavern (local-first chat frontend) | Connection settings: OpenRouter API | Page |
That list isn’t exhaustive. OpenRouter also works with Claude Desktop, Junie CLI, OpenCode, and MCP servers. The pattern is the same every time: one key, one base URL, one slug.
How routing keeps your agent alive
The single endpoint buys you routing, and that matters more for an agent than for a one-off script.
A failed API call is easy to handle on its own. You catch the error and retry. An agent on a multi-step task is less forgiving, because it holds state across many calls. A provider failure halfway through can leave a half-applied edit, a tool call that never returned its result, or a plan the agent now reasons about as if it finished. When the failover happens down at the routing layer, the agent never sees the failure. It gets its completion and keeps going. Two mechanisms do this work, and they stack.
Automatic provider failover
This needs no configuration. A given model is often served by several providers, and if the one OpenRouter tries first is down or rate-limiting you, it routes the same model to another provider serving it. You pay only for the call that lands.
Manual model fallback
This is the layer you opt into. Instead of backup providers, you name backup models by passing a models array (with the OpenAI SDK, inside extra_body={"models": [...]}). OpenRouter tries your primary first, then each fallback in order, and bills you for whichever model actually ran, returned in the response’s model field. That covers the case where a model has a single provider behind it and that provider goes dark, exactly when provider-level failover has nowhere to route.
If you would rather not choose at all, the Auto Router (openrouter/auto) picks a model per prompt, sending simpler requests to cheaper models and harder ones to stronger models. You pay the standard rate for whatever it selects, with no extra routing fee. It’s handy when prototyping, before you know which model fits a task.
Building your own agent with the SDKs
If you’re wiring up an existing tool, the steps above are all you need. If you’re building your own agent, OpenRouter gives you two SDKs.
The Client SDK, for TypeScript and Python, is a thin, type-safe layer over the REST API, with generated types and autocomplete instead of hand-written HTTP.
The Agent SDK runs the loop for you. It manages the multi-turn conversation, executes your tools, and tracks state through a single callModel primitive. Because you can change the model between turns, a cheap step like reading a file can route to a cheap model while code generation goes to a stronger one, inside the same loop.
Here’s the shape of a tool-using call. This one callModel invocation sends the prompt, lets the model call get_weather, runs it, feeds the result back, and returns the final text.
import { callModel, tool } from "@openrouter/agent";
import { z } from "zod";
const weatherTool = tool({
name: "get_weather",
description: "Get the current weather for a location",
inputSchema: z.object({ location: z.string() }),
execute: async ({ location }) => ({ temperature: 72, condition: "sunny", location }),
});
const result = await callModel({
model: "anthropic/claude-sonnet-4",
messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
tools: [weatherTool],
});
const text = await result.getText();Cost and rate limits
OpenRouter has a free tier. 20+ models run at $0, capped at 50 requests a day and 20 a minute, rising to 1,000 a day once you add $10 in credits. Two caveats before you lean on it. Failed attempts still count against the daily quota, and popular free models can get rate-limited by the upstream provider at peak times. Even so, it’s enough to take an agent end to end before you spend anything on inference.
On paid usage, OpenRouter doesn’t mark up model pricing. You pay the same per-token rate you’d pay the provider directly, which is what the model catalog shows. On top of that, credit purchases carry a 5.5% fee, with a $0.80 minimum. So your inference stays at provider rates and OpenRouter’s cut is that fee on credits. The pricing page has the current numbers, and the Activity dashboard shows per-request model and cost in real time, the fastest way to catch an agent burning credits on a model heavier than the task needs.
Frequently asked questions
Do I need a separate API key for each tool?
No. One OpenRouter key works in every tool in this list. Generate it once at openrouter.ai/keys and paste the same sk-or-... value into Claude Code, Codex CLI, Cursor, or any other supported tool.
Does OpenRouter work with the OpenAI SDK?
Yes. Point base_url (Python) or baseURL (TypeScript) at https://openrouter.ai/api/v1 and pass your OpenRouter key. OpenRouter is a drop-in replacement for the OpenAI Chat API, so the official SDKs work with no other changes.
How do I use OpenRouter for free?
Use a free model and stay within the free tier. Free models, the :free variants on the models page, run at up to 50 requests a day, rising to 1,000 a day once you add $10 in credits.
Can I use OpenRouter in VS Code?
Yes. Use an agent extension like Cline or Kilo Code that exposes an OpenRouter provider, or any extension that lets you set a custom OpenAI base URL. Set the base URL to https://openrouter.ai/api/v1, paste your key, and pick a model.
What model slug format does OpenRouter use?
The format is provider/model, for example openai/gpt-4o or anthropic/claude-sonnet-4. Prefix the author with ~, like ~anthropic/claude-sonnet-latest, to always resolve to the newest version in a family. Browse the full list at openrouter.ai/models.
Does OpenRouter log my code or prompts?
No, not by default, even if a request errors, unless you explicitly opt in. There’s an opt-in setting that trades logging for a small usage discount. See the Privacy Policy for the details.