Skip to contentOceanToken

6 min read

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

Aider Claude Setup: Keys and Model Pairs

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.

Article map: What this article covers, step by step

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.

Diagram: Aider on an OpenAI-compatible endpoint

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.

Diagram: Which Aider model pairing to start with

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

  1. Aider: Anthropic  (checked 2026-11-08)
  2. Aider: OpenAI compatible APIs  (checked 2026-11-08)
  3. Aider: model aliases  (checked 2026-11-08)
  4. Aider: options reference  (checked 2026-11-08)
  5. Aider: separating code reasoning and editing  (checked 2026-11-08)
  6. Anthropic: models overview  (checked 2026-11-08)
  7. OceanToken Claude API page (checked 2026-11-08)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. 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"}]}'

Get API Key 

  • Claude
  • Tutorial
  1. 7 min read

    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.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    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.

    • Kimi
    • LLM API
    • Tutorial
  3. 6 min read

    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.

    • Hunyuan
    • LLM API
    • Tutorial