Installing Codex is not difficult; the real challenge often lies in integration: where to put the API Key, how to write config.toml, differences between Windows and macOS, why VS Code can't read terminal variables, whether to fix the model...

If you just want to get Codex running quickly, you can condense the configuration into three values:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

Once done, the Codex CLI, Desktop, and VS Code extensions can share ~/.codex/config.toml, and models can be selected directly after startup, avoiding the need to reconfigure access each time you switch models.

Below is a step-by-step guide to complete the setup from scratch.

Preparation

Before starting, please confirm:

  • You have registered and logged into Ace Data Cloud
  • You have created or own an available application
  • Node.js and npm are installed on your machine
  • You can use a terminal or PowerShell
  • You plan to use at least one of Codex CLI, Codex Desktop, or VS Code extension

Step 1: Obtain Ace Data Cloud API Key

Open the Ace Data Cloud Applications List, go to your available application, and copy the API Key.

Note:

  • The API Key is sensitive credentials; do not commit it to public repositories
  • Do not include real keys in tutorial screenshots
  • It’s recommended to create and manage credentials separately for each environment or purpose
  • If you suspect leakage, rotate or revoke the key promptly

This document uniformly uses the environment variable ACEDATACLOUD_API_KEY to avoid writing plaintext credentials directly into the config.toml.

Step 2: Install Codex CLI

Install Codex globally via npm:

npm install -g @openai/codex

Verify installation:

codex --version

If command not found, ensure that npm’s global bin directory is added to your PATH, then reopen your terminal.

If you mainly use VS Code, you can also install OpenAI’s Codex extension:

code --install-extension openai.chatgpt

Since CLI and VS Code extension share the same configuration file, it’s recommended to configure the Provider and environment variables first, then launch the editor to verify.

Step 3: Set API Key Environment Variable

macOS / Linux: Current terminal session

export ACEDATACLOUD_API_KEY="your API Key"

This only affects the current shell and its subprocesses. Closing the terminal will discard the variable.

macOS / Linux: Persistent across sessions

If using Zsh:

echo 'export ACEDATACLOUD_API_KEY="your API Key"' >> ~/.zshrc
source ~/.zshrc

If using Bash:

echo 'export ACEDATACLOUD_API_KEY="your API Key"' >> ~/.bashrc
source ~/.bashrc

Avoid blindly copying shell configurations with real keys on shared computers; in team environments, combine with credential management tools and least privilege policies.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "your API Key"

After executing, close and reopen PowerShell. setx does not update the current session automatically, so existing terminals and VS Code may still not see the new value.

To temporarily set in the current PowerShell session:

$env:ACEDATACLOUD_API_KEY="your API Key"

Step 4: Create or Edit config.toml

The shared configuration file for Codex CLI, Desktop, and VS Code is:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

Create the directory if it does not exist.

macOS / Linux:

mkdir -p ~/.codex

Then write the configuration:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows uses the same provider and base URL, but the auth command is PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

Ensure the three names are consistent:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

The base URL must include /v1.

Step 5: Launch Codex and Select Model

After saving the configuration, reopen your terminal and run:

codex

Within Codex, run:

/model

Verify that the current provider is acedatacloud, then select a model from the available list.

You do not need to fix the model in the configuration. Separating provider and model selection reduces the need to edit the TOML repeatedly when switching models. Actual models and availability are updated regularly; always check /model and the platform’s directory.

Step 6: Verify with a Minimal Request

Avoid asking Codex to refactor the entire repository immediately. Send a simple, quick-to-evaluate request, such as:

Please summarize the directory structure of the current project without modifying any files.

Then check the Ace Data Cloud Usage History to confirm the request was received and to review status and consumption.

If the minimal request succeeds, proceed gradually to read files, generate modification plans, edit code, and run tests.

VS Code Configuration Tips

The VS Code extension reads the same ~/.codex/config.toml, but whether it can see the API Key depends on the environment of the extension process.

After configuring, fully restart VS Code. On macOS / Linux, if variables are not visible after launching from the GUI, run:

code .

from a terminal where the environment variable is set.

Variables should be configured in the environment where the extension runs, such as:

  • Remote SSH: remote host
  • WSL: WSL Linux environment
  • Dev Container: container environment
  • Codespaces or similar remote environments

Setting variables only in your local shell does not guarantee the remote extension will access them.

Key Points for Configuring Desktop

The Desktop app shares the configuration file with CLI, but it may not inherit environment variables set only in a terminal.

If Desktop cannot read the API Key:

  1. Set environment variables persistently or system-wide
  2. Fully exit Desktop
  3. Restart the application
  4. Recheck provider and model settings

Common Troubleshooting

1. 401, Unauthorized, or Incorrect API Key

Check the following:

  1. Is the API Key copied completely?
  2. Is the environment variable named ACEDATACLOUD_API_KEY?
  3. Is the process (CLI, Desktop, VS Code) started after setting the variable?
  4. Does auth.command match your OS?
  5. Is the credential still valid? Do not output the complete Key to logs or chat. You can check the variable using a "whether it exists" approach.

macOS / Linux:

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell:

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider has not become acedatacloud

Verify the configuration file path and TOML hierarchy. Common mistakes include:

  • File name written as config.toml.txt
  • Editing another user's directory
  • Inconsistent table names
  • Quotation or array format errors
  • Not restarting the client after saving

3. Base URL request failed

Ensure the address is:

https://api.acedata.cloud/v1

Do not omit https:// or the /v1 at the end, and do not mistakenly use the console page address.

4. CLI works, VS Code does not

This is usually not a Provider configuration issue, but VS Code process did not read environment variables. Launch code . from a terminal where the variables are set, or fully restart VS Code after configuring system-level variables.

5. Cannot read Key in WSL, SSH, or container

Environment variables need to be set in the environment where Codex or extensions actually run. setx on Windows host will not automatically write to WSL; local variables are not automatically passed to remote SSH hosts or containers.

6. Cannot find the model you want to use

Do not manually guess old model IDs. Run /model to see real-time options, and check application permissions, balance, and current Provider.

7. Request arrives but cannot complete complex tasks

First narrow down the task scope: let Codex only read analysis, list plans, then gradually allow modifications and testing. Successful model connection does not mean all repository tasks should be completed at once; complex changes still require clear acceptance criteria, testing, and manual review.

Before submitting your first formal task, confirm each item:

  • Obtained a valid API Key from the application list
  • Key is saved in ACEDATACLOUD_API_KEY
  • Did not write the Key into the Git repository
  • model_provider is acedatacloud
  • Base URL is https://api.acedata.cloud/v1
  • auth.command matches the operating system
  • Fully restarted Codex or VS Code
  • /model shows Provider and models
  • Minimal test request succeeds
  • Usage History shows corresponding call records

One Provider, reducing repetitive configuration

The focus of this integration method is not to write more TOML, but to establish a stable boundary:

  • API Key managed via environment variables
  • Provider connection managed by config.toml
  • Models selected within Codex per task
  • Call records and consumption viewed centrally in Ace Data Cloud console
  • CLI, Desktop, and VS Code share the same configuration

When authentication, Provider, and model selection are clearly separated, many "Why can't Codex be used again" issues can be quickly diagnosed, without repeatedly logging in, reinstalling, or copying multiple configurations.

Open Codex Configuration Center for official guides for different clients, or go to Application List to get API Keys.

References