VoyageAge

Codex Developer Guide

Use Codex with a Custom API Provider

Codex supports custom model providers through the user-level config.toml. This is a task-focused provider walkthrough; for complete installation, persistent configuration, and troubleshooting, use the full VoyageAge Codex documentation.

Get API Key Full Codex Docs
config.tomlactive provider
model_providervoyageage
base_url
https://api.voyageage.com/v1
env_key
VOYAGEAGE_API_KEY
wire_api
responses
model
gpt-5.6-sol

Fast path

Codex Custom API Setup in a Few Steps

Start with a temporary API-key variable and a user-level provider configuration. Persistent setup and restore instructions remain in the full documentation.

  1. 01

    Create an API key

    Create a dedicated VoyageAge key for the Codex provider.

  2. 02

    Open config.toml

    Use the user-level .codex configuration file for provider settings.

  3. 03

    Add the provider

    Define model_providers.voyageage and select it at the top level.

  4. 04

    Set the key variable

    Load VOYAGEAGE_API_KEY in the terminal where Codex will run.

  5. 05

    Start Codex

    Use a supported model ID such as gpt-5.6-sol.

  6. 06

    Verify the request

    Run a read-only task and confirm a Responses entry in VoyageAge Console.

Provider definition

Add VoyageAge to Codex config.toml

This example is generated from the same VoyageAge endpoint and model metadata used by the product documentation. Merge it into the user-level file; do not duplicate existing top-level keys.

Windows%USERPROFILE%\.codex\config.tomlmacOS / Linux~/.codex/config.toml

TOML~/.codex/config.toml
model_provider = "voyageage"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"

[model_providers.voyageage]
name = "VoyageAge"
base_url = "https://api.voyageage.com/v1"
env_key = "VOYAGEAGE_API_KEY"
wire_api = "responses"
Responses providerhttps://api.voyageage.com/v1
SettingWhat it does
model_providerSelects the provider ID defined in model_providers; here it selects voyageage.
modelSelects the Responses-capable model Codex requests through the active provider.
base_urlSends provider requests to https://api.voyageage.com/v1; Codex appends the Responses path.
env_keyTells Codex to read the provider API key from VOYAGEAGE_API_KEY.
wire_apiUses the Responses protocol. The current Codex configuration reference supports responses.

OpenAI's current Codex configuration reference defines model_provider as a provider ID, env_key as the API-key environment variable, and responses as the supported provider wire protocol.

Temporary key setup

Run Codex on Windows, macOS, or Linux

Create or open the config file, set the key only in the current terminal, then start Codex. Closing the terminal removes the temporary variable.

PowerShell

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
notepad "$HOME\.codex\config.toml"
$env:VOYAGEAGE_API_KEY = "YOUR_VOYAGEAGE_API_KEY"
codex
bash

macOS / Linux

mkdir -p ~/.codex
${EDITOR:-nano} ~/.codex/config.toml
export VOYAGEAGE_API_KEY="YOUR_VOYAGEAGE_API_KEY"
codex

Need installation, Windows CMD, persistent variables, restore steps, or the complete troubleshooting reference? Read the full Codex CLI documentation.

Request path

How the Codex Provider Connection Works

Developer agentCodex
ConfigurationCustom model provider
API gatewayVoyageAge API
TargetResponses-capable model

The provider entry controls the destination and authentication source; wire_api = "responses" selects the request protocol Codex uses.

VoyageAge is an independent third-party AI API gateway and is not affiliated with OpenAI.

This page focuses on Codex CLI. The current VoyageAge Codex Desktop reference uses the same user-level provider configuration, but desktop environment variables and restart behavior differ by operating system.

Connection check

How to Verify Codex Is Using VoyageAge

Use a harmless, read-only task in a disposable directory before relying on the configuration for real work.

  1. 1

    Open the terminal where VOYAGEAGE_API_KEY is currently set.

  2. 2

    Run codex in a disposable directory and ask it to list files without modifying anything.

  3. 3

    Confirm Codex returns a normal response using the configured model.

  4. 4

    Open VoyageAge Console and find the matching Responses request.

  5. 5

    Confirm the request records the provider workflow and model you selected.

The VoyageAge status page shows service health; use VoyageAge Console to confirm an individual request and model.

Common problems

Fix Common Codex Custom Provider Issues

Check the user-level file first, then the selected provider, endpoint, environment variable, and model ID.

401 Unauthorized

Confirm VOYAGEAGE_API_KEY is present in the same terminal, contains an active key, and has no copied whitespace.

Codex still calls OpenAI

Confirm the active top-level model_provider is voyageage in the user-level config.toml. Project-local config cannot override provider settings.

404 Endpoint Not Found

Use https://api.voyageage.com/v1 as base_url. Do not append /responses; Codex adds the protocol endpoint.

Model Not Found

Copy a current Responses-capable model ID from https://api.voyageage.com/v1/models, update model, and restart Codex.

config.toml parse error

Remove duplicate top-level keys, use paired quotes, and verify the table name is [model_providers.voyageage].

Need deeper troubleshooting? Open the full Codex docs

Provider flexibility

Why Use a Custom Provider with Codex?

01

Endpoint Control

Choose the API base URL used by the active Codex provider.

02

Centralized API Access

Use a dedicated VoyageAge key and Console workflow for eligible requests.

03

Provider and Model Flexibility

Change the active provider or supported model through user-level configuration.

04

Unified VoyageAge Billing

Manage eligible model usage alongside other VoyageAge API workloads.

For the broader API workflow, explore the VoyageAge OpenAI-compatible API. Using Claude Code instead? See the Claude Code custom API setup guide.

Quick answers

Codex Custom API FAQ

01

Can Codex use a custom API provider?

Yes. Codex supports custom provider definitions in the user-level config.toml. Select the definition with the top-level model_provider setting.

02

Where is the Codex config.toml file?

The user-level file is ~/.codex/config.toml. On Windows, that resolves to %USERPROFILE%\.codex\config.toml.

03

How do I set a custom base URL in Codex?

Set base_url inside your [model_providers.<id>] table, then select that provider ID with model_provider. For VoyageAge, use the value shown above.

04

What does model_provider do in Codex?

It selects a provider ID from model_providers. The selected definition supplies Codex with its API destination and authentication settings.

05

Why is Codex still using the OpenAI endpoint?

The usual causes are editing a project-local file instead of the user-level file, leaving model_provider set to openai, or retaining a duplicate top-level setting.

06

Can I use VoyageAge with Codex?

Yes. Add the VoyageAge Responses provider, keep the API key in VOYAGEAGE_API_KEY, and select a supported model ID.

Start with a temporary key

Connect Codex to VoyageAge

Create an API key, add the provider to your user-level config, and verify one harmless Responses request.

Get API Key Full Codex Docs
Need help?Chat on Discord