# Aider with Claude through a gateway: ANTHROPIC_API_BASE, config files, architect mode and fixes

Aider sends every model call through LiteLLM, so pointing it at a gateway is a LiteLLM setting rather than an Aider one. For Claude that means `ANTHROPIC_API_BASE` set to the gateway's host root and a model name with the `anthropic/` prefix. Two less obvious settings matter as much: newer Claude IDs need a model-settings entry, or Aider falls back to whole-file edits without a repo map.

## Install Aider

```bash
python -m pip install aider-install
aider-install

# or the one-line installer (installs Python 3.12 if needed)
curl -LsSf https://aider.chat/install.sh | sh
```

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"
```

If the `aider` command isn't found afterwards, which is common on Windows, `python -m aider` runs the same program.

## Connect to Claude through the gateway

```bash
export ANTHROPIC_API_KEY=your_gateway_key
export ANTHROPIC_API_BASE=https://aiprimetech.io

aider --model anthropic/claude-sonnet-5
```

```powershell
setx ANTHROPIC_API_KEY your_gateway_key
setx ANTHROPIC_API_BASE https://aiprimetech.io
# open a new terminal, then:
aider --model anthropic/claude-sonnet-5
```

> Use the host root: no `/v1` and no trailing slash. LiteLLM appends `/v1/messages` itself, so `https://aiprimetech.io/v1` becomes `/v1/v1/messages` and returns 404, and a trailing slash produces a double slash in the path.

Aider's own docs don't cover a custom Anthropic base URL. The variable is read by LiteLLM, which checks `ANTHROPIC_API_BASE` first and then `ANTHROPIC_BASE_URL`, the variable Claude Code uses. Either works; if both are set, `ANTHROPIC_API_BASE` wins.

Keep the `anthropic/` prefix on the model name. Without a provider prefix LiteLLM doesn't know where to send an unfamiliar name and fails with `LLM Provider NOT provided`.

## Put the settings in config files

Aider reads `.aider.conf.yml` and `.env` from your home directory, the git repository root and the current directory, in that order, with later files taking priority. A file in the home directory covers every project.

```yaml
model: anthropic/claude-sonnet-5
weak-model: anthropic/claude-haiku-4-5
set-env:
  - ANTHROPIC_API_BASE=https://aiprimetech.io
model-settings-file: ~/.aider.model.settings.yml
model-metadata-file: ~/.aider.model.metadata.json
```

```bash
ANTHROPIC_API_KEY=your_gateway_key
```

`weak-model` handles commit messages and chat-history summaries, so a cheap model there saves money on every session. `set-env` copies the variable into the environment before any model call, which keeps the base URL out of your shell profile.

## Keep diff edits and the repo map on newer models

Aider picks its edit format by model name. Names it recognises, including those containing `sonnet-4-`, `opus-4-` or `haiku-4-`, get `diff` edits and the repository map. A name it doesn't recognise, such as `claude-sonnet-5`, falls back to rewriting whole files and drops the repo map. That makes edits slower and more expensive. A settings entry restores the right behaviour:

```yaml
- name: anthropic/claude-sonnet-5
  edit_format: diff
  use_repo_map: true
  weak_model_name: anthropic/claude-haiku-4-5

- name: anthropic/claude-opus-5-5
  edit_format: diff
  use_repo_map: true
  weak_model_name: anthropic/claude-haiku-4-5
  editor_model_name: anthropic/claude-sonnet-5
  editor_edit_format: editor-diff
```

Unknown models also trigger a warning: `Unknown context window size and costs, using sane defaults`. It's harmless, but Aider then assumes an unlimited window and a zero price. The metadata file gives it real numbers:

```json
{
  "anthropic/claude-sonnet-5": {
    "max_tokens": 64000,
    "max_input_tokens": 200000,
    "max_output_tokens": 64000,
    "input_cost_per_token": 0.000002,
    "output_cost_per_token": 0.00001,
    "litellm_provider": "anthropic",
    "mode": "chat"
  },
  "anthropic/claude-opus-5-5": {
    "max_tokens": 64000,
    "max_input_tokens": 200000,
    "max_output_tokens": 64000,
    "input_cost_per_token": 0.000004,
    "output_cost_per_token": 0.00002,
    "litellm_provider": "anthropic",
    "mode": "chat"
  }
}
```

The prices are Anthropic's list prices per token, so Aider's cost readout shows list cost; the gateway bills less than that. A 200K input limit is a safe working ceiling even where a model supports more.

## Architect mode: plan with one model, edit with another

```bash
aider --architect --model anthropic/claude-opus-5-5 --editor-model anthropic/claude-sonnet-5
```

In architect mode the main model proposes the change and the editor model turns it into file edits. A stronger model for planning and a cheaper one for editing usually costs less than running the strong model for both. Inside a session, `/architect` switches to it for one message and `/chat-mode architect` switches for the rest of the session.

## The OpenAI-compatible route

The gateway also speaks the OpenAI Chat Completions format, which is the route for GPT models on the same account. For this route the base URL does include `/v1`, and the model name takes the `openai/` prefix:

```bash
export OPENAI_API_KEY=your_gateway_key
export OPENAI_API_BASE=https://aiprimetech.io/v1

aider --model openai/claude-sonnet-5
```

For Claude, prefer the native route above: model metadata and prompt caching line up with Anthropic's format. If a stray `OPENAI_BASE_URL` is set in your environment, LiteLLM uses it in preference to `OPENAI_API_BASE`.

## Models

| Model ID | Use it for |
| --- | --- |
| `claude-sonnet-5` | Default for coding and agent work: fast, strong, mid-priced. |
| `claude-opus-5-5` | Harder reasoning, large refactors, long agent runs. |
| `claude-fable-5-1` | Most capable and most expensive; save it for the hardest tasks. |
| `claude-haiku-4-5` | Cheap and quick: titles, summaries, classification, small steps. |

Aider's short aliases (`sonnet`, `opus`, `haiku`) point at older model IDs, so name the model explicitly. Old dated IDs such as `claude-3-5-sonnet-20241022` are not served.

## Troubleshooting

| What you see | Cause | Fix |
| --- | --- | --- |
| `404` / `NotFoundError` | `/v1` in `ANTHROPIC_API_BASE`, so the path becomes `/v1/v1/messages` | Set the host root, `https://aiprimetech.io`, with no trailing slash |
| `LLM Provider NOT provided` | Model name without a provider prefix | Use `anthropic/claude-sonnet-5` |
| `AuthenticationError`: not able to authenticate you | Key missing in the shell Aider runs in, or a key for another endpoint | `echo $ANTHROPIC_API_KEY`; on Windows open a new terminal after `setx` |
| Whole-file rewrites, no repo map | Aider doesn't recognise the model name | Add the `.aider.model.settings.yml` entry above |
| `Unknown context window size and costs` | No metadata for the model | Add the metadata file, or ignore the warning |
| Token limit errors | Too many or too large files in the chat | `/tokens` to see usage, `/drop` files, `/clear` history |
| `RateLimitError` | Concurrency or rate limit reached | Aider retries with backoff; avoid running several sessions on one key |
| Model not supported | An old or misspelled model ID | Use an ID from the table above |

For errors that come from the model side rather than from Aider, see the [Claude API errors guide](/learn/claude-api-errors-troubleshooting/).

## FAQ

### How do I use Aider with a custom Anthropic base URL?

Set ANTHROPIC_API_BASE to the gateway's host root, e.g. https://aiprimetech.io with no /v1 and no trailing slash, set ANTHROPIC_API_KEY, and run aider --model anthropic/claude-sonnet-5. LiteLLM appends /v1/messages.

### Does Aider read ANTHROPIC_BASE_URL?

Yes, through LiteLLM, as a fallback. LiteLLM checks ANTHROPIC_API_BASE first, then ANTHROPIC_BASE_URL.

### Why does Aider rewrite whole files with a new Claude model?

Aider doesn't recognise the model name and falls back to the whole edit format without a repo map. Add an entry with edit_format: diff and use_repo_map: true to .aider.model.settings.yml.

### Can Aider use an OpenAI-compatible endpoint?

Yes: set OPENAI_API_BASE to the endpoint including /v1 and OPENAI_API_KEY, then use the openai/ prefix, e.g. aider --model openai/claude-sonnet-5.

---

Source: https://aiprimetech.io/learn/use-claude-api-with-aider/
Provider: AI Prime Tech — independent Anthropic-compatible API gateway (not affiliated with Anthropic).