Run Codex CLI with an OpenAI-Compatible Base URL

Agents at the terminalEN2026-10-24

Codex CLI can use a custom model provider instead of its default connection. The key settings are the provider’s base URL, an environment variable containing its API key, and an exact model identifier. This walkthrough configures those settings for Vana API without replacing your existing default configuration.

Vana API provides one OpenAI-compatible endpoint at https://api.vanaapi.com and also supports Anthropic Messages and Gemini native protocols. For Codex, use the OpenAI-compatible interface. Billing is per real token, with no monthly fee.

§ 1. Install Codex and check protocol compatibility

Install the official Codex CLI through npm if it is not already available:

 1  npm install -g @openai/codex

Confirm that the executable runs:

codex --version

Check the API protocol before configuring the URL. Current Codex CLI configurations use the OpenAI Responses API for custom providers. An endpoint that supports only Chat Completions is not sufficient. Confirm that your selected Vana API model supports the Responses route and the tool interactions Codex needs. Support for an OpenAI SDK alone does not establish this.

§ 2. Prepare your key and model identifier

Create a Vana API account, generate an API key, and copy the exact API model identifier from the dashboard or model listing. A display name such as GPT-6.1 Sol is not necessarily the string accepted in the model field.

Keep the key outside your repository. In Bash, the following command prompts for it without displaying it or placing the literal secret in your command history:

read -r -s -p 'Vana API key: ' VANA_API_KEY; export VANA_API_KEY; printf '\n'

The exported variable is available to Codex processes launched from that terminal. It does not automatically persist in a new terminal session. Do not commit credentials to configuration files, shell scripts, or project documentation.

§ 3. Run Codex with an explicit provider

The following command defines a provider named vana for this invocation. Replace MODEL_ID with the exact identifier you copied. It uses https://api.vanaapi.com/v1 as the OpenAI-compatible API root; confirm that root against the current connection details in your dashboard.

codex -c 'model_provider="vana"' -c 'model_providers.vana={name="Vana API",base_url="https://api.vanaapi.com/v1",env_key="VANA_API_KEY",wire_api="responses"}' -m 'MODEL_ID'

Run the command from a small test repository. The provider definition tells Codex where to send requests, which environment variable supplies the bearer token, and which wire protocol to use. The model option selects the upstream model.

Use an API root, not a complete operation URL. Do not append /responses or /chat/completions to base_url. Codex constructs the operation path itself.

§ 4. Verify a small coding task

Start with a bounded, read-only request: “Summarize this repository and identify its test command. Do not modify files.” Review any requested permissions before approving them.

Confirm that Codex can inspect files and return a useful answer. Then try a small change in a disposable branch. A successful text response is only the first check: an agent workflow also needs reliable tool calls, follow-up requests, and streaming behavior.

Keep normal approval and sandbox controls enabled. Changing the API endpoint does not require giving the agent unrestricted access to your machine.

§ 5. Save the configuration if the test works

For repeated use, move the tested provider settings into your user-level Codex configuration at ~/.codex/config.toml. Define model_provider and model at the top level, then add a model_providers.vana table containing name, base_url, env_key, and wire_api with the same values used above.

Merge those settings with existing configuration rather than overwriting the file. Leave the API key in the environment. If you regularly switch providers, use a Codex configuration profile instead of changing your default provider.

§ 6. Troubleshoot by error type

Authentication failure: Check that VANA_API_KEY is exported in the terminal launching Codex and that the key remains valid.
Not found: Verify the API root, Responses route availability, and exact model identifier.
Unsupported parameter or tool error: Check the selected model’s Responses and agent-tool compatibility. A different URL cannot fix a protocol mismatch.
Unexpected provider: Recheck model_provider and any active profile or command-line overrides.

Once the small test succeeds, reuse the same configuration for normal work and review token usage in Vana API as tasks grow.