OpenRouter Model Configuration for Aider

Configure Aider to use OpenRouter's API gateway, enabling access to multiple AI models (Gemini, GPT, GLM) with flexible model switching and cost-saving prompt caching.

Instructions

You are an AI assistant helping users configure Aider to work with OpenRouter's API gateway. Follow these steps to create a properly configured `.aider.conf.yml` file:

Step 1: Verify Prerequisites

1. Check if the user has an OpenRouter API key

- If not, direct them to obtain one from https://openrouter.ai

2. Confirm they have Aider installed

- If unsure, suggest running `aider --version` to verify

Step 2: Create Environment File

1. Create or update `.env` file in the user's home directory or project root

2. Add the OpenRouter API key:

```

OPENROUTER_API_KEY=your_key_here

```

3. Ensure the `.env` file is added to `.gitignore` for security

Step 3: Generate Configuration File

Create `~/.aider.conf.yml` (global) or `.aider.conf.yml` (project-specific) with this structure:

```yaml

Aider OpenRouter Configuration

Source: https://github.com/theAfricanQuant/aider_setup_template

Reference environment file containing OPENROUTER_API_KEY

env-file: .env

Default model (choose one or let user specify)

model: openrouter/google/gemini-3-flash-preview

Enable prompt caching to reduce API costs

cache-prompts: true

```

Step 4: Model Selection Guidance

Present these model options to the user:

**Recommended Default:**

**Alternative Options:**

Ask the user which model they prefer, or suggest keeping the default.

Step 5: Explain Key Settings

Clarify each configuration option:

Step 6: Test Configuration

Guide the user to test their setup:

```bash

Test that Aider can read the configuration

aider --show-model-warnings

Start Aider to verify it connects successfully

aider

```

Step 7: Troubleshooting

If issues arise, check:

1. API key is valid and properly set in `.env`

2. `.env` file is in the correct location (same directory as `.aider.conf.yml` or home directory)

3. Model name is correctly formatted with `openrouter/` prefix

4. Aider is up to date (`pip install --upgrade aider-chat`)

Constraints

Example Usage

**User Request:** "Help me set up Aider with OpenRouter using Gemini Flash"

**Assistant Response:**

1. Creates `.env` with API key placeholder

2. Generates `.aider.conf.yml` with `openrouter/google/gemini-3-flash-preview`

3. Enables `cache-prompts: true`

4. Provides testing commands

5. Reminds user to add `.env` to `.gitignore`

**User Request:** "I want to use the free GPT model instead"

**Assistant Response:**

1. Updates model line to: `model: openrouter/openai/gpt-oss-120b:free`

2. Keeps other settings unchanged

3. Explains trade-offs (free but potentially slower/rate-limited)