Complete Guide to Codex CLI Installation and API Configuration (Third-Party Gateway Support)

Codex CLI is a powerful command-line tool that integrates the capabilities of large language models directly into your terminal. Whether you are using the official OpenAI API or a third-party API gateway, proper configuration is key to ensuring stable operation.

🛠️ Prerequisites

Before starting, ensure your system has the following environments installed:

• Node.js: Version 22+
• npm: Version 10+

📦 Step 1: Install Codex CLI

Depending on your operating system, choose the corresponding installation method:

💻 Windows

1. Environment Setup: It is recommended to install Git Bash (for a Unix-like terminal experience) and Node.js LTS.
2. Execution: Run the following command in CMD or PowerShell:

   npm install -g @openai/codex
   

3. Verification:

   codex --version
   

🍎 macOS

1. Execution:

   npm install -g @openai/codex
   

   Note: If you encounter permission issues, prepend the command with sudo.
2. Verification:

   codex --version
   

   Optional: You can also install via Homebrew $\rightarrow$ brew install codex.

🐧 Linux

1. Environment Setup: Install Node.js and npm based on your distribution (e.g., sudo apt install nodejs npm).
2. Execution:

   sudo npm install -g @openai/codex
   

3. Verification:

   codex --version
   

⚙️ Step 2: Configure API Keys and Providers

All configurations for Codex CLI are stored in a hidden folder named .codex in your user directory.

1. Locating the Directory

• Windows: C:\Users\YourUsername\.codex (If not visible, enable “Show hidden items” in File Explorer).
• macOS/Linux: ~/.codex

If the folder does not exist, create it manually:

mkdir -p ~/.codex

2. Configuring auth.json (Authentication)

Create an auth.json file in this directory to store your API Key. File Content:

{
  "OPENAI_API_KEY": "your-actual-api-key"
}

3. Configuring config.toml (Models and Gateways)

Create a config.toml file to define the model provider and request path.

Config Template:

model_provider = "ProviderName"
model = "SpecificModelName"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ProviderName]
name = "ProviderName"
base_url = "https://actual-gateway-url/v1"
wire_api = "responses"

⚠️ Important: Ensure that the value of model_provider matches the section name [model_providers.xxx] exactly.

Applying Changes: After modifying the configuration, please restart your terminal and relaunch codex for the changes to take effect.

🔌 Step 3: Integrate with VS Code Extension

After configuring the .codex folder, you can enjoy a more intuitive UI experience:

1. Search for and install the Codex extension in the VS Code Extension Marketplace.
2. Once installed, the extension will appear in the sidebar.
3. The plugin automatically reads the configuration from ~/.codex, allowing you to call AI capabilities directly within your editor.

💡 Summary

By following the path of npm install $\rightarrow$ configuring the .codex directory $\rightarrow$ linking the VS Code plugin, you now have a highly efficient AI-powered programming environment. Regardless of how the API changes, you can simply update config.toml to switch providers quickly.