> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI Terminal Usage Guide

> Codex 集成指南 - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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.

```bash theme={null}
npm install -g @openai/codex
```

### Homebrew Installation (macOS)

macOS users can also install via Homebrew:

```bash theme={null}
brew install --cask codex
```

### Verify Installation

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

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

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

```toml theme={null}
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:

```bash theme={null}
codex logout
```

If the `codex logout` command is not available, you can manually delete the cache file:

```bash theme={null}
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:

```bash theme={null}
cd /path/to/your/project
codex
```

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

```text theme={null}
Explain the directory structure of this project
```

### Verify Configuration

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

```text theme={null}
/model
```

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

```text theme={null}
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:

```bash theme={null}
echo $ACEDATACLOUD_API_KEY
```

You can also view request records and billing details via [Ace Data Cloud Console - Usage History](https://platform.acedata.cloud/console/usages), and check remaining quota via [Ace Data Cloud Console - Applications](https://platform.acedata.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:

```bash theme={null}
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](https://platform.acedata.cloud/documents/openai).

## 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`:

```toml theme={null}
[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

* [Codex CLI Official Repository](https://github.com/openai/codex)
* [Ace Data Cloud OpenAI Service Documentation](https://platform.acedata.cloud/documents/openai)
* [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications)