Plandex with a Custom OpenAI-Compatible Provider

Plandex is a terminal coding engine built for tasks that span many files and many steps. It splits a large task into subtasks, implements each one, and accumulates the changes in a sandbox you review before they touch your files. Pointing it at your own OpenAI-shaped endpoint is straightforward once you know which of the two mechanisms you are using, because Plandex has two and they do not overlap.

Custom providers live in a JSON file, not in an environment variable. OPENAI_API_BASE only re-points the built-in OpenAI provider; it does nothing for a provider you declared yourself. In the file, baseUrl includes the /v1 — the opposite of Spring AI, where the version prefix belongs in a separate property. And apiKeyEnvVar is the name of a variable, not the key itself, which is the single most common way to end up with a configuration that looks complete and fails authentication.

This page covers both mechanisms, where the file has to live, why a correct file can still be ignored on hosted plans, and what a month of long-running agent work costs once the context is counted.

Two mechanisms that do not overlap

Plandex ships with a set of built-in providers — OpenAI, OpenRouter, Anthropic, Google AI Studio and Vertex, Azure OpenAI, AWS Bedrock, DeepSeek, Perplexity and Ollama — plus a custom provider you define yourself.

There are two ways to aim the built-in OpenAI provider somewhere else:

export OPENAI_API_KEY=...
export OPENAI_API_BASE=https://gw.example.com/v1   # optional; re-points the built-in OpenAI provider

That is a redirect of an existing provider. It does not create one, and it does not apply to anything you declared in the models file.

The second mechanism is the custom models file:

plandex models custom      # or \models custom inside the REPL

The first run writes a template file and opens it in your editor. It has a $schema line pointing at https://plandex.ai/schemas/models-input.schema.json, so editors that understand JSON Schema give you completion and inline validation while you type. The file has three sections: providers, models and modelPacks.

A provider entry looks like this:

{
  "providers": [
    {
      "name": "my-gateway",
      "baseUrl": "https://gw.example.com/v1",
      "apiKeyEnvVar": "MY_GATEWAY_API_KEY"
    }
  ]
}

name is your own identifier. baseUrl is the endpoint and it must be OpenAI-compatible — including the version segment, so it ends in /v1. apiKeyEnvVar names the environment variable that holds the key; you export that variable in your shell and Plandex reads it. For a local server that does not authenticate, skipAuth replaces the key requirement, and extraAuthVars adds further variables when a gateway wants more than one header.

apiKeyEnvVar takes a name, not a key

This is the trap. The field is called *EnvVar, and the natural thing to paste into it is the key you were given:

{ "name": "my-gateway", "baseUrl": "https://gw.example.com/v1",
  "apiKeyEnvVar": "sk-live-abc123" }

Now Plandex looks for an environment variable literally named sk-live-abc123, finds nothing, and sends an unauthenticated request. There is no complaint about a malformed credential — you get the same 401 you would get from a wrong key, and the file looks right when you read it back.

The correct pairing is a name in the file and a value in the shell:

export MY_GATEWAY_API_KEY=sk-live-abc123

How much of the file is honoured depends on the plan

A correct file can be silently inert, and the reason is not in the file. Support for custom configuration is tiered by how you run Plandex:

• Self-hosted — custom providers, models and model packs all work.
• Cloud with your own API keys — custom models and model packs work, but models may only use built-in providers. A custom provider in your file is not used.
• Cloud with integrated models — only custom model packs, and only over built-in models.

So the same file that works against a self-hosted server does nothing on a cloud plan with integrated models. If a declared provider never appears, check which of the three you are on before re-reading the JSON for the fourth time.

Models, packs, and the command that selects them

Declaring a provider is not the same as using it. A models entry maps a model onto a provider and declares what it can do, and a modelPacks entry groups models into the roles Plandex fills — one model for planning, another for implementation, and so on.

Selection happens through plandex set-model, which updates the current plan, or plandex set-model default, which updates the organisation-level default. Run with no argument it opens a picker; run with --file it loads a JSON configuration. If you ever set a model explicitly, a later release that changes the default pack will not move you — you have to run set-model again to pick up the new default.

That matters for cost as much as for quality: the pack decides which model sees the large planning context and which one writes the small per-file diffs, and those are very different token shapes.

Why the input side is the whole bill

Plandex keeps the relevant files in context and keeps them updated as the work proceeds, so every subtask carries the state of the task so far. A long plan re-reads that context repeatedly. Output, by contrast, is one diff at a time.

A day of work on this page's workload is 400k input and 45k output tokens — 8M input and 0.9M output across 20 working days. With a ratio that wide, the input rate decides the month and the output rate is rounding; why output pricing dominates the bill explains the cases where that inverts.

One day = 400k input + 45k output on this page's workload. 20 days = 8M input and 0.9M output. Rates checked 2026-10-10 — gateway rates move with upstream promotions, so verify the current number in your dashboard before committing to a budget.

Verifying the route

1. Confirm which mechanism you are using. OPENAI_API_BASE only moves the built-in OpenAI provider. A declared custom provider comes from the models file, and only on plans that honour it.
2. Print the variable, not the file. echo $MY_GATEWAY_API_KEY. If that is empty, apiKeyEnvVar is pointing at a name nobody set.
3. Check the path in the gateway log. baseUrl must end in /v1; a doubled /v1/v1 means the version segment is in both the file and the gateway's own routing.
4. Run plandex set-model and pick the pack that uses your provider. Declaring a provider is not selecting it.
5. Start a deliberately small plan — one file, one change. It exercises provider, key, model id and pack together in a minute, and it tells you which of the four failed before you have paid for a large context.

FAQ

FAQ

Related

• Aider — the other terminal agent, configured through a different surface
• Crush — CLI agent with its own provider file convention
• Tools that take one endpoint — the full matrix of clients with a custom base URL field
• Official list prices vs gateway rates — which of the two numbers on this page is which

Get API access