Skip to main content
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). If you have Node.js installed, you can install directly via npm. This requires Node.js version 18 or higher.

​
Homebrew Installation (macOS)

macOS users can also install via Homebrew:

​
Verify Installation

After installation, reopen your terminal and check if the command is available:
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:
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:

​
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:
Write the following content into ~/.codex/config.toml:
Field descriptions:

​
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:
If the codex logout command is not available, you can manually delete the cache file:
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:
Once you see the Codex interactive interface, you can directly enter your requests, for example:

​
Verify Configuration

Inside Codex CLI, you can check the current model and provider in the interactive interface:
You should see the current model from the acedatacloud provider, for example:
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:
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: To temporarily switch models, you can specify the model via command line when starting Codex:
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:
Where:
  • trusted: Agent has full permissions, can execute commands and modify files.
  • untrusted: Agent has limited permissions, more suitable for unfamiliar projects.

​
Learn More