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 qiyaov without a separate subscription to an official OpenAI account. Once configured, Codex CLI will send requests to https://api.qiyaov.com/v1.

First, choose an authentication method, do not mix them. This article uses env_key = "ACEDATACLOUD_API_KEY", and the Token is read only from environment variables. If you switch to the CC Switch tutorial, then requires_openai_auth = true and ~/.codex/auth.json should be managed uniformly by CC Switch; do not keep env_key at the same time. Mixing two sets of configurations may cause Codex to read incorrect or expired Tokens, ultimately returning 401.

Application Process

To use Codex CLI, you can first go to the qiyaov 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, and after logging in or registering, you will be automatically returned to the current page.

There will be a free quota offered during the first application, 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 yet. 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 qiyaov, 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 the 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 qiyaov 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.qiyaov.com/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"

The explanations for 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 default model used
model_reasoning_effort Reasoning intensity, common values are low, medium, high
[model_providers.acedatacloud].base_url The OpenAI Responses proxy address for qiyaov
[model_providers.acedatacloud].env_key The name of the environment variable 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 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 qiyaov 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

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

/model

You should see that the current model comes 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 check in the following order:

  1. Open the actual effective ~/.codex/config.toml and confirm that model_provider = "acedatacloud" matches [model_providers.acedatacloud] character by character; case sensitivity must also match.
  2. Confirm that the current process can read the environment variable, but do not print the Token to the terminal:
    test -n "$ACEDATACLOUD_API_KEY" && echo "ACEDATACLOUD_API_KEY is set" || echo "ACEDATACLOUD_API_KEY is missing"
  3. This solution does not use ~/.codex/auth.json. If this file comes from an old official login or CC Switch, run codex logout first to ensure that another authentication source is no longer mixed.
  4. Completely exit and reopen Codex and the terminal; VS Code users also need to execute Developer: Reload Window or completely restart VS Code.
  5. Run a minimal validation:
    codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK" < /dev/null

If it still returns 401, first check if the Token was copied completely; do not add non-standard headers like X-Provider that may override. They are not universally required configurations for Codex custom providers and may alter the routing behavior of external configuration tools.

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

How It Works

Codex CLI natively uses the OpenAI Responses API protocol. qiyaov provides a proxy service compatible with the OpenAI Responses API at https://api.qiyaov.com/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 via the wire_api = "responses" protocol to base_url + /responses, which is https://api.qiyaov.com/v1/responses.
  4. qiyaov verifies your 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 interaction experience of Codex CLI, just switching the underlying model service to qiyaov.

Configure Model

The model field in ~/.codex/config.toml determines the model that Codex uses by default. qiyaov's OpenAI Responses service 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 and 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 qiyaov OpenAI service documentation.

Project Trust Levels

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

Learn More