Codex Configuration

1.Install Codex

Make sure Node.js and npm are installed locally, then run (the command is the same on Windows and macOS):

npm install -g @openai/codex

After the installation is complete, check whether Codex was installed successfully:

codex --version

2.Configure the Access Token

Add the token obtained from TokenSwitch to an environment variable.

macOS Configuration

If you use Zsh (the macOS default), run:

echo 'export OPENAI_API_KEY="YOUR_TOKEN"' >> ~/.zshrc
source ~/.zshrc

If you use Bash, run:

echo 'export OPENAI_API_KEY="YOUR_TOKEN"' >> ~/.bashrc
source ~/.bashrc

You can also set the token temporarily for the current terminal session:

export OPENAI_API_KEY="YOUR_TOKEN"

Windows Configuration

Option 1: Permanent configuration (recommended)

Run the following in PowerShell to write the token to a user-level environment variable:

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_TOKEN", "User")

After setting it, reopen PowerShell or the Command Prompt for the change to take effect.

You can also set it through the GUI: press Win + R, enter sysdm.cpl, click "Environment Variables" on the "Advanced" tab, and create OPENAI_API_KEY under "User variables".

Option 2: Set temporarily for the current PowerShell session only

$env:OPENAI_API_KEY = "YOUR_TOKEN"

Do not commit your actual token to a Git repository or write it directly into a project configuration file.

3.Create the Codex Configuration File

macOS Configuration File Path

The default location of the Codex user-level configuration file is:

~/.codex/config.toml

If the .codex directory does not exist, create it first:

mkdir -p ~/.codex

Then edit the configuration file:

nano ~/.codex/config.toml

You can also open the file with another text editor.

Windows Configuration File Path

The default location of the Codex user-level configuration file is:

C:\Users\YOUR_USERNAME\.codex\config.toml

If the .codex directory does not exist, create it in PowerShell:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

Then edit the configuration file:

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

You can also open the file with another text editor such as VS Code:

code "$env:USERPROFILE\.codex\config.toml"

4.Custom Provider Configuration Example

Add the following content to the configuration file (the content is the same on Windows and macOS):

# The model used by Codex by default; replace it with a model supported by TokenSwitch
model = "YOUR_MODEL_NAME"

# Use the Neolink provider defined below
model_provider = "neolink"

# Confirmation policy used before executing commands
approval_policy = "on-request"

# Allow Codex to read and write files in the current workspace
sandbox_mode = "workspace-write"

[model_providers.neolink]
# Provider display name
name = "Neolink"

# API endpoint provided by TokenSwitch
base_url = {{apiUrl}}

# Read the access token from this environment variable
env_key = "OPENAI_API_KEY"

# Use the OpenAI Responses API protocol
wire_api = "responses"

# The custom provider does not require signing in with an official OpenAI account
requires_openai_auth = false

Replace the following value in the configuration:

model = "YOUR_MODEL_NAME"

with the name of a model currently supported by TokenSwitch.

Configuration Options

Option	Description
model	The model used by Codex by default. It must match a model supported by the server.
model_provider	The model provider currently in use. It corresponds to a provider defined under model_providers.
approval_policy	The command execution confirmation policy. on-request means Codex requests confirmation when needed.
sandbox_mode	The sandbox permission mode. workspace-write allows Codex to read and modify files in the current workspace.
base_url	The API base URL provided by TokenSwitch.
env_key	The name of the environment variable that stores the access token.
wire_api	The API communication protocol. This example uses responses.
requires_openai_auth	Whether signing in with an official OpenAI account is required. This is usually set to false for a custom provider.

Approval Policy

The approval_policy option controls whether Codex needs user confirmation before executing commands.

A commonly used configuration is:

# Ask for confirmation when Codex considers it necessary
approval_policy = "on-request"

When using Codex for the first time, it is recommended to keep on-request to prevent Codex from performing potentially risky operations without confirmation.

Sandbox Mode

The workspace-write mode allows Codex to read files and make changes within the current workspace:

sandbox_mode = "workspace-write"

This mode is suitable for everyday development. Codex may request additional authorization when it needs to access files outside the workspace or perform restricted operations.

If you only want Codex to analyze code without modifying files, use:

sandbox_mode = "read-only"

5.Check the Environment Variable

Before starting Codex, verify that the token is available.

macOS/Linux:

test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY is configured" || echo "OPENAI_API_KEY is not configured"

Windows (PowerShell):

if ($env:OPENAI_API_KEY) { "OPENAI_API_KEY is configured" } else { "OPENAI_API_KEY is not configured" }

This command only checks whether the environment variable exists. It does not print the token.

6.Start Using Codex

Navigate to your project directory:

cd your-project

Start Codex:

codex

After Codex starts, it reads the default model, provider, approval policy, and sandbox settings from the configuration file.

7.Restore Existing Codex CLI History

Switching to a TokenSwitch API Key only changes the identity credentials Codex uses when requesting a model. It usually does not delete the Codex CLI sessions already on your machine. Codex CLI history is stored in the local Codex data directory, not in the API Key.

Restore in the Original Runtime Environment

Try to use the same environment as when you previously signed in with your GPT account:

• System user
• Operating system or terminal environment
• Codex data directory
• Project working directory

First, check the current Codex data directory:

macOS/Linux:

echo "${CODEX_HOME:-$HOME/.codex}"

Windows (PowerShell):

if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$env:USERPROFILE\.codex" }

Then check whether local sessions exist:

macOS/Linux:

ls -la "${CODEX_HOME:-$HOME/.codex}"
ls -la "${CODEX_HOME:-$HOME/.codex}/sessions"

Windows (PowerShell):

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$env:USERPROFILE\.codex" }
Get-ChildItem -Force $codexHome
Get-ChildItem -Force "$codexHome\sessions"

If the old sessions are still in the current data directory, try resuming the most recent session:

codex resume --last

You can also open the session selection list:

codex resume

If the target session does not appear in the list, run the command in the original project directory, or show sessions across all projects:

codex resume --all

After switching the API Key, a restored old session keeps its original context, but subsequent model requests are sent through the currently configured TokenSwitch service.

Migrate History from Another Environment

If you previously used Codex on another system user, computer, Windows, WSL, or container, you need to copy the Codex data directory from the original environment.

macOS/Linux Migration Steps

Before migrating, close all running Codex processes and back up the current directory:

cp -a ~/.codex ~/.codex.backup

Package the Codex data in the original environment:

tar -czf codex-history.tar.gz -C "$HOME" .codex

After safely copying the archive to the new environment, extract it:

tar -xzf codex-history.tar.gz -C "$HOME"

Then check and resume the sessions:

codex resume --all

If you only want to migrate sessions and avoid overwriting the config.toml and token configuration in the new environment, copy only the sessions directory from the original environment, for example:

mkdir -p ~/.codex/sessions
cp -a /original-user-home/.codex/sessions/. ~/.codex/sessions/

Windows Migration Steps

Before migrating, close all running Codex processes and back up the current directory in PowerShell:

Copy-Item -Recurse -Force "$env:USERPROFILE\.codex" "$env:USERPROFILE\.codex.backup"

Package the Codex data in the original environment:

Compress-Archive -Path "$env:USERPROFILE\.codex" -DestinationPath "codex-history.zip"

After safely copying the archive to the new environment, extract it:

Expand-Archive -Path "codex-history.zip" -DestinationPath $env:USERPROFILE -Force

Then check and resume the sessions:

codex resume --all

If you only want to migrate sessions and avoid overwriting the config.toml and token configuration in the new environment, copy only the sessions directory:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\sessions"
Copy-Item -Recurse -Force "ORIGINAL_PATH\.codex\sessions\*" "$env:USERPROFILE\.codex\sessions\"

Version Compatibility

Different Codex versions may use different file structures. Before migrating, it is recommended to upgrade Codex in both the old and new environments to the same version:

npm install -g @openai/codex@latest
codex --version

Migrating Between Windows and WSL

Windows and WSL use different user directories. For example:

• Windows: C:\Users\YOUR_USERNAME\.codex
• WSL: /home/YOUR_USERNAME/.codex

From Windows to WSL:

If you previously used Codex in Windows PowerShell and now run it in WSL, copy the sessions from Windows in WSL:

mkdir -p ~/.codex/sessions
cp -a /mnt/c/Users/YOUR_WINDOWS_USERNAME/.codex/sessions/. ~/.codex/sessions/

From WSL to Windows:

Run the following in Windows PowerShell:

$wslUser = "YOUR_WSL_USERNAME"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\sessions"
Copy-Item -Recurse -Force "\\wsl$\Ubuntu\home\$wslUser\.codex\sessions\*" "$env:USERPROFILE\.codex\sessions\"

Then run:

codex resume --all

Records That Cannot Be Synced

The following records cannot be automatically synced through a TokenSwitch API Key:

• Chat history in the ChatGPT web app or client
• Records stored only in the GPT/OpenAI account cloud and not written to the local Codex data directory
• Codex CLI sessions that have been deleted from the local machine without a backup

A TokenSwitch API Key is only responsible for model endpoint authentication. It cannot read GPT/OpenAI account chat history. If a record exists only in the ChatGPT web app, you need to manually export or copy the relevant content from the original account. It cannot be directly imported as Codex CLI history.

8.Troubleshooting

The Configuration File Does Not Take Effect

Confirm that the configuration file path is correct:

macOS/Linux:

ls -la ~/.codex/config.toml

Windows (PowerShell):

Test-Path "$env:USERPROFILE\.codex\config.toml"
Get-Content "$env:USERPROFILE\.codex\config.toml"

Also check that the TOML syntax is valid. For example, strings must be enclosed in quotation marks, and configuration options must not be defined more than once.

API Key Is Missing

Check whether the environment variable has been set:

macOS/Linux:

test -n "$OPENAI_API_KEY" && echo "Configured" || echo "Not configured"

Windows (PowerShell):

if ($env:OPENAI_API_KEY) { "Configured" } else { "Not configured" }

macOS/Linux: If you have just modified ~/.zshrc, reload the configuration:

source ~/.zshrc

If you use Bash, run:

source ~/.bashrc

You can also close the current terminal and open a new one.

Windows: If you have just set a permanent environment variable, reopen PowerShell or the Command Prompt for it to take effect.

The Model Is Unavailable

Check whether the model name in config.toml exactly matches a model supported by TokenSwitch:

model = "YOUR_MODEL_NAME"

If the model name, API address, or protocol configuration is incorrect, Codex may return errors such as model not found, unsupported endpoint, or request failure.

The API Does Not Support the Responses API

The configuration above uses the Responses API by default:

wire_api = "responses"

Make sure the TokenSwitch endpoint you are using supports the Responses API. If the server supports only another protocol, adjust the configuration according to the server's actual compatibility requirements.