Why does Aider need the openai/ prefix on the model name?

Aider calls models through LiteLLM, which uses the prefix to select a provider route. Without it, LiteLLM cannot tell how to format the request, so the call fails even when the base URL and key are correct.

How do I stop Aider from truncating context on a custom model?

Add an entry for the fully qualified model name to .aider.model.metadata.json with max_input_tokens and max_output_tokens. Aider ships metadata only for models it knows, and falls back to conservative guesses otherwise.

What is the point of setting a weak model?

The weak model handles commit messages and history summarisation — frequent, trivial calls. Pointing it at a cheap fast model removes a meaningful slice of usage without touching the quality of the code Aider writes.

Aider Setup Guide: Any OpenAI-Compatible Endpoint

Aider is a terminal-based pair programmer that edits files in your git repo and commits as it goes. It routes every request through LiteLLM, which is why pointing it at an arbitrary OpenAI-compatible endpoint is three lines — and why the one detail people miss breaks everything.

That detail is the openai/ prefix on the model name. LiteLLM uses it to decide which provider route to take. Omit it and Aider will not know how to talk to your endpoint, regardless of how correct your base URL is.

The three-line version

Install Aider, then set two environment variables and pass a model:

export OPENAI_API_BASE=https://api.cozyapi.com/v1
export OPENAI_API_KEY=cozy_your_key_here

aider --model openai/kimi-k3

That is the documented path for any OpenAI-compatible provider. The base URL ends at /v1 — Aider appends /chat/completions itself, so a doubled path is the most common first-attempt failure.

Swap the alias for whichever model you want to drive the session: openai/glm-5.2, openai/deepseek-v4-pro, openai/qwen-3.5-coder, openai/minimax-m3. The prefix stays; only the part after the slash changes.

Making it persistent

Exported variables die with the shell. Aider reads two kinds of config file, and both are searched in your home directory, your git repo root and the current directory, with later files taking priority.

For secrets, use a .env file:

# .env — in your git root, and in .gitignore
OPENAI_API_BASE=https://api.cozyapi.com/v1
OPENAI_API_KEY=cozy_your_key_here

For everything else, use .aider.conf.yml. The keys are the command-line flags with the leading dashes removed:

# .aider.conf.yml
model: openai/kimi-k3
openai-api-base: https://api.cozyapi.com/v1
weak-model: openai/minimax-m2.7
editor-model: openai/glm-5.2
edit-format: diff

Keep the key out of the YAML file and in .env. The YAML file is the one people commit by accident.

Every flag also has an AIDER_-prefixed environment variable — AIDER_MODEL, AIDER_EDIT_FORMAT, AIDER_WEAK_MODEL — which is the cleanest way to configure Aider inside CI or a container.

Three models, three jobs

Aider does not use one model for everything, and this is where most of the available cost saving lives.

--model is the main chat model. It does the thinking and writes the code. This is where your capability budget should go.
--weak-model writes commit messages and summarises chat history. It runs constantly and the work is trivial. Point it at the cheapest thing that produces a coherent sentence.
--editor-model is used in architect mode to translate a proposed change into actual file edits. It needs reliable formatting, not brilliance.

Architect mode is worth understanding because it changes the economics. The main model proposes a change in prose; the editor model turns that into a diff. You can therefore put an expensive, strong model on the reasoning and a fast, cheap one on the mechanical edit:

aider --architect \
  --model openai/kimi-k3 \
  --editor-model openai/qwen-3.5-coder \
  --editor-edit-format editor-diff

--architect is a shortcut for --chat-mode architect. The other modes are code (the default), ask for questions with no edits, and help for questions about Aider itself. You can switch mid-session with /chat-mode, and swap models with /model, /editor-model and /weak-model.

Teaching Aider about an unknown model

Aider ships metadata for models it knows. Point it at an alias it has never seen and two things degrade: it cannot show you accurate token costs, and it does not know the context window, so its repo-map sizing and history summarisation become guesses.

Fix that with .aider.model.metadata.json, searched in the same three locations:

{
  "openai/kimi-k3": {
    "max_input_tokens": 1000000,
    "max_output_tokens": 32000,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}

The key must be the fully qualified name including the provider prefix — the same string you pass to --model. You can add input_cost_per_token and output_cost_per_token if you want the in-session cost readout to be meaningful; on a flat-rate plan those numbers are not tracking a bill, so leaving them out is reasonable.

Behaviour, as opposed to metadata, lives in .aider.model.settings.yml:

- name: openai/kimi-k3
  edit_format: diff
  use_repo_map: true
  streaming: true
  extra_params:
    max_tokens: 16384

Anything under extra_params is passed straight through to the underlying LiteLLM call, including extra_headers if your gateway needs one. There is also a special entry name, aider/extra_params, whose parameters apply to every model, with per-model settings winning on conflict.

Choosing an edit format

The edit format determines how the model is asked to express changes, and it is the setting most likely to be behind a session that keeps failing to apply edits.

whole — the model returns the entire file. Reliable, and expensive on large files. A good fallback when a model keeps producing malformed diffs.
diff — search-and-replace blocks. The usual choice for capable models, and much cheaper on output tokens.
diff-fenced — a fenced variant oriented at Gemini models.
udiff — unified diff format.
editor-diff and editor-whole — intended for the editor model in architect mode, via --editor-edit-format.

If a model is strong but keeps having edits rejected, drop it to whole and see whether the failures stop. If they do, the problem was formatting rather than capability.

Working practices that matter more than configuration

Aider reads your git repo and builds a map of it, but it only puts files you have explicitly added into the editable context. Adding your whole project is the most common cause of a session that is slow, expensive and unfocused. Add the two or three files that need to change, use /drop when you are done with them, and let the repo map handle the rest.

Aider commits after each change by default, which is a feature rather than a nuisance: /undo reverses the last one cleanly, and a granular history makes it obvious which instruction produced which regression. Work on a branch and let it commit freely.

A CONVENTIONS.md file loaded with --read is the highest-leverage thing you can add. Aider keeps it in context without treating it as editable, and it is where your naming rules, testing patterns and framework choices belong.

When it does not work

Provider not recognised — the openai/ prefix is missing from --model.
404 on the endpoint — a doubled /v1. The base URL should end at /v1 once.
401 — the key is not reaching the process. Check that your .env is in the git root, not a subdirectory.
Edits rejected repeatedly — change edit-format to whole and retest.
Context truncated unexpectedly — Aider does not know the model's window. Add it to .aider.model.metadata.json.

Because the whole configuration is a base URL, a key and a prefixed model name, changing provider later is a two-line edit. That portability is the reason to prefer OpenAI-compatible endpoints over tool-specific integrations in the first place.