Aider OpenAI-Compatible API Setup: Base URL, API Key, and Model Configuration

Aider can connect to an OpenAI-compatible API with a small amount of configuration: one model string, one base URL, and one API key. The part that usually trips people up is the naming layer. Aider wants an OpenAI-compatible model name with the openai/ prefix, while the gateway still expects the raw upstream model ID. If you blur those two layers together, you usually get model_not_found, 401 Unauthorized, or a request that points at the wrong path.

This guide shows how to set up Aider with OurToken's unified OpenAI-compatible endpoint, how to configure aider api key and aider api base url, how to define a practical aider custom model layout, and how to diagnose the common aider model not found failure. The same gateway can serve GPT-5.6 Terra, DeepSeek V4 Pro, and GLM 5.2, so you can keep one secret and change only the model choice.

Aider's public docs confirm the relevant settings: --model, --openai-api-key, --openai-api-base, and the matching .aider.conf.yml keys. The docs also note that OpenAI-compatible model names should be prefixed with openai/, which is the detail that makes the rest of the setup click. See the Aider configuration docs, Aider API key docs, and Aider OpenAI-compatible docs for the canonical references.

Verification status: The Aider configuration names were checked against the public Aider docs on 2026-08-24, and the model examples were aligned with the current OurToken model pages. Run the examples with your own server-side API key.

The Short Version

If you just want the working configuration, start here:

Aider model:     openai/gpt-5.6-terra
Base URL:        https://api.ourtoken.ai/v1
API key:         your-own-secret-key
Upstream model:  gpt-5.6-terra

That means:

• Aider sees openai/gpt-5.6-terra.
• The OpenAI-compatible gateway sees gpt-5.6-terra.
• The request path becomes /v1/chat/completions under the base URL.

Do not paste /chat/completions into the base URL. Aider's OpenAI-compatible layer expects the gateway root, not the full operation path.

What Aider Actually Needs

Aider has three separate concerns here: how it finds the model, where it sends the request, and how it authenticates.

The important line is the base URL. Aider's docs show --openai-api-base, and the config-file version is openai-api-base. The value should stop at /v1. If you go one level deeper and set /v1/chat/completions, you usually end up with a doubled path and a confusing 404.

CLI Setup

The fastest way to get moving is to set the key and base URL in the shell, then launch Aider with the model prefix it expects.

On macOS or Linux:

export AIDER_OPENAI_API_KEY="your-api-key"
export AIDER_OPENAI_API_BASE="https://api.ourtoken.ai/v1"
aider --model openai/gpt-5.6-terra

On Windows PowerShell:

$env:AIDER_OPENAI_API_KEY = "your-api-key"
$env:AIDER_OPENAI_API_BASE = "https://api.ourtoken.ai/v1"
aider --model openai/gpt-5.6-terra

You can also pass the values directly on the command line:

aider \
  --model openai/gpt-5.6-terra \
  --openai-api-base https://api.ourtoken.ai/v1 \
  --openai-api-key YOUR_API_KEY

That is the smallest end-to-end setup. If it works, Aider is talking to the right gateway and the model prefix is correct.

.aider.conf.yml Setup

If you want a repeatable local setup, put the non-secret values in .aider.conf.yml and keep the API key in an environment variable or secret manager.

Aider's config docs say the file can live in your git root, current working directory, or home directory. In practice, the repo root is usually the least annoying place because the configuration travels with the project without depending on a global shell state.

model: openai/gpt-5.6-terra
openai-api-base: https://api.ourtoken.ai/v1
weak-model: openai/glm-5.2
editor-model: openai/deepseek-v4-pro

Then keep the key in the shell:

export AIDER_OPENAI_API_KEY="your-api-key"

If you prefer .env, Aider can read that too through its normal environment loading path. The shape is the same:

AIDER_OPENAI_API_KEY=your-api-key
AIDER_OPENAI_API_BASE=https://api.ourtoken.ai/v1
AIDER_MODEL=openai/gpt-5.6-terra

Do not commit a real secret to the repository. The file example above is only a local placeholder.

Aider Custom Model Strategy

This is where aider custom model becomes useful instead of just decorative. Aider is not limited to one model string. You can set different routes for different jobs and keep the rest of your workflow stable.

A simple OurToken mapping looks like this:

The openai/ prefix is only for Aider. It is not part of the model ID that the upstream API sees. That distinction matters a lot:

• In Aider, you write openai/gpt-5.6-terra.
• In the JSON request body, the gateway sees gpt-5.6-terra.

If you keep that split in your head, a lot of model errors become obvious instead of mysterious.

For a more structured setup, give Aider explicit roles:

aider \
  --model openai/gpt-5.6-terra \
  --weak-model openai/glm-5.2 \
  --editor-model openai/deepseek-v4-pro

That keeps the default assistant route, the cheaper route, and the stronger editing route in one place. If your team likes friendly names, Aider also supports --alias ALIAS:MODEL, which lets you map internal labels onto the same upstream models.

Verify the Gateway Before Debugging Aider

When something fails, test the gateway directly first. That cuts the problem in half.

If your gateway exposes /v1/models, list the available IDs and copy the exact data[].id value instead of guessing from a marketing page or a UI label:

curl https://api.ourtoken.ai/v1/models \
  -H "Authorization: Bearer $OURTOKEN_API_KEY"

Then send a minimal chat-completions request:

curl https://api.ourtoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $OURTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 32
  }'

If that works, Aider only needs to reuse the same base URL and key. If that fails, fix the gateway first instead of tweaking Aider for an hour.

For OurToken, the current model pages are the best source of truth for availability and the exact model IDs:

• GPT-5.6 Terra
• DeepSeek V4 Pro
• GLM 5.2

Common Failure Modes

Most Aider connection problems fall into one of a few buckets.

The most common bug is a naming mismatch. Aider wants a provider-style model name, while the gateway wants the raw model ID. If you copy a display label such as GPT-5.6 Terra instead of the actual ID, the request can fail even though the endpoint and key are fine.

Security and Production Use

Aider can edit files, run commands, and keep a chat history. That means the API configuration is part of your application security, not just a convenience setting.

Keep these habits in place:

• store the key in AIDER_OPENAI_API_KEY or a local secret manager;
• keep openai-api-base at the gateway root, not the full path;
• keep model selection on the server or in a trusted config file;
• restart Aider after changing config files or environment variables;
• log the model ID, request latency, and failure reason when you test new routes.

If you are using more than one model, choose the default route by workload rather than by brand. For example, use openai/gpt-5.6-terra for normal coding work, openai/deepseek-v4-pro for tougher refactors, and openai/glm-5.2 for cheaper or higher-volume tasks. That keeps cost and quality decisions visible instead of accidental.

Conclusion

A working Aider OpenAI-compatible setup on OurToken is compact: create an API key, set AIDER_OPENAI_API_BASE to https://api.ourtoken.ai/v1, prefix the model in Aider as openai/gpt-5.6-terra, and keep the raw upstream model ID separate from the Aider model string. Start with a single model, confirm a short response, then add weak-model, editor-model, or aliases once the basic path is solid.

When you are ready to switch routes, use the live OurToken model pages and Aider's docs as the source of truth. That is the fastest way to avoid aider model not found and the kind of base URL mistake that wastes an afternoon.

FAQ

Why does Aider want openai/ in front of the model name?

Because Aider uses that prefix to route through its OpenAI-compatible provider path. The upstream gateway still receives the raw model ID.

What base URL should I use for OurToken?

Use https://api.ourtoken.ai/v1. Do not append /chat/completions to the base URL.

Why do I get model_not_found?

Usually because the model string is wrong, the openai/ prefix was omitted, or the account does not have access to that route.

Can I put the API key in .aider.conf.yml?

Aider supports key settings in the config file, but a server-side environment variable is safer for most projects.