Codex CLI Terminal User Guide

Codex CLI is an open-source local programming agent launched by OpenAI, running in your terminal. It can read code, modify files, execute commands, explain errors, and assist with daily development tasks.

Codex CLI supports custom model providers, and you can use it through the OpenAI Responses compatible proxy provided by Ace Data Cloud without a separate subscription to an official OpenAI account. Once configured, Codex CLI will send requests to https://api.acedata.cloud/v1.

Application Process

To use Codex CLI, you can first go to the Ace Data Cloud Console to obtain your API Token for backup.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.

There is a free quota available for first-time applicants, allowing you to experience Codex CLI services for free.

Installing Codex CLI

Codex CLI supports macOS, Linux, Windows, and WSL. You can install it via npm or use Homebrew (macOS only).

npm Installation (Recommended)

If you have already installed Node.js, you can install it directly via npm. This method requires Node.js version 18 or higher.

npm install -g @openai/codex

Homebrew Installation (macOS)

macOS users can also install using Homebrew:

brew install --cask codex

Check Installation

After installation, reopen the terminal and check if the command is available:

codex --version

If you see command not found, it usually means the current terminal has not loaded the new PATH. Please close and reopen the terminal, or check the PATH configuration suggested in the installation script output.

Configuring Codex CLI

After installation, Codex CLI will attempt to connect to the official OpenAI service by default. To switch to Ace Data Cloud, you need to declare a custom model_provider in Codex's configuration file and place the API Token in the corresponding environment variable.

Step 1: Set Environment Variable

It is recommended to write the API Token into your Shell configuration file, such as ~/.zshrc, ~/.bashrc, or ~/.bash_profile:

export ACEDATACLOUD_API_KEY="{token}"

Replace {token} with the API Token you copied from the Ace Data Cloud Console.

After configuring, reopen the terminal or execute the corresponding source command to make the configuration take effect immediately:

source ~/.zshrc

Step 2: Edit Codex Configuration File

Codex CLI uses ~/.codex/config.toml as the global configuration file. If this file does not exist, you can create it:

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

Write the following content into ~/.codex/config.toml:

model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"

The descriptions of each field are as follows:

Field Description
model_provider The name of the default provider, corresponding to the key [model_providers.<name>] below
model The ID of the model to be used by default
model_reasoning_effort Reasoning intensity, common values are low, medium, high
[model_providers.acedatacloud].base_url The OpenAI Responses proxy address for Ace Data Cloud
[model_providers.acedatacloud].env_key The name of the environment variable from which Codex CLI reads the API Token
[model_providers.acedatacloud].wire_api The protocol type, must be responses for using OpenAI Responses API

Clear Cached OpenAI Login

If you have previously logged into Codex CLI with an official OpenAI account, the local login state may be cached (usually stored in ~/.codex/auth.json). It is recommended to clear the old login before switching to the Ace Data Cloud proxy:

codex logout

If the codex logout command is unavailable, you can also manually delete the cache file:

rm -f ~/.codex/auth.json

If you have never logged into an official OpenAI account, you can skip this step.

Start Session

Navigate to your project directory and then start Codex CLI:

cd /path/to/your/project
codex

Once you see the Codex interactive interface, you can directly input your requests, for example:

Explain the directory structure of this project

Verify Configuration

After entering Codex CLI, you can check the current model and provider in the interactive interface:

/model

You should see that the current model is from the acedatacloud provider, for example:

Model: gpt-5
Provider: acedatacloud

If the displayed provider is not acedatacloud, it indicates that the configuration has not taken effect. Please recheck if ~/.codex/config.toml has been saved successfully and whether ACEDATACLOUD_API_KEY is readable in the current terminal:

echo $ACEDATACLOUD_API_KEY

You can also check the request records and billing details through the Ace Data Cloud Console - Usage History and view the remaining quota through the Ace Data Cloud Console - Application List.

How It Works

Codex CLI natively uses the OpenAI Responses API protocol. Ace Data Cloud provides a proxy service compatible with the OpenAI Responses API at https://api.acedata.cloud/v1/responses, so Codex CLI does not require a local proxy program or additional plugins.

The workflow is as follows:

  1. Codex CLI reads model_provider from ~/.codex/config.toml and loads the corresponding [model_providers.acedatacloud] configuration block.
  2. Codex CLI reads the API Token from the environment variable specified by env_key (ACEDATACLOUD_API_KEY).
  3. The request is sent through the wire_api = "responses" protocol to base_url + /responses, which is https://api.acedata.cloud/v1/responses.
  4. Ace Data Cloud verifies identity using your API Token, checks the quota, and forwards the request to an available upstream model channel.
  5. After the request is completed, the platform records usage based on actual consumption and deducts from the quota.

This means you still use the original codex command and the native interactive experience of Codex CLI, just switching the underlying model service to Ace Data Cloud.

Configuring Models

The model field in ~/.codex/config.toml determines the model that Codex uses by default. The OpenAI Responses service from Ace Data Cloud supports various models, commonly including:

Model Description
gpt-5 Recommended default model, suitable for most coding tasks
gpt-5-mini Lighter, faster response, suitable for simple tasks
gpt-5.6-sol Latest flagship, preferred for complex reasoning and programming
gpt-5.6-terra Balanced option, high cost-performance ratio
gpt-5.6-luna Lightweight option, fast speed, low cost
gpt-5.5 Updated version, stronger capabilities
gpt-5.5-pro Enhanced version, suitable for complex reasoning tasks
gpt-4.1 Previous generation main model
o3 Reasoning enhanced model, suitable for tasks requiring deep reasoning
o4-mini Lightweight reasoning model

If you want to temporarily switch models, you can specify it via command line parameters when starting Codex:

codex --model gpt-5-mini

You can also directly modify the model field in ~/.codex/config.toml and restart. A complete list of models can be found in the Ace Data Cloud OpenAI service documentation.

Project Trust Levels

Codex CLI supports setting different trust levels for different projects, controlling what operations the Agent can perform. You can append the following at the end of ~/.codex/config.toml:

[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"

Where:

  • trusted: The Agent has full permissions, can execute commands and modify files.
  • untrusted: The Agent has limited permissions, more suitable for unfamiliar projects.

Learn More