How to Set Up OpenRouter as Your AI Provider

One endpoint, many models

OpenRouter is an OpenAI-compatible gateway to hundreds of models, including Anthropic, OpenAI, and open-source models behind a single API key and base URL. Swap the model string and your code stays identical.

OpenRouter also works with many agentic harnesses, so you can use the same provider across coding agents and agentic development tools. It works with tools such as OpenCode, Cline, Alder, GitHub Copilot in VS Code, Pi Agent, Oh My Pi, Reasonix, and many more. The exact setup varies by harness, but the OpenAI-compatible API makes OpenRouter broadly compatible.

Step 1 — Create an API key

1. Sign up at openrouter.ai and open Settings → Keys.
2. Create a key and store it in your environment:

OPENROUTER_API_KEY="sk-or-v1-..."

Treat it like a password: in env vars, never in source control.

Step 2 — Use the OpenAI-compatible endpoint

Because OpenRouter speaks the OpenAI protocol, you point any OpenAI SDK at it:

export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="sk-or-v1-..."

Then standard SDK code works unchanged:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-oss-20b:free",
  messages: [{ role: "user", content: "Explain Web Workers in one sentence." }],
});

console.log(completion.choices[0]?.message.content);

Step 3 — Use OpenRouter with an agentic harness

If you’re using an agentic coding harness, check its provider configuration for an OpenAI-compatible provider or a custom base URL. Set the base URL to:

https://openrouter.ai/api/v1

Then provide your OpenRouter API key and the model ID you want to use.

This lets you switch models without changing your entire agent setup. For example, the same OpenRouter account can be used across OpenCode, Cline, Alder, GitHub Copilot in VS Code, Pi Agent, Oh My Pi, Reasonix, and other compatible agentic tools.

Step 4 — Choose a model

Model IDs are provider/model. List what’s available (and free) via:

curl https://openrouter.ai/api/v1/models

Common patterns:

• openai/gpt-oss-20b:free — free tier
• anthropic/claude-sonnet-4 — strong reasoning
• meta-llama/llama-4-maverick — open weights

Pin a specific model in production; :free models can change availability.

Step 5 — Handle failures

LLM APIs are flaky and rate-limited. Wrap calls with retry + timeout:

const completion = await client.chat.completions.create(
  { model, messages },
  { timeout: 30_000, maxRetries: 3 }
);

Check the response for choices being empty (a filter refusal) before reading [0], so a rejected completion doesn’t throw a confusing error.

Troubleshooting

• 401 Unauthorized — the key is wrong, revoked, or missing the Bearer prefix.
• model not found — verify the full provider/model ID; case matters.
• Empty choices — the model refused or the content filter fired; inspect the full response object.
• Agentic harness cannot connect — verify that the harness supports an OpenAI-compatible provider or custom API base URL, and make sure the endpoint is https://openrouter.ai/api/v1.

Summary

You now have one key and one endpoint that can reach hundreds of models and work across many agentic harnesses. OpenRouter is especially useful when you want to switch models without reconfiguring your entire development workflow.

Keep the key server-side, set a spend limit, and avoid logging prompts that contain private data. If the provider powers an agent or MCP tool, pair this setup with How to Build and Secure an MCP Server for AI Agents.