Codex CC Switch Graphical Configuration Tutorial

Codex is a programming agent launched by OpenAI, which determines where requests are sent through the custom model_provider in ~/.codex/config.toml. By pointing it to the OpenAI Responses compatible proxy of Ace Data Cloud, you can use Codex at a lower price without needing a separate subscription to the official OpenAI account. Manually writing TOML configurations is not user-friendly for beginners, while CC Switch provides a graphical interface to help you write config.toml and auth.json with one click and switch between multiple vendors instantly.

This article explains how to connect Codex to Ace Data Cloud using CC Switch.

This tutorial is an alternative to the handwritten env_key tutorial. CC Switch uses requires_openai_auth = true, reading the Token from OPENAI_API_KEY in ~/.codex/auth.json. Do not add env_key = "..." to the same provider, nor mix in environment variable configurations from another tutorial; otherwise, Codex may retrieve incorrect credentials and return a 401.

What is CC Switch

CC Switch (official website ccswitch.io) is an open-source, cross-platform desktop configuration manager used to unify the management of vendor configurations for multiple AI programming tools such as Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, and Hermes. It is built on Tauri 2 and is open-sourced under the MIT license, having received over 110,000 stars on GitHub (see farion1231/cc-switch).

For Codex, CC Switch will manage two configuration files for you (see the official User Manual and 5.1 Configuration File Description):

  • ~/.codex/config.toml—stores model and interface configurations (model_provider, base_url, wire_api, etc.);
  • ~/.codex/auth.json—stores the API key.

The official main interface of CC Switch is as follows (screenshot from CC Switch Official Repository):

CC Switch Main Interface

Apply for API Token

To use Codex, first go to 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 inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. There will be a free quota offered for first-time applicants, allowing you to experience Codex services for free.

Download and Install CC Switch

Go to the Releases page of CC Switch (or directly download the latest version) and choose the corresponding installation package based on your operating system. The following installation methods are all from the official README:

Operating System System Requirements Installation Method
Windows Windows 10 and above Download the CC-Switch-v{version}-Windows.msi installer or the -Windows-Portable.zip portable version
macOS macOS 12 (Monterey) and above Recommended brew install --cask cc-switch, or download the .dmg (signed and notarized by Apple, can be opened directly)
Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+ Download .deb / .rpm / .AppImage; Arch users can use paru -S cc-switch-bin

Add Ace Data Cloud Vendor

CC Switch has built-in presets for over 50 vendors, but currently does not include Ace Data Cloud, so we will add it using the "Custom" method. The following steps correspond to the official documentation 2.1 Add Provider.

  1. Switch to the Codex application at the top of CC Switch.
  2. Click the + (Add Provider) button in the upper right corner to open the add panel.
  3. Select Custom from the preset dropdown, then fill in the configuration.

The official "Add Provider" panel of CC Switch is as follows (screenshot from CC Switch Official Repository):

CC Switch Add Provider Panel

Fill in the following information:

Field Content to Fill
Name Ace Data Cloud (customizable)
Base URL https://api.acedata.cloud/v1
API Key / Token The API Token you copied from the console

The custom configuration for Codex consists of two files (format reference in the official Codex Configuration Format). CC Switch will write the following 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.acedata.cloud/v1"
wire_api = "responses"
requires_openai_auth = true

And into ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "{token}"
}

Where {token} is replaced with the API Token you copied from the Ace Data Cloud console. After verifying that everything is correct, click Add to complete the addition.

The explanations for each field are as follows:

Field Description
model_provider The default vendor key, must match the acedatacloud in [model_providers.acedatacloud] exactly (including case)
model The default model ID, recommended gpt-5
model_reasoning_effort Reasoning intensity, common values are low, medium, high
base_url The OpenAI Responses proxy address for Ace Data Cloud, must be https://api.acedata.cloud/v1
wire_api Protocol type, must be responses for using OpenAI Responses API
requires_openai_auth Set to true to let Codex use the key in auth.json as the authentication credential

No need to enable Local Routing: The "Local Routing / Model Mapping" of CC Switch is only used for vendors that only support the OpenAI Chat Completions protocol or use non-GPT series model names (such as DeepSeek, Kimi). Ace Data Cloud belongs to the native Responses protocol vendor (wire_api = "responses"), so keep Needs Local Routing off, see the official 2.1 Add Provider - Codex Presets.

Enable and Switch Provider

After adding, find the Ace Data Cloud card in the Codex vendor list and click Enable (refer to the official 2.2 Switch Provider). You can also click the vendor name directly from the system tray menu for instant switching.

Need to restart: According to the official FAQ, except for Claude Code which supports hot switching, tools like Codex need to restart the corresponding CLI or terminal after switching vendors to take effect.

Using in Terminal and VS Code

CC Switch is only responsible for writing configurations, the Codex body still needs to be installed separately. After enabling the vendor:

  • Terminal CLI: Install and run codex, complete steps can be found in Codex Terminal Configuration Tutorial. After entering the interactive interface, type /model, and you should see the current vendor as acedatacloud.
  • VS Code Extension: Install the official OpenAI Codex extension from the extension marketplace (Marketplace ID: openai.chatgpt), complete steps can be found in Codex VS Code Configuration Tutorial. Since the VS Code extension and CLI share the same ~/.codex/config.toml configuration, the VS Code extension will directly reuse it after CC Switch is set up.

Verify Configuration

You can verify whether Codex can work through Ace Data Cloud with the same configuration in the terminal:

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

If the configuration is correct, you should see a reply similar to:

ADC_Codex_OK

Switch Model

The model field in ~/.codex/config.toml determines the model that Codex uses by default. Ace Data Cloud's OpenAI Responses service supports various models, commonly including gpt-5 (recommended default), gpt-5-mini (lighter), gpt-5.5, gpt-5.5-pro, etc. For a complete list of models and billing information, refer to the Ace Data Cloud OpenAI Service Documentation. You can also automatically discover available models from the /v1/models endpoint in the CC Switch vendor form by using the "Fetch Models" button (refer to the official Auto-Fetch Models).

Check Quota and Usage

Frequently Asked Questions

  • Returns 401 invalid token? Check in order:
    1. model_provider = "acedatacloud" matches exactly with [model_providers.acedatacloud]. For example, if written as model_provider = "OpenAI", the configuration block must also be called [model_providers.OpenAI]; do not let the name point to another provider.
    2. The current provider should only keep requires_openai_auth = true, do not write env_key = "DASHUN_API_KEY" or other environment variable names at the same time.
    3. The OPENAI_API_KEY in ~/.codex/auth.json is the current Ace Data Cloud Token, not an old official account or expired Token.
    4. Remove non-standard items like X-Provider from the Header overrides. They are not universally required configurations for Codex custom providers.
    5. After saving, completely exit and restart CC Switch, Codex, terminal, or VS Code, then run the minimal verification command in this document.
  • Not effective after switching? Confirm that Codex / terminal has been restarted; and check if model_provider in ~/.codex/config.toml points to acedatacloud. The location of CC Switch's configuration file is explained in the official 5.1 Configuration File Explanation.
  • How to switch back to official login? Add the OpenAI Official vendor from the preset list, Codex supports switching between multiple official accounts (refer to the official FAQ).
  • Where is the configuration data stored? CC Switch's own data is stored in ~/.cc-switch/cc-switch.db (SQLite), and the effective configuration is written to ~/.codex/config.toml and ~/.codex/auth.json.

Reference Sources