A Practical Guide to Running Codex CLI with a Custom Responses Provider

If you like agentic coding in the terminal, the useful question is not “which chat UI should I open?” It is: can my coding agent read this project, run commands, and use the model provider I configure without breaking my normal workflow?

This guide shows how to configure OpenAI’s Codex CLI with Ace Data Cloud as an OpenAI Responses-compatible provider. The result is still the native codex terminal experience, but requests are sent to https://api.acedata.cloud/v1 through a custom provider block.

What you can do

Codex CLI is a local programming agent that runs in your terminal. According to the source guide, it can read code, modify files, execute commands, explain errors, and help with daily development tasks.

The integration relies on Codex CLI’s support for custom model providers. The important documented values are:

• Provider base URL: https://api.acedata.cloud/v1
  


• Responses endpoint used by the workflow: https://api.acedata.cloud/v1/responses
  


• Config file: ~/.codex/config.toml
  


• Environment variable used for the token: ACEDATACLOUD_API_KEY
  


• Required protocol field: wire_api = "responses"
  


• Example default model: gpt-5
  


• Example validation model: gpt-5-mini
  

The guide is also clear about authentication: choose one method and do not mix them. This setup uses env_key = "ACEDATACLOUD_API_KEY", so Codex should read the token from an environment variable, not from a separate cached OpenAI login flow.

Install Codex CLI

Codex CLI supports macOS, Linux, Windows, and WSL. If you already have Node.js 18 or higher, the documented recommended install path is npm:

npm install -g @openai/codex

On macOS, the guide also shows a Homebrew option:

brew install --cask codex

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

codex --version

If you see command not found, reload your shell or check whether the install command added a directory that is not currently in your PATH.

Configure the token safely

Write your Ace Data Cloud API token into a shell startup file such as ~/.zshrc, ~/.bashrc, or ~/.bash_profile:

export ACEDATACLOUD_API_KEY="{token}"

Then reload your shell config:

source ~/.zshrc

Do not print the token while debugging. The source guide suggests checking only whether the variable is present:

test -n "$ACEDATACLOUD_API_KEY" && echo "ACEDATACLOUD_API_KEY is set" || echo "ACEDATACLOUD_API_KEY is missing"

That gives you a yes/no signal without leaking a credential into terminal history, logs, or a screen share.

Add the Codex provider block

Codex CLI uses ~/.codex/config.toml as its global configuration file. Create it if needed:

mkdir -p ~/.codex

touch ~/.codex/config.toml

Then add the provider configuration from the guide:

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"

A few fields matter more than they first appear:

• 
  model_provider must match the provider key in [model_providers.acedatacloud] exactly.


• 
  env_key tells Codex which environment variable contains the token.


• 
  wire_api = "responses" is required for this OpenAI Responses API-compatible route.


• 
  model_reasoning_effort can use values such as low, medium, or high.

If you previously logged in to Codex CLI with an official OpenAI account, clear the cached login before switching providers:

codex logout

If that command is unavailable, the guide gives the cache file to remove:

rm -f ~/.codex/auth.json

Start and verify a session

Move into a project and start Codex:

cd /path/to/your/project

codex

A simple first prompt is:

Explain the directory structure of this project

Inside the Codex interface, you can check the active model and provider with:

/model

The expected provider is acedatacloud, for example:

Model: gpt-5

Provider: acedatacloud

For a minimal command-line validation, the guide suggests:

codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK" < /dev/null

That test is useful because it removes project context and focuses on whether the provider configuration works.

Troubleshooting the common 401 path

If you get a 401, do not start adding random headers. The source guide specifically warns that non-standard headers such as X-Provider may alter routing behavior in external configuration tools.

Instead, check in this order:

1. Confirm model_provider = "acedatacloud" matches [model_providers.acedatacloud] character by character.


2. Confirm ACEDATACLOUD_API_KEY is set without printing its value.


3. Run codex logout or remove ~/.codex/auth.json if an old official login exists.


4. Fully restart Codex and the terminal. If you are using VS Code, reload the window or restart it.


5. Run the minimal codex exec --model gpt-5-mini validation again.

The mental model is simple: Codex reads ~/.codex/config.toml, loads the acedatacloud provider, reads the token from ACEDATACLOUD_API_KEY, and sends a Responses API request to https://api.acedata.cloud/v1/responses.

Choose a model for the task

The document lists several model IDs that can be used in the config or with codex --model, including gpt-5, gpt-5-mini, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-pro, gpt-4.1, o3, and o4-mini.

A practical default is to keep gpt-5 in config.toml, then temporarily override when you want a smaller run:

codex --model gpt-5-mini

For local agent work, that gives you a stable default while still allowing per-session experiments.

If you want the complete configuration notes, including project trust levels and the exact troubleshooting checklist, read the Ace Data Cloud Codex CLI Terminal guide: https://platform.acedata.cloud/documents/codex-terminal-integration