Aider Claude Setup: Keys and Model Pairs
Aider Claude setup: use an Anthropic API key or an OpenAI-compatible base URL, pass full model ids instead of stale aliases, and pair architect and editor.
By OceanToken Team

Editor's note: Aider is one of the easiest coding tools to budget, because it prints the tokens and estimated cost of every exchange when it knows the model's prices. That readout is worth more than any feature list. Use it to learn what a task in your own repository costs before you let any agent run unattended, and be skeptical of the short model aliases, which lag behind Anthropic's releases.
Short answer: For an Aider Claude setup, either export ANTHROPIC_API_KEY and run aider --model anthropic/claude-sonnet-5-5, or set OPENAI_API_BASE and OPENAI_API_KEY for an OpenAI-compatible endpoint and prefix the model with openai/. Pass full model ids, because Aider's sonnet and opus aliases point at older releases.

Setup route A: Anthropic key
Aider's Anthropic page shows the direct route: install Aider, set the key, and pass a model.
python -m pip install aider-install && aider-install
export ANTHROPIC_API_KEY=<your-anthropic-key> # or pass --anthropic-api-key
cd your-repo
aider --model anthropic/claude-sonnet-5-5
The model string matters more than it looks. Aider's model-aliases page maps sonnet to claude-sonnet-4-6, opus to claude-opus-4-7 and haiku to claude-haiku-4-5 (checked November 8, 2026). So aider --model sonnet gives you a 4.x model, not Sonnet 5.5. Anthropic's models overview lists the current ids as claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5. Run aider --list-models anthropic/ to see which ones your Aider version knows.
If you like short names, define your own: aider --alias "s55:anthropic/claude-sonnet-5-5". Aider's docs say command-line aliases override config-file aliases, which override the built-in ones, so yours wins.
Setup route B: any OpenAI-compatible gateway
Aider's OpenAI-compatible page needs two environment variables and a prefix on the model name.

export OPENAI_API_BASE=https://api.oceantoken.ai/v1
export OPENAI_API_KEY=$OCEANTOKEN_API_KEY
aider --model openai/anthropic/claude-sonnet-5.5
The double prefix is correct. The leading openai/ tells Aider to use its OpenAI-compatible client, and anthropic/claude-sonnet-5.5 is the id the endpoint expects. Notice the id style changes with the route: Anthropic uses hyphens (claude-sonnet-5-5), while OceanToken's catalog uses a publisher prefix and a dot (anthropic/claude-sonnet-5.5). Copying one into the other is the most common first-run error.
Aider warns about models it doesn't recognize, and without metadata it can't show context size or cost. The options page describes --model-metadata-file as "a file with context window and costs for unknown models" and --model-settings-file for other per-model settings, so add one if you want the cost readout back.
Aider Claude setup: which route to pick
Route A is the shortest path if Claude is the only family you'll use and you already have an Anthropic key. Route B is the one to pick when you want to switch models from the command line: the base URL and key stay the same and only the --model string changes, which matters once you start pairing models. The trade-off is metadata. On route B, Aider is less likely to know a model's context size and prices out of the box, so plan to write that metadata file once. If you are still deciding where to call Claude from, see Claude API: Anthropic direct vs gateway.
Architect mode: two models, two jobs
Aider's architect mode splits a request in two. The architect model works out how to solve the problem, and the editor model turns that into concrete file edits. In Aider's September 2024 write-up , Claude 3.5 Sonnet as architect with Sonnet as editor scored 80.5% on Aider's code editing benchmark, against 77.4% for Sonnet alone. That is Aider's own benchmark with models of that period, so read it as a reason to try the pattern, not a promise for your codebase.

aider --architect \
--model openai/anthropic/claude-opus-5.5 \
--editor-model openai/anthropic/claude-sonnet-5.5
For routine work, a lighter pair:
aider --architect \
--model openai/anthropic/claude-sonnet-5.5 \
--editor-model openai/anthropic/claude-haiku-4.5
The second example uses Haiku 4.5 because OceanToken's /claude-api list (checked November 8, 2026) has anthropic/claude-haiku-4.5 and no Haiku 5.5, even though Anthropic lists Haiku 5.5. Check the list on whatever endpoint you use.
| Pairing | Good for | Trade-off |
|---|---|---|
| Opus architect + Sonnet editor | Multi-file changes, unfamiliar code | Highest cost per turn of these |
| Sonnet architect + Sonnet editor | Everyday work | Two calls per turn |
| Sonnet architect + Haiku editor | Mechanical refactors | Small editor can misapply a subtle plan |
| One model, no architect | Small, local edits | Fewest calls; weakest at planning |
Our take: Start without architect mode. Turn it on when the single model visibly fails at planning, such as touching the wrong files or leaving refactors half done. Architect mode makes two calls per turn, so it has to earn that with fewer retries, and Aider's cost readout will tell you whether it does.
Keeping costs predictable
Add only the files the change needs. Aider gives the model a repo map, a compact outline of the rest of the code, so /add-ing the whole tree mostly buys you a bigger bill. --map-tokens sets how many tokens that map may use.
Turn on --cache-prompts where the provider supports caching, and consider --cache-keepalive-pings, which Aider describes as pinging at 5-minute intervals to keep the prompt cache warm. Anthropic caches prompts of 512 tokens or more on the 5.x models, and Aider's repo map plus system prompt is usually well past that. On an OpenAI-compatible route, don't assume the cache markers survive; check your usage logs before you count on it.
Clear history between unrelated tasks with /clear, so an old conversation isn't resent on every turn. For reasoning depth, Aider has --reasoning-effort and --thinking-tokens, both unset by default; set one deliberately rather than inheriting whatever the model defaults to.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Model not found after setting OPENAI_API_BASE |
Missing openai/ prefix |
Use openai/anthropic/claude-sonnet-5.5 |
You asked for sonnet and got a 4.x model |
Built-in alias is pinned to an older release | Pass the full id or define --alias |
| Cost shows as zero or unknown | Aider has no price data for the id | Add a model metadata file |
| Edits fail to apply | The model handles one edit format better | Try --edit-format diff or whole; set --editor-edit-format in architect mode |
| Warning about an unknown model | No metadata for that name | Add metadata, or check the id spelling |
How to test this on your workload
We haven't published measurements for this guide. On a throwaway branch, run the same three small tasks (rename a function across files, add a unit test, fix a failing test) with Sonnet alone and then with Opus as architect and Sonnet as editor. Record retries, tokens and Aider's cost readout for each. If the pair doesn't cut retries on your code, stay with one model.
Running it on OceanToken
Point Aider's OPENAI_API_BASE at https://api.oceantoken.ai/v1 and use ids such as anthropic/claude-opus-5.5 (see the Claude Opus 5.5 model page) or anthropic/claude-sonnet-5.5. The /claude-api page says it is OpenAI-compatible, so you change the base URL and the key and keep your code, and one API key and one prepaid balance cover every leading model. In Aider that means --weak-model, which handles commit messages and history summaries, can be a cheaper non-Claude model on the same key. Billing is prepaid with no subscription, and each key can carry its own spending limit, a sensible guard before you leave Aider running on a big refactor. See the current rate on /claude-api.
FAQ
Which environment variable does Aider use for Claude? ANTHROPIC_API_KEY for the direct route, or OPENAI_API_BASE plus OPENAI_API_KEY for an OpenAI-compatible endpoint.
Does aider --model sonnet use Sonnet 5.5? No. Aider's alias page maps sonnet to claude-sonnet-4-6. Pass the full id.
What is the weak model? A secondary model Aider uses for commit messages and chat history summarization, set with --weak-model.
Why does architect mode feel slower? It makes two model calls per turn, one to plan and one to edit.
Do I need to add every file? No. Aider's repo map outlines the rest of the code, so add only the files you want changed.
Sources
- Aider: Anthropic (checked 2026-11-08)
- Aider: OpenAI compatible APIs (checked 2026-11-08)
- Aider: model aliases (checked 2026-11-08)
- Aider: options reference (checked 2026-11-08)
- Aider: separating code reasoning and editing (checked 2026-11-08)
- Anthropic: models overview (checked 2026-11-08)
- OceanToken Claude API page (checked 2026-11-08)
Get your OceanToken API key
- Create an OceanToken account and an API key.
- Copy the snippet below, paste your key, and run it.
- Check the current rate on /claude-api.
curl https://api.oceantoken.ai/v1/chat/completions \
-H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "anthropic/claude-sonnet-5.5", "max_tokens": 400, "messages": [{"role": "user", "content": "Hello"}]}'
More from the blog
A Unified API for Chat, Image and Video
Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.
Kimi K3 API International Access Guide
Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.
Call Tencent Hy3 With the OpenAI SDK
Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.