Contact Support
Codex CLI Usage Guide
Codex is OpenAI's official command-line AI programming assistant that supports integration through the Codex API Hub proxy. Note: Codex uses OpenAI-compatible format, the endpoint needs to include the /v1 path.

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using Homebrew (recommended)
bash
# 更新 Homebrew
brew update
# 安装 Node.js
brew install node
Method 2: Download from official website
  1. Visit https://nodejs.org/
  2. Download the LTS version for macOS (v18 or higher required)
  3. Open the downloaded .pkg file and follow the installation wizard

Verify Node.js Installation

After installation, open terminal/command line and run the following commands to verify:

bash
node --version
npm --version

If version numbers are displayed, the installation was successful!

Install codex codex

Execute:

bash
npm i -g @openai/codex --registry=https://registry.npmmirror.com

Verify installation:

bash
codex --version

Connect to Codex API Hub service

Configuration file setup

  1. Open file explorer, find the ~/.codex folder (create if it doesn't exist)
  2. Create a config.toml file
  3. Open with text editor and add the following content:

Create config.toml file (when using auth.json to store the key, env_key field is not required):

toml
model_provider = "cch"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
disable_response_storage = true
sandbox_mode = "workspace-write"
[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false
streamable_shell = false
rmcp_client = true

[model_providers.cch]
name = "cch"
base_url = "Current site address/v1"
wire_api = "responses"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

Create an auth.json file and add:

json
{
  "OPENAI_API_KEY": "your-api-key-here"
}

NoteThis method stores the API key in auth.json file, no need to configure env_key field in config.toml.

Important note

  • Replace your-api-key-here with your Codex API Hub API key
  • Note: Codex uses OpenAI-compatible format, endpoint includes the /v1 path

VS Code Extension Configuration

  1. Search for and install Codex – OpenAI's coding agent in VS Code extensions
  2. Make sure you have configured config.toml and auth.json according to the steps above
  3. Set the CCH_API_KEY environment variable

Important

env_key can only be an environment variable name (such as CCH_API_KEY), not the complete key. If you directly fill in the key, it will report an error that the token is not found or the token configuration is incorrect.

Start codex

Run the following command in your project directory:

bash
cd /path/to/your/project
codex

During the first startup, codex will perform initial configuration.

Common questions

1. Command not found

bash
# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

# # Add to PATH (if missing)
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API connection failed

bash
# # Check environment variable
echo $CCH_API_KEY

# # Test network connection
curl -I Current site address

3. Update codex

bash
npm i -g @openai/codex --registry=https://registry.npmmirror.com