LibreChat OpenRouter Setup Guide

LibreChat can connect to OpenRouter to access 150+ AI models through a single API key. This eliminates vendor lock-in and lets your entire team use different models without managing multiple accounts. You pay as you go, track costs in one place, and switch models without reconfiguring anything. Here's exactly how to set it up, plus the cost-tracking gotchas most teams miss.

Why Use OpenRouter with LibreChat?

OpenRouter acts as a router between LibreChat and dozens of LLM providers. Instead of configuring Anthropic, OpenAI, Mistral, and others separately, you point LibreChat at OpenRouter once. One API key, all models.

OpenRouter solves a real problem in multi-model AI deployments. When you run LibreChat--which has 46.9K GitHub stars and is actively maintained--you have a choice: either configure each AI provider manually (each with its own API key, dashboard, billing cycle) or use a router that speaks to them all.

OpenRouter is a router. It sits between your application and dozens of LLM providers. You pay OpenRouter, OpenRouter pays the upstream providers. From LibreChat's perspective, it sees one endpoint instead of twenty.

Why this matters:

First, cost flexibility. Your team is not locked into OpenAI's pricing. Claude is expensive this month? Switch to Mistral for far less. Need speed? Grok is fast. Need reliability? Llama 2 is available on OpenRouter.

Second, failover. If one provider goes down, OpenRouter can route requests to a backup provider automatically. Your team keeps working.

Third, model diversity within the same interface. Your ML engineer might need Claude 3.5 Sonnet. Your content team might need Llama 2. Your finance manager might use GPT-4o. One API key. One LibreChat instance. All three work.

This is different from running separate instances. Different is cost-effective. Different is maintainable. Different is what teams at 10-100 people actually need.

Prerequisites: What You'll Need

An OpenRouter account with API credits, LibreChat running on a server or Docker container, and basic familiarity with editing YAML files. That's it.

One: An OpenRouter account. Go to openrouter.ai, sign up with your email, fund the account (start with $20 to $50 for testing), and you're done. No waiting for approval.

Two: LibreChat must be running somewhere. This can be a VPS, a Docker container, or a self-managed Kubernetes instance. If LibreChat is not running yet, start with Opsily's managed LibreChat hosting to skip the ops overhead.

Three: You need to edit files. Specifically, a.env file and a librechat.yaml file. These are text files. No programming required.

If you're already running LibreChat and managing your own infrastructure, you have everything. If you're considering managed hosting to avoid infrastructure maintenance, that context matters for cost and time tradeoffs. Compare self-hosted vs. managed costs before deciding.

Step 1: Create Your OpenRouter API Key

Go to openrouter.ai and click "Sign Up". Use your email address. Confirm the email.

Go to the dashboard. Look for "Keys" or "Settings" in the left sidebar. Click it.

Copy your API key. It will look like: sk-or-v1-... (long string). Store this securely. Treat it like a password. Anyone with this key can spend your OpenRouter credits.

Fund your account before testing. Click "Payments" or "Billing", add a credit card, and deposit at least $10. OpenRouter charges based on actual model usage. Free tier does not exist. But costs are transparent: you see the exact price per token before making requests.

Step 2: Add the Key to Your.env File

Add the line OPENROUTER_KEY=your-key-here to your.env file. Note the naming: OPENROUTER_KEY, not OPENROUTER_API_KEY. LibreChat will not recognize the wrong name.

Navigate to your LibreChat directory. Find or create a .env file in the root.

Add this line:

OPENROUTER_KEY=sk-or-v1-[paste-your-key-here]

The naming is critical. LibreChat's source code looks specifically for OPENROUTER_KEY. Use OPENROUTER_API_KEY and nothing happens: the key is ignored and you'll see a cryptic auth error later.

If you're running LibreChat in Docker, this.env file gets passed to the container via docker-compose.yml or your container runtime. Make sure it's mounted correctly.

Double-check for spaces or newlines. Extra whitespace breaks env variable parsing.

Step 3: Configure librechat.yaml

Create or edit your librechat.yaml file to include the OpenRouter endpoint with settings for model selection and parameter pass-through. Include fetch: true and dropParams: ["stop"].

LibreChat configuration lives in librechat.yaml. This is where you tell LibreChat which provider to use and which models to display.

Here's a minimal working example. The baseURL should be set to OpenRouter's API endpoint (refer to OpenRouter's API documentation for the current endpoint):

endpoints:
  openRouter:
    apiKey: "${OPENROUTER_KEY}"
    models:
      default: ["gpt-3.5-turbo", "claude-3-5-sonnet", "mistral-7b-instruct"]
      fetch: true
    modelDisplayOrder: 1
    parameters:
      temperature: 0.7
      top_p: 1
      stop: null
    dropParams: ["stop"]
    headers:
      HTTP-Referer: "https://your-domain.com"

Note: Add baseURL to point to the OpenRouter API endpoint before adding the configuration above.

What each part does:

apiKey: References the env variable you just set. LibreChat reads OPENROUTER_KEY and inserts it here.
models.fetch: true: Tells LibreChat to fetch the available model list from OpenRouter dynamically. Without this, your model dropdown appears blank.
models.default: The models displayed to users. Add or remove model names as needed. You can find the full list at openrouter.ai/models.
dropParams: ["stop"]: Tells LibreChat not to send the stop parameter to OpenRouter. Some models break if they receive this parameter. This is not optional.
headers: Optional but recommended. Adds metadata that OpenRouter uses for usage tracking and debugging.

Save this file. If you're running Docker, mount it as a volume in your docker-compose.yml:

services:
  librechat:
    volumes:
      -./librechat.yaml:/app/librechat.yaml

Step 4: Restart and Verify

Restart LibreChat, send a test message to an OpenRouter model, and confirm the response appears in the chat. Check OpenRouter's activity page to see the request.

Stop LibreChat. If you're running Docker: docker-compose down. If you're running it directly: kill the process.

Start it again: docker-compose up -d or npm start.

Wait 10 seconds for the service to become ready.

Open your LibreChat web interface. You should now see "OpenRouter" as an available provider dropdown. If you see "OpenRouter" but the model list is blank, fetch: true is not working. Double-check the YAML syntax and restart the container.

Select a model. Claude 3.5 Sonnet is a good test (it's reliable and relatively cheap). Type a test message: "Hello, confirm you are working." and hit send.

Wait 5-10 seconds. You should see a response from the model. That means the connection is working.

Go to openrouter.ai and log in. Click "Activity" or "Usage" in the dashboard. You should see your test request listed with a cost (probably a few cents).

If you see the request on OpenRouter but no response in LibreChat, check LibreChat's logs. If you see no request on OpenRouter, the env variable is not being read. Restart Docker and recheck the.env file.

Cost Tracking & Team Setup

One OpenRouter key means pooled usage across all LibreChat users. Track costs via the OpenRouter activity dashboard, use free models for testing, and create per-user keys if you need individual cost attribution.

Here's the gotcha most teams hit: LibreChat users share one OpenRouter API key. That means all spending pools together. You can see total cost in the OpenRouter dashboard, but you cannot see "User A cost $50, User B cost $20" without custom logging.

If cost attribution per user does not matter, this is fine. Many teams at 10-50 people just set a team budget and monitor the dashboard weekly.

If you need per-user cost tracking, you have two options:

Option one: Create separate OpenRouter keys for each user. Configure LibreChat to detect which user is logged in and route their requests to their key. This is complex and requires custom code.

Option two: Use LibreChat's managed hosting with SSO. Opsily's managed LibreChat comes with per-user key support built in. You connect each user's account to their own OpenRouter key and costs are tracked separately. This handles the complexity for you.

For testing and development, use OpenRouter's free models. Models like "openrouter/free" include Llama 2 and others. They're slow and limited, but they're free. Perfect for internal testing before you approve spending for GPT-4.

Monitor your OpenRouter account weekly. Go to the dashboard, check the activity page, and note the daily burn rate. At $0.01 per 1,000 tokens for Mistral-7B or $0.03 per 1,000 tokens for Claude, teams often spend $100-$300 per month. Know your burn rate before it surprises you.

Troubleshooting Common Issues

Model list appears blank? Check fetch: true. Getting 402 Payment Required? Your OpenRouter account ran out of credits. API key not recognized? Check the env variable name.

Models dropdown is empty:

Check fetch: true is set in librechat.yaml.
Check your env variable is actually named OPENROUTER_KEY (not OPENROUTER_API_KEY).
Check the librechat.yaml file has valid YAML syntax. Indentation matters. A single space in the wrong place breaks everything.
Restart LibreChat completely. Sometimes the config is cached.
Check Docker volume mounts are correct if you're using containers.

"402 Payment Required" error:

Your OpenRouter account ran out of credits. Go to the dashboard, check your balance, and add more funds.
Confirm your API key is not expired or revoked. If you rotated keys, make sure you updated the.env file.
Wait a few minutes. Sometimes OpenRouter's billing system lags by a few seconds.

"401 Unauthorized":

Your API key is wrong or malformed. Copy it again from the dashboard.
Make sure there are no extra spaces or newlines in the.env file.
Restart the container for env changes to take effect.

Response is cut off or the model stops early:

This is usually the stop parameter issue. Confirm dropParams: ["stop"] is in your librechat.yaml.
Some models (especially open-source ones on OpenRouter) break if they receive the stop token.
Check your YAML syntax again.

One user sees models but another does not:

LibreChat may be caching models per browser. Clear the cache and refresh.
If you're running multiple instances of LibreChat, make sure they all have the same librechat.yaml configuration.

Request succeeds in OpenRouter activity but response is empty in LibreChat:

Check LibreChat logs: docker-compose logs -f librechat or similar.
This usually means the response format from OpenRouter is not being parsed correctly. It's rare but happens with very new or beta models.

Frequently Asked Questions

Q: What is the best way to track costs when using librechat openrouter for my team? A: Use the OpenRouter activity dashboard to see total team spending. For per-user attribution, either build custom logging or use managed LibreChat hosting where per-key setup is handled for you. Most 10-100 person teams find the total-spend dashboard sufficient and adjust budget monthly based on actual usage.

Q: Can I use OpenRouter with open-source AI model routing? A: OpenRouter itself is not open source, but LibreChat supports other routers like LiteLLM and self-hosted options. If you want a fully open-source routing layer, that's a different setup. OpenRouter is the quickest way to access 150+ paid and free models.

Q: Do I need separate OpenRouter accounts for staging and production? A: No. Use the same account but create separate API keys for each environment. Log into OpenRouter, create a new key for staging, and store it in a staging.env file. This lets you track costs separately per environment.

Q: How does OpenRouter compare to other LLM routers? A: OpenRouter has 150+ models from multiple providers. Groq is fast for inference but supports fewer models. LiteLLM is open source but requires more setup. Choose based on model coverage and speed requirements for your use case.

Q: Can I use free models on OpenRouter to reduce costs? A: Yes. OpenRouter offers free-tier models like Llama 2 7B and Mistral 7B. They're slower but cost nothing. Use them for testing and internal workflows, then upgrade to paid models for customer-facing features or performance-critical tasks.

Q: What happens if OpenRouter has an outage? A: LibreChat sends requests to the OpenRouter endpoint and they fail. Users see an error. To add redundancy, you'd need to configure a fallback endpoint (another router or direct provider API). Most teams accept the risk since OpenRouter is stable.

Q: Do I need to update my configuration when OpenRouter adds new models? A: No. With fetch: true set, LibreChat fetches the model list automatically. New models appear in the dropdown without any action from you.

Q: Why does my librechat openrouter setup show "401 Unauthorized" even though my API key is correct? A: Check the env variable name is exactly OPENROUTER_KEY and contains no extra spaces. Restart the LibreChat container for.env changes to take effect. If using Docker, verify the.env file is mounted correctly in docker-compose.yml.

The Bottom Line

OpenRouter + LibreChat gives you model freedom and cost control. Setup takes 15 minutes. The tradeoff is managing one more API key and watching costs weekly. If you're already running LibreChat, adding OpenRouter is worth it. If you're starting from scratch and want to skip infrastructure, managed LibreChat hosting includes OpenRouter integration pre-configured.

How to Set Up LibreChat OpenRouter Integration