Codex CLI Terminal Usage Guide

Codex CLI is an open-source local programming agent launched by OpenAI that runs 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. You can use it through the OpenAI Responses compatible proxy provided by Ace Data Cloud without subscribing to an official OpenAI account. After configuration, Codex CLI will send requests to https://api.acedata.cloud/v1.

Application Process

To use Codex CLI, first visit 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 to register and log in. After logging in or registering, you will be automatically returned to the current page.

A free quota is granted upon first application, allowing you to try the Codex CLI service 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 Node.js installed, you can install directly via npm. This requires Node.js version 18 or higher.

npm install -g @openai/codex

Homebrew Installation (macOS)

macOS users can also install via Homebrew:

brew install --cask codex

Verify Installation

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

codex --version

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

Configuring Codex CLI

After installation, Codex CLI will by default try to connect to the official OpenAI service. 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 configuration, reopen the terminal or run the corresponding source command to apply the changes 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, 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"

Field descriptions:

Field Description
model_provider Default provider name, corresponding to the key in [model_providers.<name>] below
model Default model ID
model_reasoning_effort Reasoning intensity, common values are low, medium, high
[model_providers.acedatacloud].base_url Ace Data Cloud’s OpenAI Responses proxy URL
[model_providers.acedatacloud].env_key Environment variable name from which Codex CLI reads the API Token
[model_providers.acedatacloud].wire_api Protocol type, must be responses when using OpenAI Responses API

Clear Cached OpenAI Login

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

codex logout

If the codex logout command is not available, you can 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 a Session

Navigate to your project directory, then start Codex CLI:

cd /path/to/your/project
codex

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

Explain the directory structure of this project

Verify Configuration

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

/model

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

Model: gpt-5
Provider: acedatacloud

If the provider shown is not acedatacloud, the configuration has not taken effect. Please recheck whether ~/.codex/config.toml was saved successfully and whether ACEDATACLOUD_API_KEY is readable in the current terminal:

echo $ACEDATACLOUD_API_KEY

You can also view request records and billing details via Ace Data Cloud Console - Usage History, and check remaining quota via Ace Data Cloud Console - Applications.

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 or additional plugins.

Workflow:

  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. Requests are sent via the wire_api = "responses" protocol to base_url + /responses, i.e., https://api.acedata.cloud/v1/responses.
  4. Ace Data Cloud verifies identity and quota using your API Token, then forwards the request to an available upstream model channel.
  5. After completion, the platform records usage and deducts quota based on actual consumption.

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

Configuring Models

The model field in ~/.codex/config.toml determines the default model Codex uses. Ace Data Cloud’s OpenAI Responses service supports multiple models, commonly including:

Model Description
gpt-5 Recommended default model, suitable for most coding tasks
gpt-5-mini Lighter and faster response, suitable for simple tasks
gpt-5.5 Updated version with 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 deep reasoning tasks
o4-mini-high-all Lightweight reasoning model

To temporarily switch models, you can specify the model via command line when starting Codex:

codex --model gpt-5-mini

Or directly modify the model field in ~/.codex/config.toml and restart. For the full model list, see Ace Data Cloud OpenAI Service Documentation.

Project Trust Levels

Codex CLI supports setting different trust levels for different projects to control 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: Agent has full permissions, can execute commands and modify files.
  • untrusted: Agent has limited permissions, more suitable for unfamiliar projects.

Learn More