DEV Community

Cover image for A Practical Guide to Running Codex CLI with a Custom Responses Provider
Germey
Germey

Posted on • Originally published at platform.acedata.cloud

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

#ai #devtools #tutorial #programming

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
Enter fullscreen mode Exit fullscreen mode

On macOS, the guide also shows a Homebrew option:

brew install --cask codex
Enter fullscreen mode Exit fullscreen mode

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

codex --version
Enter fullscreen mode Exit fullscreen mode

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}"
Enter fullscreen mode Exit fullscreen mode

Then reload your shell config:

source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

rm -f ~/.codex/auth.json
Enter fullscreen mode Exit fullscreen mode

Start and verify a session

Move into a project and start Codex:

cd /path/to/your/project
codex
Enter fullscreen mode Exit fullscreen mode

A simple first prompt is:

Explain the directory structure of this project
Enter fullscreen mode Exit fullscreen mode

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

/model
Enter fullscreen mode Exit fullscreen mode

The expected provider is acedatacloud, for example:

Model: gpt-5
Provider: acedatacloud
Enter fullscreen mode Exit fullscreen mode

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

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

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (1)

Collapse
 
alexshev profile image
Alex Shev •

Custom providers are useful, but I would treat compatibility as a contract to test continuously. The scary failures are not obvious 500s; they are subtle differences in streaming, tool calls, refusal shape, and token accounting.