Codex CLI Setup

Learn how to configure the Codex CLI to use CiYuanX's API. This guide covers installation and configuration on Windows, macOS, and Linux.

What is Codex CLI?

Codex CLI is OpenAI's command-line interface, designed for code-related tasks in the terminal. Compared with general-purpose chat tools, it emphasizes engineering-ready output, delivering clearer, more actionable code changes. By configuring it to use CiYuanX, you can access multiple AI models through a cost-effective endpoint.

Prerequisites

Before you begin, make sure you have:

• A CiYuanX account (sign up here)
• A CiYuanX API key (get a key)
• Node.js v20 or later, with npm

Installation

Install the Codex CLI globally with npm:

npm install -g @openai/codex

Verify the installation:

codex --version

This should print the version number.

Configuration

Codex CLI is configured through a config.toml file. The configuration directory differs by operating system:

Operating system	Configuration directory
Windows	%USERPROFILE%\.codex
macOS / Linux	~/.codex

Choose one of the configuration methods below.

Method 1: Manual configuration

Navigate to the configuration directory and create or edit config.toml:

macOS / Linux

mkdir -p ~/.codex
nano ~/.codex/config.toml

Windows PowerShell

mkdir $env:USERPROFILE\.codex -Force
notepad $env:USERPROFILE\.codex\config.toml

Add the following configuration:

model = "gpt-5.4"
model_reasoning_effort = "medium"
model_provider = "CiYuanX"

[model_providers.CiYuanX]
name = "CiYuanX API"
base_url = "https://ciyuanx.io/v1"
env_key = "OPENAI_API_KEY"  # This refers to the name of the environment variable
wire_api = "responses"

Tip

The env_key setting tells the Codex CLI which environment variable to read. You'll set your CiYuanX API key in that variable in the next step.

Method 2: One-line configuration

macOS / Linux

mkdir -p ~/.codex && cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.4"
model_reasoning_effort = "medium"
model_provider = "CiYuanX"

[model_providers.CiYuanX]
name = "CiYuanX API"
base_url = "https://ciyuanx.io/v1"
env_key = "OPENAI_API_KEY"  # This refers to the name of the environment variable
wire_api = "responses"
EOF

Windows PowerShell

$configPath = "$env:USERPROFILE\.codex"
New-Item -ItemType Directory -Force -Path $configPath | Out-Null
@"
model = "gpt-5.4"
model_reasoning_effort = "medium"
model_provider = "CiYuanX"

[model_providers.CiYuanX]
name = "CiYuanX API"
base_url = "https://ciyuanx.io/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
"@ | Out-File -FilePath "$configPath\config.toml" -Encoding utf8

Tip

The configuration above sets the Codex CLI to read your API key from the OPENAI_API_KEY environment variable, which you'll configure with your CiYuanX API key in the next step.

Set the API key

After configuring the TOML file, set your CiYuanX API key as an environment variable.

Important

Even though the variable is named OPENAI_API_KEY, you should use your CiYuanX API key (not an OpenAI key). The Codex CLI uses this standard variable name for compatibility.

Temporary (current session only)

macOS / Linux

export OPENAI_API_KEY="sk-your-ciyuanx-api-key"

Windows PowerShell

$env:OPENAI_API_KEY="sk-your-ciyuanx-api-key"

Windows Command Prompt

set OPENAI_API_KEY=sk-your-ciyuanx-api-key

Permanent configuration

macOS / Linux (Bash)

Add to ~/.bashrc or ~/.bash_profile:

export OPENAI_API_KEY="sk-your-ciyuanx-api-key"

Apply the changes:

source ~/.bashrc  # or source ~/.bash_profile

macOS / Linux (Zsh)

Add to ~/.zshrc:

export OPENAI_API_KEY="sk-your-ciyuanx-api-key"

Apply the changes:

source ~/.zshrc

Windows PowerShell

[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-your-ciyuanx-api-key', 'User')

Windows Command Prompt

setx OPENAI_API_KEY "sk-your-ciyuanx-api-key"

Verify the configuration

Check the Node.js installation:

node -v
npm -v

Verify the Codex CLI installation:

codex --version

Test the API connection:

codex "Hi"

Check the environment variable:

macOS / Linux

echo $OPENAI_API_KEY

Windows PowerShell

echo $env:OPENAI_API_KEY

If everything is configured correctly, the Codex CLI should respond using CiYuanX's API.

Troubleshooting

401 Unauthorized error

• Verify your API key is correct: Console → API Keys
• Make sure the OPENAI_API_KEY environment variable is set correctly
• Restart your terminal after setting the environment variable

403 Forbidden error

• Check that your API key is valid
• Verify your account balance at https://ciyuanx.io/dashboard
• Make sure your API key has access to the requested model

Network errors

• Verify your internet connection
• Check that you can reach https://ciyuanx.io in a browser
• Make sure your firewall allows outbound HTTPS connections
• Confirm that base_url in config.toml is correct: https://ciyuanx.io/v1

Configuration not taking effect

• Restart your terminal after editing config.toml
• Verify the TOML syntax (no extra spaces, correct quotes)
• Check that the configuration file location is correct for your operating system
• Make sure the file is saved as config.toml (not config.toml.txt)

Codex command not found

macOS / Linux

# Check whether the npm global bin is on your PATH
npm config get prefix

# If needed, add it to your PATH in ~/.zshrc or ~/.bashrc:
export PATH="$(npm config get prefix)/bin:$PATH"

Windows

Verify that the npm global path is in your system PATH, then restart your terminal after installing.