Codex CLI with a different API base URL

Agents at the terminalEN2026-10-29

Running Codex CLI against another API endpoint looks like a small configuration change. The important distinction is between changing the destination and preserving the behavior Codex needs. An endpoint can accept OpenAI-style requests without supporting every feature used by a coding agent.

These notes compare the default provider path with a named custom provider, using Vana API as the concrete destination. The aim is to keep authentication, protocol support, and model selection separate enough to troubleshoot.

§ The default route and the custom route

Default provider: Codex uses its built-in OpenAI provider configuration. Authentication and available models depend on your sign-in method and account. Existing defaults make this the shorter setup path.
Custom provider: You explicitly choose a provider, API root, credential source, and model identifier. Vana API offers one endpoint at https://api.vanaapi.com, with token-based billing and no monthly fee. That changes the upstream service, not the local repository Codex works in.

A named provider is easier to inspect than a collection of shell overrides. Before changing anything, check your installed Codex version and retain a copy of your current configuration. Configuration options can change between releases.

§ Configuration, side by side

Default provider: Keep the built-in provider selected and follow the authentication flow documented for your Codex release. You normally do not need to define a custom provider table.
Vana API provider: In ~/.codex/config.toml, set the top-level entries model_provider = "vana" and model = "MODEL_ID". Replace MODEL_ID with the exact API identifier published by Vana API, not a display name.

For a Codex release supporting named providers and the Responses wire protocol, add a [model_providers.vana] table with these entries:

name = "Vana API"
base_url = "https://api.vanaapi.com/v1"
env_key = "VANA_API_KEY"
wire_api = "responses"

The model and model_provider entries belong outside the provider table. Export VANA_API_KEY in the shell that launches Codex, using your Vana API credential. Do not paste that credential into a tracked project file. Confirm the current API root in Vana API’s documentation before using this configuration; the base URL should not include a final /responses resource path.

§ Compatibility means more than matching JSON

Default provider: Codex’s built-in integration is designed around its expected API behavior, including streaming and tool interactions. Individual model capabilities still matter.
Custom provider: Verify that the selected route supports the Responses API behavior required by your Codex release. Support for Chat Completions alone does not establish that compatibility. Setting wire_api = "responses" selects a protocol; it does not add missing server features.

Vana API also speaks Anthropic Messages and Gemini native protocols. Those are useful for other clients, but they do not replace the protocol Codex sends. Likewise, a model appearing in a provider’s catalog does not by itself establish that its route handles Codex tool calls correctly.

If you select GPT-6.1 Sol, check its current API identifier and supported route rather than deriving an identifier from the display name. First test a short prompt, then a repository inspection, and finally a small edit that requires a tool call.

§ Credentials, costs, and failure signals

Default provider: Usage and authentication follow the account or API arrangement attached to that provider. Do not assume an existing subscription transfers to another endpoint.
Vana API provider: Requests use your Vana API credential and are billed per real token. A long agent session can generate many requests, so compare total session usage rather than only one response’s price.

Authentication errors suggest checking the environment variable and credential first. A not-found response can indicate an incorrect API root, unsupported resource, or invalid model identifier. Streaming failures or rejected tool calls deserve a protocol check before repeated retries. Keep logs free of secrets.

To try this route, create a Vana API account and begin with a disposable repository. Keep the default and custom provider configurations easy to distinguish, and judge the result by completed edits, reliable tool execution, latency, and total cost—not merely whether the first prompt returns text.