Skip to content
Guide

Setting up OpenRouter

One key for models from many companies, including free ones.

On this page

OpenRouter gives you one key for models from many companies. This guide covers getting an OpenRouter key and connecting it to Aldwin.

What OpenRouter is#

OpenRouter passes your requests on to the company that runs the model you pick, and bills you in one place. Some models are free, marked with :free at the end of the name.

When Aldwin uses OpenRouter, your prompts and the files Aldwin reads for you go to OpenRouter over the internet. If you want everything to stay on your computer, use Ollama or LM Studio instead.

What you need#

  • An OpenRouter account and API key
  • Credits, for paid models
  • Aldwin installed (uv tool install aldwin)

Free models allow 20 requests a minute and 50 a day, or 1,000 a day once you have bought at least 10 credits. Paid models use credits. See limits and models and prices.

Get a key#

  1. Sign in at OpenRouter.
  2. Open Keys and create a key. You can give it a credit limit.
  3. Copy the key. Treat it like a password.

Connect Aldwin#

In the web app#

  1. Open Settings from the bottom of the sidebar and choose Models.
  2. Find OpenRouter under Providers and select Add key.
  3. Paste your key and select Connect. Aldwin checks the key with OpenRouter before saving it. If it does not work, Aldwin says why and saves nothing.
  4. Under Model in use, pick a OpenRouter model. You can also switch models from the message box in any chat.

Setting up Aldwin for the first time? On the Connect a model page, pick Paste an API key, choose OpenRouter, and paste the key.

To change or remove the key later, use Replace key or Disconnect on the same row.

In the terminal#

  1. Start Aldwin and type /model.
  2. Pick Add a provider… and press Enter. It lists the cloud providers that don't have a key yet.
  3. Pick OpenRouter, then paste your key at OpenRouter API key: (the input is hidden) and press Enter.
  4. Aldwin checks the key with OpenRouter before saving it. When it works you see ✓ Saved key for OpenRouter. If not, Aldwin says why and saves nothing.
  5. OpenRouter now appears under Available providers. Pick it, then pick a model. You see ✓ Switched to <model> (OpenRouter).

On first launch, aldwin offers the same choice: choose to use a cloud provider, pick OpenRouter, and paste the key. You can rerun this any time with aldwin setup.

Choosing a model#

The list in /model includes every model on OpenRouter. Pick one marked ✓ tools; for free use, pick one ending in :free. Free models are slower and change often.

To switch straight to a model by name, type /model openrouter/<company>/<model-name>.

Update or remove the key#

Type /model, choose Manage keys…, and pick OpenRouter. Update key checks and saves a new key. Disconnect removes the saved key; switch to another model first if OpenRouter runs the current one.

Other ways to add the key#

These skip the check, so use them only if you prefer files or environment variables.

Secrets file. Add this line to ~/.aldwin/secrets.yaml (create the file if it does not exist, and keep any lines already in it):

openrouter_api_key: your-key-here

Environment variable, for one terminal session or in your shell profile (~/.zshrc or ~/.bashrc):

export OPENROUTER_API_KEY=your-key-here

An environment variable wins over a saved key.

Try it#

aldwin

Ask something that uses a tool:

List the files in this folder.

You should see a list_dir step and then the answer. The status line at the bottom shows your model and OpenRouter.

Privacy notes#

  • Your prompts go to OpenRouter and then to the company that runs the model, under that company's terms. In privacy settings you can block companies that may train on your data.
  • Aldwin keeps the key only in ~/.aldwin/secrets.yaml (or your environment), and removes it from any error message it shows.
  • Details: Privacy.

Troubleshooting#

Messages from /model appear right after you paste a key. Messages during a chat appear after ✗ in place of an answer.

What Aldwin saysFix
Your OpenRouter key was rejected. Check the key and try again.The key is wrong, revoked, or was pasted with extra characters. Copy it again from OpenRouter.
Could not reach OpenRouter to verify the key.Check your internet connection and try again. If it keeps happening, the account may be blocked or out of credit; check it on the provider's site.
OpenRouter runs the current model. Switch to another model first.You can't disconnect the provider you are using. Switch model with /model, then disconnect OpenRouter.
OpenRouter's key comes from OPENROUTER_API_KEY in your environment. ...Disconnect can't remove an environment variable. Delete the export OPENROUTER_API_KEY=... line from your shell profile, then restart Aldwin.
Your OpenRouter key was rejected. Run `aldwin setup` to replace it.The key stopped working after it was saved. Run /model, choose Manage keys…, pick OpenRouter, and choose Update key.
OpenRouter refused the request (HTTP 402). ...The account is out of credits. Add credits on OpenRouter, or pick a :free model.
OpenRouter rate limit reached. Wait a moment and try again.You hit a free model's per-minute or daily limit. Wait, or buy credits to raise it.
Can't reach OpenRouter. ...Check your internet connection, or switch to a local model with /model.
Model ... isn't available to your key. ...Your account can't use that model. Pick another with /model.
This conversation is too long for ... Start a fresh one with /new.Type /new. Your saved memory notes stay.
Was this page helpful?