OpenAI Codex - onetoken docs

Use OpenAI Codex CLI and the desktop app through the OneToken API.

This guide explains how to install Codex and configure the OneToken API manually. Windows, macOS, and Linux use the same configuration values; only the configuration paths and editing commands differ.

Before you start

Get a OneToken API key from the OneToken API token page.
Make sure the key is valid and has enough quota and model access.
Install Node.js 16 or later. The current LTS release is recommended.

Replace YOUR_ONETOKEN_API_KEY in the examples with your real key. Keep API keys in local configuration files only. Never commit them to Git or publish them.

Install Codex

Desktop app

Visit the OpenAI Codex download page to get the desktop app. Desktop platform support can change, so follow the systems listed on the download page. The CLI can be configured on all three platforms with the steps below.

CLI

Run the following command in Terminal, PowerShell, or CMD:

npm install -g @openai/codex

Verify the installation:

codex --version

If your system cannot find codex, close and reopen the terminal, or check that the npm global installation directory is included in PATH.

Configure the API manually

Codex uses two files for a custom model provider:

File	Purpose
`auth.json`	Stores your API key
`config.toml`	Stores the provider, API endpoint, model, and reasoning settings

The default configuration directory is ~/.codex. If you set the CODEX_HOME environment variable, Codex uses that directory instead. The platform paths below assume CODEX_HOME is not set.

1. Edit `auth.json`

The file content is the same on all three platforms:

{
  "OPENAI_API_KEY": "YOUR_ONETOKEN_API_KEY"
}

2. Edit `config.toml`

The file content is the same on all three platforms:

model = "gpt-5.2"
model_provider = "OneToken"
model_reasoning_effort = "high"
personality = "pragmatic"
cli_auth_credentials_store = "file"

[model_providers.OneToken]
name = "OneToken"
base_url = "https://onetoken.one/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

Configuration notes:

Set base_url to https://onetoken.one/v1. Do not append /responses.
Set model to a model name listed in the OneToken model catalog. If the model name changes, update this value.
model_reasoning_effort accepts high, medium, or low.
cli_auth_credentials_store = "file" tells Codex to read credentials from auth.json, which matches the manual setup in this guide. Treat this file like a password.
The model_provider value must match the [model_providers.OneToken] section name. This guide uses OneToken as the provider ID.
To maintain multiple configurations, create a separate $CODEX_HOME/<profile-name>.config.toml file for each one (~/.codex/<profile-name>.config.toml when CODEX_HOME is not set), then start Codex with codex --profile <profile-name>. A profile file is not required for the basic setup.

Platform-specific paths and editing steps

Windows
macOS
Linux

Configuration directory

Windows stores the configuration in the current user’s .codex directory:

C:\Users\<your-username>\.codex

You can also enter this path in File Explorer:

%USERPROFILE%\.codex

.codex may be hidden. Create it if it does not exist.

Create and edit files with PowerShell

Open PowerShell.
Create the directory and both files:

$codexDir = Join-Path $env:USERPROFILE ".codex"
New-Item -ItemType Directory -Force -Path $codexDir | Out-Null
New-Item -ItemType File -Force -Path (Join-Path $codexDir "auth.json") | Out-Null
New-Item -ItemType File -Force -Path (Join-Path $codexDir "config.toml") | Out-Null

Open each file and paste the JSON and TOML content shown above:

notepad "$env:USERPROFILE\.codex\auth.json"
notepad "$env:USERPROFILE\.codex\config.toml"

Save the files as UTF-8. Make sure the names are not auth.json.txt or config.toml.txt.

Create and edit files with CMD

You can also run the following commands in CMD:

if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"
if not exist "%USERPROFILE%\.codex\auth.json" type nul > "%USERPROFILE%\.codex\auth.json"
if not exist "%USERPROFILE%\.codex\config.toml" type nul > "%USERPROFILE%\.codex\config.toml"
notepad "%USERPROFILE%\.codex\auth.json"
notepad "%USERPROFILE%\.codex\config.toml"

If Codex cannot find Bash when running project commands, install Git for Windows, then use Git Bash or reopen PowerShell.

Configuration directory

macOS stores the configuration in:

~/.codex

The full path is usually similar to /Users/<your-username>/.codex.

Create and edit files in Terminal

Open Terminal.
Create the directory and both files:

mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml

Open the files with the built-in nano editor:

nano ~/.codex/auth.json
nano ~/.codex/config.toml

Paste the JSON and TOML content shown above into the corresponding files. In nano, press Control + O, press Enter to save, then press Control + X to exit.

Restrict access to the directory and API key file:

chmod 700 ~/.codex
chmod 600 ~/.codex/auth.json ~/.codex/config.toml

You can also press Command + Shift + G in Finder and enter ~/.codex to open the directory.

Configuration directory

Linux stores the configuration in the current user’s home directory:

~/.codex

The full path is usually similar to /home/<your-username>/.codex.

Create and edit files in Terminal

Open a terminal.
Create the directory and both files:

mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml

Open the files with nano or another text editor:

nano ~/.codex/auth.json
nano ~/.codex/config.toml

Paste the JSON and TOML content shown above into the corresponding files. In nano, press Control + O, press Enter to save, then press Control + X to exit.

Restrict access to the directory and files:

chmod 700 ~/.codex
chmod 600 ~/.codex/auth.json ~/.codex/config.toml

Do not use sudo to create these files. Otherwise, they may belong to root, and your normal user may not be able to read or update them.

Start and verify Codex

After saving the configuration, close and reopen your terminal. Go to your project directory and start Codex:

cd /path/to/your/project
codex

Set-Location "C:\path\to\your\project"
codex

cd /d C:\path\to\your\project
codex

Enter a simple task such as “Reply with: setup complete”. If Codex responds, the API configuration is working. You can also run a non-interactive check:

codex -q "Reply with only: setup complete"

If Codex still uses the old settings, fully quit the CLI or desktop app and start it again. The CLI and desktop app should use the same .codex directory for the current user.

Configure with CC-Switch

If you prefer not to edit the files manually, use CC-Switch:

Open CC-Switch and add a provider.

Select OneToken from the presets.

Enter your OneToken key in API Key, then click Add.

Return to the home screen, select OneToken, and click Enable.

CC-Switch writes to the current user’s .codex directory. Restart Codex after switching providers so it loads the new configuration.

Use the Codex desktop app

Start the Codex desktop app and choose a workspace folder.
Enter a simple task to test the connection.
If the app asks you to sign in or does not load the configuration, quit the app. Check auth.json and config.toml in the current user’s .codex directory, then start the app again.

Troubleshooting

401 or 403 responses

Check that the API key in auth.json is complete, valid, and has no extra spaces.
Confirm the key’s quota, expiration, and model permissions.
Confirm that base_url is https://onetoken.one/v1 and does not contain a duplicated /v1.

Model not found

Open the OneToken model catalog, copy an available model name, and update model in config.toml.

Configuration is not applied

Make sure the files are in the current user’s .codex directory, not the project directory or another user’s directory.
On Windows, check that the files were not saved as auth.json.txt or config.toml.txt.
Make sure the provider section and model_provider both use OneToken, including matching capitalization. Newer Codex versions do not require a [profiles.OneToken] table in config.toml.
Fully quit and restart the Codex CLI or desktop app.

View command help

codex -h

Common examples:

codex -m <model> "your task"
codex -q "your task"
codex --auto-edit "your task"

--auto-edit and --full-auto reduce the number of confirmation prompts. Use them only in project directories where you understand the risks. Avoid options that bypass all safety confirmations unless you are performing temporary local testing.

​Before you start

​Install Codex

​Desktop app

​CLI

​Configure the API manually

​1. Edit auth.json

​2. Edit config.toml

​Platform-specific paths and editing steps

​Configuration directory

​Create and edit files with PowerShell

​Create and edit files with CMD

​Configuration directory

​Create and edit files in Terminal

​Configuration directory

​Create and edit files in Terminal

​Start and verify Codex

​Configure with CC-Switch

​Use the Codex desktop app

​Troubleshooting

​401 or 403 responses

​Model not found

​Configuration is not applied

​View command help

Before you start

Install Codex

Desktop app

CLI

Configure the API manually

1. Edit `auth.json`

2. Edit `config.toml`

Platform-specific paths and editing steps

Configuration directory

Create and edit files with PowerShell

Create and edit files with CMD

Configuration directory

Create and edit files in Terminal

Configuration directory

Create and edit files in Terminal

Start and verify Codex

Configure with CC-Switch

Use the Codex desktop app

Troubleshooting

401 or 403 responses

Model not found

Configuration is not applied

View command help