Connect Codex CLI via OpenAI Hub

This tutorial aims to solve a simple problem: running Codex CLI locally and using OpenAI Hub’s domestic direct-connect API instead of the official one. This setup is stable and fast—you won’t need to mess with proxy configuration anymore.

1. Environment Preparation

To start Codex CLI, your system must meet the following requirements:

Node.js ≥ 22
npm ≥ 10
Stable network connection

If you’re on Windows, note that official native support is somewhat “experimental.” The more reliable way is to install WSL.

Once the environment is ready, begin installation.

2. Install Codex CLI

Windows Users

Install Git Bash—just keep clicking “Next.”
Then install the latest LTS version from Node.js official website.
When the environment is ready, execute the following in CMD or PowerShell:
```
npm install -g @openai/codex   # Install Codex CLI globally
codex --version                # Output version number to confirm success
```
Note: if you get an error saying “command not found: codex,” it’s usually because npm’s global install directory isn’t added to your PATH—just add it.

macOS Users

sudo npm install -g @openai/codex   # Install Codex CLI using npm; add sudo if permission denied
codex --version                     # Check installation success

Or use Homebrew (optional):

brew install codex

Linux Users

Works for most distributions:

sudo npm install -g @openai/codex   # Global installation
codex --version                     # Check if the executable command is recognized

Once installation is done, the next step is to configure it to use the OpenAI Hub API.

3. Configure Third-Party API Integration

When Codex CLI starts, it reads from ~/.codex in your user directory (on Windows: C:\Users\YourUsername\.codex).

Don’t have that folder? Create it manually.

Inside, you’ll need two configuration files: auth.json and config.toml.

1. Add Your Key

Contents of auth.json:

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

Note: be careful—no spaces before or after the key! Many people accidentally include extra spaces when copying, which causes authentication failure.

2. Specify Model and Gateway

Contents of config.toml:

model_provider = "openai-hub"
model = "gpt-4o-codex"               # Use whichever model you actually need
model_reasoning_effort = "high"      # Controls reasoning depth
disable_response_storage = true      # Don’t store response history
preferred_auth_method = "apikey"     # Use API Key for authentication

[model_providers.openai-hub]
name = "openai-hub"
base_url = "https://api.openai-hub.com/v1"

The logic is straightforward: Codex CLI is like a driver; config.toml tells it where to go (base_url), and auth.json is its pass (API Key).

After saving, start the terminal and enter:

codex

If you can enter the interactive interface normally, it means you have successfully connected to the OpenAI Hub gateway.

4. Verify That API Calls Work

In Codex CLI, try a simple test like:

# Example conversation
Please write a Node.js utility function that parses CSV files.

If it outputs code normally, the request is being routed through OpenAI Hub successfully.

If you see errors like Invalid auth or Connection failed, check:

Whether your API Key is correct
Whether base_url is https://api.openai-hub.com/v1
Whether your network can reach that address (usually fine within China)

5. FAQs

Q: Why does it say the model is unavailable at runtime?
The Codex CLI model name must match one supported on Hub, e.g. gpt-4o-codex, gpt-4-turbo. You can check the “Model List” in the console.

Q: Do auth.json and config.toml need to be placed in my VS Code project?
No. They’re global configurations—just having them in your user directory is enough.

Q: Does the CLI require logging into an official OpenAI account?
No. Authentication is done directly using your OpenAI Hub API Key.

Next, you can try setting up the Codex extension in VS Code. It can help you refactor code snippets or automatically fix project issues—that’s where its real power shines.